Commit | Line | Data |
---|---|---|
168e428f | 1 | //////////////////////////////////////////////////////////////////////////// |
f9daeae0 | 2 | $Cambridge: exim/doc/doc-docbook/spec.ascd,v 1.4 2005/12/05 14:38:18 ph10 Exp $ |
168e428f PH |
3 | |
4 | This is the primary source of the Exim Manual. It is an AsciiDoc document | |
5 | that is converted into DocBook XML for subsequent conversion into printing | |
6 | and online formats. The markup used herein is traditional AsciiDoc markup, | |
7 | with some extras. The markup is summarized in a file called AdMarkup.txt. A | |
8 | private AsciiDoc configuration file specifies how the extra markup is to be | |
9 | translated into DocBook XML. You MUST use this private AsciiDoc markup if you | |
10 | want to get sensible results from processing this document. | |
11 | //////////////////////////////////////////////////////////////////////////// | |
12 | ||
13 | ||
14 | ||
15 | //////////////////////////////////////////////////////////////////////////// | |
16 | I am abusing the <abstract> DocBook element as the only trivial way of getting | |
17 | this information onto the title verso page in the printed renditions. A better | |
18 | title page would be a useful improvement. The <abstract> element is removed by | |
19 | preprocessing for the HTML renditions, and the whole <docbookinfo> element is | |
20 | removed for ascii output formats. | |
21 | //////////////////////////////////////////////////////////////////////////// | |
22 | ||
23 | Specification of the Exim Mail Transfer Agent | |
24 | ============================================= | |
25 | :abstract: University of Cambridge Computing Service, New Museums Site, Pembroke Street, Cambridge CB2 3QH, England | |
26 | :author: Philip Hazel | |
27 | :copyright: University of Cambridge | |
28 | :cpyear: 2005 | |
068aaea8 | 29 | :date: 01 November 2005 |
168e428f | 30 | :doctitleabbrev: The Exim MTA |
068aaea8 | 31 | :revision: 4.60 |
168e428f PH |
32 | |
33 | ||
34 | ////////////////////////////////////////////////////////////////////////////// | |
35 | ***WARNING*** Do not put anything, not even a titleabbrev, setting before | |
36 | the first chapter (luckily it does not need one) because if you do, AsciiDoc | |
37 | creates an empty <preface> element, which we do not want. | |
38 | ////////////////////////////////////////////////////////////////////////////// | |
39 | ||
40 | Introduction | |
41 | ------------ | |
42 | ||
43 | //////////////////////////////////////////////////////////////////////////// | |
44 | These are definitions of AsciiDoc "attributes" that are in effect "variables" | |
45 | whose values can be substituted. The first makes index entries shorter. The | |
46 | second avoids problems with literal asterisks getting tangled up with bold | |
47 | emphasis quotes. The others are here for convenience of editing. | |
48 | ||
49 | ***WARNING*** The positioning of these definitions, after the first Chapter | |
50 | title, seems to be important. If they are placed earlier, they give rise to | |
51 | incorrect XML. | |
52 | //////////////////////////////////////////////////////////////////////////// | |
53 | ||
54 | :ACL: access control lists (ACLs) | |
55 | :star: * | |
068aaea8 PH |
56 | :previousversion: 4.50 |
57 | :version: 4.60 | |
168e428f PH |
58 | |
59 | ||
60 | //////////////////////////////////////////////////////////////////////////// | |
61 | This chunk of literal XML implements index entries of the form "x, see y" and | |
62 | "x, see also y". It didn't seem worth inventing AsciiDoc markup for this, | |
63 | because is it not something that is likely to change often. | |
64 | //////////////////////////////////////////////////////////////////////////// | |
65 | ||
66 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | |
67 | <indexterm role="concept"> | |
68 | <primary>$1, $2, etc.</primary> | |
69 | <see><emphasis>numerical variables</emphasis></see> | |
70 | </indexterm> | |
71 | <indexterm role="concept"> | |
72 | <primary>address</primary> | |
73 | <secondary>rewriting</secondary> | |
74 | <see><emphasis>rewriting</emphasis></see> | |
75 | </indexterm> | |
068aaea8 PH |
76 | <indexterm role="concept"> |
77 | <primary>Bounce Address Tag Validation</primary> | |
78 | <see><emphasis>BATV</emphasis></see> | |
79 | </indexterm> | |
80 | <indexterm role="concept"> | |
81 | <primary>Client SMTP Authorization</primary> | |
82 | <see><emphasis>CSA</emphasis></see> | |
83 | </indexterm> | |
168e428f PH |
84 | <indexterm role="concept"> |
85 | <primary>CR character</primary> | |
86 | <see><emphasis>carriage return</emphasis></see> | |
87 | </indexterm> | |
88 | <indexterm role="concept"> | |
89 | <primary>CRL</primary> | |
90 | <see><emphasis>certificate revocation list</emphasis></see> | |
91 | </indexterm> | |
92 | <indexterm role="concept"> | |
93 | <primary>delivery</primary> | |
94 | <secondary>failure report</secondary> | |
95 | <see><emphasis>bounce message</emphasis></see> | |
96 | </indexterm> | |
97 | <indexterm role="concept"> | |
98 | <primary>dialup</primary> | |
99 | <see><emphasis>intermittently connected hosts</emphasis></see> | |
100 | </indexterm> | |
101 | <indexterm role="concept"> | |
102 | <primary>exiscan</primary> | |
103 | <see><emphasis>content scanning</emphasis></see> | |
104 | </indexterm> | |
105 | <indexterm role="concept"> | |
106 | <primary>failover</primary> | |
107 | <see><emphasis>fallback</emphasis></see> | |
108 | </indexterm> | |
109 | <indexterm role="concept"> | |
110 | <primary>fallover</primary> | |
111 | <see><emphasis>fallback</emphasis></see> | |
112 | </indexterm> | |
113 | <indexterm role="concept"> | |
114 | <primary>filter</primary> | |
115 | <secondary>Sieve</secondary> | |
116 | <see><emphasis>Sieve filter</emphasis></see> | |
117 | </indexterm> | |
118 | <indexterm role="concept"> | |
119 | <primary>ident</primary> | |
120 | <see><emphasis>RFC 1413</emphasis></see> | |
121 | </indexterm> | |
122 | <indexterm role="concept"> | |
123 | <primary>LF character</primary> | |
124 | <see><emphasis>linefeed</emphasis></see> | |
125 | </indexterm> | |
126 | <indexterm role="concept"> | |
127 | <primary>maximum</primary> | |
128 | <see><emphasis>limit</emphasis></see> | |
129 | </indexterm> | |
068aaea8 PH |
130 | <indexterm role="concept"> |
131 | <primary>monitor</primary> | |
132 | <see><emphasis>Exim monitor</emphasis></see> | |
133 | </indexterm> | |
168e428f PH |
134 | <indexterm role="concept"> |
135 | <primary>no_<emphasis>xxx</emphasis></primary> | |
136 | <see>entry for xxx</see> | |
137 | </indexterm> | |
138 | <indexterm role="concept"> | |
139 | <primary>NUL</primary> | |
140 | <see><emphasis>binary zero</emphasis></see> | |
141 | </indexterm> | |
142 | <indexterm role="concept"> | |
143 | <primary>passwd file</primary> | |
144 | <see><emphasis>/etc/passwd</emphasis></see> | |
145 | </indexterm> | |
146 | <indexterm role="concept"> | |
147 | <primary>process id</primary> | |
148 | <see><emphasis>pid</emphasis></see> | |
149 | </indexterm> | |
150 | <indexterm role="concept"> | |
151 | <primary>RBL</primary> | |
152 | <see><emphasis>DNS list</emphasis></see> | |
153 | </indexterm> | |
154 | <indexterm role="concept"> | |
155 | <primary>redirection</primary> | |
156 | <see><emphasis>address redirection</emphasis></see> | |
157 | </indexterm> | |
158 | <indexterm role="concept"> | |
159 | <primary>return path</primary> | |
160 | <seealso><emphasis>envelope sender</emphasis></seealso> | |
161 | </indexterm> | |
162 | <indexterm role="concept"> | |
163 | <primary>scanning</primary> | |
164 | <see><emphasis>content scanning</emphasis></see> | |
165 | </indexterm> | |
166 | <indexterm role="concept"> | |
167 | <primary>SSL</primary> | |
168 | <see><emphasis>TLS</emphasis></see> | |
169 | </indexterm> | |
170 | <indexterm role="concept"> | |
171 | <primary>string</primary> | |
172 | <secondary>expansion</secondary> | |
173 | <see><emphasis>expansion</emphasis></see> | |
174 | </indexterm> | |
175 | <indexterm role="concept"> | |
176 | <primary>top bit</primary> | |
177 | <see><emphasis>8-bit characters</emphasis></see> | |
178 | </indexterm> | |
179 | <indexterm role="concept"> | |
180 | <primary>variables</primary> | |
181 | <see><emphasis>expansion, variables</emphasis></see> | |
182 | </indexterm> | |
183 | <indexterm role="concept"> | |
184 | <primary>zero, binary</primary> | |
185 | <see><emphasis>binary zero</emphasis></see> | |
186 | </indexterm> | |
187 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | |
188 | ||
189 | ||
190 | //////////////////////////////////////////////////////////////////////////// | |
191 | OK, now we start with the real data for this first chapter. | |
192 | //////////////////////////////////////////////////////////////////////////// | |
193 | ||
194 | Exim is a mail transfer agent (MTA) for hosts that are running Unix or | |
195 | Unix-like operating systems. It was designed on the assumption that it would be | |
196 | run on hosts that are permanently connected to the Internet. However, it can be | |
197 | used on intermittently connected hosts with suitable configuration adjustments. | |
198 | ||
199 | Configuration files currently exist for the following operating systems: AIX, | |
068aaea8 PH |
200 | BSD/OS (aka BSDI), Darwin (Mac OS X), DGUX, Dragonfly, FreeBSD, GNU/Hurd, |
201 | GNU/Linux, HI-OSF (Hitachi), HI-UX, HP-UX, IRIX, MIPS RISCOS, NetBSD, OpenBSD, | |
202 | OpenUNIX, QNX, SCO, SCO SVR4.2 (aka UNIX-SV), Solaris (aka SunOS5), SunOS4, | |
203 | Tru64-Unix (formerly Digital UNIX, formerly DEC-OSF1), Ultrix, and Unixware. | |
204 | Some of these operating systems are no longer current and cannot easily be | |
205 | tested, so the configuration files may no longer work in practice. | |
168e428f PH |
206 | |
207 | There are also configuration files for compiling Exim in the Cygwin environment | |
208 | that can be installed on systems running Windows. However, this document does | |
209 | not contain any information about running Exim in the Cygwin environment. | |
210 | ||
211 | The terms and conditions for the use and distribution of Exim are contained in | |
212 | the file _NOTICE_. Exim is distributed under the terms of the GNU General | |
213 | Public Licence, a copy of which may be found in the file _LICENCE_. | |
214 | ||
215 | The use, supply or promotion of Exim for the purpose of sending bulk, | |
216 | unsolicited electronic mail is incompatible with the basic aims of the program, | |
217 | which revolve around the free provision of a service that enhances the quality | |
218 | of personal communications. The author of Exim regards indiscriminate | |
219 | mass-mailing as an antisocial, irresponsible abuse of the Internet. | |
220 | ||
221 | Exim owes a great deal to Smail 3 and its author, Ron Karr. Without the | |
222 | experience of running and working on the Smail 3 code, I could never have | |
223 | contemplated starting to write a new MTA. Many of the ideas and user interfaces | |
224 | were originally taken from Smail 3, though the actual code of Exim is entirely | |
225 | new, and has developed far beyond the initial concept. | |
226 | ||
227 | Many people, both in Cambridge and around the world, have contributed to the | |
228 | development and the testing of Exim, and to porting it to various operating | |
229 | systems. I am grateful to them all. The distribution now contains a file called | |
230 | _ACKNOWLEDGMENTS_, in which I have started recording the names of | |
231 | contributors. | |
232 | ||
233 | ||
234 | ||
235 | Exim documentation | |
236 | ~~~~~~~~~~~~~~~~~~ | |
237 | [revisionflag="changed"] | |
238 | cindex:[documentation] | |
239 | This edition of the Exim specification applies to version {version} of Exim. | |
240 | Substantive changes from the {previousversion} edition are marked in some | |
241 | renditions of the document; this paragraph is so marked if the rendition is | |
242 | capable of showing a change indicator. | |
243 | ||
244 | This document is very much a reference manual; it is not a tutorial. The reader | |
245 | is expected to have some familiarity with the SMTP mail transfer protocol and | |
246 | with general Unix system administration. Although there are some discussions | |
247 | and examples in places, the information is mostly organized in a way that makes | |
248 | it easy to look up, rather than in a natural order for sequential reading. | |
249 | Furthermore, the manual aims to cover every aspect of Exim in detail, including | |
250 | a number of rarely-used, special-purpose features that are unlikely to be of | |
251 | very wide interest. | |
252 | ||
253 | cindex:[books about Exim] | |
254 | An ``easier'' discussion of Exim which provides more in-depth explanatory, | |
255 | introductory, and tutorial material can be found in a book entitled | |
256 | 'The Exim SMTP Mail Server', published by UIT Cambridge | |
257 | (*http://www.uit.co.uk/exim-book/[]*). | |
258 | ||
259 | This book also contains a chapter that gives a general introduction to SMTP and | |
260 | Internet mail. Inevitably, however, the book is unlikely to be fully up-to-date | |
261 | with the latest release of Exim. (Note that the earlier book about Exim, | |
262 | published by O'Reilly, covers Exim 3, and many things have changed in Exim 4.) | |
263 | ||
068aaea8 PH |
264 | [revisionflag="changed"] |
265 | cindex:[Debian,information sources] | |
266 | If you are using a Debian distribution of Exim, you will find information about | |
267 | Debian-specific features in the file | |
268 | &&&& | |
269 | _/usr/share/doc/exim4-base/README.Debian_ | |
270 | &&&& | |
271 | The command ^man update-exim.conf^ is another source of Debian-specific | |
272 | information. | |
273 | ||
168e428f PH |
274 | cindex:[_doc/NewStuff_] |
275 | cindex:[_doc/ChangeLog_] | |
276 | cindex:[change log] | |
277 | As the program develops, there may be features in newer versions that have not | |
278 | yet made it into this document, which is updated only when the most significant | |
279 | digit of the fractional part of the version number changes. Specifications of | |
280 | new features that are not yet in this manual are placed in the file | |
281 | _doc/NewStuff_ in the Exim distribution. | |
282 | ||
283 | Some features may be classified as ``experimental''. These may change | |
284 | incompatibly while they are developing, or even be withdrawn. For this reason, | |
285 | they are not documented in this manual. Information about experimental features | |
286 | can be found in the file _doc/experimental.txt_. | |
287 | ||
288 | All changes to the program (whether new features, bug fixes, or other kinds of | |
289 | change) are noted briefly in the file called _doc/ChangeLog_. | |
290 | ||
291 | cindex:[_doc/spec.txt_] | |
292 | This specification itself is available as an ASCII file in _doc/spec.txt_ so | |
293 | that it can easily be searched with a text editor. Other files in the _doc_ | |
294 | directory are: | |
295 | ||
296 | [frame="none"] | |
297 | `--------------------`------------------------------------------ | |
298 | _OptionLists.txt_ list of all options in alphabetical order | |
299 | _dbm.discuss.txt_ discussion about DBM libraries | |
300 | _exim.8_ a man page of Exim's command line options | |
301 | _experimental.txt_ documentation of experimental features | |
302 | _filter.txt_ specification of the filter language | |
303 | _pcrepattern.txt_ specification of PCRE regular expressions | |
304 | _pcretest.txt_ specification of the PCRE testing program | |
305 | _Exim3.upgrade_ upgrade notes from release 2 to release 3 | |
306 | _Exim4.upgrade_ upgrade notes from release 3 to release 4 | |
307 | ---------------------------------------------------------------- | |
308 | ||
309 | The main specification and the specification of the filtering language are also | |
310 | available in other formats (HTML, PostScript, PDF, and Texinfo). Section | |
311 | <<SECTavail>> below tells you how to get hold of these. | |
312 | ||
313 | ||
314 | ||
315 | FTP and web sites | |
316 | ~~~~~~~~~~~~~~~~~ | |
317 | cindex:[web site] | |
318 | cindex:[FTP site] | |
068aaea8 | 319 | The primary site for Exim source distributions is currently the University of |
168e428f PH |
320 | Cambridge's FTP site, whose contents are described in 'Where to find the Exim |
321 | distribution' below. In addition, there is a web site and an FTP site at | |
322 | %exim.org%. These are now also hosted at the University of Cambridge. The | |
323 | %exim.org% site was previously hosted for a number of years by Energis Squared, | |
324 | formerly Planet Online Ltd, whose support I gratefully acknowledge. | |
325 | ||
326 | As well as Exim distribution tar files, the Exim web site contains a number of | |
327 | differently formatted versions of the documentation, including the | |
328 | cindex:[FAQ] FAQ in both text and HTML formats. The HTML version comes with | |
329 | a keyword-in-context index. A recent addition to the online information is the | |
330 | cindex:[wiki] | |
331 | Exim wiki (*http://www.exim.org/eximwiki/[]*). | |
332 | We hope that this will make it easier for Exim users to contribute examples, | |
333 | tips, and know-how for the benefit of others. | |
334 | ||
335 | ||
336 | ||
337 | Mailing lists | |
338 | ~~~~~~~~~~~~~ | |
339 | cindex:[mailing lists,for Exim users] | |
340 | The following are the three main Exim mailing lists: | |
341 | ||
342 | [frame="none"] | |
343 | `-------------------------------`---------------------------------------- | |
344 | 'exim-users@exim.org' general discussion list | |
345 | 'exim-dev@exim.org' discussion of bugs, enhancements, etc. | |
346 | 'exim-announce@exim.org' moderated, low volume announcements list | |
347 | ------------------------------------------------------------------------- | |
348 | ||
349 | You can subscribe to these lists, change your existing subscriptions, and view | |
350 | or search the archives via the mailing lists link on the Exim home page. The | |
351 | 'exim-users' mailing list is also forwarded to | |
352 | *http://www.egroups.com/list/exim-users[]*, an archiving system with searching | |
353 | capabilities. | |
354 | ||
068aaea8 PH |
355 | [revisionflag="changed"] |
356 | cindex:[Debian,mailing list for] | |
357 | If you are using a Debian distribution of Exim, you may wish to subscribe to | |
358 | the Debian-specific mailing list, which is | |
359 | 'pkg-exim4-users@lists.alioth.debian.org'. | |
360 | ||
168e428f PH |
361 | |
362 | Exim training | |
363 | ~~~~~~~~~~~~~ | |
364 | cindex:[training courses] | |
068aaea8 PH |
365 | From time to time (approximately annually at the time of writing), training |
366 | courses are run by the author of Exim in Cambridge, UK. Details can be found on | |
367 | the web site *http://www-tus.csx.cam.ac.uk/courses/exim/[]*. | |
168e428f PH |
368 | |
369 | ||
370 | Bug reports | |
371 | ~~~~~~~~~~~ | |
372 | cindex:[bug reports] | |
373 | cindex:[reporting bugs] | |
374 | Reports of obvious bugs should be emailed to 'bugs@exim.org'. However, if | |
375 | you are unsure whether some behaviour is a bug or not, the best thing to do is | |
068aaea8 | 376 | to post a message to the 'exim-dev' mailing list and have it discussed. |
168e428f PH |
377 | |
378 | ||
379 | ||
380 | [[SECTavail]] | |
381 | Where to find the Exim distribution | |
382 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
383 | cindex:[FTP site] | |
384 | cindex:[distribution,ftp site] | |
385 | The master ftp site for the Exim distribution is | |
386 | ||
387 | &&& | |
388 | *ftp://ftp.csx.cam.ac.uk/pub/software/email/exim[]* | |
389 | &&& | |
390 | ||
391 | This is mirrored by | |
392 | ||
393 | &&& | |
394 | *ftp://ftp.exim.org/pub/exim[]* | |
395 | &&& | |
396 | ||
397 | The file references that follow are relative to the _exim_ directories at these | |
398 | sites. There are now quite a number of independent mirror sites around the | |
399 | world. Those that I know about are listed in the file called _Mirrors_. | |
400 | ||
401 | Within the _exim_ directory there are subdirectories called _exim3_ (for | |
402 | previous Exim 3 distributions), _exim4_ (for the latest Exim 4 | |
403 | distributions), and _Testing_ for testing versions. In the _exim4_ | |
404 | subdirectory, the current release can always be found in files called | |
405 | ||
406 | &&& | |
407 | _exim-n.nn.tar.gz_ | |
408 | _exim-n.nn.tar.bz2_ | |
409 | &&& | |
410 | ||
411 | where 'n.nn' is the highest such version number in the directory. The two | |
412 | files contain identical data; the only difference is the type of compression. | |
413 | The _.bz2_ file is usually a lot smaller than the _.gz_ file. | |
414 | ||
415 | cindex:[distribution,signing details] | |
416 | cindex:[distribution,public key] | |
417 | cindex:[public key for signed distribution] | |
418 | The distributions are currently signed with Philip Hazel's GPG key. The | |
419 | corresponding public key is available from a number of keyservers, and there is | |
420 | also a copy in the file _Public-Key_. The signatures for the tar bundles are | |
421 | in: | |
422 | ||
423 | &&& | |
424 | _exim-n.nn.tar.gz.sig_ | |
425 | _exim-n.nn.tar.bz2.sig_ | |
426 | &&& | |
427 | ||
428 | For each released version, the log of changes is made separately available in a | |
429 | separate file in the directory _ChangeLogs_ so that it is possible to | |
430 | find out what has changed without having to download the entire distribution. | |
431 | ||
432 | cindex:[documentation,available formats] | |
433 | The main distribution contains ASCII versions of this specification and other | |
434 | documentation; other formats of the documents are available in separate files | |
435 | inside the _exim4_ directory of the FTP site: | |
436 | ||
437 | &&& | |
438 | _exim-html-n.nn.tar.gz_ | |
439 | _exim-pdf-n.nn.tar.gz_ | |
440 | _exim-postscript-n.nn.tar.gz_ | |
441 | _exim-texinfo-n.nn.tar.gz_ | |
442 | &&& | |
443 | ||
444 | These tar files contain only the _doc_ directory, not the complete | |
445 | distribution, and are also available in _.bz2_ as well as _.gz_ forms. | |
446 | cindex:[FAQ] | |
447 | The FAQ is available for downloading in two different formats in these files: | |
448 | ||
449 | &&& | |
450 | _exim4/FAQ.txt.gz_ | |
451 | _exim4/FAQ.html.tar.gz_ | |
452 | &&& | |
453 | ||
454 | The first of these is a single ASCII file that can be searched with a text | |
455 | editor. The second is a directory of HTML files, normally accessed by starting | |
456 | at _index.html_. The HTML version of the FAQ (which is also included in the | |
457 | HTML documentation tarbundle) includes a keyword-in-context index, which is | |
458 | often the most convenient way of finding your way around. | |
459 | ||
460 | ||
461 | Wish list | |
462 | ~~~~~~~~~ | |
463 | cindex:[wish list] | |
464 | A wish list is maintained, containing ideas for new features that have been | |
465 | submitted. From time to time the file is exported to the ftp site into the file | |
466 | _exim4/WishList_. Items are removed from the list if they get implemented. | |
467 | ||
468 | ||
469 | ||
470 | Contributed material | |
471 | ~~~~~~~~~~~~~~~~~~~~ | |
472 | cindex:[contributed material] | |
473 | At the ftp site, there is a directory called _Contrib_ that contains | |
474 | miscellaneous files contributed to the Exim community by Exim users. There is | |
475 | also a collection of contributed configuration examples in | |
476 | _exim4/config.samples.tar.gz_. These samples are referenced from the FAQ. | |
477 | ||
478 | ||
479 | ||
480 | Limitations | |
481 | ~~~~~~~~~~~ | |
482 | - cindex:[limitations of Exim] | |
483 | Exim is designed for use as an Internet MTA, and therefore handles addresses | |
484 | in RFC 2822 domain format only. | |
485 | cindex:[bang paths,not handled by Exim] | |
486 | It cannot handle UUCP ``bang paths'', though simple two-component bang paths can | |
487 | be converted by a straightforward rewriting configuration. This restriction | |
488 | does not prevent Exim from being interfaced to UUCP as a transport mechanism, | |
489 | provided that domain addresses are used. | |
490 | ||
491 | - cindex:[domainless addresses] | |
492 | cindex:[address,without domain] | |
493 | Exim insists that every address it handles has a domain attached. For incoming | |
494 | local messages, domainless addresses are automatically qualified with a | |
495 | configured domain value. Configuration options specify from which remote | |
496 | systems unqualified addresses are acceptable. These are then qualified on | |
497 | arrival. | |
498 | ||
499 | - cindex:[transport,external] | |
500 | cindex:[external transports] | |
501 | The only external transport currently implemented is an SMTP transport over a | |
502 | TCP/IP network (using sockets, including support for IPv6). However, a pipe | |
503 | transport is available, and there are facilities for writing messages to files | |
504 | and pipes, optionally in 'batched SMTP' format; these facilities can be used | |
505 | to send messages to some other transport mechanism such as UUCP, provided it | |
506 | can handle domain-style addresses. Batched SMTP input is also catered for. | |
507 | ||
508 | - Exim is not designed for storing mail for dial-in hosts. When the volumes of | |
509 | such mail are large, it is better to get the messages ``delivered'' into files | |
510 | (that is, off Exim's queue) and subsequently passed on to the dial-in hosts by | |
511 | other means. | |
512 | ||
513 | - Although Exim does have basic facilities for scanning incoming messages, these | |
514 | are not comprehensive enough to do full virus or spam scanning. Such operations | |
515 | are best carried out using additional specialized software packages. If you | |
516 | compile Exim with the content-scanning extension, straightforward interfaces to | |
517 | a number of common scanners are provided. | |
518 | ||
519 | ||
520 | ||
521 | ||
522 | ||
523 | Run time configuration | |
524 | ~~~~~~~~~~~~~~~~~~~~~~ | |
525 | Exim's run time configuration is held in a single text file that is divided | |
526 | into a number of sections. The entries in this file consist of keywords and | |
527 | values, in the style of Smail 3 configuration files. A default configuration | |
528 | file which is suitable for simple online installations is provided in the | |
529 | distribution, and is described in chapter <<CHAPdefconfil>> below. | |
530 | ||
531 | ||
532 | ||
533 | Calling interface | |
534 | ~~~~~~~~~~~~~~~~~ | |
535 | cindex:[Sendmail compatibility,command line interface] | |
536 | Like many MTAs, Exim has adopted the Sendmail command line interface so that it | |
537 | can be a straight replacement for _/usr/lib/sendmail_ or | |
538 | _/usr/sbin/sendmail_ when sending mail, but you do not need to know anything | |
539 | about Sendmail in order to run Exim. For actions other than sending messages, | |
540 | Sendmail-compatible options also exist, but those that produce output (for | |
541 | example, %-bp%, which lists the messages on the queue) do so in Exim's own | |
542 | format. There are also some additional options that are compatible with Smail | |
543 | 3, and some further options that are new to Exim. Chapter <<CHAPcommandline>> | |
544 | documents all Exim's command line options. This information is automatically | |
545 | made into the man page that forms part of the Exim distribution. | |
546 | ||
547 | Control of messages on the queue can be done via certain privileged command | |
548 | line options. There is also an optional monitor program called 'eximon', which | |
549 | displays current information in an X window, and which contains a menu | |
550 | interface to Exim's command line administration options. | |
551 | ||
552 | ||
553 | ||
554 | Terminology | |
555 | ~~~~~~~~~~~ | |
556 | cindex:[terminology definitions] | |
557 | cindex:[body of message,definition of] | |
558 | The 'body' of a message is the actual data that the sender wants to transmit. | |
559 | It is the last part of a message, and is separated from the 'header' (see | |
560 | below) by a blank line. | |
561 | ||
562 | cindex:[bounce message,definition of] | |
563 | When a message cannot be delivered, it is normally returned to the sender in a | |
564 | delivery failure message or a ``non-delivery report'' (NDR). The term 'bounce' | |
565 | is commonly used for this action, and the error reports are often called | |
566 | 'bounce messages'. This is a convenient shorthand for ``delivery failure error | |
567 | report''. Such messages have an empty sender address in the message's | |
568 | 'envelope' (see below) to ensure that they cannot themselves give rise to | |
569 | further bounce messages. | |
570 | ||
571 | The term 'default' appears frequently in this manual. It is used to qualify a | |
572 | value which is used in the absence of any setting in the configuration. It may | |
573 | also qualify an action which is taken unless a configuration setting specifies | |
574 | otherwise. | |
575 | ||
576 | The term 'defer' is used when the delivery of a message to a specific | |
577 | destination cannot immediately take place for some reason (a remote host may be | |
578 | down, or a user's local mailbox may be full). Such deliveries are 'deferred' | |
579 | until a later time. | |
580 | ||
581 | The word 'domain' is sometimes used to mean all but the first component of a | |
582 | host's name. It is 'not' used in that sense here, where it normally | |
583 | refers to the part of an email address following the @ sign. | |
584 | ||
585 | cindex:[envelope, definition of] | |
586 | cindex:[sender,definition of] | |
587 | A message in transit has an associated 'envelope', as well as a header and a | |
588 | body. The envelope contains a sender address (to which bounce messages should | |
589 | be delivered), and any number of recipient addresses. References to the | |
590 | sender or the recipients of a message usually mean the addresses in the | |
591 | envelope. An MTA uses these addresses for delivery, and for returning bounce | |
592 | messages, not the addresses that appear in the header lines. | |
593 | ||
594 | cindex:[message header, definition of] | |
595 | cindex:[header section,definition of] | |
596 | The 'header' of a message is the first part of a message's text, consisting | |
597 | of a number of lines, each of which has a name such as 'From:', 'To:', | |
598 | 'Subject:', etc. Long header lines can be split over several text lines by | |
599 | indenting the continuations. The header is separated from the body by a blank | |
600 | line. | |
601 | ||
602 | cindex:[local part,definition of] | |
603 | cindex:[domain,definition of] | |
604 | The term 'local part', which is taken from RFC 2822, is used to refer to that | |
605 | part of an email address that precedes the @ sign. The part that follows the | |
606 | @ sign is called the 'domain' or 'mail domain'. | |
607 | ||
608 | cindex:[local delivery,definition of] | |
609 | cindex:[remote delivery, definition of] | |
610 | The terms 'local delivery' and 'remote delivery' are used to distinguish | |
611 | delivery to a file or a pipe on the local host from delivery by SMTP over | |
068aaea8 PH |
612 | TCP/IP to another host. As far as Exim is concerned, all hosts other than the |
613 | host it is running on are 'remote'. | |
168e428f PH |
614 | |
615 | cindex:[return path,definition of] | |
616 | 'Return path' is another name that is used for the sender address in a | |
617 | message's envelope. | |
618 | ||
619 | cindex:[queue,definition of] | |
620 | The term 'queue' is used to refer to the set of messages awaiting delivery, | |
621 | because this term is in widespread use in the context of MTAs. However, in | |
622 | Exim's case the reality is more like a pool than a queue, because there is | |
623 | normally no ordering of waiting messages. | |
624 | ||
625 | cindex:[queue runner,definition of] | |
626 | The term 'queue runner' is used to describe a process that scans the queue | |
627 | and attempts to deliver those messages whose retry times have come. This term | |
628 | is used by other MTAs, and also relates to the command %runq%, but in Exim | |
629 | the waiting messages are normally processed in an unpredictable order. | |
630 | ||
631 | cindex:[spool directory,definition of] | |
632 | The term 'spool directory' is used for a directory in which Exim keeps the | |
633 | messages on its queue -- that is, those that it is in the process of | |
634 | delivering. This should not be confused with the directory in which local | |
635 | mailboxes are stored, which is called a ``spool directory'' by some people. In | |
636 | the Exim documentation, ``spool'' is always used in the first sense. | |
637 | ||
638 | ||
639 | ||
640 | ||
641 | ||
642 | ||
643 | //////////////////////////////////////////////////////////////////////////// | |
644 | //////////////////////////////////////////////////////////////////////////// | |
645 | ||
646 | Incorporated code | |
647 | ----------------- | |
648 | cindex:[incorporated code] | |
649 | cindex:[regular expressions,library] | |
650 | cindex:[PCRE] | |
651 | A number of pieces of external code are included in the Exim distribution. | |
652 | ||
653 | - Regular expressions are supported in the main Exim program and in the Exim | |
654 | monitor using the freely-distributable PCRE library, copyright (c) University | |
655 | of Cambridge. The source is distributed in the directory _src/pcre_. However, | |
656 | this is a cut-down version of PCRE. If you want to use the PCRE library in | |
657 | other programs, you should obtain and install the full version from | |
658 | *ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre[]*. | |
659 | ||
660 | - cindex:[cdb,acknowledgement] | |
661 | Support for the cdb (Constant DataBase) lookup method is provided by code | |
662 | contributed by Nigel Metheringham of (at the time he contributed it) Planet | |
663 | Online Ltd. which contains the following statements: | |
664 | + | |
068aaea8 PH |
665 | ++++++++++++++++++++++ |
666 | <blockquote> | |
667 | ++++++++++++++++++++++ | |
668 | + | |
168e428f PH |
669 | Copyright (c) 1998 Nigel Metheringham, Planet Online Ltd |
670 | + | |
671 | This program is free software; you can redistribute it and/or modify it under | |
672 | the terms of the GNU General Public License as published by the Free Software | |
673 | Foundation; either version 2 of the License, or (at your option) any later | |
674 | version. | |
675 | + | |
676 | This code implements Dan Bernstein's Constant DataBase (cdb) spec. Information, | |
677 | the spec and sample code for cdb can be obtained from | |
678 | *http://www.pobox.com/{tl}djb/cdb.html[]*. This implementation borrows some code | |
679 | from Dan Bernstein's implementation (which has no license restrictions applied | |
680 | to it). | |
681 | + | |
068aaea8 PH |
682 | ++++++++++++++++++++++ |
683 | </blockquote> | |
684 | ++++++++++++++++++++++ | |
685 | + | |
168e428f PH |
686 | The implementation is completely contained within the code of Exim. |
687 | It does not link against an external cdb library. | |
688 | ||
689 | - cindex:[SPA authentication] | |
690 | cindex:[Samba project] | |
691 | cindex:[Microsoft Secure Password Authentication] | |
692 | Client support for Microsoft's 'Secure Password Authentication' is provided | |
693 | by code contributed by Marc Prud'hommeaux. Server support was contributed by | |
694 | Tom Kistner. This includes code taken from the Samba project, which is released | |
695 | under the Gnu GPL. | |
696 | ||
697 | - cindex:[Cyrus] | |
698 | cindex:['pwcheck' daemon] | |
699 | cindex:['pwauthd' daemon] | |
700 | Support for calling the Cyrus 'pwcheck' and 'saslauthd' daemons is provided | |
701 | by code taken from the Cyrus-SASL library and adapted by Alexander S. | |
702 | Sabourenkov. The permission notice appears below, in accordance with the | |
703 | conditions expressed therein. | |
704 | + | |
068aaea8 PH |
705 | ++++++++++++++++++++++ |
706 | <blockquote> | |
707 | ++++++++++++++++++++++ | |
708 | + | |
168e428f PH |
709 | Copyright (c) 2001 Carnegie Mellon University. All rights reserved. |
710 | + | |
711 | Redistribution and use in source and binary forms, with or without | |
712 | modification, are permitted provided that the following conditions | |
713 | are met: | |
714 | + | |
715 | . Redistributions of source code must retain the above copyright | |
716 | notice, this list of conditions and the following disclaimer. | |
717 | ||
718 | . Redistributions in binary form must reproduce the above copyright | |
719 | notice, this list of conditions and the following disclaimer in | |
720 | the documentation and/or other materials provided with the | |
721 | distribution. | |
722 | ||
723 | . The name ``Carnegie Mellon University'' must not be used to | |
724 | endorse or promote products derived from this software without | |
725 | prior written permission. For permission or any other legal | |
726 | details, please contact | |
727 | + | |
728 | &&& | |
068aaea8 PH |
729 | Office of Technology Transfer |
730 | Carnegie Mellon University | |
731 | 5000 Forbes Avenue | |
732 | Pittsburgh, PA 15213-3890 | |
733 | (412) 268-4387, fax: (412) 268-7395 | |
734 | tech-transfer@andrew.cmu.edu | |
168e428f | 735 | &&& |
068aaea8 PH |
736 | /// |
737 | The need to indent that block explicitly is a pain. | |
738 | /// | |
168e428f PH |
739 | |
740 | . Redistributions of any form whatsoever must retain the following | |
741 | acknowledgment: | |
742 | + | |
068aaea8 PH |
743 | ``This product includes software developed by Computing Services |
744 | at Carnegie Mellon University (*http://www.cmu.edu/computing/[]*).'' | |
168e428f PH |
745 | + |
746 | CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO | |
747 | THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY | |
748 | AND FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE | |
749 | FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | |
750 | WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN | |
751 | AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING | |
752 | OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | |
753 | ||
068aaea8 PH |
754 | /// |
755 | Note, no "+" line there, because we want to terminate the inner list item | |
756 | before ending the block quote. | |
757 | /// | |
758 | + | |
759 | ++++++++++++++++++++++ | |
760 | </blockquote> | |
761 | ++++++++++++++++++++++ | |
762 | ||
763 | - cindex:[Exim monitor,acknowledgement] | |
168e428f PH |
764 | cindex:[X-windows] |
765 | cindex:[Athena] | |
766 | The Exim Monitor program, which is an X-Window application, includes | |
767 | modified versions of the Athena StripChart and TextPop widgets. | |
768 | This code is copyright by DEC and MIT, and their permission notice appears | |
769 | below, in accordance with the conditions expressed therein. | |
770 | + | |
068aaea8 PH |
771 | ++++++++++++++++++++++ |
772 | <blockquote> | |
773 | ++++++++++++++++++++++ | |
774 | + | |
168e428f PH |
775 | Copyright 1987, 1988 by Digital Equipment Corporation, Maynard, Massachusetts, |
776 | and the Massachusetts Institute of Technology, Cambridge, Massachusetts. | |
777 | + | |
778 | All Rights Reserved | |
779 | + | |
780 | Permission to use, copy, modify, and distribute this software and its | |
781 | documentation for any purpose and without fee is hereby granted, | |
782 | provided that the above copyright notice appear in all copies and that | |
783 | both that copyright notice and this permission notice appear in | |
784 | supporting documentation, and that the names of Digital or MIT not be | |
785 | used in advertising or publicity pertaining to distribution of the | |
786 | software without specific, written prior permission. | |
787 | + | |
788 | DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING | |
789 | ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL | |
790 | DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR | |
791 | ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, | |
792 | WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, | |
793 | ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS | |
794 | SOFTWARE. | |
068aaea8 PH |
795 | + |
796 | ++++++++++++++++++++++ | |
797 | </blockquote> | |
798 | ++++++++++++++++++++++ | |
168e428f | 799 | |
068aaea8 | 800 | - Many people have contributed code fragments, some large, some small, that were |
168e428f PH |
801 | not covered by any specific licence requirements. It is assumed that the |
802 | contributors are happy to see their code incoporated into Exim under the GPL. | |
803 | ||
804 | ||
805 | ||
806 | ||
807 | ||
808 | //////////////////////////////////////////////////////////////////////////// | |
809 | //////////////////////////////////////////////////////////////////////////// | |
810 | ||
811 | [titleabbrev="Receiving and delivering mail"] | |
812 | How Exim receives and delivers mail | |
813 | ----------------------------------- | |
814 | ||
815 | ||
816 | Overall philosophy | |
817 | ~~~~~~~~~~~~~~~~~~ | |
818 | cindex:[design philosophy] | |
819 | Exim is designed to work efficiently on systems that are permanently connected | |
820 | to the Internet and are handling a general mix of mail. In such circumstances, | |
821 | most messages can be delivered immediately. Consequently, Exim does not | |
822 | maintain independent queues of messages for specific domains or hosts, though | |
823 | it does try to send several messages in a single SMTP connection after a host | |
824 | has been down, and it also maintains per-host retry information. | |
825 | ||
826 | ||
827 | ||
828 | Policy control | |
829 | ~~~~~~~~~~~~~~ | |
830 | cindex:[policy control,overview] | |
831 | Policy controls are now an important feature of MTAs that are connected to the | |
832 | Internet. Perhaps their most important job is to stop MTAs being abused as | |
833 | ``open relays'' by misguided individuals who send out vast amounts of unsolicited | |
834 | junk, and want to disguise its source. Exim provides flexible facilities for | |
835 | specifying policy controls on incoming mail: | |
836 | ||
837 | - cindex:[{ACL},introduction] | |
838 | Exim 4 (unlike previous versions of Exim) implements policy controls on | |
839 | incoming mail by means of 'Access Control Lists' (ACLs). Each list is a | |
840 | series of statements that may either grant or deny access. ACLs can be used at | |
841 | several places in the SMTP dialogue while receiving a message from a remote | |
842 | host. However, the most common places are after each RCPT command, and at | |
843 | the very end of the message. The sysadmin can specify conditions for accepting | |
844 | or rejecting individual recipients or the entire message, respectively, at | |
845 | these two points (see chapter <<CHAPACL>>). Denial of access results in an SMTP | |
846 | error code. | |
847 | ||
848 | - An ACL is also available for locally generated, non-SMTP messages. In this | |
849 | case, the only available actions are to accept or deny the entire message. | |
850 | ||
851 | - When Exim is compiled with the content-scanning extension, facilities are | |
852 | provided in the ACL mechanism for passing the message to external virus and/or | |
853 | spam scanning software. The result of such a scan is passed back to the ACL, | |
854 | which can then use it to decide what to do with the message. | |
855 | ||
856 | - When a message has been received, either from a remote host or from the local | |
857 | host, but before the final acknowledgement has been sent, a locally supplied C | |
858 | function called 'local_scan()' can be run to inspect the message and decide | |
859 | whether to accept it or not (see chapter <<CHAPlocalscan>>). If the message is | |
860 | accepted, the list of recipients can be modified by the function. | |
861 | ||
862 | - Using the 'local_scan()' mechanism is another way of calling external | |
863 | scanner software. The %SA-Exim% add-on package works this way. It does not | |
864 | require Exim to be compiled with the content-scanning extension. | |
865 | ||
866 | - After a message has been accepted, a further checking mechanism is available in | |
867 | the form of the 'system filter' (see chapter <<CHAPsystemfilter>>). This runs | |
868 | at the start of every delivery process. | |
869 | ||
870 | ||
871 | ||
872 | User filters | |
873 | ~~~~~~~~~~~~ | |
874 | cindex:[filter,introduction] | |
875 | cindex:[Sieve filter] | |
876 | In a conventional Exim configuration, users are able to run private filters by | |
877 | setting up appropriate _.forward_ files in their home directories. See | |
878 | chapter <<CHAPredirect>> (about the ^redirect^ router) for the configuration | |
879 | needed to support this, and the separate document entitled 'Exim's interfaces | |
880 | to mail filtering' for user details. Two different kinds of filtering are | |
881 | available: | |
882 | ||
883 | - Sieve filters are written in the standard filtering language that is defined | |
884 | by RFC 3028. | |
885 | ||
886 | - Exim filters are written in a syntax that is unique to Exim, but which is more | |
887 | powerful than Sieve, which it pre-dates. | |
888 | ||
889 | User filters are run as part of the routing process, described below. | |
890 | ||
891 | ||
892 | ||
893 | [[SECTmessiden]] | |
894 | Message identification | |
895 | ~~~~~~~~~~~~~~~~~~~~~~ | |
896 | cindex:[message ids, details of format] | |
897 | cindex:[format,of message id] | |
898 | cindex:[id of message] | |
899 | cindex:[base62] | |
900 | cindex:[base36] | |
901 | cindex:[Darwin] | |
902 | cindex:[Cygwin] | |
903 | Every message handled by Exim is given a 'message id' which is sixteen | |
904 | characters long. It is divided into three parts, separated by hyphens, for | |
905 | example `16VDhn-0001bo-D3`. Each part is a sequence of letters and digits, | |
906 | normally encoding numbers in base 62. However, in the Darwin operating | |
907 | system (Mac OS X) and when Exim is compiled to run under Cygwin, base 36 | |
908 | (avoiding the use of lower case letters) is used instead, because the message | |
909 | id is used to construct file names, and the names of files in those systems are | |
068aaea8 | 910 | not always case-sensitive. |
168e428f PH |
911 | |
912 | cindex:[pid (process id),re-use of] | |
913 | The detail of the contents of the message id have changed as Exim has evolved. | |
914 | Earlier versions relied on the operating system not re-using a process id (pid) | |
915 | within one second. On modern operating systems, this assumption can no longer | |
916 | be made, so the algorithm had to be changed. To retain backward compatibility, | |
917 | the format of the message id was retained, which is why the following rules are | |
918 | somewhat eccentric: | |
919 | ||
920 | - The first six characters of the message id are the time at which the message | |
921 | started to be received, to a granularity of one second. That is, this field | |
922 | contains the number of seconds since the start of the epoch (the normal Unix | |
923 | way of representing the date and time of day). | |
924 | ||
925 | - After the first hyphen, the next six characters are the id of the process that | |
926 | received the message. | |
927 | ||
928 | - There are two different possibilities for the final two characters: | |
929 | ||
930 | . cindex:[%localhost_number%] | |
931 | If %localhost_number% is not set, this value is the fractional part of the | |
932 | time of reception, normally in units of 1/2000 of a second, but for systems | |
933 | that must use base 36 instead of base 62 (because of case-insensitive file | |
934 | systems), the units are 1/1000 of a second. | |
935 | ||
936 | . If %localhost_number% is set, it is multiplied by 200 (100) and added to | |
937 | the fractional part of the time, which in this case is in units of 1/200 | |
938 | (1/100) of a second. | |
939 | ||
940 | After a message has been received, Exim waits for the clock to tick at the | |
941 | appropriate resolution before proceeding, so that if another message is | |
942 | received by the same process, or by another process with the same (re-used) | |
943 | pid, it is guaranteed that the time will be different. In most cases, the clock | |
944 | will already have ticked while the message was being received. | |
945 | ||
946 | ||
947 | Receiving mail | |
948 | ~~~~~~~~~~~~~~ | |
949 | cindex:[receiving mail] | |
950 | cindex:[message,reception] | |
068aaea8 PH |
951 | The only way Exim can receive mail from another host is using SMTP over |
952 | TCP/IP, in which case the sender and recipient addresses are transferred using | |
168e428f PH |
953 | SMTP commands. However, from a locally running process (such as a user's MUA), |
954 | there are several possibilities: | |
955 | ||
956 | - If the process runs Exim with the %-bm% option, the message is read | |
957 | non-interactively (usually via a pipe), with the recipients taken from the | |
958 | command line, or from the body of the message if %-t% is also used. | |
959 | ||
960 | - If the process runs Exim with the %-bS% option, the message is also read | |
961 | non-interactively, but in this case the recipients are listed at the start of | |
962 | the message in a series of SMTP RCPT commands, terminated by a DATA | |
963 | command. This is so-called ``batch SMTP'' format, | |
964 | but it isn't really SMTP. The SMTP commands are just another way of passing | |
965 | envelope addresses in a non-interactive submission. | |
966 | ||
967 | - If the process runs Exim with the %-bs% option, the message is read | |
968 | interactively, using the SMTP protocol. A two-way pipe is normally used for | |
969 | passing data between the local process and the Exim process. | |
970 | This is ``real'' SMTP and is handled in the same way as SMTP over TCP/IP. For | |
971 | example, the ACLs for SMTP commands are used for this form of submission. | |
972 | ||
973 | - A local process may also make a TCP/IP call to the host's loopback address | |
974 | (127.0.0.1) or any other of its IP addresses. When receiving messages, Exim | |
975 | does not treat the loopback address specially. It treats all such connections | |
976 | in the same way as connections from other hosts. | |
977 | ||
978 | ||
979 | cindex:[message sender, constructed by Exim] | |
980 | cindex:[sender,constructed by Exim] | |
981 | In the three cases that do not involve TCP/IP, the sender address is | |
982 | constructed from the login name of the user that called Exim and a default | |
983 | qualification domain (which can be set by the %qualify_domain% configuration | |
984 | option). For local or batch SMTP, a sender address that is passed using the | |
985 | SMTP MAIL command is ignored. However, the system administrator may allow | |
986 | certain users (``trusted users'') to specify a different sender address | |
987 | unconditionally, or all users to specify certain forms of different sender | |
988 | address. The %-f% option or the SMTP MAIL command is used to specify these | |
989 | different addresses. See section <<SECTtrustedadmin>> for details of trusted | |
990 | users, and the %untrusted_set_sender% option for a way of allowing untrusted | |
991 | users to change sender addresses. | |
992 | ||
993 | Messages received by either of the non-interactive mechanisms are subject to | |
994 | checking by the non-SMTP ACL, if one is defined. Messages received using SMTP | |
995 | (either over TCP/IP, or interacting with a local process) can be checked by a | |
996 | number of ACLs that operate at different times during the SMTP session. Either | |
997 | individual recipients, or the entire message, can be rejected if local policy | |
998 | requirements are not met. The 'local_scan()' function (see chapter | |
999 | <<CHAPlocalscan>>) is run for all incoming messages. | |
1000 | ||
1001 | Exim can be configured not to start a delivery process when a message is | |
1002 | received; this can be unconditional, or depend on the number of incoming SMTP | |
1003 | connections or the system load. In these situations, new messages wait on the | |
1004 | queue until a queue runner process picks them up. However, in standard | |
1005 | configurations under normal conditions, delivery is started as soon as a | |
1006 | message is received. | |
1007 | ||
1008 | ||
1009 | ||
1010 | ||
1011 | ||
1012 | Handling an incoming message | |
1013 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1014 | cindex:[spool directory,files that hold a message] | |
1015 | cindex:[file,how a message is held] | |
1016 | When Exim accepts a message, it writes two files in its spool directory. The | |
1017 | first contains the envelope information, the current status of the message, and | |
1018 | the header lines, and the second contains the body of the message. The names of | |
1019 | the two spool files consist of the message id, followed by `-H` for the | |
1020 | file containing the envelope and header, and `-D` for the data file. | |
1021 | ||
1022 | cindex:[spool directory,_input_ sub-directory] | |
1023 | By default all these message files are held in a single directory called | |
1024 | _input_ inside the general Exim spool directory. Some operating systems do | |
1025 | not perform very well if the number of files in a directory gets very large; to | |
1026 | improve performance in such cases, the %split_spool_directory% option can be | |
1027 | used. This causes Exim to split up the input files into 62 sub-directories | |
1028 | whose names are single letters or digits. | |
1029 | ||
1030 | The envelope information consists of the address of the message's sender and | |
1031 | the addresses of the recipients. This information is entirely separate from | |
1032 | any addresses contained in the header lines. The status of the message includes | |
1033 | a list of recipients who have already received the message. The format of the | |
1034 | first spool file is described in chapter <<CHAPspool>>. | |
1035 | ||
1036 | cindex:[rewriting,addresses] | |
1037 | Address rewriting that is specified in the rewrite section of the configuration | |
1038 | (see chapter <<CHAPrewrite>>) is done once and for all on incoming addresses, | |
1039 | both in the header lines and the envelope, at the time the message is accepted. | |
1040 | If during the course of delivery additional addresses are generated (for | |
1041 | example, via aliasing), these new addresses are rewritten as soon as they are | |
1042 | generated. At the time a message is actually delivered (transported) further | |
1043 | rewriting can take place; because this is a transport option, it can be | |
1044 | different for different forms of delivery. It is also possible to specify the | |
1045 | addition or removal of certain header lines at the time the message is | |
1046 | delivered (see chapters <<CHAProutergeneric>> and <<CHAPtransportgeneric>>). | |
1047 | ||
1048 | ||
1049 | ||
1050 | Life of a message | |
1051 | ~~~~~~~~~~~~~~~~~ | |
1052 | cindex:[message,life of] | |
1053 | cindex:[message,frozen] | |
1054 | A message remains in the spool directory until it is completely delivered to | |
1055 | its recipients or to an error address, or until it is deleted by an | |
1056 | administrator or by the user who originally created it. In cases when delivery | |
1057 | cannot proceed -- for example, when a message can neither be delivered to its | |
1058 | recipients nor returned to its sender, the message is marked ``frozen'' on the | |
1059 | spool, and no more deliveries are attempted. | |
1060 | ||
1061 | cindex:[frozen messages,thawing] | |
1062 | cindex:[message,thawing frozen] | |
1063 | An administrator can ``thaw'' such messages when the problem has been corrected, | |
1064 | and can also freeze individual messages by hand if necessary. In addition, an | |
1065 | administrator can force a delivery error, causing a bounce message to be sent. | |
1066 | ||
068aaea8 | 1067 | [revisionflag="changed"] |
168e428f | 1068 | cindex:[%timeout_frozen_after%] |
068aaea8 PH |
1069 | cindex:[%ignore_bounce_errors_after%] |
1070 | There are options called %ignore_bounce_errors_after% and | |
1071 | %timeout_frozen_after%, which discard frozen messages after a certain time. | |
1072 | The first applies only to frozen bounces, the second to any frozen messages. | |
168e428f PH |
1073 | |
1074 | cindex:[message,log file for] | |
1075 | cindex:[log,file for each message] | |
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 |
168e428f PH |
1078 | delayed deliveries for each recipient (see chapter <<CHAPlog>>). The log lines |
1079 | are also written to a separate 'message log' file for each message. These | |
1080 | logs are solely for the benefit of the administrator, and are normally deleted | |
1081 | along with the spool files when processing of a message is complete. | |
1082 | The use of individual message logs can be disabled by setting | |
1083 | %no_message_logs%; this might give an improvement in performance on very | |
1084 | busy systems. | |
1085 | ||
1086 | cindex:[journal file] | |
1087 | cindex:[file,journal] | |
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 | |
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) | |
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 | ||
1105 | [[SECTprocaddress]] | |
1106 | Processing an address for delivery | |
1107 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1108 | cindex:[drivers,definition of] | |
1109 | cindex:[router,definition of] | |
1110 | cindex:[transport,definition of] | |
1111 | The main delivery processing elements of Exim are called 'routers' and | |
1112 | 'transports', and collectively these are known as 'drivers'. Code for a | |
1113 | number of them is provided in the source distribution, and compile-time options | |
1114 | specify which ones are included in the binary. Run time options specify which | |
1115 | ones are actually used for delivering messages. | |
1116 | ||
1117 | cindex:[drivers,instance definition] | |
1118 | Each driver that is specified in the run time configuration is an 'instance' | |
1119 | of that particular driver type. Multiple instances are allowed; for example, | |
1120 | you can set up several different ^smtp^ transports, each with different | |
1121 | option values that might specify different ports or different timeouts. Each | |
1122 | instance has its own identifying name. In what follows we will normally use the | |
1123 | instance name when discussing one particular instance (that is, one specific | |
1124 | configuration of the driver), and the generic driver name when discussing | |
1125 | the driver's features in general. | |
1126 | ||
1127 | A 'router' is a driver that operates on an address, either determining how | |
068aaea8 | 1128 | its delivery should happen, by assigning it to a specific transport, or |
168e428f PH |
1129 | converting the address into one or more new addresses (for example, via an |
1130 | alias file). A router may also explicitly choose to fail an address, causing it | |
1131 | to be bounced. | |
1132 | ||
1133 | A 'transport' is a driver that transmits a copy of the message from Exim's | |
1134 | spool to some destination. There are two kinds of transport: for a 'local' | |
1135 | transport, the destination is a file or a pipe on the local host, whereas for a | |
1136 | 'remote' transport the destination is some other host. A message is passed | |
1137 | to a specific transport as a result of successful routing. If a message has | |
1138 | several recipients, it may be passed to a number of different transports. | |
1139 | ||
1140 | cindex:[preconditions,definition of] | |
1141 | An address is processed by passing it to each configured router instance in | |
1142 | turn, subject to certain preconditions, until a router accepts the address or | |
1143 | specifies that it should be bounced. We will describe this process in more | |
068aaea8 PH |
1144 | detail shortly. First, as a simple example, we consider how each recipient |
1145 | address in a message is processed in a small configuration of three routers. | |
168e428f | 1146 | |
068aaea8 | 1147 | To make this a more concrete example, it is described in terms of some actual |
168e428f PH |
1148 | routers, but remember, this is only an example. You can configure Exim's |
1149 | routers in many different ways, and there may be any number of routers in a | |
1150 | configuration. | |
1151 | ||
1152 | The first router that is specified in a configuration is often one that handles | |
1153 | addresses in domains that are not recognized specially by the local host. These | |
1154 | are typically addresses for arbitrary domains on the Internet. A precondition | |
1155 | is set up which looks for the special domains known to the host (for example, | |
1156 | its own domain name), and the router is run for addresses that do 'not' | |
1157 | match. Typically, this is a router that looks up domains in the DNS in order to | |
1158 | find the hosts to which this address routes. If it succeeds, the address is | |
068aaea8 | 1159 | assigned to a suitable SMTP transport; if it does not succeed, the router is |
168e428f PH |
1160 | configured to fail the address. |
1161 | ||
068aaea8 PH |
1162 | The second router is reached only when the domain is recognized as one that |
1163 | ``belongs'' to the local host. This router does redirection -- also known as | |
1164 | aliasing and forwarding. When it generates one or more new addresses from the | |
1165 | original, each of them is routed independently from the start. Otherwise, the | |
1166 | router may cause an address to fail, or it may simply decline to handle the | |
1167 | address, in which case the address is passed to the next router. | |
168e428f PH |
1168 | |
1169 | The final router in many configurations is one that checks to see if the | |
1170 | address belongs to a local mailbox. The precondition may involve a check to | |
1171 | see if the local part is the name of a login account, or it may look up the | |
1172 | local part in a file or a database. If its preconditions are not met, or if | |
1173 | the router declines, we have reached the end of the routers. When this happens, | |
1174 | the address is bounced. | |
1175 | ||
1176 | ||
1177 | ||
1178 | Processing an address for verification | |
1179 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1180 | cindex:[router,for verification] | |
1181 | cindex:[verifying address, overview] | |
1182 | As well as being used to decide how to deliver to an address, Exim's routers | |
1183 | are also used for 'address verification'. Verification can be requested as | |
1184 | one of the checks to be performed in an ACL for incoming messages, on both | |
1185 | sender and recipient addresses, and it can be tested using the %-bv% and | |
1186 | %-bvs% command line options. | |
1187 | ||
1188 | When an address is being verified, the routers are run in ``verify mode''. This | |
1189 | does not affect the way the routers work, but it is a state that can be | |
1190 | detected. By this means, a router can be skipped or made to behave differently | |
1191 | when verifying. A common example is a configuration in which the first router | |
1192 | sends all messages to a message-scanning program, unless they have been | |
1193 | previously scanned. Thus, the first router accepts all addresses without any | |
1194 | checking, making it useless for verifying. Normally, the %no_verify% option | |
1195 | would be set for such a router, causing it to be skipped in verify mode. | |
1196 | ||
1197 | ||
1198 | ||
1199 | ||
1200 | [[SECTrunindrou]] | |
1201 | Running an individual router | |
1202 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1203 | cindex:[router,running details] | |
1204 | cindex:[preconditions,checking] | |
1205 | cindex:[router,result of running] | |
1206 | As explained in the example above, a number of preconditions are checked before | |
1207 | running a router. If any are not met, the router is skipped, and the address is | |
1208 | passed to the next router. When all the preconditions on a router 'are' met, | |
1209 | the router is run. What happens next depends on the outcome, which is one of | |
1210 | the following: | |
1211 | ||
068aaea8 | 1212 | - 'accept': The router accepts the address, and either assigns it to a |
168e428f PH |
1213 | transport, or generates one or more ``child'' addresses. Processing the original |
1214 | address ceases, | |
1215 | cindex:[%unseen% option] | |
1216 | unless the %unseen% option is set on the router. This option | |
1217 | can be used to set up multiple deliveries with different routing (for example, | |
1218 | for keeping archive copies of messages). When %unseen% is set, the address is | |
1219 | passed to the next router. Normally, however, an 'accept' return marks the | |
1220 | end of routing. | |
1221 | + | |
068aaea8 PH |
1222 | Any child addresses generated by the router are processed independently, |
1223 | starting with the first router by default. It is possible to change this by | |
1224 | setting the %redirect_router% option to specify which router to start at for | |
1225 | child addresses. Unlike %pass_router% (see below) the router specified by | |
168e428f PH |
1226 | %redirect_router% may be anywhere in the router configuration. |
1227 | ||
1228 | - 'pass': The router recognizes the address, but cannot handle it itself. It | |
1229 | requests that the address be passed to another router. By default the address | |
1230 | is passed to the next router, but this can be changed by setting the | |
1231 | %pass_router% option. However, (unlike %redirect_router%) the named router | |
1232 | must be below the current router (to avoid loops). | |
1233 | ||
1234 | - 'decline': The router declines to accept the address because it does not | |
1235 | recognize it at all. By default, the address is passed to the next router, but | |
1236 | this can be prevented by setting the %no_more% option. When %no_more% is set, | |
068aaea8 PH |
1237 | all the remaining routers are skipped. In effect, %no_more% converts 'decline' |
1238 | into 'fail'. | |
168e428f PH |
1239 | |
1240 | - 'fail': The router determines that the address should fail, and queues it for | |
1241 | the generation of a bounce message. There is no further processing of the | |
1242 | original address unless %unseen% is set on the router. | |
1243 | ||
068aaea8 PH |
1244 | - 'defer': The router cannot handle the address at the present time. (A |
1245 | database may be offline, or a DNS lookup may have timed out.) No further | |
1246 | processing of the address happens in this delivery attempt. It is tried again | |
1247 | next time the message is considered for delivery. | |
168e428f PH |
1248 | |
1249 | - 'error': There is some error in the router (for example, a syntax error in | |
1250 | its configuration). The action is as for defer. | |
1251 | ||
1252 | If an address reaches the end of the routers without having been accepted by | |
068aaea8 PH |
1253 | any of them, it is bounced as unrouteable. The default error message in this |
1254 | situation is ``unrouteable address'', but you can set your own message by | |
1255 | making use of the %cannot_route_message% option. This can be set for any | |
1256 | router; the value from the last router that ``saw'' the address is used. | |
168e428f PH |
1257 | |
1258 | Sometimes while routing you want to fail a delivery when some conditions are | |
1259 | met but others are not, instead of passing the address on for further routing. | |
1260 | You can do this by having a second router that explicitly fails the delivery | |
1261 | when the relevant conditions are met. The ^redirect^ router has a ``fail'' | |
1262 | facility for this purpose. | |
1263 | ||
1264 | ||
068aaea8 PH |
1265 | Duplicate addresses |
1266 | ~~~~~~~~~~~~~~~~~~~ | |
1267 | ||
1268 | [revisionflag="changed"] | |
1269 | cindex:[case of local parts] | |
1270 | cindex:[address duplicate, discarding] | |
1271 | Once routing is complete, Exim scans the addresses that are assigned to local | |
1272 | and remote transports, and discards any duplicates that it finds. During this | |
1273 | check, local parts are treated as case-sensitive. | |
1274 | ||
168e428f PH |
1275 | |
1276 | ||
1277 | [[SECTrouprecon]] | |
1278 | Router preconditions | |
1279 | ~~~~~~~~~~~~~~~~~~~~ | |
1280 | cindex:[router preconditions, order of processing] | |
1281 | cindex:[preconditions,order of processing] | |
1282 | The preconditions that are tested for each router are listed below, in the | |
1283 | order in which they are tested. The individual configuration options are | |
1284 | described in more detail in chapter <<CHAProutergeneric>>. | |
1285 | ||
1286 | - The %local_part_prefix% and %local_part_suffix% options can specify that | |
1287 | the local parts handled by the router may or must have certain prefixes and/or | |
1288 | suffixes. If a mandatory affix (prefix or suffix) is not present, the router is | |
1289 | skipped. These conditions are tested first. When an affix is present, it is | |
1290 | removed from the local part before further processing, including the evaluation | |
1291 | of any other conditions. | |
1292 | ||
1293 | - Routers can be designated for use only when not verifying an address, that is, | |
1294 | only when routing it for delivery (or testing its delivery routing). If the | |
1295 | %verify% option is set false, the router is skipped when Exim is verifying an | |
1296 | address. | |
1297 | Setting the %verify% option actually sets two options, %verify_sender% and | |
1298 | %verify_recipient%, which independently control the use of the router for | |
1299 | sender and recipient verification. You can set these options directly if | |
1300 | you want a router to be used for only one type of verification. | |
1301 | ||
1302 | - If the %address_test% option is set false, the router is skipped when Exim is | |
1303 | run with the %-bt% option to test an address routing. This can be helpful when | |
1304 | the first router sends all new messages to a scanner of some sort; it makes it | |
1305 | possible to use %-bt% to test subsequent delivery routing without having to | |
1306 | simulate the effect of the scanner. | |
1307 | ||
1308 | - Routers can be designated for use only when verifying an address, as | |
1309 | opposed to routing it for delivery. The %verify_only% option controls this. | |
1310 | ||
068aaea8 PH |
1311 | - Individual routers can be explicitly skipped when running the routers to |
1312 | check an address given in the SMTP EXPN command (see the %expn% option). | |
168e428f | 1313 | |
068aaea8 PH |
1314 | - If the %domains% option is set, the domain of the address must be in the set |
1315 | of domains that it defines. | |
168e428f | 1316 | |
068aaea8 PH |
1317 | - cindex:[$local_part_prefix$] |
1318 | cindex:[$local_part$] | |
1319 | cindex:[$local_part_suffix$] | |
1320 | If the %local_parts% option is set, the local part of the address must be in | |
168e428f PH |
1321 | the set of local parts that it defines. If %local_part_prefix% or |
1322 | %local_part_suffix% is in use, the prefix or suffix is removed from the local | |
1323 | part before this check. If you want to do precondition tests on local parts | |
1324 | that include affixes, you can do so by using a %condition% option (see below) | |
1325 | that uses the variables $local_part$, $local_part_prefix$, and | |
1326 | $local_part_suffix$ as necessary. | |
1327 | ||
068aaea8 PH |
1328 | - cindex:[$local_user_uid$] |
1329 | cindex:[$local_user_gid$] | |
1330 | cindex:[$home$] | |
1331 | If the %check_local_user% option is set, the local part must be the name of | |
1332 | an account on the local host. If this check succeeds, the uid and gid of the | |
1333 | local user are placed in $local_user_uid$ and $local_user_gid$ and the user's | |
1334 | home directory is placed in $home$; these values can be used in the remaining | |
1335 | preconditions. | |
168e428f PH |
1336 | |
1337 | - If the %router_home_directory% option is set, it is expanded at this point, | |
1338 | because it overrides the value of $home$. If this expansion were left till | |
1339 | later, the value of $home$ as set by %check_local_user% would be used in | |
1340 | subsequent tests. Having two different values of $home$ in the same router | |
1341 | could lead to confusion. | |
1342 | ||
1343 | - If the %senders% option is set, the envelope sender address must be in the set | |
1344 | of addresses that it defines. | |
1345 | ||
1346 | - If the %require_files% option is set, the existence or non-existence of | |
1347 | specified files is tested. | |
1348 | ||
1349 | - cindex:[customizing,precondition] | |
1350 | If the %condition% option is set, it is evaluated and tested. This option uses | |
1351 | an expanded string to allow you to set up your own custom preconditions. | |
1352 | Expanded strings are described in chapter <<CHAPexpand>>. | |
1353 | ||
1354 | ||
1355 | Note that %require_files% comes near the end of the list, so you cannot use it | |
1356 | to check for the existence of a file in which to lookup up a domain, local | |
1357 | part, or sender. However, as these options are all expanded, you can use the | |
1358 | %exists% expansion condition to make such tests within each condition. The | |
1359 | %require_files% option is intended for checking files that the router may be | |
1360 | going to use internally, or which are needed by a specific transport (for | |
1361 | example, _.procmailrc_). | |
1362 | ||
1363 | ||
1364 | ||
1365 | Delivery in detail | |
1366 | ~~~~~~~~~~~~~~~~~~ | |
1367 | cindex:[delivery,in detail] | |
1368 | When a message is to be delivered, the sequence of events is as follows: | |
1369 | ||
1370 | - If a system-wide filter file is specified, the message is passed to it. The | |
1371 | filter may add recipients to the message, replace the recipients, discard the | |
1372 | message, cause a new message to be generated, or cause the message delivery to | |
1373 | fail. The format of the system filter file is the same as for Exim user filter | |
1374 | files, described in the separate document entitled | |
1375 | 'Exim's interfaces to mail filtering'. | |
1376 | cindex:[Sieve filter,not available for system filter] | |
1377 | (*Note*: Sieve cannot be used for system filter files.) | |
1378 | + | |
1379 | Some additional features are available in system filters -- see chapter | |
1380 | <<CHAPsystemfilter>> for details. Note that a message is passed to the system | |
1381 | filter only once per delivery attempt, however many recipients it has. However, | |
1382 | if there are several delivery attempts because one or more addresses could not | |
1383 | be immediately delivered, the system filter is run each time. The filter | |
1384 | condition %first_delivery% can be used to detect the first run of the system | |
1385 | filter. | |
1386 | ||
1387 | - Each recipient address is offered to each configured router in turn, subject | |
1388 | to its preconditions, until one is able to handle it. If no router can handle | |
1389 | the address, that is, if they all decline, the address is failed. Because | |
1390 | routers can be targeted at particular domains, several locally handled domains | |
1391 | can be processed entirely independently of each other. | |
1392 | ||
1393 | - cindex:[routing,loops in] | |
1394 | cindex:[loop,while routing] | |
068aaea8 PH |
1395 | A router that accepts an address may assign it to a local or a remote transport. However, the transport is not run at this time. Instead, the address is |
1396 | placed on a list for the particular transport, which will be run later. | |
1397 | Alternatively, the router may generate one or more new addresses (typically | |
1398 | from alias, forward, or filter files). New addresses are fed back into this | |
1399 | process from the top, but in order to avoid loops, a router ignores any address | |
1400 | which has an identically-named ancestor that was processed by itself. | |
168e428f PH |
1401 | |
1402 | - When all the routing has been done, addresses that have been successfully | |
1403 | handled are passed to their assigned transports. When local transports are | |
1404 | doing real local deliveries, they handle only one address at a time, but if a | |
1405 | local transport is being used as a pseudo-remote transport (for example, to | |
1406 | collect batched SMTP messages for transmission by some other means) multiple | |
1407 | addresses can be handled. Remote transports can always handle more than one | |
1408 | address at a time, but can be configured not to do so, or to restrict multiple | |
1409 | addresses to the same domain. | |
1410 | ||
1411 | - Each local delivery to a file or a pipe runs in a separate process under a | |
1412 | non-privileged uid, and these deliveries are run one at a time. Remote | |
1413 | deliveries also run in separate processes, normally under a uid that is private | |
1414 | to Exim (``the Exim user''), but in this case, several remote deliveries can be | |
1415 | run in parallel. The maximum number of simultaneous remote deliveries for any | |
1416 | one message is set by the %remote_max_parallel% option. | |
1417 | The order in which deliveries are done is not defined, except that all local | |
1418 | deliveries happen before any remote deliveries. | |
1419 | ||
1420 | - cindex:[queue runner] | |
1421 | When it encounters a local delivery during a queue run, Exim checks its retry | |
1422 | database to see if there has been a previous temporary delivery failure for the | |
1423 | address before running the local transport. If there was a previous failure, | |
1424 | Exim does not attempt a new delivery until the retry time for the address is | |
1425 | reached. However, this happens only for delivery attempts that are part of a | |
1426 | queue run. Local deliveries are always attempted when delivery immediately | |
1427 | follows message reception, even if retry times are set for them. This makes for | |
1428 | better behaviour if one particular message is causing problems (for example, | |
1429 | causing quota overflow, or provoking an error in a filter file). | |
1430 | ||
1431 | - cindex:[delivery,retry in remote transports] | |
1432 | Remote transports do their own retry handling, since an address may be | |
1433 | deliverable to one of a number of hosts, each of which may have a different | |
1434 | retry time. If there have been previous temporary failures and no host has | |
1435 | reached its retry time, no delivery is attempted, whether in a queue run or | |
1436 | not. See chapter <<CHAPretry>> for details of retry strategies. | |
1437 | ||
1438 | - If there were any permanent errors, a bounce message is returned to an | |
1439 | appropriate address (the sender in the common case), with details of the error | |
1440 | for each failing address. Exim can be configured to send copies of bounce | |
1441 | messages to other addresses. | |
1442 | ||
1443 | - cindex:[delivery,deferral] | |
1444 | If one or more addresses suffered a temporary failure, the message is left on | |
1445 | the queue, to be tried again later. Delivery of these addresses is said to be | |
1446 | 'deferred'. | |
1447 | ||
1448 | - When all the recipient addresses have either been delivered or bounced, | |
1449 | handling of the message is complete. The spool files and message log are | |
1450 | deleted, though the message log can optionally be preserved if required. | |
1451 | ||
1452 | ||
1453 | ||
1454 | ||
1455 | Retry mechanism | |
1456 | ~~~~~~~~~~~~~~~ | |
1457 | cindex:[delivery,retry mechanism] | |
1458 | cindex:[retry,description of mechanism] | |
1459 | cindex:[queue runner] | |
1460 | Exim's mechanism for retrying messages that fail to get delivered at the first | |
1461 | attempt is the queue runner process. You must either run an Exim daemon that | |
1462 | uses the %-q% option with a time interval to start queue runners at regular | |
1463 | intervals, or use some other means (such as 'cron') to start them. If you do | |
1464 | not arrange for queue runners to be run, messages that fail temporarily at the | |
1465 | first attempt will remain on your queue for ever. A queue runner process works | |
068aaea8 | 1466 | its way through the queue, one message at a time, trying each delivery that has |
168e428f PH |
1467 | passed its retry time. |
1468 | You can run several queue runners at once. | |
1469 | ||
1470 | Exim uses a set of configured rules to determine when next to retry the failing | |
1471 | address (see chapter <<CHAPretry>>). These rules also specify when Exim should | |
1472 | give up trying to deliver to the address, at which point it generates a bounce | |
1473 | message. If no retry rules are set for a particular host, address, and error | |
1474 | combination, no retries are attempted, and temporary errors are treated as | |
1475 | permanent. | |
1476 | ||
1477 | ||
1478 | ||
1479 | Temporary delivery failure | |
1480 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1481 | cindex:[delivery,temporary failure] | |
1482 | There are many reasons why a message may not be immediately deliverable to a | |
1483 | particular address. Failure to connect to a remote machine (because it, or the | |
1484 | connection to it, is down) is one of the most common. Temporary failures may be | |
1485 | detected during routing as well as during the transport stage of delivery. | |
1486 | Local deliveries may be delayed if NFS files are unavailable, or if a mailbox | |
1487 | is on a file system where the user is over quota. Exim can be configured to | |
1488 | impose its own quotas on local mailboxes; where system quotas are set they will | |
1489 | also apply. | |
1490 | ||
1491 | If a host is unreachable for a period of time, a number of messages may be | |
1492 | waiting for it by the time it recovers, and sending them in a single SMTP | |
1493 | connection is clearly beneficial. Whenever a delivery to a remote host is | |
1494 | deferred, | |
1495 | ||
1496 | cindex:[hints database] | |
1497 | Exim makes a note in its hints database, and whenever a successful | |
1498 | SMTP delivery has happened, it looks to see if any other messages are waiting | |
1499 | for the same host. If any are found, they are sent over the same SMTP | |
1500 | connection, subject to a configuration limit as to the maximum number in any | |
1501 | one connection. | |
1502 | ||
1503 | ||
1504 | ||
1505 | ||
1506 | Permanent delivery failure | |
1507 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1508 | cindex:[delivery,permanent failure] | |
1509 | cindex:[bounce message,when generated] | |
1510 | When a message cannot be delivered to some or all of its intended recipients, a | |
1511 | bounce message is generated. Temporary delivery failures turn into permanent | |
1512 | errors when their timeout expires. All the addresses that fail in a given | |
1513 | delivery attempt are listed in a single message. If the original message has | |
1514 | many recipients, it is possible for some addresses to fail in one delivery | |
1515 | attempt and others to fail subsequently, giving rise to more than one bounce | |
1516 | message. The wording of bounce messages can be customized by the administrator. | |
1517 | See chapter <<CHAPemsgcust>> for details. | |
1518 | ||
1519 | cindex:['X-Failed-Recipients:' header line] | |
1520 | Bounce messages contain an 'X-Failed-Recipients:' header line that lists the | |
1521 | failed addresses, for the benefit of programs that try to analyse such messages | |
1522 | automatically. | |
1523 | ||
1524 | cindex:[bounce message,recipient of] | |
1525 | A bounce message is normally sent to the sender of the original message, as | |
1526 | obtained from the message's envelope. For incoming SMTP messages, this is the | |
1527 | address given in the MAIL command. However, when an address is | |
1528 | expanded via a forward or alias file, an alternative address can be specified | |
1529 | for delivery failures of the generated addresses. For a mailing list expansion | |
1530 | (see section <<SECTmailinglists>>) it is common to direct bounce messages to the | |
1531 | manager of the list. | |
1532 | ||
1533 | ||
1534 | ||
1535 | ||
1536 | Failures to deliver bounce messages | |
1537 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1538 | cindex:[bounce message,failure to deliver] | |
1539 | If a bounce message (either locally generated or received from a remote host) | |
1540 | itself suffers a permanent delivery failure, the message is left on the queue, | |
1541 | but it is frozen, awaiting the attention of an administrator. There are options | |
068aaea8 | 1542 | that can be used to make Exim discard such failed messages, or to keep them |
168e428f PH |
1543 | for only a short time (see %timeout_frozen_after% and |
1544 | %ignore_bounce_errors_after%). | |
1545 | ||
1546 | ||
1547 | ||
1548 | ||
1549 | ||
1550 | //////////////////////////////////////////////////////////////////////////// | |
1551 | //////////////////////////////////////////////////////////////////////////// | |
1552 | ||
1553 | Building and installing Exim | |
1554 | ---------------------------- | |
1555 | ||
1556 | cindex:[building Exim] | |
1557 | ||
1558 | Unpacking | |
1559 | ~~~~~~~~~ | |
1560 | Exim is distributed as a gzipped or bzipped tar file which, when upacked, | |
1561 | creates a directory with the name of the current release (for example, | |
1562 | _exim-{version}_) into which the following files are placed: | |
1563 | ||
1564 | [frame="none"] | |
1565 | `--------------------`-------------------------------------------------------- | |
1566 | _ACKNOWLEDGMENTS_ contains some acknowledgments | |
1567 | _CHANGES_ contains a reference to where changes are documented | |
1568 | _LICENCE_ the GNU General Public Licence | |
1569 | _Makefile_ top-level make file | |
1570 | _NOTICE_ conditions for the use of Exim | |
1571 | _README_ list of files, directories and simple build instructions | |
1572 | ------------------------------------------------------------------------------ | |
1573 | ||
1574 | Other files whose names begin with _README_ may also be present. The | |
1575 | following subdirectories are created: | |
1576 | ||
1577 | [frame="none"] | |
1578 | `--------------------`------------------------------------------------ | |
1579 | _Local_ an empty directory for local configuration files | |
1580 | _OS_ OS-specific files | |
1581 | _doc_ documentation files | |
1582 | _exim_monitor_ source files for the Exim monitor | |
1583 | _scripts_ scripts used in the build process | |
1584 | _src_ remaining source files | |
1585 | _util_ independent utilities | |
1586 | ---------------------------------------------------------------------- | |
1587 | ||
1588 | The main utility programs are contained in the _src_ directory, and are built | |
1589 | with the Exim binary. The _util_ directory contains a few optional scripts | |
1590 | that may be useful to some sites. | |
1591 | ||
1592 | ||
1593 | Multiple machine architectures and operating systems | |
1594 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1595 | cindex:[building Exim,multiple OS/architectures] | |
1596 | The building process for Exim is arranged to make it easy to build binaries for | |
1597 | a number of different architectures and operating systems from the same set of | |
1598 | source files. Compilation does not take place in the _src_ directory. Instead, | |
1599 | a 'build directory' is created for each architecture and operating system. | |
1600 | ||
1601 | cindex:[symbolic link,to build directory] | |
1602 | Symbolic links to the sources are installed in this directory, which is where | |
1603 | the actual building takes place. | |
1604 | ||
1605 | In most cases, Exim can discover the machine architecture and operating system | |
1606 | for itself, but the defaults can be overridden if necessary. | |
1607 | ||
1608 | ||
1609 | [[SECTdb]] | |
1610 | DBM libraries | |
1611 | ~~~~~~~~~~~~~ | |
1612 | cindex:[DBM libraries, discussion of] | |
1613 | cindex:[hints database,DBM files used for] | |
1614 | Even if you do not use any DBM files in your configuration, Exim still needs a | |
1615 | DBM library in order to operate, because it uses indexed files for its hints | |
1616 | databases. Unfortunately, there are a number of DBM libraries in existence, and | |
1617 | different operating systems often have different ones installed. | |
1618 | ||
1619 | cindex:[Solaris,DBM library for] | |
1620 | cindex:[IRIX, DBM library for] | |
1621 | cindex:[BSD, DBM library for] | |
1622 | cindex:[Linux, DBM library for] | |
1623 | If you are using Solaris, IRIX, one of the modern BSD systems, or a modern | |
1624 | Linux distribution, the DBM configuration should happen automatically, and you | |
1625 | may be able to ignore this section. Otherwise, you may have to learn more than | |
1626 | you would like about DBM libraries from what follows. | |
1627 | ||
1628 | cindex:['ndbm' DBM library] | |
1629 | Licensed versions of Unix normally contain a library of DBM functions operating | |
1630 | via the 'ndbm' interface, and this is what Exim expects by default. Free | |
1631 | versions of Unix seem to vary in what they contain as standard. In particular, | |
1632 | some early versions of Linux have no default DBM library, and different | |
1633 | distributors have chosen to bundle different libraries with their packaged | |
1634 | versions. However, the more recent releases seem to have standardised on the | |
1635 | Berkeley DB library. | |
1636 | ||
1637 | Different DBM libraries have different conventions for naming the files they | |
1638 | use. When a program opens a file called _dbmfile_, there are four | |
1639 | possibilities: | |
1640 | ||
1641 | . A traditional 'ndbm' implementation, such as that supplied as part of | |
1642 | Solaris, operates on two files called _dbmfile.dir_ and _dbmfile.pag_. | |
1643 | ||
1644 | . cindex:['gdbm' DBM library] | |
1645 | The GNU library, 'gdbm', operates on a single file. If used via its 'ndbm' | |
1646 | compatibility interface it makes two different hard links to it with names | |
1647 | _dbmfile.dir_ and _dbmfile.pag_, but if used via its native interface, the | |
1648 | file name is used unmodified. | |
1649 | ||
1650 | . cindex:[Berkeley DB library] | |
1651 | The Berkeley DB package, if called via its 'ndbm' compatibility interface, | |
1652 | operates on a single file called _dbmfile.db_, but otherwise looks to the | |
1653 | programmer exactly the same as the traditional 'ndbm' implementation. | |
1654 | ||
1655 | . If the Berkeley package is used in its native mode, it operates on a single | |
1656 | file called _dbmfile_; the programmer's interface is somewhat different to | |
1657 | the traditional 'ndbm' interface. | |
1658 | ||
1659 | . To complicate things further, there are several very different versions of the | |
1660 | Berkeley DB package. Version 1.85 was stable for a very long time, releases | |
1661 | 2.'x' and 3.'x' were current for a while, but the latest versions are now | |
1662 | numbered 4.'x'. Maintenance of some of the earlier releases has ceased. All | |
1663 | versions of Berkeley DB can be obtained from | |
1664 | + | |
1665 | &&& | |
1666 | *http://www.sleepycat.com/[]* | |
1667 | &&& | |
1668 | ||
1669 | . cindex:['tdb' DBM library] | |
1670 | Yet another DBM library, called 'tdb', has become available from | |
1671 | + | |
1672 | &&& | |
1673 | *http://download.sourceforge.net/tdb[]* | |
1674 | &&& | |
1675 | + | |
1676 | It has its own interface, and also operates on a single file. | |
1677 | ||
1678 | cindex:[USE_DB] | |
1679 | cindex:[DBM libraries, configuration for building] | |
1680 | Exim and its utilities can be compiled to use any of these interfaces. In order | |
1681 | to use any version of the Berkeley DB package in native mode, you must set | |
1682 | USE_DB in an appropriate configuration file (typically | |
1683 | _Local/Makefile_). For example: | |
1684 | ||
1685 | USE_DB=yes | |
1686 | ||
1687 | Similarly, for gdbm you set USE_GDBM, and for tdb you set USE_TDB. An | |
1688 | error is diagnosed if you set more than one of these. | |
1689 | ||
1690 | At the lowest level, the build-time configuration sets none of these options, | |
1691 | thereby assuming an interface of type (1). However, some operating system | |
1692 | configuration files (for example, those for the BSD operating systems and | |
1693 | Linux) assume type (4) by setting USE_DB as their default, and the | |
1694 | configuration files for Cygwin set USE_GDBM. Anything you set in | |
1695 | _Local/Makefile_, however, overrides these system defaults. | |
1696 | ||
1697 | As well as setting USE_DB, USE_GDBM, or USE_TDB, it may also be | |
1698 | necessary to set DBMLIB, to cause inclusion of the appropriate library, as | |
1699 | in one of these lines: | |
1700 | ||
1701 | DBMLIB = -ldb | |
1702 | DBMLIB = -ltdb | |
1703 | ||
1704 | Settings like that will work if the DBM library is installed in the standard | |
1705 | place. Sometimes it is not, and the library's header file may also not be in | |
1706 | the default path. You may need to set INCLUDE to specify where the header | |
1707 | file is, and to specify the path to the library more fully in DBMLIB, as in | |
1708 | this example: | |
1709 | ||
1710 | INCLUDE=-I/usr/local/include/db-4.1 | |
1711 | DBMLIB=/usr/local/lib/db-4.1/libdb.a | |
1712 | ||
1713 | ||
1714 | There is further detailed discussion about the various DBM libraries in the | |
1715 | file _doc/dbm.discuss.txt_ in the Exim distribution. | |
1716 | ||
1717 | ||
1718 | ||
1719 | Pre-building configuration | |
1720 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1721 | cindex:[building Exim,pre-building configuration] | |
1722 | cindex:[configuration for building Exim] | |
1723 | cindex:[_Local/Makefile_] | |
1724 | cindex:[_src/EDITME_] | |
1725 | Before building Exim, a local configuration file that specifies options | |
1726 | independent of any operating system has to be created with the name | |
1727 | _Local/Makefile_. A template for this file is supplied as the file | |
1728 | _src/EDITME_, and it contains full descriptions of all the option settings | |
1729 | therein. These descriptions are therefore not repeated here. If you are | |
1730 | building Exim for the first time, the simplest thing to do is to copy | |
1731 | _src/EDITME_ to _Local/Makefile_, then read it and edit it appropriately. | |
1732 | ||
1733 | There are three settings that you must supply, because Exim will not build | |
1734 | without them. They are the location of the run time configuration file | |
1735 | (CONFIGURE_FILE), the directory in which Exim binaries will be installed | |
1736 | (BIN_DIRECTORY), and the identity of the Exim user (EXIM_USER and | |
1737 | maybe EXIM_GROUP as well). The value of CONFIGURE_FILE can in fact be | |
1738 | a colon-separated list of file names; Exim uses the first of them that exists. | |
1739 | ||
1740 | There are a few other parameters that can be specified either at build time or | |
1741 | at run time, to enable the same binary to be used on a number of different | |
1742 | machines. However, if the locations of Exim's spool directory and log file | |
1743 | directory (if not within the spool directory) are fixed, it is recommended that | |
1744 | you specify them in _Local/Makefile_ instead of at run time, so that errors | |
1745 | detected early in Exim's execution (such as a malformed configuration file) can | |
1746 | be logged. | |
1747 | ||
1748 | cindex:[content scanning,specifying at build time] | |
068aaea8 | 1749 | Exim's interfaces for calling virus and spam scanning software directly from |
168e428f PH |
1750 | access control lists are not compiled by default. If you want to include these |
1751 | facilities, you need to set | |
1752 | ||
1753 | WITH_CONTENT_SCAN=yes | |
1754 | ||
1755 | in your _Local/Makefile_. For details of the facilities themselves, see | |
1756 | chapter <<CHAPexiscan>>. | |
1757 | ||
1758 | ||
1759 | cindex:[_Local/eximon.conf_] | |
1760 | cindex:[_exim_monitor/EDITME_] | |
1761 | If you are going to build the Exim monitor, a similar configuration process is | |
1762 | required. The file _exim_monitor/EDITME_ must be edited appropriately for | |
1763 | your installation and saved under the name _Local/eximon.conf_. If you are | |
1764 | happy with the default settings described in _exim_monitor/EDITME_, | |
1765 | _Local/eximon.conf_ can be empty, but it must exist. | |
1766 | ||
1767 | This is all the configuration that is needed in straightforward cases for known | |
1768 | operating systems. However, the building process is set up so that it is easy | |
1769 | to override options that are set by default or by operating-system-specific | |
1770 | configuration files, for example to change the name of the C compiler, which | |
1771 | defaults to %gcc%. See section <<SECToverride>> below for details of how to do | |
1772 | this. | |
1773 | ||
1774 | ||
1775 | ||
1776 | Support for iconv() | |
1777 | ~~~~~~~~~~~~~~~~~~~ | |
1778 | cindex:['iconv()' support] | |
d1e83bff | 1779 | cindex:[RFC 2047] |
168e428f PH |
1780 | The contents of header lines in messages may be encoded according to the rules |
1781 | described RFC 2047. This makes it possible to transmit characters that are not | |
1782 | in the ASCII character set, and to label them as being in a particular | |
1783 | character set. When Exim is inspecting header lines by means of the %\$h_% | |
1784 | mechanism, it decodes them, and translates them into a specified character set | |
1785 | (default ISO-8859-1). The translation is possible only if the operating system | |
1786 | supports the 'iconv()' function. | |
1787 | ||
1788 | However, some of the operating systems that supply 'iconv()' do not support | |
1789 | very many conversions. The GNU %libiconv% library (available from | |
1790 | *http://www.gnu.org/software/libiconv/[]*) can be installed on such systems to | |
1791 | remedy this deficiency, as well as on systems that do not supply 'iconv()' at | |
1792 | all. After installing %libiconv%, you should add | |
1793 | ||
1794 | HAVE_ICONV=yes | |
1795 | ||
1796 | to your _Local/Makefile_ and rebuild Exim. | |
1797 | ||
1798 | ||
1799 | ||
1800 | [[SECTinctlsssl]] | |
1801 | Including TLS/SSL encryption support | |
1802 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1803 | cindex:[TLS,including support for TLS] | |
1804 | cindex:[encryption,including support for] | |
1805 | cindex:[SUPPORT_TLS] | |
1806 | cindex:[OpenSSL,building Exim with] | |
1807 | cindex:[GnuTLS,building Exim with] | |
1808 | Exim can be built to support encrypted SMTP connections, using the STARTTLS | |
1809 | command as per RFC 2487. It can also support legacy clients that expect to | |
1810 | start a TLS session immediately on connection to a non-standard port (see the | |
1811 | %tls_on_connect_ports% runtime option and the %-tls-on-connect% command | |
1812 | line option). | |
1813 | ||
1814 | If you want to build Exim with TLS support, you must first install either the | |
1815 | OpenSSL or GnuTLS library. There is no cryptographic code in Exim itself for | |
1816 | implementing SSL. | |
1817 | ||
1818 | If OpenSSL is installed, you should set | |
1819 | ||
1820 | SUPPORT_TLS=yes | |
1821 | TLS_LIBS=-lssl -lcrypto | |
1822 | ||
1823 | in _Local/Makefile_. You may also need to specify the locations of the | |
1824 | OpenSSL library and include files. For example: | |
1825 | ||
1826 | SUPPORT_TLS=yes | |
1827 | TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto | |
1828 | TLS_INCLUDE=-I/usr/local/openssl/include/ | |
1829 | ||
1830 | cindex:[USE_GNUTLS] | |
1831 | If GnuTLS is installed, you should set | |
1832 | ||
1833 | SUPPORT_TLS=yes | |
1834 | USE_GNUTLS=yes | |
1835 | TLS_LIBS=-lgnutls -ltasn1 -lgcrypt | |
1836 | ||
1837 | in _Local/Makefile_, and again you may need to specify the locations of the | |
1838 | library and include files. For example: | |
1839 | ||
1840 | SUPPORT_TLS=yes | |
1841 | USE_GNUTLS=yes | |
1842 | TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt | |
1843 | TLS_INCLUDE=-I/usr/gnu/include | |
1844 | ||
1845 | You do not need to set TLS_INCLUDE if the relevant directory is already | |
1846 | specified in INCLUDE. Details of how to configure Exim to make use of TLS | |
1847 | are given in chapter <<CHAPTLS>>. | |
1848 | ||
1849 | ||
1850 | ||
1851 | ||
1852 | Use of tcpwrappers | |
1853 | ~~~~~~~~~~~~~~~~~~ | |
1854 | cindex:[tcpwrappers, building Exim to support] | |
1855 | cindex:[USE_TCP_WRAPPERS] | |
1856 | Exim can be linked with the 'tcpwrappers' library in order to check incoming | |
1857 | SMTP calls using the 'tcpwrappers' control files. This may be a convenient | |
1858 | alternative to Exim's own checking facilities for installations that are | |
1859 | already making use of 'tcpwrappers' for other purposes. To do this, you should | |
1860 | set USE_TCP_WRAPPERS in _Local/Makefile_, arrange for the file | |
1861 | _tcpd.h_ to be available at compile time, and also ensure that the library | |
1862 | _libwrap.a_ is available at link time, typically by including %-lwrap% in | |
1863 | EXTRALIBS_EXIM. For example, if 'tcpwrappers' is installed in | |
1864 | _/usr/local_, you might have | |
1865 | ||
1866 | USE_TCP_WRAPPERS=yes | |
1867 | CFLAGS=-O -I/usr/local/include | |
1868 | EXTRALIBS_EXIM=-L/usr/local/lib -lwrap | |
1869 | ||
1870 | in _Local/Makefile_. The name to use in the 'tcpwrappers' control files is | |
1871 | ``exim''. For example, the line | |
1872 | ||
1873 | exim : LOCAL 192.168.1. .friendly.domain.example | |
1874 | ||
1875 | in your _/etc/hosts.allow_ file allows connections from the local host, from | |
1876 | the subnet 192.168.1.0/24, and from all hosts in 'friendly.domain.example'. | |
1877 | All other connections are denied. Consult the 'tcpwrappers' documentation for | |
1878 | further details. | |
1879 | ||
1880 | ||
1881 | ||
1882 | Including support for IPv6 | |
1883 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1884 | cindex:[IPv6,including support for] | |
1885 | Exim contains code for use on systems that have IPv6 support. Setting | |
1886 | `HAVE_IPV6=YES` in _Local/Makefile_ causes the IPv6 code to be included; | |
1887 | it may also be necessary to set IPV6_INCLUDE and IPV6_LIBS on systems | |
1888 | where the IPv6 support is not fully integrated into the normal include and | |
1889 | library files. | |
1890 | ||
1891 | Two different types of DNS record for handling IPv6 addresses have been | |
1892 | defined. AAAA records (analagous to A records for IPv4) are in use, and are | |
1893 | currently seen as the mainstream. Another record type called A6 was proposed | |
1894 | as better than AAAA because it had more flexibility. However, it was felt to be | |
1895 | over-complex, and its status was reduced to ``experimental''. It is not known | |
1896 | if anyone is actually using A6 records. Exim has support for A6 records, but | |
1897 | this is included only if you set `SUPPORT_A6=YES` in _Local/Makefile_. The | |
1898 | support has not been tested for some time. | |
1899 | ||
1900 | ||
1901 | ||
1902 | The building process | |
1903 | ~~~~~~~~~~~~~~~~~~~~ | |
1904 | cindex:[build directory] | |
1905 | Once _Local/Makefile_ (and _Local/eximon.conf_, if required) have been | |
1906 | created, run 'make' at the top level. It determines the architecture and | |
1907 | operating system types, and creates a build directory if one does not exist. | |
1908 | For example, on a Sun system running Solaris 8, the directory | |
1909 | _build-SunOS5-5.8-sparc_ is created. | |
1910 | cindex:[symbolic link,to source files] | |
1911 | Symbolic links to relevant source files are installed in the build directory. | |
1912 | ||
1913 | *Warning*: The %-j% (parallel) flag must not be used with 'make'; the | |
1914 | building process fails if it is set. | |
1915 | ||
1916 | If this is the first time 'make' has been run, it calls a script that builds | |
1917 | a make file inside the build directory, using the configuration files from the | |
1918 | _Local_ directory. The new make file is then passed to another instance of | |
1919 | 'make'. This does the real work, building a number of utility scripts, and | |
1920 | then compiling and linking the binaries for the Exim monitor (if configured), a | |
1921 | number of utility programs, and finally Exim itself. The command 'make | |
1922 | makefile' can be used to force a rebuild of the make file in the build | |
1923 | directory, should this ever be necessary. | |
1924 | ||
1925 | If you have problems building Exim, check for any comments there may be in the | |
1926 | _README_ file concerning your operating system, and also take a look at the | |
1927 | FAQ, where some common problems are covered. | |
1928 | ||
1929 | ||
1930 | ||
068aaea8 PH |
1931 | Output from ``make'' |
1932 | ~~~~~~~~~~~~~~~~~~~~ | |
1933 | ||
1934 | [revisionflag="changed"] | |
1935 | The output produced by the 'make' process for compile lines is often very | |
1936 | unreadable, because these lines can be very long. For this reason, the normal | |
1937 | output is suppressed by default, and instead output similar to that which | |
1938 | appears when compiling the 2.6 Linux kernel is generated: just a short line for | |
1939 | each module that is being compiled or linked. However, it is still possible to | |
1940 | get the full output, by calling 'make' like this: | |
1941 | ||
1942 | FULLECHO='' make -e | |
1943 | ||
1944 | The value of FULLECHO defaults to ``@'', the flag character that suppresses | |
1945 | command reflection in 'make'. When you ask for the full output, it is | |
1946 | given in addition to the the short output. | |
1947 | ||
1948 | ||
1949 | ||
168e428f PH |
1950 | |
1951 | [[SECToverride]] | |
1952 | Overriding build-time options for Exim | |
1953 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1954 | cindex:[build-time options, overriding] | |
1955 | The main make file that is created at the beginning of the building process | |
1956 | consists of the concatenation of a number of files which set configuration | |
1957 | values, followed by a fixed set of 'make' instructions. If a value is set | |
1958 | more than once, the last setting overrides any previous ones. This provides a | |
1959 | convenient way of overriding defaults. The files that are concatenated are, in | |
1960 | order: | |
1961 | ||
1962 | &&& | |
1963 | _OS/Makefile-Default_ | |
1964 | _OS/Makefile-_<'ostype'> | |
1965 | _Local/Makefile_ | |
1966 | _Local/Makefile-_<'ostype'> | |
1967 | _Local/Makefile-_<'archtype'> | |
1968 | _Local/Makefile-_<'ostype'>-<'archtype'> | |
1969 | _OS/Makefile-Base_ | |
1970 | &&& | |
1971 | ||
1972 | cindex:[_Local/Makefile_] | |
1973 | cindex:[building Exim,operating system type] | |
1974 | cindex:[building Exim,architecture type] | |
1975 | where <'ostype'> is the operating system type and <'archtype'> is the | |
1976 | architecture type. _Local/Makefile_ is required to exist, and the building | |
1977 | process fails if it is absent. The other three _Local_ files are optional, | |
1978 | and are often not needed. | |
1979 | ||
1980 | The values used for <'ostype'> and <'archtype'> are obtained from scripts | |
1981 | called _scripts/os-type_ and _scripts/arch-type_ respectively. If either of | |
1982 | the environment variables EXIM_OSTYPE or EXIM_ARCHTYPE is set, their | |
1983 | values are used, thereby providing a means of forcing particular settings. | |
1984 | Otherwise, the scripts try to get values from the %uname% command. If this | |
1985 | fails, the shell variables OSTYPE and ARCHTYPE are inspected. A number | |
1986 | of 'ad hoc' transformations are then applied, to produce the standard names | |
1987 | that Exim expects. You can run these scripts directly from the shell in order | |
1988 | to find out what values are being used on your system. | |
1989 | ||
1990 | ||
1991 | _OS/Makefile-Default_ contains comments about the variables that are set | |
1992 | therein. Some (but not all) are mentioned below. If there is something that | |
1993 | needs changing, review the contents of this file and the contents of the make | |
1994 | file for your operating system (_OS/Makefile-<ostype>_) to see what the | |
1995 | default values are. | |
1996 | ||
1997 | ||
1998 | cindex:[building Exim,overriding default settings] | |
1999 | If you need to change any of the values that are set in _OS/Makefile-Default_ | |
2000 | or in _OS/Makefile-<ostype>_, or to add any new definitions, you do not | |
2001 | need to change the original files. Instead, you should make the changes by | |
2002 | putting the new values in an appropriate _Local_ file. For example, | |
2003 | cindex:[Tru64-Unix build-time settings] | |
2004 | when building Exim in many releases of the Tru64-Unix (formerly Digital UNIX, | |
2005 | formerly DEC-OSF1) operating system, it is necessary to specify that the C | |
2006 | compiler is called 'cc' rather than 'gcc'. Also, the compiler must be | |
2007 | called with the option %-std1%, to make it recognize some of the features of | |
2008 | Standard C that Exim uses. (Most other compilers recognize Standard C by | |
2009 | default.) To do this, you should create a file called _Local/Makefile-OSF1_ | |
2010 | containing the lines | |
2011 | ||
2012 | CC=cc | |
2013 | CFLAGS=-std1 | |
2014 | ||
2015 | If you are compiling for just one operating system, it may be easier to put | |
2016 | these lines directly into _Local/Makefile_. | |
2017 | ||
2018 | Keeping all your local configuration settings separate from the distributed | |
2019 | files makes it easy to transfer them to new versions of Exim simply by copying | |
2020 | the contents of the _Local_ directory. | |
2021 | ||
2022 | ||
2023 | cindex:[NIS lookup type,including support for] | |
2024 | cindex:[NIS+ lookup type,including support for] | |
2025 | cindex:[LDAP,including support for] | |
2026 | cindex:[lookup,inclusion in binary] | |
2027 | Exim contains support for doing LDAP, NIS, NIS+, and other kinds of file | |
2028 | lookup, but not all systems have these components installed, so the default is | |
2029 | not to include the relevant code in the binary. All the different kinds of file | |
2030 | and database lookup that Exim supports are implemented as separate code modules | |
2031 | which are included only if the relevant compile-time options are set. In the | |
2032 | case of LDAP, NIS, and NIS+, the settings for _Local/Makefile_ are: | |
2033 | ||
2034 | LOOKUP_LDAP=yes | |
2035 | LOOKUP_NIS=yes | |
2036 | LOOKUP_NISPLUS=yes | |
2037 | ||
2038 | and similar settings apply to the other lookup types. They are all listed in | |
068aaea8 | 2039 | _src/EDITME_. In many cases the relevant include files and interface |
168e428f PH |
2040 | libraries need to be installed before compiling Exim. |
2041 | cindex:[cdb,including support for] | |
068aaea8 PH |
2042 | However, there are some optional lookup types (such as cdb) for which |
2043 | the code is entirely contained within Exim, and no external include | |
168e428f PH |
2044 | files or libraries are required. When a lookup type is not included in the |
2045 | binary, attempts to configure Exim to use it cause run time configuration | |
2046 | errors. | |
2047 | ||
2048 | cindex:[Perl,including support for] | |
2049 | Exim can be linked with an embedded Perl interpreter, allowing Perl | |
2050 | subroutines to be called during string expansion. To enable this facility, | |
2051 | ||
2052 | EXIM_PERL=perl.o | |
2053 | ||
2054 | must be defined in _Local/Makefile_. Details of this facility are given in | |
2055 | chapter <<CHAPperl>>. | |
2056 | ||
2057 | cindex:[X11 libraries, location of] | |
2058 | The location of the X11 libraries is something that varies a lot between | |
068aaea8 | 2059 | operating systems, and there may be different versions of X11 to cope |
168e428f PH |
2060 | with. Exim itself makes no use of X11, but if you are compiling the Exim |
2061 | monitor, the X11 libraries must be available. | |
2062 | The following three variables are set in _OS/Makefile-Default_: | |
2063 | ||
2064 | X11=/usr/X11R6 | |
2065 | XINCLUDE=-I$(X11)/include | |
2066 | XLFLAGS=-L$(X11)/lib | |
2067 | ||
2068 | These are overridden in some of the operating-system configuration files. For | |
2069 | example, in _OS/Makefile-SunOS5_ there is | |
2070 | ||
2071 | X11=/usr/openwin | |
2072 | XINCLUDE=-I$(X11)/include | |
2073 | XLFLAGS=-L$(X11)/lib -R$(X11)/lib | |
2074 | ||
2075 | If you need to override the default setting for your operating system, place a | |
2076 | definition of all three of these variables into your | |
2077 | _Local/Makefile-<ostype>_ file. | |
2078 | ||
2079 | cindex:[EXTRALIBS] | |
2080 | If you need to add any extra libraries to the link steps, these can be put in a | |
2081 | variable called EXTRALIBS, which appears in all the link commands, but by | |
2082 | default is not defined. In contrast, EXTRALIBS_EXIM is used only on the | |
2083 | command for linking the main Exim binary, and not for any associated utilities. | |
2084 | ||
2085 | cindex:[DBM libraries, configuration for building] | |
2086 | There is also DBMLIB, which appears in the link commands for binaries that | |
2087 | use DBM functions (see also section <<SECTdb>>). Finally, there is | |
2088 | EXTRALIBS_EXIMON, which appears only in the link step for the Exim monitor | |
2089 | binary, and which can be used, for example, to include additional X11 | |
2090 | libraries. | |
2091 | ||
2092 | cindex:[configuration file,editing] | |
2093 | The make file copes with rebuilding Exim correctly if any of the configuration | |
2094 | files are edited. However, if an optional configuration file is deleted, it is | |
2095 | necessary to touch the associated non-optional file (that is, _Local/Makefile_ | |
2096 | or _Local/eximon.conf_) before rebuilding. | |
2097 | ||
2098 | ||
2099 | OS-specific header files | |
2100 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
2101 | cindex:[_os.h_] | |
2102 | cindex:[building Exim,OS-specific C header files] | |
2103 | The _OS_ directory contains a number of files with names of the form | |
2104 | _os.h-<ostype>_. These are system-specific C header files that should not | |
2105 | normally need to be changed. There is a list of macro settings that are | |
2106 | recognized in the file _OS/os.configuring_, which should be consulted if you | |
2107 | are porting Exim to a new operating system. | |
2108 | ||
2109 | ||
2110 | ||
2111 | Overriding build-time options for the monitor | |
2112 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
2113 | cindex:[building Eximon,overriding default options] | |
2114 | A similar process is used for overriding things when building the Exim monitor, | |
2115 | where the files that are involved are | |
2116 | ||
2117 | &&& | |
2118 | _OS/eximon.conf-Default_ | |
2119 | _OS/eximon.conf-_<'ostype'> | |
2120 | _Local/eximon.conf_ | |
2121 | _Local/eximon.conf-_<'ostype'> | |
2122 | _Local/eximon.conf-_<'archtype'> | |
2123 | _Local/eximon.conf-_<'ostype'>-<'archtype'> | |
2124 | &&& | |
2125 | ||
2126 | cindex:[_Local/eximon.conf_] | |
2127 | As with Exim itself, the final three files need not exist, and in this case the | |
2128 | _OS/eximon.conf-<ostype>_ file is also optional. The default values in | |
2129 | _OS/eximon.conf-Default_ can be overridden dynamically by setting environment | |
2130 | variables of the same name, preceded by EXIMON_. For example, setting | |
2131 | EXIMON_LOG_DEPTH in the environment overrides the value of | |
2132 | LOG_DEPTH at run time. | |
2133 | ||
2134 | ||
2135 | ||
2136 | ||
2137 | Installing Exim binaries and scripts | |
2138 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
2139 | cindex:[installing Exim] | |
2140 | cindex:[BIN_DIRECTORY] | |
068aaea8 PH |
2141 | The command 'make install' runs the 'exim_install' script with no arguments. |
2142 | The script copies binaries and utility scripts into the directory whose name is | |
2143 | specified by the BIN_DIRECTORY setting in _Local/Makefile_. | |
2144 | cindex:[setuid,installing Exim with] | |
2145 | The install script copies files only if they are newer than the files they are | |
2146 | going to replace. The Exim binary is required to be owned by root and have the | |
2147 | 'setuid' bit set, for normal configurations. Therefore, you must run 'make | |
2148 | install' as root so that it can set up the Exim binary in this way. However, in | |
2149 | some special situations (for example, if a host is doing no local deliveries) | |
2150 | it may be possible to run Exim without making the binary setuid root (see | |
2151 | chapter <<CHAPsecurity>> for details). | |
168e428f PH |
2152 | |
2153 | cindex:[CONFIGURE_FILE] | |
2154 | Exim's run time configuration file is named by the CONFIGURE_FILE setting | |
2155 | in _Local/Makefile_. If this names a single file, and the file does not | |
2156 | exist, the default configuration file _src/configure.default_ is copied there | |
2157 | by the installation script. If a run time configuration file already exists, it | |
2158 | is left alone. If CONFIGURE_FILE is a colon-separated list, naming several | |
2159 | alternative files, no default is installed. | |
2160 | ||
2161 | cindex:[system aliases file] | |
2162 | cindex:[_/etc/aliases_] | |
2163 | One change is made to the default configuration file when it is installed: the | |
2164 | default configuration contains a router that references a system aliases file. | |
2165 | The path to this file is set to the value specified by | |
2166 | SYSTEM_ALIASES_FILE in _Local/Makefile_ (_/etc/aliases_ by default). | |
2167 | If the system aliases file does not exist, the installation script creates it, | |
2168 | and outputs a comment to the user. | |
2169 | ||
2170 | The created file contains no aliases, but it does contain comments about the | |
2171 | aliases a site should normally have. Mail aliases have traditionally been | |
2172 | kept in _/etc/aliases_. However, some operating systems are now using | |
2173 | _/etc/mail/aliases_. You should check if yours is one of these, and change | |
2174 | Exim's configuration if necessary. | |
2175 | ||
2176 | The default configuration uses the local host's name as the only local domain, | |
2177 | and is set up to do local deliveries into the shared directory _/var/mail_, | |
2178 | running as the local user. System aliases and _.forward_ files in users' home | |
2179 | directories are supported, but no NIS or NIS+ support is configured. Domains | |
2180 | other than the name of the local host are routed using the DNS, with delivery | |
2181 | over SMTP. | |
2182 | ||
168e428f PH |
2183 | It is possible to install Exim for special purposes (such as building a binary |
2184 | distribution) in a private part of the file system. You can do this by a | |
2185 | command such as | |
2186 | ||
2187 | make DESTDIR=/some/directory/ install | |
2188 | ||
2189 | This has the effect of pre-pending the specified directory to all the file | |
2190 | paths, except the name of the system aliases file that appears in the default | |
2191 | configuration. (If a default alias file is created, its name 'is' modified.) | |
2192 | For backwards compatibility, ROOT is used if DESTDIR is not set, | |
2193 | but this usage is deprecated. | |
2194 | ||
2195 | cindex:[installing Exim,what is not installed] | |
2196 | Running 'make install' does not copy the Exim 4 conversion script | |
2197 | 'convert4r4', or the 'pcretest' test program. You will probably run the | |
2198 | first of these only once (if you are upgrading from Exim 3), and the second | |
2199 | isn't really part of Exim. None of the documentation files in the _doc_ | |
2200 | directory are copied, except for the info files when you have set | |
2201 | INFO_DIRECTORY, as described in section <<SECTinsinfdoc>> below. | |
2202 | ||
2203 | For the utility programs, old versions are renamed by adding the suffix _.O_ | |
2204 | to their names. The Exim binary itself, however, is handled differently. It is | |
2205 | installed under a name that includes the version number and the compile number, | |
2206 | for example _exim-{version}-1_. The script then arranges for a symbolic link | |
2207 | called _exim_ to point to the binary. If you are updating a previous version | |
2208 | of Exim, the script takes care to ensure that the name _exim_ is never absent | |
2209 | from the directory (as seen by other processes). | |
2210 | ||
2211 | cindex:[installing Exim,testing the script] | |
2212 | If you want to see what the 'make install' will do before running it for | |
2213 | real, you can pass the %-n% option to the installation script by this command: | |
2214 | ||
2215 | make INSTALL_ARG=-n install | |
2216 | ||
2217 | The contents of the variable INSTALL_ARG are passed to the installation | |
2218 | script. You do not need to be root to run this test. Alternatively, you can run | |
2219 | the installation script directly, but this must be from within the build | |
2220 | directory. For example, from the top-level Exim directory you could use this | |
2221 | command: | |
2222 | ||
2223 | (cd build-SunOS5-5.5.1-sparc; ../scripts/exim_install -n) | |
2224 | ||
2225 | cindex:[installing Exim,install script options] | |
2226 | There are two other options that can be supplied to the installation script. | |
2227 | ||
2228 | - %-no_chown% bypasses the call to change the owner of the installed binary | |
2229 | to root, and the call to make it a setuid binary. | |
2230 | ||
2231 | - %-no_symlink% bypasses the setting up of the symbolic link _exim_ to the | |
2232 | installed binary. | |
2233 | ||
2234 | INSTALL_ARG can be used to pass these options to the script. For example: | |
2235 | ||
2236 | make INSTALL_ARG=-no_symlink install | |
2237 | ||
2238 | ||
2239 | The installation script can also be given arguments specifying which files are | |
2240 | to be copied. For example, to install just the Exim binary, and nothing else, | |
2241 | without creating the symbolic link, you could use: | |
2242 | ||
2243 | make INSTALL_ARG='-no_symlink exim' install | |
2244 | ||
2245 | ||
2246 | ||
2247 | ||
2248 | [[SECTinsinfdoc]] | |
2249 | Installing info documentation | |
2250 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
2251 | cindex:[installing Exim,'info' documentation] | |
2252 | Not all systems use the GNU 'info' system for documentation, and for this | |
2253 | reason, the Texinfo source of Exim's documentation is not included in the main | |
2254 | distribution. Instead it is available separately from the ftp site (see section | |
2255 | <<SECTavail>>). | |
2256 | ||
2257 | If you have defined INFO_DIRECTORY in _Local/Makefile_ and the Texinfo | |
2258 | source of the documentation is found in the source tree, running 'make | |
2259 | install' automatically builds the info files and installs them. | |
2260 | ||
2261 | ||
2262 | ||
2263 | Setting up the spool directory | |
2264 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
2265 | cindex:[spool directory,creating] | |
2266 | When it starts up, Exim tries to create its spool directory if it does not | |
2267 | exist. The Exim uid and gid are used for the owner and group of the spool | |
2268 | directory. Sub-directories are automatically created in the spool directory as | |
2269 | necessary. | |
2270 | ||
2271 | ||
2272 | ||
2273 | ||
2274 | Testing | |
2275 | ~~~~~~~ | |
2276 | cindex:[testing,installation] | |
2277 | Having installed Exim, you can check that the run time configuration file is | |
2278 | syntactically valid by running the following command, which assumes that the | |
2279 | Exim binary directory is within your PATH environment variable: | |
2280 | ||
2281 | exim -bV | |
2282 | ||
2283 | If there are any errors in the configuration file, Exim outputs error messages. | |
2284 | Otherwise it outputs the version number and build date, | |
2285 | the DBM library that is being used, and information about which drivers and | |
2286 | other optional code modules are included in the binary. | |
2287 | Some simple routing tests can be done by using the address testing option. For | |
2288 | example, | |
2289 | ||
2290 | exim -bt <local username> | |
2291 | ||
2292 | should verify that it recognizes a local mailbox, and | |
2293 | ||
2294 | exim -bt <remote address> | |
2295 | ||
2296 | a remote one. Then try getting it to deliver mail, both locally and remotely. | |
2297 | This can be done by passing messages directly to Exim, without going through a | |
2298 | user agent. For example: | |
2299 | ||
068aaea8 PH |
2300 | .... |
2301 | exim -v postmaster@your.domain.example | |
2302 | From: user@your.domain.example | |
2303 | To: postmaster@your.domain.example | |
2304 | Subject: Testing Exim | |
168e428f | 2305 | |
068aaea8 PH |
2306 | This is a test message. |
2307 | ^D | |
2308 | .... | |
168e428f PH |
2309 | |
2310 | The %-v% option causes Exim to output some verification of what it is doing. | |
2311 | In this case you should see copies of three log lines, one for the message's | |
2312 | arrival, one for its delivery, and one containing ``Completed''. | |
2313 | ||
2314 | cindex:[delivery,problems with] | |
2315 | If you encounter problems, look at Exim's log files ('mainlog' and | |
2316 | 'paniclog') to see if there is any relevant information there. Another source | |
2317 | of information is running Exim with debugging turned on, by specifying the | |
2318 | %-d% option. If a message is stuck on Exim's spool, you can force a delivery | |
2319 | with debugging turned on by a command of the form | |
2320 | ||
2321 | exim -d -M <message-id> | |
2322 | ||
2323 | You must be root or an ``admin user'' in order to do this. The %-d% option | |
2324 | produces rather a lot of output, but you can cut this down to specific areas. | |
2325 | For example, if you use %-d-all+route% only the debugging information relevant | |
2326 | to routing is included. (See the %-d% option in chapter <<CHAPcommandline>> for | |
2327 | more details.) | |
2328 | ||
2329 | cindex:[``sticky'' bit] | |
2330 | cindex:[lock files] | |
2331 | One specific problem that has shown up on some sites is the inability to do | |
2332 | local deliveries into a shared mailbox directory, because it does not have the | |
2333 | ``sticky bit'' set on it. By default, Exim tries to create a lock file before | |
2334 | writing to a mailbox file, and if it cannot create the lock file, the delivery | |
2335 | is deferred. You can get round this either by setting the ``sticky bit'' on the | |
2336 | directory, or by setting a specific group for local deliveries and allowing | |
2337 | that group to create files in the directory (see the comments above the | |
2338 | ^local_delivery^ transport in the default configuration file). Another | |
2339 | approach is to configure Exim not to use lock files, but just to rely on | |
2340 | 'fcntl()' locking instead. However, you should do this only if all user | |
2341 | agents also use 'fcntl()' locking. For further discussion of locking issues, | |
2342 | see chapter <<CHAPappendfile>>. | |
2343 | ||
2344 | One thing that cannot be tested on a system that is already running an MTA is | |
2345 | the receipt of incoming SMTP mail on the standard SMTP port. However, the | |
2346 | %-oX% option can be used to run an Exim daemon that listens on some other | |
2347 | port, or 'inetd' can be used to do this. The %-bh% option and the | |
2348 | 'exim_checkaccess' utility can be used to check out policy controls on | |
2349 | incoming SMTP mail. | |
2350 | ||
2351 | Testing a new version on a system that is already running Exim can most easily | |
2352 | be done by building a binary with a different CONFIGURE_FILE setting. From | |
2353 | within the run time configuration, all other file and directory names | |
2354 | that Exim uses can be altered, in order to keep it entirely clear of the | |
2355 | production version. | |
2356 | ||
2357 | ||
2358 | Replacing another MTA with Exim | |
2359 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
2360 | cindex:[replacing another MTA] | |
2361 | Building and installing Exim for the first time does not of itself put it in | |
2362 | general use. The name by which the system's MTA is called by mail user agents | |
2363 | is either _/usr/sbin/sendmail_, or _/usr/lib/sendmail_ (depending on the | |
2364 | operating system), and it is necessary to make this name point to the 'exim' | |
2365 | binary in order to get the user agents to pass messages to Exim. This is | |
2366 | normally done by renaming any existing file and making _/usr/sbin/sendmail_ | |
2367 | or _/usr/lib/sendmail_ | |
2368 | ||
2369 | cindex:[symbolic link,to 'exim' binary] | |
2370 | a symbolic link to the 'exim' binary. It is a good idea to remove any setuid | |
2371 | privilege and executable status from the old MTA. It is then necessary to stop | |
2372 | and restart the mailer daemon, if one is running. | |
2373 | ||
2374 | cindex:[FreeBSD, MTA indirection] | |
2375 | cindex:[_/etc/mail/mailer.conf_] | |
2376 | Some operating systems have introduced alternative ways of switching MTAs. For | |
2377 | example, if you are running FreeBSD, you need to edit the file | |
2378 | _/etc/mail/mailer.conf_ instead of setting up a symbolic link as just | |
2379 | described. A typical example of the contents of this file for running Exim is | |
2380 | as follows: | |
2381 | ||
2382 | sendmail /usr/exim/bin/exim | |
2383 | send-mail /usr/exim/bin/exim | |
2384 | mailq /usr/exim/bin/exim -bp | |
2385 | newaliases /usr/bin/true | |
2386 | ||
2387 | ||
2388 | Once you have set up the symbolic link, or edited _/etc/mail/mailer.conf_, | |
2389 | your Exim installation is ``live''. Check it by sending a message from your | |
2390 | favourite user agent. | |
2391 | ||
2392 | You should consider what to tell your users about the change of MTA. Exim may | |
2393 | have different capabilities to what was previously running, and there are | |
2394 | various operational differences such as the text of messages produced by | |
2395 | command line options and in bounce messages. If you allow your users to make | |
2396 | use of Exim's filtering capabilities, you should make the document entitled | |
2397 | 'Exim's interface to mail filtering' | |
2398 | available to them. | |
2399 | ||
2400 | ||
2401 | ||
2402 | Upgrading Exim | |
2403 | ~~~~~~~~~~~~~~ | |
2404 | cindex:[upgrading Exim] | |
2405 | If you are already running Exim on your host, building and installing a new | |
2406 | version automatically makes it available to MUAs, or any other programs that | |
2407 | call the MTA directly. However, if you are running an Exim daemon, you do need | |
2408 | to send it a HUP signal, to make it re-exec itself, and thereby pick up the new | |
2409 | binary. You do not need to stop processing mail in order to install a new | |
068aaea8 PH |
2410 | version of Exim. The install script does not modify an existing runtime |
2411 | configuration file. | |
2412 | ||
168e428f PH |
2413 | |
2414 | ||
2415 | ||
2416 | Stopping the Exim daemon on Solaris | |
2417 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
2418 | cindex:[Solaris,stopping Exim on] | |
2419 | The standard command for stopping the mailer daemon on Solaris is | |
2420 | ||
2421 | /etc/init.d/sendmail stop | |
2422 | ||
2423 | If _/usr/lib/sendmail_ has been turned into a symbolic link, this script | |
2424 | fails to stop Exim because it uses the command 'ps -e' and greps the output | |
2425 | for the text ``sendmail''; this is not present because the actual program name | |
2426 | (that is, ``exim'') is given by the 'ps' command with these options. A solution | |
2427 | is to replace the line that finds the process id with something like | |
2428 | ||
2429 | pid=`cat /var/spool/exim/exim-daemon.pid` | |
2430 | ||
2431 | to obtain the daemon's pid directly from the file that Exim saves it in. | |
2432 | ||
2433 | Note, however, that stopping the daemon does not ``stop Exim''. Messages can | |
2434 | still be received from local processes, and if automatic delivery is configured | |
2435 | (the normal case), deliveries will still occur. | |
2436 | ||
2437 | ||
2438 | ||
2439 | ||
2440 | //////////////////////////////////////////////////////////////////////////// | |
2441 | //////////////////////////////////////////////////////////////////////////// | |
2442 | ||
2443 | [[CHAPcommandline]] | |
2444 | The Exim command line | |
2445 | --------------------- | |
2446 | cindex:[command line,options] | |
2447 | cindex:[options,command line] | |
2448 | Exim's command line takes the standard Unix form of a sequence of options, | |
2449 | each starting with a hyphen character, followed by a number of arguments. The | |
2450 | options are compatible with the main options of Sendmail, and there are also | |
2451 | some additional options, some of which are compatible with Smail 3. Certain | |
2452 | combinations of options do not make sense, and provoke an error if used. | |
2453 | The form of the arguments depends on which options are set. | |
2454 | ||
2455 | ||
2456 | Setting options by program name | |
2457 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
2458 | cindex:['mailq'] | |
2459 | If Exim is called under the name 'mailq', it behaves as if the option %-bp% | |
2460 | were present before any other options. | |
2461 | The %-bp% option requests a listing of the contents of the mail queue on the | |
2462 | standard output. | |
2463 | This feature is for compatibility with some systems that contain a command of | |
2464 | that name in one of the standard libraries, symbolically linked to | |
2465 | _/usr/sbin/sendmail_ or _/usr/lib/sendmail_. | |
2466 | ||
2467 | cindex:['rsmtp'] | |
2468 | If Exim is called under the name 'rsmtp' it behaves as if the option %-bS% | |
2469 | were present before any other options, for compatibility with Smail. The %-bS% | |
2470 | option is used for reading in a number of messages in batched SMTP format. | |
2471 | ||
2472 | cindex:['rmail'] | |
2473 | If Exim is called under the name 'rmail' it behaves as if the %-i% and | |
2474 | %-oee% options were present before any other options, for compatibility with | |
2475 | Smail. The name 'rmail' is used as an interface by some UUCP systems. | |
2476 | ||
2477 | cindex:['runq'] | |
2478 | cindex:[queue runner] | |
2479 | If Exim is called under the name 'runq' it behaves as if the option %-q% were | |
2480 | present before any other options, for compatibility with Smail. The %-q% | |
2481 | option causes a single queue runner process to be started. | |
2482 | ||
2483 | cindex:['newaliases'] | |
2484 | cindex:[alias file,building] | |
2485 | cindex:[Sendmail compatibility,calling Exim as 'newaliases'] | |
2486 | If Exim is called under the name 'newaliases' it behaves as if the option | |
2487 | %-bi% were present before any other options, for compatibility with Sendmail. | |
2488 | This option is used for rebuilding Sendmail's alias file. Exim does not have | |
2489 | the concept of a single alias file, but can be configured to run a given | |
2490 | command if called with the %-bi% option. | |
2491 | ||
2492 | ||
2493 | [[SECTtrustedadmin]] | |
2494 | Trusted and admin users | |
2495 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
2496 | Some Exim options are available only to 'trusted users' and others are | |
2497 | available only to 'admin users'. In the description below, the phrases ``Exim | |
2498 | user'' and ``Exim group'' mean the user and group defined by EXIM_USER and | |
2499 | EXIM_GROUP in _Local/Makefile_ or set by the %exim_user% and | |
2500 | %exim_group% options. These do not necessarily have to use the name ``exim''. | |
2501 | ||
2502 | - cindex:[trusted user,definition of] | |
2503 | cindex:[user, trusted definition of] | |
2504 | The trusted users are root, the Exim user, any user listed in the | |
2505 | %trusted_users% configuration option, and any user whose current group or any | |
2506 | supplementary group is one of those listed in the %trusted_groups% | |
2507 | configuration option. Note that the Exim group is not automatically trusted. | |
2508 | + | |
2509 | cindex:[``From'' line] | |
2510 | cindex:[envelope sender] | |
2511 | Trusted users are always permitted to use the %-f% option or a leading ``From '' | |
2512 | line to specify the envelope sender of a message that is passed to Exim through | |
2513 | the local interface (see the %-bm% and %-f% options below). See the | |
2514 | %untrusted_set_sender% option for a way of permitting non-trusted users to | |
2515 | set envelope senders. | |
2516 | + | |
2517 | cindex:['From:' header line] | |
2518 | cindex:['Sender:' header line] | |
2519 | For a trusted user, there is never any check on the contents of the 'From:' | |
2520 | header line, and a 'Sender:' line is never added. Furthermore, any existing | |
2521 | 'Sender:' line in incoming local (non-TCP/IP) messages is not removed. | |
2522 | + | |
2523 | Trusted users may also specify a host name, host address, interface address, | |
2524 | protocol name, ident value, and authentication data when submitting a message | |
2525 | locally. Thus, they are able to insert messages into Exim's queue locally that | |
2526 | have the characteristics of messages received from a remote host. Untrusted | |
2527 | users may in some circumstances use %-f%, but can never set the other values | |
2528 | that are available to trusted users. | |
2529 | ||
2530 | - cindex:[user, admin definition of] | |
2531 | cindex:[admin user,definition of] | |
2532 | The admin users are root, the Exim user, and any user that is a member of the | |
2533 | Exim group or of any group listed in the %admin_groups% configuration option. | |
2534 | The current group does not have to be one of these groups. | |
2535 | + | |
2536 | Admin users are permitted to list the queue, and to carry out certain | |
2537 | operations on messages, for example, to force delivery failures. It is also | |
2538 | necessary to be an admin user in order to see the full information provided by | |
2539 | the Exim monitor, and full debugging output. | |
2540 | + | |
2541 | By default, the use of the %-M%, %-q%, %-R%, and %-S% options to cause Exim | |
2542 | to attempt delivery of messages on its queue is restricted to admin users. | |
2543 | However, this restriction can be relaxed by setting the %prod_requires_admin% | |
2544 | option false (that is, specifying %no_prod_requires_admin%). | |
2545 | + | |
2546 | Similarly, the use of the %-bp% option to list all the messages in the queue | |
2547 | is restricted to admin users unless %queue_list_requires_admin% is set | |
2548 | false. | |
2549 | ||
2550 | ||
2551 | *Warning*: If you configure your system so that admin users are able to | |
2552 | edit Exim's configuration file, you are giving those users an easy way of | |
2553 | getting root. There is further discussion of this issue at the start of chapter | |
2554 | <<CHAPconf>>. | |
2555 | ||
2556 | ||
2557 | ||
2558 | ||
2559 | Command line options | |
2560 | ~~~~~~~~~~~~~~~~~~~~ | |
2561 | The command options are described in alphabetical order below. | |
2562 | ||
2563 | /// | |
2564 | We insert a stylized DocBook comment here, to identify the start of the command | |
2565 | line options. This is for the benefit of the Perl script that automatically | |
2566 | creates a man page for the options. | |
2567 | /// | |
2568 | ||
2569 | ++++ | |
2570 | <!-- === Start of command line options === --> | |
2571 | ++++ | |
2572 | ||
2573 | ||
2574 | *{hh}*:: | |
2575 | oindex:[{hh}] | |
2576 | cindex:[options, command line; terminating] | |
2577 | This is a pseudo-option whose only purpose is to terminate the options and | |
2578 | therefore to cause subsequent command line items to be treated as arguments | |
2579 | rather than options, even if they begin with hyphens. | |
2580 | ||
2581 | *--help*:: | |
2582 | oindex:[%{hh}help%] | |
2583 | This option causes Exim to output a few sentences stating what it is. | |
2584 | The same output is generated if the Exim binary is called with no options and | |
2585 | no arguments. | |
2586 | ||
2587 | *-B*<'type'>:: | |
2588 | oindex:[%-B%] | |
2589 | cindex:[8-bit characters] | |
2590 | cindex:[Sendmail compatibility,8-bit characters] | |
2591 | This is a Sendmail option for selecting 7 or 8 bit processing. Exim is 8-bit | |
2592 | clean; it ignores this option. | |
2593 | ||
2594 | *-bd*:: | |
2595 | oindex:[%-bd%] | |
2596 | cindex:[daemon] | |
2597 | cindex:[SMTP listener] | |
2598 | cindex:[queue runner] | |
2599 | This option runs Exim as a daemon, awaiting incoming SMTP connections. Usually | |
2600 | the %-bd% option is combined with the %-q%<'time'> option, to specify that | |
2601 | the daemon should also initiate periodic queue runs. | |
2602 | + | |
2603 | The %-bd% option can be used only by an admin user. If either of the %-d% | |
2604 | (debugging) or %-v% (verifying) options are set, the daemon does not | |
2605 | disconnect from the controlling terminal. When running this way, it can be | |
2606 | stopped by pressing ctrl-C. | |
2607 | + | |
2608 | By default, Exim listens for incoming connections to the standard SMTP port on | |
2609 | all the host's running interfaces. However, it is possible to listen on other | |
2610 | ports, on multiple ports, and only on specific interfaces. Chapter | |
2611 | <<CHAPinterfaces>> contains a description of the options that control this. | |
2612 | + | |
2613 | When a listening daemon | |
2614 | cindex:[daemon,process id (pid)] | |
2615 | cindex:[pid (process id),of daemon] | |
2616 | is started without the use of %-oX% (that is, without overriding the normal | |
2617 | configuration), it writes its process id to a file called _exim-daemon.pid_ in | |
2618 | Exim's spool directory. This location can be overridden by setting | |
2619 | PID_FILE_PATH in _Local/Makefile_. The file is written while Exim is still | |
2620 | running as root. | |
2621 | + | |
2622 | When %-oX% is used on the command line to start a listening daemon, the | |
2623 | process id is not written to the normal pid file path. However, %-oP% can be | |
2624 | used to specify a path on the command line if a pid file is required. | |
2625 | + | |
2626 | The SIGHUP signal | |
2627 | cindex:[SIGHUP] | |
2628 | can be used to cause the daemon to re-exec itself. This should be done whenever | |
2629 | Exim's configuration file, or any file that is incorporated into it by means of | |
2630 | the %.include% facility, is changed, and also whenever a new version of Exim is | |
2631 | installed. It is not necessary to do this when other files that are referenced | |
2632 | from the configuration (for example, alias files) are changed, because these | |
2633 | are reread each time they are used. | |
2634 | ||
2635 | *-bdf*:: | |
2636 | oindex:[%-bdf%] | |
2637 | This option has the same effect as %-bd% except that it never disconnects from | |
2638 | the controlling terminal, even when no debugging is specified. | |
2639 | ||
2640 | *-be*:: | |
2641 | oindex:[%-be%] | |
2642 | cindex:[testing,string expansion] | |
2643 | cindex:[expansion,testing] | |
2644 | Run Exim in expansion testing mode. Exim discards its root privilege, to | |
2645 | prevent ordinary users from using this mode to read otherwise inaccessible | |
2646 | files. If no arguments are given, Exim runs interactively, prompting for lines | |
2647 | of data. | |
2648 | + | |
2649 | If Exim was built with USE_READLINE=yes in _Local/Makefile_, it tries | |
2650 | to load the %libreadline% library dynamically whenever the %-be% option is | |
2651 | used without command line arguments. If successful, it uses the 'readline()' | |
2652 | function, which provides extensive line-editing facilities, for reading the | |
2653 | test data. A line history is supported. | |
2654 | + | |
2655 | Long expansion expressions can be split over several lines by using backslash | |
068aaea8 | 2656 | continuations. As in Exim's run time configuration, white space at the start of |
168e428f PH |
2657 | continuation lines is ignored. Each argument or data line is passed through the |
2658 | string expansion mechanism, and the result is output. Variable values from the | |
2659 | configuration file (for example, $qualify_domain$) are available, but no | |
2660 | message-specific values (such as $domain$) are set, because no message is | |
2661 | being processed. | |
2662 | ||
2663 | *-bF*~<'filename'>:: | |
2664 | oindex:[%-bF%] | |
2665 | cindex:[system filter,testing] | |
2666 | cindex:[testing,system filter] | |
2667 | This option is the same as %-bf% except that it assumes that the filter being | |
2668 | tested is a system filter. The additional commands that are available only in | |
2669 | system filters are recognized. | |
2670 | ||
2671 | *-bf*~<'filename'>:: | |
2672 | oindex:[%-bf%] | |
2673 | cindex:[filter,testing] | |
2674 | cindex:[testing,filter file] | |
2675 | cindex:[forward file,testing] | |
2676 | cindex:[testing,forward file] | |
2677 | cindex:[Sieve filter,testing] | |
2678 | This option runs Exim in user filter testing mode; the file is the filter file | |
2679 | to be tested, and a test message must be supplied on the standard input. If | |
2680 | there are no message-dependent tests in the filter, an empty file can be | |
2681 | supplied. | |
2682 | + | |
2683 | If you want to test a system filter file, use %-bF% instead of %-bf%. You can | |
2684 | use both %-bF% and %-bf% on the same command, in order to | |
2685 | test a system filter and a user filter in the same run. For example: | |
2686 | ||
2687 | exim -bF /system/filter -bf /user/filter </test/message | |
2688 | + | |
2689 | This is helpful when the system filter adds header lines or sets filter | |
2690 | variables that are used by the user filter. | |
2691 | + | |
2692 | If the test filter file does not begin with one of the special lines | |
2693 | ||
2694 | # Exim filter | |
2695 | # Sieve filter | |
2696 | + | |
2697 | it is taken to be a normal _.forward_ file, and is tested for validity under | |
2698 | that interpretation. See sections <<SECTitenonfilred>> to <<SECTspecitredli>> for a | |
2699 | description of the possible contents of non-filter redirection lists. | |
2700 | + | |
2701 | The result of an Exim command that uses %-bf%, provided no errors are | |
2702 | detected, is a list of the actions that Exim would try to take if presented | |
2703 | with the message for real. More details of filter testing are given in the | |
2704 | separate document entitled 'Exim's interfaces to mail filtering'. | |
2705 | + | |
2706 | When testing a filter file, | |
2707 | cindex:[``From'' line] | |
2708 | cindex:[envelope sender] | |
2709 | cindex:[%-f% option,for filter testing] | |
2710 | the envelope sender can be set by the %-f% option, | |
2711 | or by a ``From '' line at the start of the test message. Various parameters that | |
2712 | would normally be taken from the envelope recipient address of the message can | |
2713 | be set by means of additional command line options (see the next four options). | |
2714 | ||
2715 | *-bfd*~<'domain'>:: | |
2716 | oindex:[%-bfd%] | |
068aaea8 | 2717 | cindex:[$qualify_domain$] |
168e428f PH |
2718 | This sets the domain of the recipient address when a filter file is being |
2719 | tested by means of the %-bf% option. The default is the value of | |
2720 | $qualify_domain$. | |
2721 | ||
2722 | *-bfl*~<'local~part'>:: | |
2723 | oindex:[%-bfl%] | |
2724 | This sets the local part of the recipient address when a filter file is being | |
2725 | tested by means of the %-bf% option. The default is the username of the | |
2726 | process that calls Exim. A local part should be specified with any prefix or | |
2727 | suffix stripped, because that is how it appears to the filter when a message is | |
2728 | actually being delivered. | |
2729 | ||
2730 | *-bfp*~<'prefix'>:: | |
2731 | oindex:[%-bfp%] | |
2732 | This sets the prefix of the local part of the recipient address when a filter | |
2733 | file is being tested by means of the %-bf% option. The default is an empty | |
2734 | prefix. | |
2735 | ||
2736 | *-bfs*~<'suffix'>:: | |
2737 | oindex:[%-bfs%] | |
2738 | This sets the suffix of the local part of the recipient address when a filter | |
2739 | file is being tested by means of the %-bf% option. The default is an empty | |
2740 | suffix. | |
2741 | ||
2742 | *-bh*~<'IP~address'>:: | |
2743 | oindex:[%-bh%] | |
2744 | cindex:[testing,incoming SMTP] | |
2745 | cindex:[SMTP,testing incoming] | |
2746 | cindex:[testing,relay control] | |
2747 | cindex:[relaying,testing configuration] | |
2748 | cindex:[policy control,testing] | |
2749 | cindex:[debugging,%-bh% option] | |
2750 | This option runs a fake SMTP session as if from the given IP address, using the | |
2751 | standard input and output. The IP address may include a port number at the end, | |
2752 | after a full stop. For example: | |
2753 | ||
2754 | exim -bh 10.9.8.7.1234 | |
2755 | exim -bh fe80::a00:20ff:fe86:a061.5678 | |
2756 | + | |
2757 | When an IPv6 address is given, it is converted into canonical form. In the case | |
2758 | of the second example above, the value of $sender_host_address$ after | |
2759 | conversion to the canonical form is `fe80:0000:0000:0a00:20ff:fe86:a061.5678`. | |
2760 | + | |
2761 | Comments as to what is going on are written to the standard error file. These | |
2762 | include lines beginning with ``LOG'' for anything that would have been logged. | |
2763 | This facility is provided for testing configuration options for incoming | |
2764 | messages, to make sure they implement the required policy. For example, you can | |
2765 | test your relay controls using %-bh%. | |
2766 | + | |
2767 | *Warning 1*: | |
2768 | cindex:[RFC 1413] | |
2769 | You cannot test features of the configuration that rely on | |
2770 | ident (RFC 1413) callouts. These cannot be done when testing using | |
2771 | %-bh% because there is no incoming SMTP connection. | |
2772 | + | |
2773 | *Warning 2*: Address verification callouts (see section <<SECTcallver>>) are | |
2774 | also skipped when testing using %-bh%. If you want these callouts to occur, | |
2775 | use %-bhc% instead. | |
2776 | + | |
2777 | Messages supplied during the testing session are discarded, and nothing is | |
2778 | written to any of the real log files. There may be pauses when DNS (and other) | |
2779 | lookups are taking place, and of course these may time out. The %-oMi% option | |
2780 | can be used to specify a specific IP interface and port if this is important. | |
2781 | + | |
2782 | The 'exim_checkaccess' utility is a ``packaged'' version of %-bh% whose | |
2783 | output just states whether a given recipient address from a given host is | |
2784 | acceptable or not. See section <<SECTcheckaccess>>. | |
2785 | ||
2786 | *-bhc*~<'IP~address'>:: | |
2787 | oindex:[%-bhc%] | |
2788 | This option operates in the same way as %-bh%, except that address | |
2789 | verification callouts are performed if required. This includes consulting and | |
2790 | updating the callout cache database. | |
2791 | ||
2792 | *-bi*:: | |
2793 | oindex:[%-bi%] | |
2794 | cindex:[alias file,building] | |
2795 | cindex:[building alias file] | |
2796 | cindex:[Sendmail compatibility,%-bi% option] | |
2797 | Sendmail interprets the %-bi% option as a request to rebuild its alias file. | |
2798 | Exim does not have the concept of a single alias file, and so it cannot mimic | |
2799 | this behaviour. However, calls to _/usr/lib/sendmail_ with the %-bi% option | |
2800 | tend to appear in various scripts such as NIS make files, so the option must be | |
2801 | recognized. | |
2802 | + | |
2803 | If %-bi% is encountered, the command specified by the %bi_command% | |
2804 | configuration option is run, under the uid and gid of the caller of Exim. If | |
2805 | the %-oA% option is used, its value is passed to the command as an argument. | |
2806 | The command set by %bi_command% may not contain arguments. The command can use | |
2807 | the 'exim_dbmbuild' utility, or some other means, to rebuild alias files if | |
2808 | this is required. If the %bi_command% option is not set, calling Exim with | |
2809 | %-bi% is a no-op. | |
2810 | ||
2811 | *-bm*:: | |
2812 | oindex:[%-bm%] | |
2813 | cindex:[local message reception] | |
2814 | This option runs an Exim receiving process that accepts an incoming, | |
2815 | locally-generated message on the current input. The recipients are given as the | |
2816 | command arguments (except when %-t% is also present -- see below). Each | |
2817 | argument can be a comma-separated list of RFC 2822 addresses. This is the | |
2818 | default option for selecting the overall action of an Exim call; it is assumed | |
2819 | if no other conflicting option is present. | |
2820 | + | |
2821 | If any addresses in the message are unqualified (have no domain), they are | |
2822 | qualified by the values of the %qualify_domain% or %qualify_recipient% | |
2823 | options, as appropriate. The %-bnq% option (see below) provides a way of | |
2824 | suppressing this for special cases. | |
2825 | + | |
2826 | Policy checks on the contents of local messages can be enforced by means of | |
2827 | the non-SMTP ACL. See chapter <<CHAPACL>> for details. | |
2828 | + | |
2829 | The return code | |
2830 | cindex:[return code,for %-bm%] | |
2831 | is zero if the message is successfully accepted. Otherwise, the | |
2832 | action is controlled by the %-oe'x'% option setting -- see below. | |
2833 | + | |
2834 | The format | |
2835 | cindex:[message,format] | |
2836 | cindex:[format,message] | |
2837 | cindex:[``From'' line] | |
2838 | cindex:[UUCP,``From'' line] | |
2839 | cindex:[Sendmail compatibility,``From'' line] | |
2840 | of the message must be as defined in RFC 2822, except that, for | |
2841 | compatibility with Sendmail and Smail, a line in one of the forms | |
2842 | ||
2843 | From sender Fri Jan 5 12:55 GMT 1997 | |
2844 | From sender Fri, 5 Jan 97 12:55:01 | |
2845 | + | |
2846 | (with the weekday optional, and possibly with additional text after the date) | |
2847 | is permitted to appear at the start of the message. There appears to be no | |
2848 | authoritative specification of the format of this line. Exim recognizes it by | |
2849 | matching against the regular expression defined by the %uucp_from_pattern% | |
2850 | option, which can be changed if necessary. | |
2851 | + | |
2852 | The | |
2853 | cindex:[%-f% option,overriding ``From'' line] | |
2854 | specified sender is treated as if it were given as the argument to the | |
2855 | %-f% option, but if a %-f% option is also present, its argument is used in | |
2856 | preference to the address taken from the message. The caller of Exim must be a | |
2857 | trusted user for the sender of a message to be set in this way. | |
2858 | ||
2859 | *-bnq*:: | |
2860 | oindex:[%-bnq%] | |
2861 | cindex:[address qualification, suppressing] | |
2862 | By default, Exim automatically qualifies unqualified addresses (those | |
2863 | without domains) that appear in messages that are submitted locally (that | |
2864 | is, not over TCP/IP). This qualification applies both to addresses in | |
2865 | envelopes, and addresses in header lines. Sender addresses are qualified using | |
2866 | %qualify_domain%, and recipient addresses using %qualify_recipient% (which | |
2867 | defaults to the value of %qualify_domain%). | |
2868 | + | |
2869 | Sometimes, qualification is not wanted. For example, if %-bS% (batch SMTP) is | |
2870 | being used to re-submit messages that originally came from remote hosts after | |
2871 | content scanning, you probably do not want to qualify unqualified addresses in | |
2872 | header lines. (Such lines will be present only if you have not enabled a header | |
2873 | syntax check in the appropriate ACL.) | |
2874 | + | |
2875 | The %-bnq% option suppresses all qualification of unqualified addresses in | |
2876 | messages that originate on the local host. When this is used, unqualified | |
2877 | addresses in the envelope provoke errors (causing message rejection) and | |
2878 | unqualified addresses in header lines are left alone. | |
2879 | ||
2880 | ||
2881 | *-bP*:: | |
2882 | oindex:[%-bP%] | |
2883 | cindex:[configuration options, extracting] | |
2884 | cindex:[options,configuration -- extracting] | |
2885 | If this option is given with no arguments, it causes the values of all Exim's | |
2886 | main configuration options to be written to the standard output. The values | |
2887 | of one or more specific options can be requested by giving their names as | |
2888 | arguments, for example: | |
2889 | ||
2890 | exim -bP qualify_domain hold_domains | |
2891 | + | |
2892 | However, any option setting that is preceded by the word ``hide'' in the | |
2893 | configuration file is not shown in full, except to an admin user. For other | |
2894 | users, the output is as in this example: | |
2895 | ||
2896 | mysql_servers = <value not displayable> | |
2897 | + | |
2898 | If %configure_file% is given as an argument, the name of the run time | |
2899 | configuration file is output. | |
2900 | If a list of configuration files was supplied, the value that is output here | |
2901 | is the name of the file that was actually used. | |
2902 | + | |
2903 | cindex:[daemon,process id (pid)] | |
2904 | cindex:[pid (process id),of daemon] | |
2905 | If %log_file_path% or %pid_file_path% are given, the names of the directories | |
2906 | where log files and daemon pid files are written are output, respectively. If | |
2907 | these values are unset, log files are written in a sub-directory of the spool | |
2908 | directory called %log%, and the pid file is written directly into the spool | |
2909 | directory. | |
2910 | + | |
2911 | If %-bP% is followed by a name preceded by `+`, for example, | |
2912 | ||
2913 | exim -bP +local_domains | |
2914 | + | |
2915 | it searches for a matching named list of any type (domain, host, address, or | |
2916 | local part) and outputs what it finds. | |
2917 | + | |
2918 | If | |
2919 | cindex:[options,router -- extracting] | |
2920 | cindex:[options,transport -- extracting] | |
2921 | one of the words %router%, %transport%, or %authenticator% is given, | |
2922 | followed by the name of an appropriate driver instance, the option settings for | |
2923 | that driver are output. For example: | |
2924 | ||
2925 | exim -bP transport local_delivery | |
2926 | + | |
2927 | The generic driver options are output first, followed by the driver's private | |
2928 | options. A list of the names of drivers of a particular type can be obtained by | |
2929 | using one of the words %router_list%, %transport_list%, or | |
2930 | %authenticator_list%, and a complete list of all drivers with their option | |
2931 | settings can be obtained by using %routers%, %transports%, or %authenticators%. | |
2932 | ||
2933 | ||
2934 | *-bp*:: | |
2935 | oindex:[%-bp%] | |
2936 | cindex:[queue,listing messages on] | |
2937 | cindex:[listing,messages on the queue] | |
2938 | This option requests a listing of the contents of the mail queue on the | |
2939 | standard output. If the %-bp% option is followed by a list of message ids, | |
2940 | just those messages are listed. By default, this option can be used only by an | |
2941 | admin user. However, the %queue_list_requires_admin% option can be set false | |
2942 | to allow any user to see the queue. | |
2943 | + | |
2944 | Each message on the queue is displayed as in the following example: | |
2945 | ||
2946 | 25m 2.9K 0t5C6f-0000c8-00 <alice@wonderland.fict.example> | |
2947 | red.king@looking-glass.fict.example | |
2948 | <other addresses> | |
2949 | + | |
2950 | The | |
2951 | cindex:[message,size in queue listing] | |
2952 | cindex:[size,of message] | |
2953 | first line contains the length of time the message has been on the queue | |
2954 | (in this case 25 minutes), the size of the message (2.9K), the unique local | |
2955 | identifier for the message, and the message sender, as contained in the | |
2956 | envelope. For bounce messages, the sender address is empty, and appears as | |
2957 | ``<>''. If the message was submitted locally by an untrusted user who overrode | |
2958 | the default sender address, the user's login name is shown in parentheses | |
2959 | before the sender address. | |
2960 | + | |
2961 | If | |
2962 | cindex:[frozen messages,in queue listing] | |
2963 | the message is frozen (attempts to deliver it are suspended) then the text | |
2964 | ``\*\*\* frozen \*\*\*'' is displayed at the end of this line. | |
2965 | + | |
2966 | The recipients of the message (taken from the envelope, not the headers) are | |
2967 | displayed on subsequent lines. Those addresses to which the message has already | |
2968 | been delivered are marked with the letter D. If an original address gets | |
2969 | expanded into several addresses via an alias or forward file, the original is | |
2970 | displayed with a D only when deliveries for all of its child addresses are | |
2971 | complete. | |
2972 | ||
2973 | ||
2974 | *-bpa*:: | |
2975 | oindex:[%-bpa%] | |
2976 | This option operates like %-bp%, but in addition it shows delivered addresses | |
2977 | that were generated from the original top level address(es) in each message by | |
2978 | alias or forwarding operations. These addresses are flagged with ``+D'' instead | |
2979 | of just ``D''. | |
2980 | ||
2981 | ||
2982 | *-bpc*:: | |
2983 | oindex:[%-bpc%] | |
2984 | cindex:[queue,count of messages on] | |
2985 | This option counts the number of messages on the queue, and writes the total | |
2986 | to the standard output. It is restricted to admin users, unless | |
2987 | %queue_list_requires_admin% is set false. | |
2988 | ||
2989 | ||
2990 | *-bpr*:: | |
2991 | oindex:[%-bpr%] | |
2992 | This option operates like %-bp%, but the output is not sorted into | |
2993 | chronological order of message arrival. This can speed it up when there are | |
2994 | lots of messages on the queue, and is particularly useful if the output is | |
2995 | going to be post-processed in a way that doesn't need the sorting. | |
2996 | ||
2997 | *-bpra*:: | |
2998 | oindex:[%-bpra%] | |
2999 | This option is a combination of %-bpr% and %-bpa%. | |
3000 | ||
3001 | *-bpru*:: | |
3002 | oindex:[%-bpru%] | |
3003 | This option is a combination of %-bpr% and %-bpu%. | |
3004 | ||
3005 | ||
3006 | *-bpu*:: | |
3007 | oindex:[%-bpu%] | |
3008 | This option operates like %-bp% but shows only undelivered top-level addresses | |
3009 | for each message displayed. Addresses generated by aliasing or forwarding are | |
3010 | not shown, unless the message was deferred after processing by a router with | |
3011 | the %one_time% option set. | |
3012 | ||
3013 | ||
3014 | *-brt*:: | |
3015 | oindex:[%-brt%] | |
3016 | cindex:[testing,retry configuration] | |
3017 | cindex:[retry,configuration testing] | |
3018 | This option is for testing retry rules, and it must be followed by up to three | |
3019 | arguments. It causes Exim to look for a retry rule that matches the values | |
3020 | and to write it to the standard output. For example: | |
3021 | ||
3022 | exim -brt bach.comp.mus.example | |
3023 | Retry rule: *.comp.mus.example F,2h,15m; F,4d,30m; | |
3024 | + | |
3025 | See chapter <<CHAPretry>> for a description of Exim's retry rules. The first | |
3026 | argument, which is required, can be a complete address in the form | |
3027 | 'local_part@domain', or it can be just a domain name. The second argument is | |
3028 | an optional second domain name; if no retry rule is found for the first | |
3029 | argument, the second is tried. This ties in with Exim's behaviour when looking | |
3030 | for retry rules for remote hosts -- if no rule is found that matches the host, | |
3031 | one that matches the mail domain is sought. The final argument is the name of a | |
3032 | specific delivery error, as used in setting up retry rules, for example | |
3033 | ``quota_3d''. | |
3034 | ||
3035 | *-brw*:: | |
3036 | oindex:[%-brw%] | |
3037 | cindex:[testing,rewriting] | |
3038 | cindex:[rewriting,testing] | |
3039 | This option is for testing address rewriting rules, and it must be followed by | |
3040 | a single argument, consisting of either a local part without a domain, or a | |
3041 | complete address with a fully qualified domain. Exim outputs how this address | |
3042 | would be rewritten for each possible place it might appear. See chapter | |
3043 | <<CHAPrewrite>> for further details. | |
3044 | ||
3045 | *-bS*:: | |
3046 | oindex:[%-bS%] | |
3047 | cindex:[SMTP,batched incoming] | |
3048 | cindex:[batched SMTP input] | |
3049 | This option is used for batched SMTP input, which is an alternative interface | |
3050 | for non-interactive local message submission. A number of messages can be | |
3051 | submitted in a single run. However, despite its name, this is not really SMTP | |
3052 | input. Exim reads each message's envelope from SMTP commands on the standard | |
3053 | input, but generates no responses. If the caller is trusted, or | |
3054 | %untrusted_set_sender% is set, the senders in the SMTP MAIL commands are | |
3055 | believed; otherwise the sender is always the caller of Exim. | |
3056 | + | |
3057 | The message itself is read from the standard input, in SMTP format (leading | |
3058 | dots doubled), terminated by a line containing just a single dot. An error is | |
3059 | provoked if the terminating dot is missing. A further message may then follow. | |
3060 | + | |
3061 | As for other local message submissions, the contents of incoming batch SMTP | |
3062 | messages can be checked using the non-SMTP ACL (see chapter <<CHAPACL>>). | |
3063 | Unqualified addresses are automatically qualified using %qualify_domain% and | |
3064 | %qualify_recipient%, as appropriate, unless the %-bnq% option is used. | |
3065 | + | |
3066 | Some other SMTP commands are recognized in the input. HELO and EHLO act | |
3067 | as RSET; VRFY, EXPN, ETRN, and HELP act as NOOP; | |
3068 | QUIT quits, ignoring the rest of the standard input. | |
3069 | + | |
3070 | cindex:[return code,for %-bS%] | |
3071 | If any error is encountered, reports are written to the standard output and | |
3072 | error streams, and Exim gives up immediately. The return code is 0 if no error | |
3073 | was detected; it is 1 if one or more messages were accepted before the error | |
3074 | was detected; otherwise it is 2. | |
3075 | + | |
3076 | More details of input using batched SMTP are given in section | |
3077 | <<SECTincomingbatchedSMTP>>. | |
3078 | ||
3079 | *-bs*:: | |
3080 | oindex:[%-bs%] | |
3081 | cindex:[SMTP,local input] | |
3082 | cindex:[local SMTP input] | |
3083 | This option causes Exim to accept one or more messages by reading SMTP commands | |
3084 | on the standard input, and producing SMTP replies on the standard output. SMTP | |
3085 | policy controls, as defined in ACLs (see chapter <<CHAPACL>>) are applied. | |
3086 | Some user agents use this interface as a way of passing locally-generated | |
3087 | messages to the MTA. | |
3088 | + | |
3089 | In | |
3090 | cindex:[sender,source of] | |
3091 | this usage, if the caller of Exim is trusted, or %untrusted_set_sender% is | |
3092 | set, the senders of messages are taken from the SMTP MAIL commands. | |
3093 | Otherwise the content of these commands is ignored and the sender is set up as | |
3094 | the calling user. Unqualified addresses are automatically qualified using | |
3095 | %qualify_domain% and %qualify_recipient%, as appropriate, unless the %-bnq% | |
3096 | option is used. | |
3097 | + | |
3098 | cindex:[inetd] | |
3099 | The | |
3100 | %-bs% option is also used to run Exim from 'inetd', as an alternative to using | |
3101 | a listening daemon. Exim can distinguish the two cases by checking whether the | |
3102 | standard input is a TCP/IP socket. When Exim is called from 'inetd', the source | |
3103 | of the mail is assumed to be remote, and the comments above concerning senders | |
3104 | and qualification do not apply. In this situation, Exim behaves in exactly the | |
3105 | same way as it does when receiving a message via the listening daemon. | |
3106 | ||
3107 | *-bt*:: | |
3108 | oindex:[%-bt%] | |
3109 | cindex:[testing,addresses] | |
3110 | cindex:[address,testing] | |
3111 | This option runs Exim in address testing mode, in which each argument is taken | |
3112 | as an address to be tested for deliverability. The results are written to the | |
3113 | standard output. If a test fails, and the caller is not an admin user, no | |
3114 | details of the failure are output, because these might contain sensitive | |
3115 | information such as usernames and passwords for database lookups. | |
3116 | + | |
3117 | If no arguments are given, Exim runs in an interactive manner, prompting with a | |
3118 | right angle bracket for addresses to be tested. | |
3119 | + | |
3120 | Unlike the %-be% test option, you cannot arrange for Exim to use the | |
3121 | 'readline()' function, because it is running as 'root' and there are | |
3122 | security issues. | |
3123 | + | |
3124 | Each address is handled as if it were the recipient address of a message | |
3125 | (compare the %-bv% option). It is passed to the routers and the result is | |
3126 | written to the standard output. However, any router that has | |
3127 | %no_address_test% set is bypassed. This can make %-bt% easier to use for | |
3128 | genuine routing tests if your first router passes everything to a scanner | |
3129 | program. | |
3130 | + | |
3131 | The | |
3132 | cindex:[return code,for %-bt%] | |
3133 | return code is 2 if any address failed outright; it is 1 if no address | |
3134 | failed outright but at least one could not be resolved for some reason. Return | |
3135 | code 0 is given only when all addresses succeed. | |
3136 | + | |
3137 | *Warning*: %-bt% can only do relatively simple testing. If any of the | |
3138 | routers in the configuration makes any tests on the sender address of a | |
3139 | message, | |
3140 | cindex:[%-f% option,for address testing] | |
3141 | you can use the %-f% option to set an appropriate sender when running | |
3142 | %-bt% tests. Without it, the sender is assumed to be the calling user at the | |
3143 | default qualifying domain. However, if you have set up (for example) routers | |
3144 | whose behaviour depends on the contents of an incoming message, you cannot test | |
3145 | those conditions using %-bt%. The %-N% option provides a possible way of | |
3146 | doing such tests. | |
3147 | ||
3148 | *-bV*:: | |
3149 | oindex:[%-bV%] | |
3150 | cindex:[version number of Exim, verifying] | |
3151 | This option causes Exim to write the current version number, compilation | |
3152 | number, and compilation date of the 'exim' binary to the standard output. | |
3153 | It also lists the DBM library this is being used, the optional modules (such as | |
3154 | specific lookup types), the drivers that are included in the binary, and the | |
3155 | name of the run time configuration file that is in use. | |
3156 | + | |
3157 | As part of its operation, %-bV% causes Exim to read and syntax check its | |
3158 | configuration file. However, this is a static check only. It cannot check | |
3159 | values that are to be expanded. For example, although a misspelt ACL verb is | |
3160 | detected, an error in the verb's arguments is not. You cannot rely on %-bV% | |
3161 | alone to discover (for example) all the typos in the configuration; some | |
3162 | realistic testing is needed. The %-bh% and %-N% options provide more dynamic | |
3163 | testing facilities. | |
3164 | ||
3165 | *-bv*:: | |
3166 | oindex:[%-bv%] | |
3167 | cindex:[verifying address, using %-bv%] | |
3168 | cindex:[address,verification] | |
3169 | This option runs Exim in address verification mode, in which each argument is | |
3170 | taken as an address to be verified. During normal operation, verification | |
3171 | happens mostly as a consequence processing a %verify% condition in an ACL (see | |
3172 | chapter <<CHAPACL>>). If you want to test an entire ACL, see the %-bh% option. | |
3173 | + | |
3174 | If verification fails, and the caller is not an admin user, no details of the | |
3175 | failure are output, because these might contain sensitive information such as | |
3176 | usernames and passwords for database lookups. | |
3177 | + | |
3178 | If no arguments are given, Exim runs in an interactive manner, prompting with a | |
3179 | right angle bracket for addresses to be verified. | |
3180 | + | |
3181 | Unlike the %-be% test option, you cannot arrange for Exim to use the | |
3182 | 'readline()' function, because it is running as 'exim' and there are | |
3183 | security issues. | |
3184 | + | |
3185 | Verification differs from address testing (the %-bt% option) in that routers | |
3186 | that have %no_verify% set are skipped, and if the address is accepted by a | |
3187 | router that has %fail_verify% set, verification fails. The address is verified | |
3188 | as a recipient if %-bv% is used; to test verification for a sender address, | |
3189 | %-bvs% should be used. | |
3190 | + | |
3191 | If the %-v% option is not set, the output consists of a single line for each | |
3192 | address, stating whether it was verified or not, and giving a reason in the | |
3193 | latter case. Otherwise, more details are given of how the address has been | |
3194 | handled, and in the case of address redirection, all the generated addresses | |
3195 | are also considered. Without %-v%, generating more than one address by | |
3196 | redirection causes verification to end sucessfully. | |
3197 | + | |
3198 | The | |
3199 | cindex:[return code,for %-bv%] | |
3200 | return code is 2 if any address failed outright; it is 1 if no address | |
3201 | failed outright but at least one could not be resolved for some reason. Return | |
3202 | code 0 is given only when all addresses succeed. | |
3203 | + | |
3204 | If any of the routers in the configuration makes any tests on the sender | |
3205 | address of a message, you should use the %-f% option to set an appropriate | |
3206 | sender when running %-bv% tests. Without it, the sender is assumed to be the | |
3207 | calling user at the default qualifying domain. | |
3208 | ||
3209 | *-bvs*:: | |
3210 | oindex:[%-bvs%] | |
3211 | This option acts like %-bv%, but verifies the address as a sender rather | |
3212 | than a recipient address. This affects any rewriting and qualification that | |
3213 | might happen. | |
3214 | ||
3215 | *-C*~<'filelist'>:: | |
3216 | oindex:[%-C%] | |
3217 | cindex:[configuration file,alternate] | |
3218 | cindex:[CONFIGURE_FILE] | |
3219 | cindex:[alternate configuration file] | |
3220 | This option causes Exim to find the run time configuration file from the given | |
3221 | list instead of from the list specified by the CONFIGURE_FILE | |
3222 | compile-time setting. Usually, the list will consist of just a single file | |
3223 | name, but it can be a colon-separated list of names. In this case, the first | |
3224 | file that exists is used. Failure to open an existing file stops Exim from | |
3225 | proceeding any further along the list, and an error is generated. | |
3226 | + | |
3227 | When this option is used by a caller other than root or the Exim user, and the | |
3228 | list is different from the compiled-in list, Exim gives up its root privilege | |
3229 | immediately, and runs with the real and effective uid and gid set to those of | |
3230 | the caller. However, if ALT_CONFIG_ROOT_ONLY is defined in | |
3231 | _Local/Makefile_, root privilege is retained for %-C% only if the caller of | |
3232 | Exim is root. | |
3233 | + | |
3234 | That is, the Exim user is no longer privileged in this regard. This build-time | |
3235 | option is not set by default in the Exim source distribution tarbundle. | |
3236 | However, if you are using a ``packaged'' version of Exim (source or binary), the | |
3237 | packagers might have enabled it. | |
3238 | + | |
3239 | Setting ALT_CONFIG_ROOT_ONLY locks out the possibility of testing a | |
3240 | configuration using %-C% right through message reception and delivery, even if | |
3241 | the caller is root. The reception works, but by that time, Exim is running as | |
3242 | the Exim user, so when it re-execs to regain privilege for the delivery, the | |
3243 | use of %-C% causes privilege to be lost. However, root can test reception and | |
3244 | delivery using two separate commands (one to put a message on the queue, using | |
3245 | %-odq%, and another to do the delivery, using %-M%). | |
3246 | + | |
3247 | If ALT_CONFIG_PREFIX is defined _in Local/Makefile_, it specifies a | |
3248 | prefix string with which any file named in a %-C% command line option | |
3249 | must start. In addition, the file name must not contain the sequence `/../`. | |
3250 | However, if the value of the %-C% option is identical to the value of | |
3251 | CONFIGURE_FILE in _Local/Makefile_, Exim ignores %-C% and proceeds as | |
3252 | usual. There is no default setting for ALT_CONFIG_PREFIX; when it is | |
3253 | unset, any file name can be used with %-C%. | |
3254 | + | |
3255 | ALT_CONFIG_PREFIX can be used to confine alternative configuration files | |
3256 | to a directory to which only root has access. This prevents someone who has | |
3257 | broken into the Exim account from running a privileged Exim with an arbitrary | |
3258 | configuration file. | |
3259 | + | |
3260 | The %-C% facility is useful for ensuring that configuration files are | |
3261 | syntactically correct, but cannot be used for test deliveries, unless the | |
3262 | caller is privileged, or unless it is an exotic configuration that does not | |
3263 | require privilege. No check is made on the owner or group of the files | |
3264 | specified by this option. | |
3265 | ||
3266 | *-D*<'macro'>=<'value'>:: | |
3267 | oindex:[%-D%] | |
3268 | cindex:[macro,setting on command line] | |
3269 | This option can be used to override macro definitions in the configuration file | |
3270 | (see section <<SECTmacrodefs>>). However, like %-C%, if it is used by an | |
3271 | unprivileged caller, it causes Exim to give up its root privilege. | |
3272 | If DISABLE_D_OPTION is defined in _Local/Makefile_, the use of %-D% is | |
3273 | completely disabled, and its use causes an immediate error exit. | |
3274 | + | |
3275 | The entire option (including equals sign if present) must all be within one | |
3276 | command line item. %-D% can be used to set the value of a macro to the empty | |
3277 | string, in which case the equals sign is optional. These two commands are | |
3278 | synonymous: | |
3279 | ||
3280 | exim -DABC ... | |
3281 | exim -DABC= ... | |
3282 | + | |
3283 | To include spaces in a macro definition item, quotes must be used. If you use | |
3284 | quotes, spaces are permitted around the macro name and the equals sign. For | |
3285 | example: | |
3286 | ||
3287 | exim '-D ABC = something' ... | |
3288 | + | |
3289 | %-D% may be repeated up to 10 times on a command line. | |
3290 | ||
3291 | *-d*<'debug~options'>:: | |
3292 | oindex:[%-d%] | |
3293 | cindex:[debugging,list of selectors] | |
3294 | cindex:[debugging,%-d% option] | |
3295 | This option causes debugging information to be written to the standard | |
3296 | error stream. It is restricted to admin users because debugging output may show | |
3297 | database queries that contain password information. Also, the details of users' | |
068aaea8 PH |
3298 | filter files should be protected. When %-d% is used, %-v% is assumed. If %-d% |
3299 | is given on its own, a lot of standard debugging data is output. This can be | |
3300 | reduced, or increased to include some more rarely needed information, by | |
3301 | directly following %-d% with a string made up of names preceded by plus or | |
3302 | minus characters. These add or remove sets of debugging data, respectively. For | |
168e428f | 3303 | example, %-d+filter% adds filter debugging, whereas %-d-all+filter% selects |
068aaea8 PH |
3304 | only filter debugging. Note that no spaces are allowed in the debug setting. |
3305 | The available debugging categories are: | |
168e428f PH |
3306 | + |
3307 | &&& | |
3308 | `acl ` ACL interpretation | |
3309 | `auth ` authenticators | |
3310 | `deliver ` general delivery logic | |
3311 | `dns ` DNS lookups (see also resolver) | |
3312 | `dnsbl ` DNS black list (aka RBL) code | |
3313 | `exec ` arguments for ^^execv()^^ calls | |
3314 | `expand ` detailed debugging for string expansions | |
3315 | `filter ` filter handling | |
3316 | `hints_lookup ` hints data lookups | |
3317 | `host_lookup ` all types of name-to-IP address handling | |
3318 | `ident ` ident lookup | |
3319 | `interface ` lists of local interfaces | |
3320 | `lists ` matching things in lists | |
3321 | `load ` system load checks | |
3322 | `local_scan ` can be used by ^^local_scan()^^ (see chapter <<CHAPlocalscan>>) | |
3323 | `lookup ` general lookup code and all lookups | |
3324 | `memory ` memory handling | |
3325 | `pid ` add pid to debug output lines | |
3326 | `process_info ` setting info for the process log | |
3327 | `queue_run ` queue runs | |
3328 | `receive ` general message reception logic | |
3329 | `resolver ` turn on the DNS resolver's debugging output | |
3330 | `retry ` retry handling | |
3331 | `rewrite ` address rewriting | |
3332 | `route ` address routing | |
3333 | `timestamp ` add timestamp to debug output lines | |
3334 | `tls ` TLS logic | |
3335 | `transport ` transports | |
3336 | `uid ` changes of uid/gid and looking up uid/gid | |
3337 | `verify ` address verification logic | |
068aaea8 | 3338 | `all ` almost all of the above (see below), and also %-v% |
168e428f PH |
3339 | &&& |
3340 | + | |
068aaea8 PH |
3341 | [revisionflag="changed"] |
3342 | The `all` option excludes `memory` when used as `+all`, but includes it for | |
3343 | `-all`. The reason for this is that `+all` is something that people tend to use | |
3344 | when generating debug output for Exim maintainers. If `+memory` is included, an | |
3345 | awful lot of output that is very rarely of interest is generated, so it now has | |
3346 | to be explicitly requested. However, `-all` does turn everything off. | |
3347 | + | |
168e428f PH |
3348 | The |
3349 | cindex:[resolver, debugging output] | |
3350 | cindex:[DNS resolver, debugging output] | |
3351 | `resolver` option produces output only if the DNS resolver was compiled | |
3352 | with DEBUG enabled. This is not the case in some operating systems. Also, | |
3353 | unfortunately, debugging output from the DNS resolver is written to stdout | |
3354 | rather than stderr. | |
3355 | + | |
3356 | The default (%-d% with no argument) omits `expand`, `filter`, | |
3357 | `interface`, `load`, `memory`, `pid`, `resolver`, and `timestamp`. | |
3358 | However, the `pid` selector is forced when debugging is turned on for a | |
3359 | daemon, which then passes it on to any re-executed Exims. Exim also | |
3360 | automatically adds the pid to debug lines when several remote deliveries are | |
3361 | run in parallel. | |
3362 | + | |
3363 | The `timestamp` selector causes the current time to be inserted at the start | |
3364 | of all debug output lines. This can be useful when trying to track down delays | |
3365 | in processing. | |
3366 | + | |
3367 | If the %debug_print% option is set in any driver, it produces output whenever | |
3368 | any debugging is selected, or if %-v% is used. | |
3369 | ||
3370 | *-dd*<'debug~options'>:: | |
3371 | oindex:[%-dd%] | |
3372 | This option behaves exactly like %-d% except when used on a command that | |
3373 | starts a daemon process. In that case, debugging is turned off for the | |
3374 | subprocesses that the daemon creates. Thus, it is useful for monitoring the | |
3375 | behaviour of the daemon without creating as much output as full debugging does. | |
3376 | ||
3377 | *-dropcr*:: | |
3378 | oindex:[%-dropcr%] | |
3379 | This is an obsolete option that is now a no-op. It used to affect the way Exim | |
3380 | handled CR and LF characters in incoming messages. What happens now is | |
3381 | described in section <<SECTlineendings>>. | |
3382 | ||
3383 | *-E*:: | |
3384 | oindex:[%-E%] | |
3385 | cindex:[bounce message,generating] | |
3386 | This option specifies that an incoming message is a locally-generated delivery | |
3387 | failure report. It is used internally by Exim when handling delivery failures | |
3388 | and is not intended for external use. Its only effect is to stop Exim | |
3389 | generating certain messages to the postmaster, as otherwise message cascades | |
3390 | could occur in some situations. As part of the same option, a message id may | |
3391 | follow the characters %-E%. If it does, the log entry for the receipt of the | |
3392 | new message contains the id, following ``R='', as a cross-reference. | |
3393 | ||
3394 | *-e*'x':: | |
3395 | oindex:[%-e'x'%] | |
3396 | There are a number of Sendmail options starting with %-oe% which seem to be | |
3397 | called by various programs without the leading %o% in the option. For example, | |
3398 | the %vacation% program uses %-eq%. Exim treats all options of the form | |
3399 | %-e'x'% as synonymous with the corresponding %-oe'x'% options. | |
3400 | ||
3401 | *-F*~<'string'>:: | |
3402 | oindex:[%-F%] | |
3403 | cindex:[sender,name] | |
3404 | cindex:[name,of sender] | |
3405 | This option sets the sender's full name for use when a locally-generated | |
3406 | message is being accepted. In the absence of this option, the user's 'gecos' | |
3407 | entry from the password data is used. As users are generally permitted to alter | |
3408 | their 'gecos' entries, no security considerations are involved. White space | |
3409 | between %-F% and the <'string'> is optional. | |
3410 | ||
3411 | *-f*~<'address'>:: | |
3412 | oindex:[%-f%] | |
3413 | cindex:[sender,address] | |
3414 | cindex:[address,sender] | |
3415 | cindex:[trusted user] | |
3416 | cindex:[envelope sender] | |
3417 | cindex:[user,trusted] | |
3418 | This option sets the address of the envelope sender of a locally-generated | |
3419 | message (also known as the return path). The option can normally be used only | |
3420 | by a trusted user, but %untrusted_set_sender% can be set to allow untrusted | |
3421 | users to use it. | |
3422 | + | |
3423 | Processes running as root or the Exim user are always trusted. Other | |
3424 | trusted users are defined by the %trusted_users% or %trusted_groups% options. | |
3425 | In the absence of %-f%, or if the caller is not trusted, the sender of a local | |
3426 | message is set to the caller's login name at the default qualify domain. | |
3427 | + | |
3428 | There is one exception to the restriction on the use of %-f%: an empty sender | |
3429 | can be specified by any user, trusted or not, to create a message that can | |
3430 | never provoke a bounce. An empty sender can be specified either as an empty | |
3431 | string, or as a pair of angle brackets with nothing between them, as in these | |
3432 | examples of shell commands: | |
3433 | ||
3434 | exim -f '<>' user@domain | |
3435 | exim -f "" user@domain | |
3436 | + | |
3437 | In addition, the use of %-f% is not restricted when testing a filter file with | |
3438 | %-bf% or when testing or verifying addresses using the %-bt% or %-bv% | |
3439 | options. | |
3440 | + | |
3441 | Allowing untrusted users to change the sender address does not of itself make | |
3442 | it possible to send anonymous mail. Exim still checks that the 'From:' header | |
3443 | refers to the local user, and if it does not, it adds a 'Sender:' header, | |
3444 | though this can be overridden by setting %no_local_from_check%. | |
3445 | + | |
3446 | White | |
3447 | cindex:[``From'' line] | |
3448 | space between %-f% and the <'address'> is optional (that is, they can be given | |
3449 | as two arguments or one combined argument). The sender of a locally-generated | |
3450 | message can also be set (when permitted) by an initial ``From '' line in the | |
3451 | message -- see the description of %-bm% above -- but if %-f% is also present, | |
3452 | it overrides ``From''. | |
3453 | ||
3454 | *-G*:: | |
3455 | oindex:[%-G%] | |
3456 | cindex:[Sendmail compatibility,%-G% option ignored] | |
3457 | This is a Sendmail option which is ignored by Exim. | |
3458 | ||
3459 | *-h*~<'number'>:: | |
3460 | oindex:[%-h%] | |
3461 | cindex:[Sendmail compatibility,%-h% option ignored] | |
3462 | This option is accepted for compatibility with Sendmail, but has no effect. (In | |
3463 | Sendmail it overrides the ``hop count'' obtained by counting 'Received:' | |
3464 | headers.) | |
3465 | ||
3466 | *-i*:: | |
3467 | oindex:[%-i%] | |
3468 | cindex:[Solaris,'mail' command] | |
3469 | cindex:[dot in incoming, non-SMTP message] | |
3470 | This option, which has the same effect as %-oi%, specifies that a dot on a line | |
3471 | by itself should not terminate an incoming, non-SMTP message. I can find no | |
3472 | documentation for this option in Solaris 2.4 Sendmail, but the 'mailx' command | |
3473 | in Solaris 2.4 uses it. See also %-ti%. | |
3474 | ||
3475 | *-M*~<'message~id'>~<'message~id'>~...:: | |
3476 | oindex:[%-M%] | |
3477 | cindex:[forcing delivery] | |
3478 | cindex:[delivery,forcing attempt] | |
3479 | cindex:[frozen messages,forcing delivery] | |
3480 | This option requests Exim to run a delivery attempt on each message in turn. If | |
3481 | any of the messages are frozen, they are automatically thawed before the | |
3482 | delivery attempt. The settings of %queue_domains%, %queue_smtp_domains%, and | |
3483 | %hold_domains% are ignored. | |
3484 | + | |
3485 | Retry | |
3486 | cindex:[hints database,overriding retry hints] | |
3487 | hints for any of the addresses are overridden -- Exim tries to deliver even if | |
3488 | the normal retry time has not yet been reached. This option requires the caller | |
3489 | to be an admin user. However, there is an option called %prod_requires_admin% | |
3490 | which can be set false to relax this restriction (and also the same requirement | |
3491 | for the %-q%, %-R%, and %-S% options). | |
068aaea8 PH |
3492 | + |
3493 | [revisionflag="changed"] | |
3494 | The deliveries happen synchronously, that is, the original Exim process does | |
3495 | not terminate until all the delivery attempts have finished. No output is | |
3496 | produced unless there is a serious error. If you want to see what is happening, | |
3497 | use the %-v% option as well, or inspect Exim's main log. | |
168e428f PH |
3498 | |
3499 | *-Mar*~<'message~id'>~<'address'>~<'address'>~...:: | |
3500 | oindex:[%-Mar%] | |
3501 | cindex:[message,adding recipients] | |
3502 | cindex:[recipient,adding] | |
3503 | This option requests Exim to add the addresses to the list of recipients of the | |
3504 | message (``ar'' for ``add recipients''). The first argument must be a message id, | |
3505 | and the remaining ones must be email addresses. However, if the message is | |
3506 | active (in the middle of a delivery attempt), it is not altered. This option | |
3507 | can be used only by an admin user. | |
3508 | ||
3509 | *-MC*~<'transport'>~<'hostname'>~<'sequence~number'>~<'message~id'>:: | |
3510 | oindex:[%-MC%] | |
3511 | cindex:[SMTP,passed connection] | |
3512 | cindex:[SMTP,multiple deliveries] | |
3513 | cindex:[multiple SMTP deliveries] | |
3514 | This option is not intended for use by external callers. It is used internally | |
3515 | by Exim to invoke another instance of itself to deliver a waiting message using | |
3516 | an existing SMTP connection, which is passed as the standard input. Details are | |
3517 | given in chapter <<CHAPSMTP>>. This must be the final option, and the caller must | |
3518 | be root or the Exim user in order to use it. | |
3519 | ||
3520 | *-MCA*:: | |
3521 | oindex:[%-MCA%] | |
3522 | This option is not intended for use by external callers. It is used internally | |
3523 | by Exim in conjunction with the %-MC% option. It signifies that the connection | |
3524 | to the remote host has been authenticated. | |
3525 | ||
3526 | *-MCP*:: | |
3527 | oindex:[%-MCP%] | |
3528 | This option is not intended for use by external callers. It is used internally | |
3529 | by Exim in conjunction with the %-MC% option. It signifies that the server to | |
3530 | which Exim is connected supports pipelining. | |
3531 | ||
3532 | *-MCQ*~<'process~id'>~<'pipe~fd'>:: | |
3533 | oindex:[%-MCQ%] | |
3534 | This option is not intended for use by external callers. It is used internally | |
3535 | by Exim in conjunction with the %-MC% option when the original delivery was | |
3536 | started by a queue runner. It passes on the process id of the queue runner, | |
3537 | together with the file descriptor number of an open pipe. Closure of the pipe | |
3538 | signals the final completion of the sequence of processes that are passing | |
3539 | messages through the same SMTP connection. | |
3540 | ||
3541 | *-MCS*:: | |
3542 | oindex:[%-MCS%] | |
3543 | This option is not intended for use by external callers. It is used internally | |
3544 | by Exim in conjunction with the %-MC% option, and passes on the fact that the | |
3545 | SMTP SIZE option should be used on messages delivered down the existing | |
3546 | connection. | |
3547 | ||
3548 | *-MCT*:: | |
3549 | oindex:[%-MCT%] | |
3550 | This option is not intended for use by external callers. It is used internally | |
3551 | by Exim in conjunction with the %-MC% option, and passes on the fact that the | |
3552 | host to which Exim is connected supports TLS encryption. | |
3553 | ||
3554 | *-Mc*~<'message~id'>~<'message~id'>~...:: | |
3555 | oindex:[%-Mc%] | |
3556 | cindex:[hints database,not overridden by %-Mc%] | |
3557 | cindex:[delivery,manually started -- not forced] | |
3558 | This option requests Exim to run a delivery attempt on each message in turn, | |
3559 | but unlike the %-M% option, it does check for retry hints, and respects any | |
3560 | that are found. This option is not very useful to external callers. It is | |
3561 | provided mainly for internal use by Exim when it needs to re-invoke itself in | |
3562 | order to regain root privilege for a delivery (see chapter <<CHAPsecurity>>). | |
3563 | However, %-Mc% can be useful when testing, in order to run a delivery that | |
3564 | respects retry times and other options such as %hold_domains% that are | |
3565 | overridden when %-M% is used. Such a delivery does not count as a queue run. | |
3566 | If you want to run a specific delivery as if in a queue run, you should use | |
3567 | %-q% with a message id argument. A distinction between queue run deliveries | |
3568 | and other deliveries is made in one or two places. | |
3569 | ||
3570 | *-Mes*~<'message~id'>~<'address'>:: | |
3571 | oindex:[%-Mes%] | |
3572 | cindex:[message,changing sender] | |
3573 | cindex:[sender,changing] | |
3574 | This option requests Exim to change the sender address in the message to the | |
3575 | given address, which must be a fully qualified address or ``<>'' (``es'' for ``edit | |
3576 | sender''). There must be exactly two arguments. The first argument must be a | |
3577 | message id, and the second one an email address. However, if the message is | |
3578 | active (in the middle of a delivery attempt), its status is not altered. This | |
3579 | option can be used only by an admin user. | |
3580 | ||
3581 | *-Mf*~<'message~id'>~<'message~id'>~...:: | |
3582 | oindex:[%-Mf%] | |
3583 | cindex:[freezing messages] | |
3584 | cindex:[message,manually freezing] | |
3585 | This option requests Exim to mark each listed message as ``frozen''. This | |
3586 | prevents any delivery attempts taking place until the message is ``thawed'', | |
3587 | either manually or as a result of the %auto_thaw% configuration option. | |
3588 | However, if any of the messages are active (in the middle of a delivery | |
3589 | attempt), their status is not altered. This option can be used only by an admin | |
3590 | user. | |
3591 | ||
3592 | *-Mg*~<'message~id'>~<'message~id'>~...:: | |
3593 | oindex:[%-Mg%] | |
3594 | cindex:[giving up on messages] | |
3595 | cindex:[message,abandoning delivery attempts] | |
3596 | cindex:[delivery,abandoning further attempts] | |
3597 | This option requests Exim to give up trying to deliver the listed messages, | |
3598 | including any that are frozen. However, if any of the messages are active, | |
3599 | their status is not altered. For non-bounce messages, a delivery error message | |
3600 | is sent to the sender, containing the text ``cancelled by administrator''. | |
3601 | Bounce messages are just discarded. This option can be used only by an admin | |
3602 | user. | |
3603 | ||
3604 | *-Mmad*~<'message~id'>~<'message~id'>~...:: | |
3605 | oindex:[%-Mmad%] | |
3606 | cindex:[delivery,cancelling all] | |
3607 | This option requests Exim to mark all the recipient addresses in the messages | |
3608 | as already delivered (``mad'' for ``mark all delivered''). However, if any | |
3609 | message is active (in the middle of a delivery attempt), its status is not | |
3610 | altered. This option can be used only by an admin user. | |
3611 | ||
3612 | *-Mmd*~<'message~id'>~<'address'>~<'address'>~...:: | |
3613 | oindex:[%-Mmd%] | |
3614 | cindex:[delivery,cancelling by address] | |
3615 | cindex:[recipient,removing] | |
3616 | cindex:[removing recipients] | |
3617 | This option requests Exim to mark the given addresses as already delivered | |
3618 | (``md'' for ``mark delivered''). The first argument must be a message id, and | |
3619 | the remaining ones must be email addresses. These are matched to recipient | |
3620 | addresses in the message in a case-sensitive manner. If the message is active | |
3621 | (in the middle of a delivery attempt), its status is not altered. This option | |
3622 | can be used only by an admin user. | |
3623 | ||
3624 | *-Mrm*~<'message~id'>~<'message~id'>~...:: | |
3625 | oindex:[%-Mrm%] | |
3626 | cindex:[removing messages] | |
3627 | cindex:[abandoning mail] | |
3628 | cindex:[message,manually discarding] | |
3629 | This option requests Exim to remove the given messages from the queue. No | |
3630 | bounce messages are sent; each message is simply forgotten. However, if any of | |
3631 | the messages are active, their status is not altered. This option can be used | |
3632 | only by an admin user or by the user who originally caused the message to be | |
3633 | placed on the queue. | |
3634 | ||
3635 | *-Mt*~<'message~id'>~<'message~id'>~...:: | |
3636 | oindex:[%-Mt%] | |
3637 | cindex:[thawing messages] | |
3638 | cindex:[unfreezing messages] | |
3639 | cindex:[frozen messages,thawing] | |
3640 | cindex:[message,thawing frozen] | |
3641 | This option requests Exim to ``thaw'' any of the listed messages that are | |
3642 | ``frozen'', so that delivery attempts can resume. However, if any of the messages | |
3643 | are active, their status is not altered. This option can be used only by an | |
3644 | admin user. | |
3645 | ||
3646 | *-Mvb*~<'message~id'>:: | |
3647 | oindex:[%-Mvb%] | |
3648 | cindex:[listing,message body] | |
3649 | cindex:[message,listing body of] | |
3650 | This option causes the contents of the message body (-D) spool file to be | |
3651 | written to the standard output. This option can be used only by an admin user. | |
3652 | ||
3653 | *-Mvh*~<'message~id'>:: | |
3654 | oindex:[%-Mvh%] | |
3655 | cindex:[listing,message headers] | |
3656 | cindex:[header lines,listing] | |
3657 | cindex:[message,listing header lines] | |
3658 | This option causes the contents of the message headers (-H) spool file to be | |
3659 | written to the standard output. This option can be used only by an admin user. | |
3660 | ||
3661 | *-Mvl*~<'message~id'>:: | |
3662 | oindex:[%-Mvl%] | |
3663 | cindex:[listing,message log] | |
3664 | cindex:[message,listing message log] | |
3665 | This option causes the contents of the message log spool file to be written to | |
3666 | the standard output. This option can be used only by an admin user. | |
3667 | ||
3668 | *-m*:: | |
3669 | oindex:[%-m%] | |
3670 | This is apparently a synonym for %-om% that is accepted by Sendmail, so Exim | |
3671 | treats it that way too. | |
3672 | ||
3673 | *-N*:: | |
3674 | oindex:[%-N%] | |
3675 | cindex:[debugging,%-N% option] | |
3676 | cindex:[debugging,suppressing delivery] | |
3677 | This is a debugging option that inhibits delivery of a message at the transport | |
3678 | level. It implies %-v%. Exim goes through many of the motions of delivery -- | |
3679 | it just doesn't actually transport the message, but instead behaves as if it | |
3680 | had successfully done so. However, it does not make any updates to the retry | |
3681 | database, and the log entries for deliveries are flagged with ``\*>'' rather | |
3682 | than ``=>''. | |
3683 | + | |
3684 | Because %-N% discards any message to which it applies, only root or the Exim | |
3685 | user are allowed to use it with %-bd%, %-q%, %-R% or %-M%. In other words, | |
3686 | an ordinary user can use it only when supplying an incoming message to which it | |
3687 | will apply. Although transportation never fails when %-N% is set, an address | |
3688 | may be deferred because of a configuration problem on a transport, or a routing | |
3689 | problem. Once %-N% has been used for a delivery attempt, it sticks to the | |
3690 | message, and applies to any subsequent delivery attempts that may happen for | |
3691 | that message. | |
3692 | ||
3693 | *-n*:: | |
3694 | oindex:[%-n%] | |
3695 | cindex:[Sendmail compatibility,%-n% option ignored] | |
3696 | This option is interpreted by Sendmail to mean ``no aliasing''. It is ignored by | |
3697 | Exim. | |
3698 | ||
3699 | *-O*~<'data'>:: | |
3700 | oindex:[%-O%] | |
3701 | This option is interpreted by Sendmail to mean `set option`. It is ignored by | |
3702 | Exim. | |
3703 | ||
3704 | *-oA*~<'file~name'>:: | |
3705 | oindex:[%-oA%] | |
3706 | cindex:[Sendmail compatibility,%-oA% option] | |
3707 | This option is used by Sendmail in conjunction with %-bi% to specify an | |
3708 | alternative alias file name. Exim handles %-bi% differently; see the | |
3709 | description above. | |
3710 | ||
3711 | *-oB*~<'n'>:: | |
3712 | oindex:[%-oB%] | |
3713 | cindex:[SMTP,passed connection] | |
3714 | cindex:[SMTP,multiple deliveries] | |
3715 | cindex:[multiple SMTP deliveries] | |
3716 | This is a debugging option which limits the maximum number of messages that can | |
3717 | be delivered down one SMTP connection, overriding the value set in any ^smtp^ | |
3718 | transport. If <'n'> is omitted, the limit is set to 1. | |
3719 | ||
3720 | *-odb*:: | |
3721 | oindex:[%-odb%] | |
3722 | cindex:[background delivery] | |
3723 | cindex:[delivery,in the background] | |
3724 | This option applies to all modes in which Exim accepts incoming messages, | |
3725 | including the listening daemon. It requests ``background'' delivery of such | |
3726 | messages, which means that the accepting process automatically starts a | |
3727 | delivery process for each message received, but does not wait for the delivery | |
3728 | processes to finish. | |
3729 | + | |
3730 | When all the messages have been received, the reception process exits, | |
3731 | leaving the delivery processes to finish in their own time. The standard output | |
3732 | and error streams are closed at the start of each delivery process. | |
3733 | This is the default action if none of the %-od% options are present. | |
3734 | + | |
3735 | If one of the queueing options in the configuration file | |
3736 | (%queue_only% or %queue_only_file%, for example) is in effect, %-odb% | |
3737 | overrides it if %queue_only_override% is set true, which is the default | |
3738 | setting. If %queue_only_override% is set false, %-odb% has no effect. | |
3739 | ||
3740 | *-odf*:: | |
3741 | oindex:[%-odf%] | |
3742 | cindex:[foreground delivery] | |
3743 | cindex:[delivery,in the foreground] | |
3744 | This option requests ``foreground'' (synchronous) delivery when Exim has accepted | |
3745 | a locally-generated message. (For the daemon it is exactly the same as | |
3746 | %-odb%.) A delivery process is automatically started to deliver the | |
3747 | message, and Exim waits for it to complete before proceeding. | |
3748 | + | |
3749 | The original Exim reception process does not finish until the delivery | |
3750 | process for the final message has ended. The standard error stream is left open | |
3751 | during deliveries. | |
3752 | + | |
3753 | However, like %-odb%, this option has no effect if %queue_only_override% is | |
3754 | false and one of the queueing options in the configuration file is in effect. | |
3755 | + | |
3756 | If there is a temporary delivery error during foreground delivery, the | |
3757 | message is left on the queue for later delivery, and the original reception | |
068aaea8 | 3758 | process exits. See chapter <<CHAPnonqueueing>> for a way of setting up a |
168e428f PH |
3759 | restricted configuration that never queues messages. |
3760 | ||
3761 | ||
3762 | *-odi*:: | |
3763 | oindex:[%-odi%] | |
3764 | This option is synonymous with %-odf%. It is provided for compatibility with | |
3765 | Sendmail. | |
3766 | ||
3767 | *-odq*:: | |
3768 | oindex:[%-odq%] | |
3769 | cindex:[non-immediate delivery] | |
3770 | cindex:[delivery,suppressing immediate] | |
3771 | cindex:[queueing incoming messages] | |
3772 | This option applies to all modes in which Exim accepts incoming messages, | |
3773 | including the listening daemon. It specifies that the accepting process should | |
3774 | not automatically start a delivery process for each message received. Messages | |
3775 | are placed on the queue, and remain there until a subsequent queue runner | |
3776 | process encounters them. There are several configuration options (such as | |
3777 | %queue_only%) that can be used to queue incoming messages under certain | |
3778 | conditions. This option overrides all of them and also %-odqs%. It always | |
3779 | forces queueing. | |
3780 | ||
3781 | *-odqs*:: | |
3782 | oindex:[%-odqs%] | |
3783 | cindex:[SMTP,delaying delivery] | |
3784 | This option is a hybrid between %-odb%/%-odi% and %-odq%. | |
3785 | However, like %-odb% and %-odi%, this option has no effect if | |
3786 | %queue_only_override% is false and one of the queueing options in the | |
3787 | configuration file is in effect. | |
3788 | + | |
3789 | When %-odqs% does operate, a delivery process is started for each incoming | |
3790 | message, in the background by default, but in the foreground if %-odi% is also | |
3791 | present. The recipient addresses are routed, and local deliveries are done in | |
3792 | the normal way. However, if any SMTP deliveries are required, they are not done | |
3793 | at this time, so the message remains on the queue until a subsequent queue | |
3794 | runner process encounters it. Because routing was done, Exim knows which | |
3795 | messages are waiting for which hosts, and so a number of messages for the same | |
3796 | host can be sent in a single SMTP connection. The %queue_smtp_domains% | |
3797 | configuration option has the same effect for specific domains. See also the | |
3798 | %-qq% option. | |
3799 | ||
3800 | *-oee*:: | |
3801 | oindex:[%-oee%] | |
3802 | cindex:[error,reporting] | |
3803 | If an error is detected while a non-SMTP message is being received (for | |
3804 | example, a malformed address), the error is reported to the sender in a mail | |
3805 | message. | |
3806 | + | |
3807 | Provided | |
3808 | cindex:[return code,for %-oee%] | |
3809 | this error message is successfully sent, the Exim receiving process | |
3810 | exits with a return code of zero. If not, the return code is 2 if the problem | |
3811 | is that the original message has no recipients, or 1 any other error. This is | |
3812 | the default %-oe'x'% option if Exim is called as 'rmail'. | |
3813 | ||
3814 | *-oem*:: | |
3815 | oindex:[%-oem%] | |
3816 | cindex:[error,reporting] | |
3817 | cindex:[return code,for %-oem%] | |
3818 | This is the same as %-oee%, except that Exim always exits with a non-zero | |
3819 | return code, whether or not the error message was successfully sent. | |
3820 | This is the default %-oe'x'% option, unless Exim is called as 'rmail'. | |
3821 | ||
3822 | *-oep*:: | |
3823 | oindex:[%-oep%] | |
3824 | cindex:[error,reporting] | |
3825 | If an error is detected while a non-SMTP message is being received, the | |
3826 | error is reported by writing a message to the standard error file (stderr). | |
3827 | cindex:[return code,for %-oep%] | |
3828 | The return code is 1 for all errors. | |
3829 | ||
3830 | *-oeq*:: | |
3831 | oindex:[%-oeq%] | |
3832 | cindex:[error,reporting] | |
3833 | This option is supported for compatibility with Sendmail, but has the same | |
3834 | effect as %-oep%. | |
3835 | ||
3836 | *-oew*:: | |
3837 | oindex:[%-oew%] | |
3838 | cindex:[error,reporting] | |
3839 | This option is supported for compatibility with Sendmail, but has the same | |
3840 | effect as %-oem%. | |
3841 | ||
3842 | *-oi*:: | |
3843 | oindex:[%-oi%] | |
3844 | cindex:[dot in incoming, non-SMTP message] | |
3845 | This option, which has the same effect as %-i%, specifies that a dot on a line | |
3846 | by itself should not terminate an incoming, non-SMTP message. | |
3847 | Otherwise, a single dot does terminate, though Exim does no special processing | |
3848 | for other lines that start with a dot. | |
3849 | This option is set by default if Exim is called as 'rmail'. See also %-ti%. | |
3850 | ||
3851 | *-oitrue*:: | |
3852 | oindex:[%-oitrue%] | |
3853 | This option is treated as synonymous with %-oi%. | |
3854 | ||
3855 | *-oMa*~<'host~address'>:: | |
3856 | oindex:[%-oMa%] | |
3857 | cindex:[sender host address, specifying for local message] | |
3858 | A number of options starting with %-oM% can be used to set values associated | |
3859 | with remote hosts on locally-submitted messages (that is, messages not received | |
3860 | over TCP/IP). These options can be used by any caller in conjunction with the | |
3861 | %-bh%, %-be%, %-bf%, %-bF%, %-bt%, or %-bv% testing options. In other | |
3862 | circumstances, they are ignored unless the caller is trusted. | |
3863 | + | |
3864 | The %-oMa% option sets the sender host address. This may include a port number | |
3865 | at the end, after a full stop (period). For example: | |
3866 | ||
3867 | exim -bs -oMa 10.9.8.7.1234 | |
3868 | + | |
3869 | An alternative syntax is to enclose the IP address in square brackets, | |
3870 | followed by a colon and the port number: | |
3871 | ||
3872 | exim -bs -oMa [10.9.8.7]:1234 | |
3873 | + | |
3874 | The IP address is placed in the $sender_host_address$ variable, and the | |
3875 | port, if present, in $sender_host_port$. | |
3876 | ||
3877 | *-oMaa*~<'name'>:: | |
3878 | oindex:[%-oMaa%] | |
3879 | cindex:[authentication name, specifying for local message] | |
3880 | See %-oMa% above for general remarks about the %-oM% options. The %-oMaa% | |
3881 | option sets the value of $sender_host_authenticated$ (the authenticator | |
3882 | name). See chapter <<CHAPSMTPAUTH>> for a discussion of SMTP authentication. | |
3883 | ||
3884 | *-oMai*~<'string'>:: | |
3885 | oindex:[%-oMai%] | |
3886 | cindex:[authentication id, specifying for local message] | |
3887 | See %-oMa% above for general remarks about the %-oM% options. The %-oMai% | |
3888 | option sets the value of $authenticated_id$ (the id that was authenticated). | |
3889 | This overrides the default value (the caller's login id) for messages from | |
3890 | local sources. See chapter <<CHAPSMTPAUTH>> for a discussion of authenticated | |
3891 | ids. | |
3892 | ||
3893 | *-oMas*~<'address'>:: | |
3894 | oindex:[%-oMas%] | |
3895 | cindex:[authentication sender, specifying for local message] | |
3896 | See %-oMa% above for general remarks about the %-oM% options. The %-oMas% | |
3897 | option sets the authenticated sender value in $authenticated_sender$. It | |
3898 | overrides the sender address that is created from the caller's login id for | |
3899 | messages from local sources. See chapter <<CHAPSMTPAUTH>> for a discussion of | |
3900 | authenticated senders. | |
3901 | ||
3902 | *-oMi*~<'interface~address'>:: | |
3903 | oindex:[%-oMi%] | |
3904 | cindex:[interface address, specifying for local message] | |
3905 | See %-oMa% above for general remarks about the %-oM% options. The %-oMi% option | |
3906 | sets the IP interface address value. A port number may be included, using the | |
3907 | same syntax as for %-oMa%. The interface address is placed in | |
3908 | $interface_address$ and the port number, if present, in $interface_port$. | |
3909 | ||
3910 | *-oMr*~<'protocol~name'>:: | |
3911 | oindex:[%-oMr%] | |
3912 | cindex:[protocol,incoming -- specifying for local message] | |
068aaea8 | 3913 | cindex:[$received_protocol$] |
168e428f PH |
3914 | See %-oMa% above for general remarks about the %-oM% options. The %-oMr% option |
3915 | sets the received protocol value that is stored in $received_protocol$. | |
3916 | However, this applies only when %-bs% is not used. For interactive SMTP input | |
3917 | (%-bs%), the protocol is always ``local-'' followed by one of the standard SMTP | |
3918 | protocol names (see the description of $received_protocol$ in section | |
3919 | <<SECTexpvar>>). For %-bS% (batch SMTP) however, the protocol can be set by | |
3920 | <<%-oMr%. | |
3921 | ||
3922 | *-oMs*~<'host~name'>:: | |
3923 | oindex:[%-oMs%] | |
3924 | cindex:[sender host name, specifying for local message] | |
3925 | See %-oMa% above for general remarks about the %-oM% options. The %-oMs% option | |
3926 | sets the sender host name in $sender_host_name$. When this option is present, | |
3927 | Exim does not attempt to look up a host name from an IP address; it uses the | |
3928 | name it is given. | |
3929 | ||
3930 | *-oMt*~<'ident~string'>:: | |
3931 | oindex:[%-oMt%] | |
3932 | cindex:[sender ident string, specifying for local message] | |
3933 | See %-oMa% above for general remarks about the %-oM% options. The %-oMt% option | |
3934 | sets the sender ident value in $sender_ident$. The default setting for local | |
3935 | callers is the login id of the calling process. | |
3936 | ||
3937 | *-om*:: | |
3938 | oindex:[%-om%] | |
3939 | cindex:[Sendmail compatibility,%-om% option ignored] | |
3940 | In Sendmail, this option means ``me too'', indicating that the sender of a | |
3941 | message should receive a copy of the message if the sender appears in an alias | |
3942 | expansion. Exim always does this, so the option does nothing. | |
3943 | ||
3944 | *-oo*:: | |
3945 | oindex:[%-oo%] | |
3946 | cindex:[Sendmail compatibility,%-oo% option ignored] | |
3947 | This option is ignored. In Sendmail it specifies ``old style headers'', whatever | |
3948 | that means. | |
3949 | ||
3950 | *-oP*~<'path'>:: | |
3951 | oindex:[%-oP%] | |
3952 | cindex:[pid (process id),of daemon] | |
3953 | cindex:[daemon,process id (pid)] | |
3954 | This option is useful only in conjunction with %-bd% or %-q% with a time | |
3955 | value. The option specifies the file to which the process id of the daemon is | |
3956 | written. When %-oX% is used with %-bd%, or when %-q% with a time is used | |
3957 | without %-bd%, this is the only way of causing Exim to write a pid file, | |
3958 | because in those cases, the normal pid file is not used. | |
3959 | ||
3960 | *-or*~<'time'>:: | |
3961 | oindex:[%-or%] | |
3962 | cindex:[timeout,for non-SMTP input] | |
3963 | This option sets a timeout value for incoming non-SMTP messages. If it is not | |
3964 | set, Exim will wait forever for the standard input. The value can also be set | |
3965 | by the %receive_timeout% option. The format used for specifying times is | |
3966 | described in section <<SECTtimeformat>>. | |
3967 | ||
3968 | *-os*~<'time'>:: | |
3969 | oindex:[%-os%] | |
3970 | cindex:[timeout,for SMTP input] | |
3971 | cindex:[SMTP timeout, input] | |
3972 | This option sets a timeout value for incoming SMTP messages. The timeout | |
3973 | applies to each SMTP command and block of data. The value can also be set by | |
3974 | the %smtp_receive_timeout% option; it defaults to 5 minutes. The format used | |
3975 | for specifying times is described in section <<SECTtimeformat>>. | |
3976 | ||
3977 | *-ov*:: | |
3978 | oindex:[%-ov%] | |
3979 | This option has exactly the same effect as %-v%. | |
3980 | ||
3981 | *-oX*~<'number~or~string'>:: | |
3982 | oindex:[%-oX%] | |
3983 | cindex:[TCP/IP,setting listening ports] | |
3984 | cindex:[TCP/IP,setting listening interfaces] | |
3985 | cindex:[port,receiving TCP/IP] | |
3986 | This option is relevant only when the %-bd% (start listening daemon) option is | |
3987 | also given. It controls which ports and interfaces the daemon uses. Details of | |
3988 | the syntax, and how it interacts with configuration file options, are given in | |
3989 | chapter <<CHAPinterfaces>>. When %-oX% is used to start a daemon, no pid file is | |
3990 | written unless %-oP% is also present to specify a pid file name. | |
3991 | ||
3992 | *-pd*:: | |
3993 | oindex:[%-pd%] | |
3994 | cindex:[Perl,starting the interpreter] | |
3995 | This option applies when an embedded Perl interpreter is linked with Exim (see | |
3996 | chapter <<CHAPperl>>). It overrides the setting of the %perl_at_start% option, | |
3997 | forcing the starting of the interpreter to be delayed until it is needed. | |
3998 | ||
3999 | *-ps*:: | |
4000 | oindex:[%-ps%] | |
4001 | cindex:[Perl,starting the interpreter] | |
4002 | This option applies when an embedded Perl interpreter is linked with Exim (see | |
4003 | chapter <<CHAPperl>>). It overrides the setting of the %perl_at_start% option, | |
4004 | forcing the starting of the interpreter to occur as soon as Exim is started. | |
4005 | ||
4006 | *-p*<'rval'>:<'sval'>:: | |
4007 | oindex:[%-p%] | |
4008 | For compatibility with Sendmail, this option is equivalent to | |
4009 | ||
4010 | -oMr <rval> -oMs <sval> | |
4011 | + | |
4012 | It sets the incoming protocol and host name (for trusted callers). The | |
4013 | host name and its colon can be omitted when only the protocol is to be set. | |
4014 | Note the Exim already has two private options, %-pd% and %-ps%, that refer to | |
4015 | embedded Perl. It is therefore impossible to set a protocol value of `p` or | |
4016 | `s` using this option (but that does not seem a real limitation). | |
4017 | ||
4018 | *-q*:: | |
4019 | oindex:[%-q%] | |
4020 | cindex:[queue runner,starting manually] | |
4021 | This option is normally restricted to admin users. However, there is a | |
4022 | configuration option called %prod_requires_admin% which can be set false to | |
4023 | relax this restriction (and also the same requirement for the %-M%, %-R%, and | |
4024 | %-S% options). | |
4025 | + | |
4026 | The | |
4027 | cindex:[queue runner,description of operation] | |
4028 | %-q% option starts one queue runner process. This scans the queue of | |
4029 | waiting messages, and runs a delivery process for each one in turn. It waits | |
4030 | for each delivery process to finish before starting the next one. A delivery | |
4031 | process may not actually do any deliveries if the retry times for the addresses | |
4032 | have not been reached. Use %-qf% (see below) if you want to override this. | |
4033 | + | |
4034 | If | |
4035 | cindex:[SMTP,passed connection] | |
4036 | cindex:[SMTP,multiple deliveries] | |
4037 | cindex:[multiple SMTP deliveries] | |
4038 | the delivery process spawns other processes to deliver other messages down | |
4039 | passed SMTP connections, the queue runner waits for these to finish before | |
4040 | proceeding. | |
4041 | + | |
4042 | When all the queued messages have been considered, the original queue runner | |
4043 | process terminates. In other words, a single pass is made over the waiting | |
4044 | mail, one message at a time. Use %-q% with a time (see below) if you want this | |
4045 | to be repeated periodically. | |
4046 | + | |
4047 | Exim processes the waiting messages in an unpredictable order. It isn't very | |
4048 | random, but it is likely to be different each time, which is all that matters. | |
4049 | If one particular message screws up a remote MTA, other messages to the same | |
4050 | MTA have a chance of getting through if they get tried first. | |
4051 | + | |
4052 | It is possible to cause the messages to be processed in lexical message id | |
4053 | order, which is essentially the order in which they arrived, by setting the | |
4054 | %queue_run_in_order% option, but this is not recommended for normal use. | |
4055 | ||
4056 | *-q*<'qflags'>:: | |
4057 | The %-q% option may be followed by one or more flag letters that change its | |
4058 | behaviour. They are all optional, but if more than one is present, they must | |
4059 | appear in the correct order. Each flag is described in a separate item below. | |
4060 | ||
4061 | *-qq...*:: | |
4062 | oindex:[%-qq%] | |
4063 | cindex:[queue,double scanning] | |
4064 | cindex:[queue,routing] | |
4065 | cindex:[routing,whole queue before delivery] | |
4066 | An option starting with %-qq% requests a two-stage queue run. In the first | |
4067 | stage, the queue is scanned as if the %queue_smtp_domains% option matched | |
4068 | every domain. Addresses are routed, local deliveries happen, but no remote | |
4069 | transports are run. | |
4070 | + | |
4071 | The | |
4072 | cindex:[hints database,remembering routing] | |
4073 | hints database that remembers which messages are waiting for specific hosts is | |
4074 | updated, as if delivery to those hosts had been deferred. After this is | |
4075 | complete, a second, normal queue scan happens, with routing and delivery taking | |
4076 | place as normal. Messages that are routed to the same host should mostly be | |
4077 | delivered down a single SMTP | |
4078 | cindex:[SMTP,passed connection] | |
4079 | cindex:[SMTP,multiple deliveries] | |
4080 | cindex:[multiple SMTP deliveries] | |
4081 | connection because of the hints that were set up during the first queue scan. | |
4082 | This option may be useful for hosts that are connected to the Internet | |
4083 | intermittently. | |
4084 | ||
4085 | *-q[q]i...*:: | |
4086 | oindex:[%-qi%] | |
4087 | cindex:[queue,initial delivery] | |
4088 | If the 'i' flag is present, the queue runner runs delivery processes only for | |
4089 | those messages that haven't previously been tried. ('i' stands for ``initial | |
4090 | delivery''.) This can be helpful if you are putting messages on the queue using | |
4091 | %-odq% and want a queue runner just to process the new messages. | |
4092 | ||
4093 | *-q[q][i]f...*:: | |
4094 | oindex:[%-qf%] | |
4095 | cindex:[queue,forcing delivery] | |
4096 | cindex:[delivery,forcing in queue run] | |
4097 | If one 'f' flag is present, a delivery attempt is forced for each non-frozen | |
4098 | message, whereas without %f% only those non-frozen addresses that have passed | |
4099 | their retry times are tried. | |
4100 | ||
4101 | *-q[q][i]ff...*:: | |
4102 | oindex:[%-qff%] | |
4103 | cindex:[frozen messages,forcing delivery] | |
4104 | If 'ff' is present, a delivery attempt is forced for every message, whether | |
4105 | frozen or not. | |
4106 | ||
4107 | *-q[q][i][f[f]]l*:: | |
4108 | oindex:[%-ql%] | |
4109 | cindex:[queue,local deliveries only] | |
4110 | The 'l' (the letter ``ell'') flag specifies that only local deliveries are to be | |
4111 | done. If a message requires any remote deliveries, it remains on the queue for | |
4112 | later delivery. | |
4113 | ||
4114 | *-q*<'qflags'>~<'start~id'>~<'end~id'>:: | |
4115 | cindex:[queue,delivering specific messages] | |
4116 | When scanning the queue, Exim can be made to skip over messages whose ids are | |
4117 | lexically less than a given value by following the %-q% option with a starting | |
4118 | message id. For example: | |
4119 | ||
4120 | exim -q 0t5C6f-0000c8-00 | |
4121 | + | |
4122 | Messages that arrived earlier than `0t5C6f-0000c8-00` are not inspected. If a | |
4123 | second message id is given, messages whose ids are lexically greater than it | |
4124 | are also skipped. If the same id is given twice, for example, | |
4125 | ||
4126 | exim -q 0t5C6f-0000c8-00 0t5C6f-0000c8-00 | |
4127 | + | |
4128 | just one delivery process is started, for that message. This differs from %-M% | |
4129 | in that retry data is respected, and it also differs from %-Mc% in that it | |
4130 | counts as a delivery from a queue run. Note that the selection mechanism does | |
4131 | not affect the order in which the messages are scanned. There are also other | |
4132 | ways of selecting specific sets of messages for delivery in a queue run -- see | |
4133 | %-R% and %-S%. | |
4134 | ||
4135 | *-q*<'qflags'><'time'>:: | |
4136 | cindex:[queue runner,starting periodically] | |
4137 | cindex:[periodic queue running] | |
4138 | When a time value is present, the %-q% option causes Exim to run as a daemon, | |
4139 | starting a queue runner process at intervals specified by the given time value | |
4140 | (whose format is described in section <<SECTtimeformat>>). This form of the %-q% | |
4141 | option is commonly combined with the %-bd% option, in which case a single | |
4142 | daemon process handles both functions. A common way of starting up a combined | |
4143 | daemon at system boot time is to use a command such as | |
4144 | ||
4145 | /usr/exim/bin/exim -bd -q30m | |
4146 | + | |
4147 | Such a daemon listens for incoming SMTP calls, and also starts a queue runner | |
4148 | process every 30 minutes. | |
4149 | + | |
4150 | When a daemon is started by %-q% with a time value, but without %-bd%, no pid | |
4151 | file is written unless one is explicitly requested by the %-oP% option. | |
4152 | ||
4153 | *-qR*<'rsflags'>~<'string'>:: | |
4154 | oindex:[%-qR%] | |
4155 | This option is synonymous with %-R%. It is provided for Sendmail compatibility. | |
4156 | ||
4157 | *-qS*<'rsflags'>~<'string'>:: | |
4158 | oindex:[%-qS%] | |
4159 | This option is synonymous with %-S%. | |
4160 | ||
4161 | *-R*<'rsflags'>~<'string'>:: | |
4162 | oindex:[%-R%] | |
4163 | cindex:[queue runner,for specific recipients] | |
4164 | cindex:[delivery,to given domain] | |
4165 | cindex:[domain,delivery to] | |
4166 | The <'rsflags'> may be empty, in which case the white space before the string | |
4167 | is optional, unless the string is 'f', 'ff', 'r', 'rf', or 'rff', which are the | |
4168 | possible values for <'rsflags'>. White space is required if <'rsflags'> is not | |
4169 | empty. | |
4170 | + | |
4171 | This option is similar to %-q% with no time value, that is, it causes Exim to | |
4172 | perform a single queue run, except that, when scanning the messages on the | |
4173 | queue, Exim processes only those that have at least one undelivered recipient | |
4174 | address containing the given string, which is checked in a case-independent | |
4175 | way. If the <'rsflags'> start with 'r', <'string'> is interpreted as a regular | |
4176 | expression; otherwise it is a literal string. | |
4177 | + | |
4178 | Once a message is selected, all its addresses are processed. For the first | |
4179 | selected message, Exim overrides any retry information and forces a delivery | |
4180 | attempt for each undelivered address. This means that if delivery of any | |
4181 | address in the first message is successful, any existing retry information is | |
4182 | deleted, and so delivery attempts for that address in subsequently selected | |
4183 | messages (which are processed without forcing) will run. However, if delivery | |
4184 | of any address does not succeed, the retry information is updated, and in | |
4185 | subsequently selected messages, the failing address will be skipped. | |
4186 | + | |
4187 | If the <'rsflags'> contain 'f' or 'ff', the delivery forcing applies to all | |
4188 | selected messages, not just the first; | |
4189 | cindex:[frozen messages,forcing delivery] | |
4190 | frozen messages are included when 'ff' is present. | |
4191 | + | |
4192 | The %-R% option makes it straightforward to initiate delivery of all messages | |
4193 | to a given domain after a host has been down for some time. When the SMTP | |
4194 | command ETRN is accepted by its ACL (see chapter <<CHAPACL>>), its default | |
4195 | effect is to run Exim with the %-R% option, but it can be configured to run an | |
4196 | arbitrary command instead. | |
4197 | ||
4198 | *-r*:: | |
4199 | oindex:[%-r%] | |
4200 | This is a documented (for Sendmail) obsolete alternative name for %-f%. | |
4201 | ||
4202 | *-S*<'rsflags'>~<'string'>:: | |
4203 | oindex:[%-S%] | |
4204 | cindex:[delivery,from given sender] | |
4205 | cindex:[queue runner,for specific senders] | |
4206 | This option acts like %-R% except that it checks the string against each | |
4207 | message's sender instead of against the recipients. If %-R% is also set, both | |
4208 | conditions must be met for a message to be selected. If either of the options | |
4209 | has 'f' or 'ff' in its flags, the associated action is taken. | |
4210 | ||
4211 | *-Tqt*~<'times'>:: | |
4212 | oindex:[%-Tqt%] | |
4213 | This an option that is exclusively for use by the Exim testing suite. It is not | |
4214 | recognized when Exim is run normally. It allows for the setting up of explicit | |
4215 | ``queue times'' so that various warning/retry features can be tested. | |
4216 | ||
4217 | *-t*:: | |
4218 | oindex:[%-t%] | |
4219 | cindex:[recipient,extracting from header lines] | |
4220 | cindex:['Bcc:' header line] | |
4221 | cindex:['Cc:' header line] | |
4222 | cindex:['To:' header line] | |
4223 | When Exim is receiving a locally-generated, non-SMTP message on its standard | |
4224 | input, the %-t% option causes the recipients of the message to be obtained | |
4225 | from the 'To:', 'Cc:', and 'Bcc:' header lines in the message instead of from | |
4226 | the command arguments. The addresses are extracted before any rewriting takes | |
4227 | place. | |
4228 | + | |
4229 | If | |
4230 | cindex:[Sendmail compatibility,%-t% option] | |
4231 | the command has any arguments, they specify addresses to which the message | |
4232 | is 'not' to be delivered. That is, the argument addresses are removed from | |
4233 | the recipients list obtained from the headers. This is compatible with Smail 3 | |
4234 | and in accordance with the documented behaviour of several versions of | |
4235 | Sendmail, as described in man pages on a number of operating systems (e.g. | |
4236 | Solaris 8, IRIX 6.5, HP-UX 11). However, some versions of Sendmail 'add' | |
4237 | argument addresses to those obtained from the headers, and the O'Reilly | |
4238 | Sendmail book documents it that way. Exim can be made to add argument addresses | |
4239 | instead of subtracting them by setting the option | |
4240 | %extract_addresses_remove_arguments% false. | |
4241 | + | |
4242 | If a 'Bcc:' header line is present, it is removed from the message unless | |
4243 | there is no 'To:' or 'Cc:', in which case a 'Bcc:' line with no data is | |
4244 | created. This is necessary for conformity with the original RFC 822 standard; | |
4245 | the requirement has been removed in RFC 2822, but that is still very new. | |
4246 | + | |
4247 | If | |
4248 | cindex:[%Resent-% header lines,with %-t%] | |
4249 | there are any %Resent-% header lines in the message, Exim extracts | |
4250 | recipients from all 'Resent-To:', 'Resent-Cc:', and 'Resent-Bcc:' header | |
4251 | lines instead of from 'To:', 'Cc:', and 'Bcc:'. This is for compatibility | |
4252 | with Sendmail and other MTAs. (Prior to release 4.20, Exim gave an error if | |
4253 | %-t% was used in conjunction with %Resent-% header lines.) | |
4254 | + | |
4255 | RFC 2822 talks about different sets of %Resent-% header lines (for when a | |
4256 | message is resent several times). The RFC also specifies that they should be | |
4257 | added at the front of the message, and separated by 'Received:' lines. It is | |
4258 | not at all clear how %-t% should operate in the present of multiple sets, | |
4259 | nor indeed exactly what constitutes a ``set''. | |
4260 | In practice, it seems that MUAs do not follow the RFC. The %Resent-% lines are | |
4261 | often added at the end of the header, and if a message is resent more than | |
4262 | once, it is common for the original set of %Resent-% headers to be renamed as | |
4263 | %X-Resent-% when a new set is added. This removes any possible ambiguity. | |
4264 | ||
4265 | *-ti*:: | |
4266 | oindex:[%-ti%] | |
4267 | This option is exactly equivalent to %-t% %-i%. It is provided for | |
4268 | compatibility with Sendmail. | |
4269 | ||
4270 | *-tls-on-connect*:: | |
4271 | oindex:[%-tls-on-connect%] | |
4272 | cindex:[TLS,use without STARTTLS] | |
4273 | cindex:[TLS,automatic start] | |
4274 | This option is available when Exim is compiled with TLS support. It forces all | |
4275 | incoming SMTP connections to behave as if the incoming port is listed in the | |
4276 | %tls_on_connect_ports% option. See section <<SECTsupobssmt>> and chapter | |
4277 | <<CHAPTLS>> for further details. | |
4278 | ||
4279 | ||
4280 | *-U*:: | |
4281 | oindex:[%-U%] | |
4282 | cindex:[Sendmail compatibility,%-U% option ignored] | |
4283 | Sendmail uses this option for ``initial message submission'', and its | |
4284 | documentation states that in future releases, it may complain about | |
4285 | syntactically invalid messages rather than fixing them when this flag is not | |
4286 | set. Exim ignores this option. | |
4287 | ||
4288 | *-v*:: | |
4289 | oindex:[%-v%] | |
4290 | This option causes Exim to write information to the standard error stream, | |
4291 | describing what it is doing. In particular, it shows the log lines for | |
4292 | receiving and delivering a message, and if an SMTP connection is made, the SMTP | |
4293 | dialogue is shown. Some of the log lines shown may not actually be written to | |
4294 | the log if the setting of %log_selector% discards them. Any relevant selectors | |
4295 | are shown with each log line. If none are shown, the logging is unconditional. | |
4296 | ||
4297 | *-x*:: | |
4298 | oindex:[%-x%] | |
4299 | AIX uses %-x% for a private purpose (``mail from a local mail program has | |
4300 | National Language Support extended characters in the body of the mail item''). | |
4301 | It sets %-x% when calling the MTA from its %mail% command. Exim ignores this | |
4302 | option. | |
4303 | ||
4304 | /// | |
4305 | We insert a stylized DocBook comment here, to identify the end of the command | |
4306 | line options. This is for the benefit of the Perl script that automatically | |
4307 | creates a man page for the options. | |
4308 | /// | |
4309 | ||
4310 | ++++ | |
4311 | <!-- === End of command line options === --> | |
4312 | ++++ | |
4313 | ||
4314 | ||
4315 | ||
4316 | ||
4317 | ||
4318 | //////////////////////////////////////////////////////////////////////////// | |
4319 | //////////////////////////////////////////////////////////////////////////// | |
4320 | ||
4321 | ||
4322 | [[CHAPconf]] | |
4323 | [titleabbrev="The runtime configuration file"] | |
4324 | The Exim run time configuration file | |
4325 | ------------------------------------ | |
4326 | ||
4327 | cindex:[run time configuration] | |
4328 | cindex:[configuration file,general description] | |
4329 | cindex:[CONFIGURE_FILE] | |
4330 | cindex:[configuration file,errors in] | |
4331 | cindex:[error,in configuration file] | |
4332 | cindex:[return code,for bad configuration] | |
4333 | Exim uses a single run time configuration file that is read whenever an Exim | |
4334 | binary is executed. Note that in normal operation, this happens frequently, | |
4335 | because Exim is designed to operate in a distributed manner, without central | |
4336 | control. | |
4337 | ||
4338 | If a syntax error is detected while reading the configuration file, Exim | |
4339 | writes a message on the standard error, and exits with a non-zero return code. | |
4340 | The message is also written to the panic log. *Note*: only simple syntax | |
4341 | errors can be detected at this time. The values of any expanded options are | |
4342 | not checked until the expansion happens, even when the expansion does not | |
4343 | actually alter the string. | |
4344 | ||
4345 | ||
4346 | ||
4347 | The name of the configuration file is compiled into the binary for security | |
4348 | reasons, and is specified by the CONFIGURE_FILE compilation option. In | |
4349 | most configurations, this specifies a single file. However, it is permitted to | |
4350 | give a colon-separated list of file names, in which case Exim uses the first | |
4351 | existing file in the list. | |
4352 | ||
4353 | cindex:[EXIM_USER] | |
4354 | cindex:[EXIM_GROUP] | |
4355 | cindex:[CONFIGURE_OWNER] | |
4356 | cindex:[CONFIGURE_GROUP] | |
4357 | cindex:[configuration file,ownership] | |
4358 | cindex:[ownership,configuration file] | |
4359 | The run time configuration file must be owned by root or by the user that is | |
4360 | specified at compile time by the EXIM_USER option, or by the user that is | |
4361 | specified at compile time by the CONFIGURE_OWNER option (if set). The | |
4362 | configuration file must not be world-writeable or group-writeable, unless its | |
4363 | group is the one specified at compile time by the EXIM_GROUP option | |
4364 | ||
4365 | or by the CONFIGURE_GROUP option. | |
4366 | ||
4367 | ||
4368 | *Warning*: In a conventional configuration, where the Exim binary is setuid | |
4369 | to root, anybody who is able to edit the run time configuration file has an | |
4370 | easy way to run commands as root. If you make your mail administrators members | |
4371 | of the Exim group, but do not trust them with root, make sure that the run time | |
4372 | configuration is not group writeable. | |
4373 | ||
4374 | A default configuration file, which will work correctly in simple situations, | |
4375 | is provided in the file _src/configure.default_. If CONFIGURE_FILE | |
4376 | defines just one file name, the installation process copies the default | |
4377 | configuration to a new file of that name if it did not previously exist. If | |
4378 | CONFIGURE_FILE is a list, no default is automatically installed. Chapter | |
4379 | <<CHAPdefconfil>> is a ``walk-through'' discussion of the default configuration. | |
4380 | ||
4381 | ||
4382 | ||
4383 | Using a different configuration file | |
4384 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
4385 | cindex:[configuration file,alternate] | |
4386 | A one-off alternate configuration can be specified by the %-C% command line | |
4387 | option, which may specify a single file or a list of files. However, when %-C% | |
4388 | is used, Exim gives up its root privilege, unless called by root or the Exim | |
4389 | user (or unless the argument for %-C% is identical to the built-in value from | |
4390 | CONFIGURE_FILE). %-C% is useful mainly for checking the syntax of | |
4391 | configuration files before installing them. No owner or group checks are done | |
4392 | on a configuration file specified by %-C%. | |
4393 | ||
4394 | The privileged use of %-C% by the Exim user can be locked out by setting | |
4395 | ALT_CONFIG_ROOT_ONLY in _Local/Makefile_ when building Exim. However, | |
4396 | if you do this, you also lock out the possibility of testing a | |
4397 | configuration using %-C% right through message reception and delivery, even if | |
4398 | the caller is root. The reception works, but by that time, Exim is running as | |
4399 | the Exim user, so when it re-execs to regain privilege for the delivery, the | |
4400 | use of %-C% causes privilege to be lost. However, root can test reception and | |
4401 | delivery using two separate commands (one to put a message on the queue, using | |
4402 | %-odq%, and another to do the delivery, using %-M%). | |
4403 | ||
4404 | If ALT_CONFIG_PREFIX is defined _in Local/Makefile_, it specifies a | |
4405 | prefix string with which any file named in a %-C% command line option must | |
068aaea8 PH |
4406 | start. In addition, the file name must not contain the sequence ``##`/../`##''. |
4407 | There is no default setting for ALT_CONFIG_PREFIX; when it is unset, any file | |
168e428f PH |
4408 | name can be used with %-C%. |
4409 | ||
4410 | One-off changes to a configuration can be specified by the %-D% command line | |
4411 | option, which defines and overrides values for macros used inside the | |
4412 | configuration file. However, like %-C%, the use of this option by a | |
4413 | non-privileged user causes Exim to discard its root privilege. | |
4414 | If DISABLE_D_OPTION is defined in _Local/Makefile_, the use of %-D% is | |
4415 | completely disabled, and its use causes an immediate error exit. | |
4416 | ||
4417 | Some sites may wish to use the same Exim binary on different machines that | |
4418 | share a file system, but to use different configuration files on each machine. | |
4419 | If CONFIGURE_FILE_USE_NODE is defined in _Local/Makefile_, Exim first | |
4420 | looks for a file whose name is the configuration file name followed by a dot | |
4421 | and the machine's node name, as obtained from the 'uname()' function. If this | |
4422 | file does not exist, the standard name is tried. This processing occurs for | |
4423 | each file name in the list given by CONFIGURE_FILE or %-C%. | |
4424 | ||
4425 | In some esoteric situations different versions of Exim may be run under | |
4426 | different effective uids and the CONFIGURE_FILE_USE_EUID is defined to | |
4427 | help with this. See the comments in _src/EDITME_ for details. | |
4428 | ||
4429 | ||
4430 | ||
4431 | [[SECTconffilfor]] | |
4432 | Configuration file format | |
4433 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
4434 | cindex:[configuration file,format of] | |
4435 | cindex:[format,configuration file] | |
4436 | Exim's configuration file is divided into a number of different parts. General | |
4437 | option settings must always appear at the start of the file. The other parts | |
4438 | are all optional, and may appear in any order. Each part other than the first | |
4439 | is introduced by the word ``begin'' followed by the name of the part. The | |
4440 | optional parts are: | |
4441 | ||
4442 | - 'ACL': Access control lists for controlling incoming SMTP mail. | |
4443 | ||
4444 | - cindex:[AUTH,configuration] | |
4445 | 'authenticators': Configuration settings for the authenticator drivers. These | |
4446 | are concerned with the SMTP AUTH command (see chapter <<CHAPSMTPAUTH>>). | |
4447 | ||
4448 | - 'routers': Configuration settings for the router drivers. Routers process | |
4449 | addresses and determine how the message is to be delivered. | |
4450 | ||
4451 | - 'transports': Configuration settings for the transport drivers. Transports | |
4452 | define mechanisms for copying messages to destinations. | |
4453 | ||
4454 | - 'retry': Retry rules, for use when a message cannot be immediately delivered. | |
4455 | ||
4456 | - 'rewrite': Global address rewriting rules, for use when a message arrives and | |
4457 | when new addresses are generated during delivery. | |
4458 | ||
4459 | - 'local_scan': Private options for the 'local_scan()' function. If you | |
4460 | want to use this feature, you must set | |
4461 | ||
4462 | LOCAL_SCAN_HAS_OPTIONS=yes | |
4463 | + | |
4464 | in _Local/Makefile_ before building Exim. Full details of the | |
4465 | 'local_scan()' facility are given in chapter <<CHAPlocalscan>>. | |
4466 | ||
068aaea8 PH |
4467 | cindex:[configuration file,leading white space in] |
4468 | cindex:[configuration file,trailing white space in] | |
4469 | cindex:[white space,in configuration file] | |
4470 | Leading and trailing white space in configuration lines is always ignored. | |
168e428f PH |
4471 | |
4472 | Blank lines in the file, and lines starting with a # character (ignoring | |
4473 | leading white space) are treated as comments and are ignored. *Note*: a | |
4474 | # character other than at the beginning of a line is not treated specially, | |
4475 | and does not introduce a comment. | |
4476 | ||
4477 | Any non-comment line can be continued by ending it with a backslash. Note that | |
068aaea8 PH |
4478 | the general rule for white space means that trailing white space after the |
4479 | backslash and leading white space at the start of continuation | |
4480 | lines is ignored. Comment lines beginning with # (but not empty lines) may | |
168e428f PH |
4481 | appear in the middle of a sequence of continuation lines. |
4482 | ||
4483 | A convenient way to create a configuration file is to start from the | |
4484 | default, which is supplied in _src/configure.default_, and add, delete, or | |
4485 | change settings as required. | |
4486 | ||
4487 | The ACLs, retry rules, and rewriting rules have their own syntax which is | |
4488 | described in chapters <<CHAPACL>>, <<CHAPretry>>, and <<CHAPrewrite>>, | |
4489 | respectively. The other parts of the configuration file have some syntactic | |
4490 | items in common, and these are described below, from section <<SECTcos>> | |
4491 | onwards. Before that, the inclusion, macro, and conditional facilities are | |
4492 | described. | |
4493 | ||
4494 | ||
4495 | ||
4496 | File inclusions in the configuration file | |
4497 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
4498 | cindex:[inclusions in configuration file] | |
4499 | cindex:[configuration file,including other files] | |
4500 | cindex:[.include in configuration file] | |
4501 | cindex:[.include_if_exists in configuration file] | |
4502 | You can include other files inside Exim's run time configuration file by | |
4503 | using this syntax: | |
4504 | ||
4505 | .include <file name> | |
4506 | ||
4507 | or | |
4508 | ||
4509 | .include_if_exists <file name> | |
4510 | ||
4511 | on a line by itself. Double quotes round the file name are optional. If you use | |
4512 | the first form, a configuration error occurs if the file does not exist; the | |
4513 | second form does nothing for non-existent files. | |
4514 | ||
4515 | Includes may be nested to any depth, but remember that Exim reads its | |
4516 | configuration file often, so it is a good idea to keep them to a minimum. | |
4517 | If you change the contents of an included file, you must HUP the daemon, | |
4518 | because an included file is read only when the configuration itself is read. | |
4519 | ||
4520 | The processing of inclusions happens early, at a physical line level, so, like | |
4521 | comment lines, an inclusion can be used in the middle of an option setting, | |
4522 | for example: | |
4523 | ||
4524 | .... | |
4525 | hosts_lookup = a.b.c \ | |
4526 | .include /some/file | |
4527 | .... | |
4528 | ||
4529 | Include processing happens after macro processing (see below). Its effect is to | |
4530 | process the lines of the file as if they occurred inline where the inclusion | |
4531 | appears. | |
4532 | ||
4533 | ||
4534 | ||
4535 | [[SECTmacrodefs]] | |
4536 | Macros in the configuration file | |
4537 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
4538 | cindex:[macro,description of] | |
4539 | cindex:[configuration file,macros] | |
4540 | If a line in the main part of the configuration (that is, before the first | |
4541 | ``begin'' line) begins with an upper case letter, it is taken as a macro | |
4542 | definition, and must be of the form | |
4543 | ||
4544 | &&& | |
4545 | <'name'> = <'rest of line'> | |
4546 | &&& | |
4547 | ||
4548 | The name must consist of letters, digits, and underscores, and need not all be | |
4549 | in upper case, though that is recommended. The rest of the line, including any | |
4550 | continuations, is the replacement text, and has leading and trailing white | |
4551 | space removed. Quotes are not removed. The replacement text can never end with | |
4552 | a backslash character, but this doesn't seem to be a serious limitation. | |
4553 | ||
068aaea8 PH |
4554 | [revisionflag="changed"] |
4555 | Macros may also be defined between router, transport, authenticator, or ACL | |
4556 | definitions. They may not, however, be defined within an individual driver or | |
4557 | ACL, or in the %local_scan%, retry, or rewrite sections of the configuration. | |
4558 | ||
4559 | ||
4560 | Macro substitution | |
4561 | ~~~~~~~~~~~~~~~~~~ | |
168e428f PH |
4562 | Once a macro is defined, all subsequent lines in the file (and any included |
4563 | files) are scanned for the macro name; if there are several macros, the line is | |
068aaea8 | 4564 | scanned for each in turn, in the order in which the macros are defined. The |
168e428f PH |
4565 | replacement text is not re-scanned for the current macro, though it is scanned |
4566 | for subsequently defined macros. For this reason, a macro name may not contain | |
4567 | the name of a previously defined macro as a substring. You could, for example, | |
4568 | define | |
4569 | ||
4570 | &&& | |
4571 | `ABCD_XYZ = `<'something'> | |
4572 | `ABCD = `<'something else'> | |
4573 | &&& | |
4574 | ||
4575 | but putting the definitions in the opposite order would provoke a configuration | |
068aaea8 PH |
4576 | error. Macro expansion is applied to individual physical lines from the file, |
4577 | before checking for line continuation or file inclusion (see above). If a line | |
4578 | consists solely of a macro name, and the expansion of the macro is empty, the | |
4579 | line is ignored. A macro at the start of a line may turn the line into a | |
4580 | comment line or a `.include` line. | |
4581 | ||
4582 | ||
4583 | Redefining macros | |
4584 | ~~~~~~~~~~~~~~~~~ | |
4585 | [revisionflag="changed"] | |
4586 | Once defined, the value of a macro can be redefined later in the configuration | |
4587 | (or in an included file). Redefinition is specified by using '==' instead of | |
4588 | '='. For example: | |
4589 | ||
4590 | MAC = initial value | |
4591 | ... | |
4592 | MAC == updated value | |
4593 | ||
4594 | Redefinition does not alter the order in which the macros are applied to | |
4595 | the subsequent lines of the configuration file. It is still the same | |
4596 | order in which the macros were originally defined. All that changes is | |
4597 | the macro's value. Redefinition makes it possible to accumulate values. | |
4598 | For example: | |
4599 | ||
4600 | MAC = initial value | |
4601 | ... | |
4602 | MAC == MAC and something added | |
4603 | ||
4604 | This can be helpful in situations where the configuration file is built | |
4605 | from a number of other files. | |
4606 | ||
4607 | ||
4608 | Overriding macro values | |
4609 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
4610 | The values set for macros in the configuration file can be overridden by the | |
4611 | %-D% command line option, but Exim gives up its root privilege when %-D% is | |
4612 | used, unless called by root or the Exim user. A definition on the command line | |
4613 | using the %-D% option causes all definitions and redefinitions within the file | |
4614 | to be ignored. | |
4615 | ||
168e428f | 4616 | |
168e428f | 4617 | |
068aaea8 PH |
4618 | Example of macro usage |
4619 | ~~~~~~~~~~~~~~~~~~~~~~ | |
168e428f PH |
4620 | As an example of macro usage, consider a configuration where aliases are looked |
4621 | up in a MySQL database. It helps to keep the file less cluttered if long | |
4622 | strings such as SQL statements are defined separately as macros, for example: | |
4623 | ||
4624 | .... | |
4625 | ALIAS_QUERY = select mailbox from user where \ | |
4626 | login=${quote_mysql:$local_part}; | |
4627 | .... | |
4628 | ||
4629 | This can then be used in a ^redirect^ router setting like this: | |
4630 | ||
4631 | data = ${lookup mysql{ALIAS_QUERY}} | |
4632 | ||
4633 | In earlier versions of Exim macros were sometimes used for domain, host, or | |
4634 | address lists. In Exim 4 these are handled better by named lists -- see section | |
4635 | <<SECTnamedlists>>. | |
4636 | ||
168e428f PH |
4637 | |
4638 | Conditional skips in the configuration file | |
4639 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
4640 | cindex:[configuration file,conditional skips] | |
4641 | cindex:[.ifdef] | |
4642 | You can use the directives `.ifdef`, `.ifndef`, `.elifdef`, | |
4643 | `.elifndef`, `.else`, and `.endif` to dynamically include or exclude | |
4644 | portions of the configuration file. The processing happens whenever the file is | |
4645 | read (that is, when an Exim binary starts to run). | |
4646 | ||
4647 | The implementation is very simple. Instances of the first four directives must | |
4648 | be followed by text that includes the names of one or macros. The condition | |
4649 | that is tested is whether or not any macro substitution has taken place in the | |
4650 | line. Thus: | |
4651 | ||
4652 | .ifdef AAA | |
4653 | message_size_limit = 50M | |
4654 | .else | |
4655 | message_size_limit = 100M | |
4656 | .endif | |
4657 | ||
4658 | sets a message size limit of 50M if the macro `AAA` is defined, and 100M | |
4659 | otherwise. If there is more than one macro named on the line, the condition | |
4660 | is true if any of them are defined. That is, it is an ``or'' condition. To | |
4661 | obtain an ``and'' condition, you need to use nested `.ifdef`##s. | |
4662 | ||
4663 | Although you can use a macro expansion to generate one of these directives, | |
4664 | it is not very useful, because the condition ``there was a macro substitution | |
4665 | in this line'' will always be true. | |
4666 | ||
4667 | Text following `.else` and `.endif` is ignored, and can be used as comment | |
4668 | to clarify complicated nestings. | |
4669 | ||
4670 | ||
4671 | ||
4672 | [[SECTcos]] | |
4673 | Common option syntax | |
4674 | ~~~~~~~~~~~~~~~~~~~~ | |
4675 | cindex:[common option syntax] | |
4676 | cindex:[syntax of common options] | |
4677 | cindex:[configuration file,common option syntax] | |
4678 | For the main set of options, driver options, and 'local_scan()' options, | |
4679 | each setting is on a line by itself, and starts with a name consisting of | |
4680 | lower-case letters and underscores. Many options require a data value, and in | |
4681 | these cases the name must be followed by an equals sign (with optional white | |
4682 | space) and then the value. For example: | |
4683 | ||
4684 | qualify_domain = mydomain.example.com | |
4685 | ||
4686 | Some option settings may contain sensitive data, for example, passwords for | |
4687 | accessing databases. To stop non-admin users from using the %-bP% command line | |
4688 | option to read these values, you can precede the option settings with the word | |
4689 | ``hide''. For example: | |
4690 | ||
4691 | hide mysql_servers = localhost/users/admin/secret-password | |
4692 | ||
4693 | For non-admin users, such options are displayed like this: | |
4694 | ||
4695 | mysql_servers = <value not displayable> | |
4696 | ||
4697 | If ``hide'' is used on a driver option, it hides the value of that option on all | |
4698 | instances of the same driver. | |
4699 | ||
4700 | The following sections describe the syntax used for the different data types | |
4701 | that are found in option settings. | |
4702 | ||
4703 | ||
4704 | Boolean options | |
4705 | ~~~~~~~~~~~~~~~ | |
4706 | cindex:[format,boolean] | |
4707 | cindex:[boolean configuration values] | |
068aaea8 PH |
4708 | oindex:[%no_%'xxx'] |
4709 | oindex:[%not_%'xxx'] | |
168e428f PH |
4710 | Options whose type is given as boolean are on/off switches. There are two |
4711 | different ways of specifying such options: with and without a data value. If | |
4712 | the option name is specified on its own without data, the switch is turned on; | |
4713 | if it is preceded by ``no_'' or ``not_'' the switch is turned off. However, | |
068aaea8 PH |
4714 | boolean options may be followed by an equals sign and one of the words |
4715 | ``true'', ``false'', ``yes'', or ``no'', as an alternative syntax. For example, | |
168e428f PH |
4716 | the following two settings have exactly the same effect: |
4717 | ||
4718 | queue_only | |
4719 | queue_only = true | |
4720 | ||
4721 | The following two lines also have the same (opposite) effect: | |
4722 | ||
4723 | no_queue_only | |
4724 | queue_only = false | |
4725 | ||
4726 | You can use whichever syntax you prefer. | |
4727 | ||
4728 | ||
4729 | ||
4730 | ||
4731 | Integer values | |
4732 | ~~~~~~~~~~~~~~ | |
4733 | cindex:[integer configuration values] | |
4734 | cindex:[format,integer] | |
4735 | If an integer data item starts with the characters ``0x'', the remainder of it | |
4736 | is interpreted as a hexadecimal number. Otherwise, it is treated as octal if it | |
4737 | starts with the digit 0, and decimal if not. If an integer value is followed by | |
4738 | the letter K, it is multiplied by 1024; if it is followed by the letter M, it | |
4739 | is multiplied by 1024x1024. | |
4740 | ||
4741 | When the values of integer option settings are output, values which are an | |
4742 | exact multiple of 1024 or 1024x1024 are | |
4743 | sometimes, but not always, | |
4744 | printed using the letters K and M. The printing style is independent of the | |
4745 | actual input format that was used. | |
4746 | ||
4747 | ||
4748 | Octal integer values | |
4749 | ~~~~~~~~~~~~~~~~~~~~ | |
4750 | cindex:[integer format] | |
4751 | cindex:[format,octal integer] | |
4752 | The value of an option specified as an octal integer is always interpreted in | |
4753 | octal, whether or not it starts with the digit zero. Such options are always | |
4754 | output in octal. | |
4755 | ||
4756 | ||
4757 | ||
4758 | Fixed point number values | |
4759 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
4760 | cindex:[fixed point configuration values] | |
4761 | cindex:[format,fixed point] | |
4762 | A fixed point number consists of a decimal integer, optionally followed by a | |
4763 | decimal point and up to three further digits. | |
4764 | ||
4765 | ||
4766 | ||
4767 | [[SECTtimeformat]] | |
4768 | Time interval values | |
4769 | ~~~~~~~~~~~~~~~~~~~~ | |
4770 | cindex:[time interval,specifying in configuration] | |
4771 | cindex:[format,time interval] | |
4772 | A time interval is specified as a sequence of numbers, each followed by one of | |
4773 | the following letters, with no intervening white space: | |
4774 | ||
4775 | [frame="none"] | |
4776 | `-`-----`-------- | |
4777 | %s% seconds | |
4778 | %m% minutes | |
4779 | %h% hours | |
4780 | %d% days | |
4781 | %w% weeks | |
4782 | ----------------- | |
4783 | ||
4784 | For example, ``3h50m'' specifies 3 hours and 50 minutes. The values of time | |
4785 | intervals are output in the same format. Exim does not restrict the values; it | |
4786 | is perfectly acceptable, for example, to specify ``90m'' instead of ``1h30m''. | |
4787 | ||
4788 | ||
4789 | ||
4790 | [[SECTstrings]] | |
4791 | String values | |
4792 | ~~~~~~~~~~~~~ | |
4793 | cindex:[string,format of configuration values] | |
4794 | cindex:[format,string] | |
4795 | If a string data item does not start with a double-quote character, it is taken | |
4796 | as consisting of the remainder of the line plus any continuation lines, | |
4797 | starting at the first character after any leading white space, with trailing | |
4798 | white space characters removed, and with no interpretation of the characters in | |
4799 | the string. Because Exim removes comment lines (those beginning with #) at an | |
4800 | early stage, they can appear in the middle of a multi-line string. The | |
4801 | following settings are therefore equivalent: | |
4802 | ||
4803 | .... | |
4804 | trusted_users = uucp:mail | |
4805 | ||
4806 | trusted_users = uucp:\ | |
4807 | # This comment line is ignored | |
4808 | ||
4809 | .... | |
4810 | ||
4811 | cindex:[string,quoted] | |
4812 | cindex:[escape characters in quoted strings] | |
4813 | If a string does start with a double-quote, it must end with a closing | |
4814 | double-quote, and any backslash characters other than those used for line | |
4815 | continuation are interpreted as escape characters, as follows: | |
4816 | ||
4817 | [frame="none"] | |
4818 | `-`----------------------`-------------------------------------------------- | |
4819 | `\\` single backslash | |
4820 | `\n` newline | |
4821 | `\r` carriage return | |
4822 | `\t` tab | |
4823 | `\`<'octal digits'> up to 3 octal digits specify one character | |
4824 | `\x`<'hex digits'> up to 2 hexadecimal digits specify one character | |
4825 | ---------------------------------------------------------------------------- | |
4826 | ||
4827 | If a backslash is followed by some other character, including a double-quote | |
4828 | character, that character replaces the pair. | |
4829 | ||
4830 | Quoting is necessary only if you want to make use of the backslash escapes to | |
4831 | insert special characters, or if you need to specify a value with leading or | |
4832 | trailing spaces. These cases are rare, so quoting is almost never needed in | |
4833 | current versions of Exim. In versions of Exim before 3.14, quoting was required | |
4834 | in order to continue lines, so you may come across older configuration files | |
4835 | and examples that apparently quote unnecessarily. | |
4836 | ||
4837 | ||
4838 | Expanded strings | |
4839 | ~~~~~~~~~~~~~~~~ | |
4840 | cindex:[string expansion, definition of] | |
4841 | cindex:[expansion,definition of] | |
4842 | Some strings in the configuration file are subjected to 'string expansion', | |
4843 | by which means various parts of the string may be changed according to the | |
4844 | circumstances (see chapter <<CHAPexpand>>). The input syntax for such strings is | |
4845 | as just described; in particular, the handling of backslashes in quoted strings | |
4846 | is done as part of the input process, before expansion takes place. However, | |
4847 | backslash is also an escape character for the expander, so any backslashes that | |
4848 | are required for that reason must be doubled if they are within a quoted | |
4849 | configuration string. | |
4850 | ||
4851 | ||
4852 | User and group names | |
4853 | ~~~~~~~~~~~~~~~~~~~~ | |
4854 | cindex:[user name,format of] | |
4855 | cindex:[format,user name] | |
4856 | cindex:[group,name format] | |
4857 | cindex:[format,group name] | |
4858 | User and group names are specified as strings, using the syntax described | |
4859 | above, but the strings are interpreted specially. A user or group name must | |
4860 | either consist entirely of digits, or be a name that can be looked up using the | |
4861 | 'getpwnam()' or 'getgrnam()' function, as appropriate. | |
4862 | ||
4863 | ||
4864 | [[SECTlistconstruct]] | |
4865 | List construction | |
4866 | ~~~~~~~~~~~~~~~~~ | |
4867 | cindex:[list,syntax of in configuration] | |
4868 | cindex:[format,list item in configuration] | |
4869 | cindex:[string list, definition] | |
4870 | The data for some configuration options is a list of items, with colon as the | |
4871 | default separator. Many of these options are shown with type ``string list'' in | |
4872 | the descriptions later in this document. Others are listed as ``domain list'', | |
068aaea8 PH |
4873 | ``host list'', ``address list'', or ``local part list''. Syntactically, they |
4874 | are all the same; however, those other than ``string list'' are subject to | |
4875 | particular kinds of interpretation, as described in chapter | |
4876 | <<CHAPdomhosaddlists>>. | |
168e428f PH |
4877 | |
4878 | In all these cases, the entire list is treated as a single string as far as the | |
4879 | input syntax is concerned. The %trusted_users% setting in section | |
4880 | <<SECTstrings>> above is an example. If a colon is actually needed in an item in | |
4881 | a list, it must be entered as two colons. Leading and trailing white space on | |
4882 | each item in a list is ignored. This makes it possible to include items that | |
4883 | start with a colon, and in particular, certain forms of IPv6 address. For | |
4884 | example, the list | |
4885 | ||
4886 | local_interfaces = 127.0.0.1 : ::::1 | |
4887 | ||
068aaea8 PH |
4888 | contains two IP addresses, the IPv4 address 127.0.0.1 and the IPv6 address ::1. |
4889 | ||
4890 | [revisionflag="changed"] | |
4891 | *Note*: Although leading and trailing white space is ignored in individual list | |
4892 | items, it is not ignored when parsing the list. The space after the first colon | |
4893 | in the example above is necessary. If it were not there, the list would be | |
4894 | interpreted as the two items 127.0.0.1:: and 1. | |
168e428f PH |
4895 | |
4896 | cindex:[list separator, changing] | |
4897 | cindex:[IPv6,addresses in lists] | |
4898 | Doubling colons in IPv6 addresses is an unwelcome chore, so a mechanism was | |
4899 | introduced to allow the separator character to be changed. If a list begins | |
4900 | with a left angle bracket, followed by any punctuation character, that | |
4901 | character is used instead of colon as the list separator. For example, the list | |
4902 | above can be rewritten to use a semicolon separator like this: | |
4903 | ||
4904 | local_interfaces = <; 127.0.0.1 ; ::1 | |
4905 | ||
4906 | This facility applies to all lists, with the exception of the list in | |
4907 | %log_file_path%. It is recommended that the use of non-colon separators be | |
4908 | confined to circumstances where they really are needed. | |
4909 | ||
4910 | ||
4911 | ||
4912 | [[SECTempitelis]] | |
4913 | Empty items in lists | |
4914 | ~~~~~~~~~~~~~~~~~~~~ | |
4915 | cindex:[list,empty item in] | |
4916 | An empty item at the end of a list is always ignored. In other words, trailing | |
4917 | separator characters are ignored. Thus, the list in | |
4918 | ||
4919 | senders = user@domain : | |
4920 | ||
4921 | contains only a single item. If you want to include an empty string as one item | |
4922 | in a list, it must not be the last item. For example, this list contains three | |
4923 | items, the second of which is empty: | |
4924 | ||
4925 | senders = user1@domain : : user2@domain | |
4926 | ||
068aaea8 | 4927 | *Note*: there must be white space between the two colons, as otherwise they |
168e428f PH |
4928 | are interpreted as representing a single colon data character (and the list |
4929 | would then contain just one item). If you want to specify a list that contains | |
4930 | just one, empty item, you can do it as in this example: | |
4931 | ||
4932 | senders = : | |
4933 | ||
4934 | In this case, the first item is empty, and the second is discarded because it | |
4935 | is at the end of the list. | |
4936 | ||
4937 | ||
4938 | ||
4939 | ||
4940 | [[SECTfordricon]] | |
4941 | Format of driver configurations | |
4942 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
4943 | cindex:[drivers,configuration format] | |
4944 | There are separate parts in the configuration for defining routers, transports, | |
4945 | and authenticators. In each part, you are defining a number of driver | |
4946 | instances, each with its own set of options. Each driver instance is defined by | |
4947 | a sequence of lines like this: | |
4948 | ||
4949 | &&& | |
4950 | <'instance name'>: | |
4951 | <'option'> | |
4952 | ... | |
4953 | <'option'> | |
4954 | &&& | |
4955 | ||
4956 | In the following example, the instance name is ^localuser^, and it is | |
4957 | followed by three options settings: | |
4958 | ||
4959 | localuser: | |
4960 | driver = accept | |
4961 | check_local_user | |
4962 | transport = local_delivery | |
4963 | ||
4964 | For each driver instance, you specify which Exim code module it uses -- by the | |
4965 | setting of the %driver% option -- and (optionally) some configuration settings. | |
4966 | For example, in the case of transports, if you want a transport to deliver with | |
4967 | SMTP you would use the ^smtp^ driver; if you want to deliver to a local file | |
4968 | you would use the ^appendfile^ driver. Each of the drivers is described in | |
4969 | detail in its own separate chapter later in this manual. | |
4970 | ||
4971 | You can have several routers, transports, or authenticators that are based on | |
068aaea8 | 4972 | the same underlying driver (each must have a different instance name). |
168e428f PH |
4973 | |
4974 | The order in which routers are defined is important, because addresses are | |
4975 | passed to individual routers one by one, in order. The order in which | |
4976 | transports are defined does not matter at all. The order in which | |
4977 | authenticators are defined is used only when Exim, as a client, is searching | |
4978 | them to find one that matches an authentication mechanism offered by the | |
4979 | server. | |
4980 | ||
4981 | cindex:[generic options] | |
4982 | cindex:[options, generic -- definition of] | |
4983 | Within a driver instance definition, there are two kinds of option: | |
4984 | 'generic' and 'private'. The generic options are those that apply to all | |
4985 | drivers of the same type (that is, all routers, all transports or all | |
4986 | authenticators). | |
4987 | The %driver% option is a generic option that must appear in every definition. | |
4988 | ||
4989 | cindex:[private options] | |
4990 | The private options are special for each driver, and none need appear, because | |
4991 | they all have default values. | |
4992 | ||
4993 | The options may appear in any order, except that the %driver% option must | |
4994 | precede any private options, since these depend on the particular driver. For | |
4995 | this reason, it is recommended that %driver% always be the first option. | |
4996 | ||
4997 | Driver instance names, which are used for reference in log entries and | |
4998 | elsewhere, can be any sequence of letters, digits, and underscores (starting | |
4999 | with a letter) and must be unique among drivers of the same type. A router and | |
5000 | a transport (for example) can each have the same name, but no two router | |
5001 | instances can have the same name. The name of a driver instance should not be | |
5002 | confused with the name of the underlying driver module. For example, the | |
5003 | configuration lines: | |
5004 | ||
5005 | remote_smtp: | |
5006 | driver = smtp | |
5007 | ||
5008 | create an instance of the ^smtp^ transport driver whose name is | |
5009 | ^remote_smtp^. The same driver code can be used more than once, with | |
5010 | different instance names and different option settings each time. A second | |
5011 | instance of the ^smtp^ transport, with different options, might be defined | |
5012 | thus: | |
5013 | ||
5014 | special_smtp: | |
5015 | driver = smtp | |
5016 | port = 1234 | |
5017 | command_timeout = 10s | |
5018 | ||
5019 | The names ^remote_smtp^ and ^special_smtp^ would be used to reference | |
5020 | these transport instances from routers, and these names would appear in log | |
5021 | lines. | |
5022 | ||
5023 | Comment lines may be present in the middle of driver specifications. The full | |
5024 | list of option settings for any particular driver instance, including all the | |
5025 | defaulted values, can be extracted by making use of the %-bP% command line | |
5026 | option. | |
5027 | ||
5028 | ||
5029 | ||
5030 | ||
5031 | ||
5032 | ||
5033 | //////////////////////////////////////////////////////////////////////////// | |
5034 | //////////////////////////////////////////////////////////////////////////// | |
5035 | ||
5036 | [[CHAPdefconfil]] | |
5037 | The default configuration file | |
5038 | ------------------------------ | |
5039 | cindex:[configuration file,default ``walk through''] | |
5040 | cindex:[default,configuration file ``walk through''] | |
5041 | The default configuration file supplied with Exim as _src/configure.default_ | |
5042 | is sufficient for a host with simple mail requirements. As an introduction to | |
5043 | the way Exim is configured, this chapter ``walks through'' the default | |
5044 | configuration, giving brief explanations of the settings. Detailed descriptions | |
5045 | of the options are given in subsequent chapters. The default configuration file | |
5046 | itself contains extensive comments about ways you might want to modify the | |
5047 | initial settings. However, note that there are many options that are not | |
5048 | mentioned at all in the default configuration. | |
5049 | ||
5050 | ||
5051 | ||
5052 | Main configuration settings | |
5053 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
5054 | The main (global) configuration option settings must always come first in the | |
5055 | file. The first thing you'll see in the file, after some initial comments, is | |
5056 | the line | |
5057 | ||
5058 | # primary_hostname = | |
5059 | ||
5060 | This is a commented-out setting of the %primary_hostname% option. Exim needs | |
5061 | to know the official, fully qualified name of your host, and this is where you | |
5062 | can specify it. However, in most cases you do not need to set this option. When | |
5063 | it is unset, Exim uses the 'uname()' system function to obtain the host name. | |
5064 | ||
5065 | The first three non-comment configuration lines are as follows: | |
5066 | ||
5067 | domainlist local_domains = @ | |
5068 | domainlist relay_to_domains = | |
5069 | hostlist relay_from_hosts = 127.0.0.1 | |
5070 | ||
5071 | These are not, in fact, option settings. They are definitions of two named | |
5072 | domain lists and one named host list. Exim allows you to give names to lists of | |
5073 | domains, hosts, and email addresses, in order to make it easier to manage the | |
5074 | configuration file (see section <<SECTnamedlists>>). | |
5075 | ||
5076 | The first line defines a domain list called 'local_domains'; this is used | |
5077 | later in the configuration to identify domains that are to be delivered | |
5078 | on the local host. | |
5079 | ||
5080 | cindex:[@ in a domain list] | |
5081 | There is just one item in this list, the string ``@''. This is a special form of | |
5082 | entry which means ``the name of the local host''. Thus, if the local host is | |
5083 | called 'a.host.example', mail to 'any.user@a.host.example' is expected to | |
5084 | be delivered locally. Because the local host's name is referenced indirectly, | |
5085 | the same configuration file can be used on different hosts. | |
5086 | ||
5087 | The second line defines a domain list called 'relay_to_domains', but the | |
5088 | list itself is empty. Later in the configuration we will come to the part that | |
5089 | controls mail relaying through the local host; it allows relaying to any | |
5090 | domains in this list. By default, therefore, no relaying on the basis of a mail | |
5091 | domain is permitted. | |
5092 | ||
5093 | The third line defines a host list called 'relay_from_hosts'. This list is | |
5094 | used later in the configuration to permit relaying from any host or IP address | |
5095 | that matches the list. The default contains just the IP address of the IPv4 | |
5096 | loopback interface, which means that processes on the local host are able to | |
5097 | submit mail for relaying by sending it over TCP/IP to that interface. No other | |
5098 | hosts are permitted to submit messages for relaying. | |
5099 | ||
5100 | Just to be sure there's no misunderstanding: at this point in the configuration | |
5101 | we aren't actually setting up any controls. We are just defining some domains | |
5102 | and hosts that will be used in the controls that are specified later. | |
5103 | ||
068aaea8 | 5104 | The next two configuration lines are genuine option settings: |
168e428f PH |
5105 | |
5106 | acl_smtp_rcpt = acl_check_rcpt | |
068aaea8 | 5107 | acl_smtp_data = acl_check_data |
168e428f | 5108 | |
068aaea8 PH |
5109 | [revisionflag="changed"] |
5110 | These options specify 'Access Control Lists' (ACLs) that are to be used during | |
5111 | an incoming SMTP session for every recipient of a message (every RCPT command), | |
5112 | and after the contents of the message have been received, respectively. The | |
5113 | names of the lists are 'acl_check_rcpt' and 'acl_check_data', and we will come | |
5114 | to their definitions below, in the ACL section of the configuration. The RCPT | |
5115 | ACL controls which recipients are accepted for an incoming message -- if a | |
168e428f | 5116 | configuration does not provide an ACL to check recipients, no SMTP mail can be |
068aaea8 PH |
5117 | accepted. The DATA ACL allows the contents of a message to be checked. |
5118 | ||
5119 | [revisionflag="changed"] | |
5120 | Two commented-out option settings are next: | |
5121 | ||
5122 | [revisionflag="changed"] | |
5123 | .... | |
5124 | # av_scanner = clamd:/tmp/clamd | |
5125 | # spamd_address = 127.0.0.1 783 | |
5126 | .... | |
5127 | ||
5128 | [revisionflag="changed"] | |
5129 | These are example settings that can be used when Exim is compiled with the | |
5130 | content-scanning extension. The first specifies the interface to the virus | |
5131 | scanner, and the second specifies the interface to SpamAssassin. Further | |
5132 | details are given in chapter <<CHAPexiscan>>. | |
168e428f | 5133 | |
068aaea8 | 5134 | Two more commented-out options settings follow: |
168e428f PH |
5135 | |
5136 | # qualify_domain = | |
5137 | # qualify_recipient = | |
5138 | ||
5139 | The first of these specifies a domain that Exim uses when it constructs a | |
5140 | complete email address from a local login name. This is often needed when Exim | |
5141 | receives a message from a local process. If you do not set %qualify_domain%, | |
5142 | the value of %primary_hostname% is used. If you set both of these options, you | |
5143 | can have different qualification domains for sender and recipient addresses. If | |
5144 | you set only the first one, its value is used in both cases. | |
5145 | ||
5146 | cindex:[domain literal,recognizing format] | |
5147 | The following line must be uncommented if you want Exim to recognize | |
5148 | addresses of the form 'user@[10.11.12.13]' that is, with a ``domain literal'' | |
068aaea8 | 5149 | (an IP address within square brackets) instead of a named domain. |
168e428f PH |
5150 | |
5151 | # allow_domain_literals | |
5152 | ||
5153 | The RFCs still require this form, but many people think that in the modern | |
5154 | Internet it makes little sense to permit mail to be sent to specific hosts by | |
5155 | quoting their IP addresses. This ancient format has been used by people who | |
5156 | try to abuse hosts by using them for unwanted relaying. However, some | |
5157 | people believe there are circumstances (for example, messages addressed to | |
5158 | 'postmaster') where domain literals are still useful. | |
5159 | ||
5160 | The next configuration line is a kind of trigger guard: | |
5161 | ||
5162 | never_users = root | |
5163 | ||
5164 | It specifies that no delivery must ever be run as the root user. The normal | |
5165 | convention is to set up 'root' as an alias for the system administrator. This | |
5166 | setting is a guard against slips in the configuration. | |
5167 | The list of users specified by %never_users% is not, however, the complete | |
5168 | list; the build-time configuration in _Local/Makefile_ has an option called | |
5169 | FIXED_NEVER_USERS specifying a list that cannot be overridden. The | |
5170 | contents of %never_users% are added to this list. By default | |
5171 | FIXED_NEVER_USERS also specifies root. | |
5172 | ||
5173 | When a remote host connects to Exim in order to send mail, the only information | |
5174 | Exim has about the host's identity is its IP address. The next configuration | |
5175 | line, | |
5176 | ||
5177 | host_lookup = * | |
5178 | ||
5179 | specifies that Exim should do a reverse DNS lookup on all incoming connections, | |
5180 | in order to get a host name. This improves the quality of the logging | |
5181 | information, but if you feel it is too expensive, you can remove it entirely, | |
5182 | or restrict the lookup to hosts on ``nearby'' networks. | |
5183 | Note that it is not always possible to find a host name from an IP address, | |
5184 | because not all DNS reverse zones are maintained, and sometimes DNS servers are | |
5185 | unreachable. | |
5186 | ||
5187 | The next two lines are concerned with 'ident' callbacks, as defined by RFC | |
5188 | 1413 (hence their names): | |
5189 | ||
5190 | rfc1413_hosts = * | |
5191 | rfc1413_query_timeout = 30s | |
5192 | ||
5193 | These settings cause Exim to make ident callbacks for all incoming SMTP calls. | |
5194 | You can limit the hosts to which these calls are made, or change the timeout | |
5195 | that is used. If you set the timeout to zero, all ident calls are disabled. | |
5196 | Although they are cheap and can provide useful information for tracing problem | |
5197 | messages, some hosts and firewalls have problems with ident calls. This can | |
5198 | result in a timeout instead of an immediate refused connection, leading to | |
5199 | delays on starting up an incoming SMTP session. | |
5200 | ||
5201 | When Exim receives messages over SMTP connections, it expects all addresses to | |
5202 | be fully qualified with a domain, as required by the SMTP definition. However, | |
5203 | if you are running a server to which simple clients submit messages, you may | |
5204 | find that they send unqualified addresses. The two commented-out options: | |
5205 | ||
5206 | # sender_unqualified_hosts = | |
5207 | # recipient_unqualified_hosts = | |
5208 | ||
5209 | show how you can specify hosts that are permitted to send unqualified sender | |
5210 | and recipient addresses, respectively. | |
5211 | ||
5212 | The %percent_hack_domains% option is also commented out: | |
5213 | ||
5214 | # percent_hack_domains = | |
5215 | ||
5216 | It provides a list of domains for which the ``percent hack'' is to operate. This | |
5217 | is an almost obsolete form of explicit email routing. If you do not know | |
5218 | anything about it, you can safely ignore this topic. | |
5219 | ||
5220 | The last two settings in the main part of the default configuration are | |
5221 | concerned with messages that have been ``frozen'' on Exim's queue. When a message | |
5222 | is frozen, Exim no longer continues to try to deliver it. Freezing occurs when | |
5223 | a bounce message encounters a permanent failure because the sender address of | |
5224 | the original message that caused the bounce is invalid, so the bounce cannot be | |
5225 | delivered. This is probably the most common case, but there are also other | |
5226 | conditions that cause freezing, and frozen messages are not always bounce | |
5227 | messages. | |
5228 | ||
5229 | ignore_bounce_errors_after = 2d | |
5230 | timeout_frozen_after = 7d | |
5231 | ||
5232 | The first of these options specifies that failing bounce messages are to be | |
5233 | discarded after 2 days on the queue. The second specifies that any frozen | |
5234 | message (whether a bounce message or not) is to be timed out (and discarded) | |
5235 | after a week. In this configuration, the first setting ensures that no failing | |
5236 | bounce message ever lasts a week. | |
5237 | ||
5238 | ||
5239 | ||
5240 | ACL configuration | |
5241 | ~~~~~~~~~~~~~~~~~ | |
5242 | cindex:[default,ACLs] | |
5243 | cindex:[{ACL},default configuration] | |
5244 | In the default configuration, the ACL section follows the main configuration. | |
5245 | It starts with the line | |
5246 | ||
5247 | begin acl | |
5248 | ||
068aaea8 PH |
5249 | and it contains the definitions of two ACLs, called 'acl_check_rcpt' and |
5250 | 'acl_check_data', that were referenced in the settings of %acl_smtp_rcpt% and | |
5251 | %acl_smtp_data% above. | |
168e428f PH |
5252 | |
5253 | cindex:[RCPT,ACL for] | |
068aaea8 | 5254 | The first ACL is used for every RCPT command in an incoming SMTP message. Each |
168e428f PH |
5255 | RCPT command specifies one of the message's recipients. The ACL statements |
5256 | are considered in order, until the recipient address is either accepted or | |
5257 | rejected. The RCPT command is then accepted or rejected, according to the | |
5258 | result of the ACL processing. | |
5259 | ||
5260 | acl_check_rcpt: | |
5261 | ||
5262 | This line, consisting of a name terminated by a colon, marks the start of the | |
5263 | ACL, and names it. | |
5264 | ||
5265 | accept hosts = : | |
5266 | ||
5267 | This ACL statement accepts the recipient if the sending host matches the list. | |
5268 | But what does that strange list mean? It doesn't actually contain any host | |
5269 | names or IP addresses. The presence of the colon puts an empty item in the | |
068aaea8 PH |
5270 | list; Exim matches this only if the incoming message did not come from a remote |
5271 | host, because in that case, the remote hostname is empty. The colon is | |
5272 | important. Without it, the list itself is empty, and can never match anything. | |
168e428f PH |
5273 | |
5274 | What this statement is doing is to accept unconditionally all recipients in | |
5275 | messages that are submitted by SMTP from local processes using the standard | |
5276 | input and output (that is, not using TCP/IP). A number of MUAs operate in this | |
5277 | manner. | |
5278 | ||
068aaea8 PH |
5279 | deny message = Restricted characters in address |
5280 | domains = +local_domains | |
168e428f PH |
5281 | local_parts = ^[.] : ^.*[@%!/|] |
5282 | ||
068aaea8 PH |
5283 | deny message = Restricted characters in address |
5284 | domains = !+local_domains | |
168e428f PH |
5285 | local_parts = ^[./|] : ^.*[@%!] : ^.*/\\.\\./ |
5286 | ||
5287 | These statements are concerned with local parts that contain any of the | |
5288 | characters ``@'', ``%'', ``!'', ``/'', ``|'', or dots in unusual places. Although these | |
5289 | characters are entirely legal in local parts (in the case of ``@'' and leading | |
5290 | dots, only if correctly quoted), they do not commonly occur in Internet mail | |
5291 | addresses. | |
5292 | ||
5293 | The first three have in the past been associated with explicitly routed | |
5294 | addresses (percent is still sometimes used -- see the %percent_hack_domains% | |
5295 | option). Addresses containing these characters are regularly tried by spammers | |
5296 | in an attempt to bypass relaying restrictions, and also by open relay testing | |
5297 | programs. Unless you really need them it is safest to reject these characters | |
5298 | at this early stage. This configuration is heavy-handed in rejecting these | |
5299 | characters for all messages it accepts from remote hosts. This is a deliberate | |
5300 | policy of being as safe as possible. | |
5301 | ||
5302 | The first rule above is stricter, and is applied to messages that are addressed | |
5303 | to one of the local domains handled by this host. This is implemented by the | |
5304 | first condition, which restricts it to domains that are listed in the | |
5305 | 'local_domains' domain list. The ``+'' character is used to indicate a | |
5306 | reference to a named list. In this configuration, there is just one domain in | |
5307 | 'local_domains', but in general there may be many. | |
5308 | ||
5309 | The second condition on the first statement uses two regular expressions to | |
5310 | block local parts that begin with a dot or contain ``@'', ``%'', ``!'', ``/'', or ``|''. | |
5311 | If you have local accounts that include these characters, you will have to | |
5312 | modify this rule. | |
5313 | ||
5314 | Empty components (two dots in a row) are not valid in RFC 2822, but Exim | |
5315 | allows them because they have been encountered in practice. (Consider local | |
5316 | parts constructed as ``first-initial.second-initial.family-name'' when applied to | |
5317 | someone like the author of Exim, who has no second initial.) However, a local | |
5318 | part starting with a dot or containing ``/../'' can cause trouble if it is used | |
5319 | as part of a file name (for example, for a mailing list). This is also true for | |
5320 | local parts that contain slashes. A pipe symbol can also be troublesome if the | |
5321 | local part is incorporated unthinkingly into a shell command line. | |
5322 | ||
5323 | The second rule above applies to all other domains, and is less strict. This | |
5324 | allows your own users to send outgoing messages to sites that use slashes | |
5325 | and vertical bars in their local parts. It blocks local parts that begin | |
5326 | with a dot, slash, or vertical bar, but allows these characters within the | |
5327 | local part. However, the sequence ``/../'' is barred. The use of ``@'', ``%'', and | |
5328 | ``!'' is blocked, as before. The motivation here is to prevent your users (or | |
5329 | your users' viruses) from mounting certain kinds of attack on remote sites. | |
5330 | ||
5331 | accept local_parts = postmaster | |
5332 | domains = +local_domains | |
5333 | ||
5334 | This statement, which has two conditions, accepts an incoming address if the | |
5335 | local part is 'postmaster' and the domain is one of those listed in the | |
5336 | 'local_domains' domain list. The ``+'' character is used to indicate a | |
5337 | reference to a named list. In this configuration, there is just one domain in | |
5338 | 'local_domains', but in general there may be many. | |
5339 | ||
5340 | The presence of this statement means that mail to postmaster is never blocked | |
5341 | by any of the subsequent tests. This can be helpful while sorting out problems | |
5342 | in cases where the subsequent tests are incorrectly denying access. | |
5343 | ||
5344 | require verify = sender | |
5345 | ||
5346 | This statement requires the sender address to be verified before any subsequent | |
5347 | ACL statement can be used. If verification fails, the incoming recipient | |
5348 | address is refused. Verification consists of trying to route the address, to | |
068aaea8 PH |
5349 | see if a bounce message could be delivered to it. In the case of remote |
5350 | addresses, basic verification checks only the domain, but 'callouts' can be | |
5351 | used for more verification if required. Section <<SECTaddressverification>> | |
5352 | discusses the details of address verification. | |
5353 | ||
5354 | accept hosts = +relay_from_hosts | |
5355 | control = submission | |
5356 | ||
5357 | [revisionflag="changed"] | |
5358 | This statement accepts the address if the message is coming from one of the | |
5359 | hosts that are defined as being allowed to relay through this host. Recipient | |
5360 | verification is omitted here, because in many cases the clients are dumb MUAs | |
5361 | that do not cope well with SMTP error responses. For the same reason, the | |
5362 | second line specifies ``submission mode'' for messages that are accepted. This | |
5363 | is described in detail in section <<SECTsubmodnon>>; it causes Exim to fix | |
5364 | messages that are deficient in some way, for example, because they lack a | |
5365 | 'Date:' header line. If you are actually relaying out from MTAs, you should | |
5366 | probably add recipient verification here, and disable submission mode. | |
5367 | ||
5368 | accept authenticated = * | |
5369 | control = submission | |
5370 | ||
5371 | [revisionflag="changed"] | |
5372 | This statement accepts the address if the client host has authenticated itself. | |
5373 | Submission mode is again specified, on the grounds that such messages are most | |
5374 | likely to come from MUAs. The default configuration does not define any | |
5375 | authenticators, which means that no client can in fact authenticate. You will | |
5376 | need to add authenticator definitions if you want to make use of this ACL | |
5377 | statement. | |
168e428f PH |
5378 | |
5379 | .... | |
5380 | # deny message = rejected because $sender_host_address is \ | |
5381 | # in a black list at $dnslist_domain\n\ | |
5382 | # $dnslist_text | |
5383 | # dnslists = black.list.example | |
5384 | # | |
5385 | # warn message = X-Warning: $sender_host_address is \ | |
5386 | # in a black list at $dnslist_domain | |
5387 | # log_message = found in $dnslist_domain | |
5388 | # dnslists = black.list.example | |
5389 | .... | |
5390 | ||
5391 | These commented-out lines are examples of how you could configure Exim to check | |
5392 | sending hosts against a DNS black list. The first statement rejects messages | |
5393 | from blacklisted hosts, whereas the second merely inserts a warning header | |
5394 | line. | |
5395 | ||
5396 | accept domains = +local_domains | |
5397 | endpass | |
168e428f PH |
5398 | verify = recipient |
5399 | ||
5400 | This statement accepts the incoming recipient address if its domain is one of | |
5401 | the local domains, but only if the address can be verified. Verification of | |
5402 | local addresses normally checks both the local part and the domain. The | |
5403 | %endpass% line needs some explanation: if the condition above %endpass% fails, | |
5404 | that is, if the address is not in a local domain, control is passed to the next | |
5405 | ACL statement. However, if the condition below %endpass% fails, that is, if a | |
5406 | recipient in a local domain cannot be verified, access is denied and the | |
5407 | recipient is rejected. | |
5408 | ||
168e428f PH |
5409 | accept domains = +relay_to_domains |
5410 | endpass | |
168e428f PH |
5411 | verify = recipient |
5412 | ||
5413 | This statement accepts the incoming recipient address if its domain is one of | |
5414 | the domains for which this host is a relay, but again, only if the address can | |
5415 | be verified. | |
5416 | ||
168e428f PH |
5417 | deny message = relay not permitted |
5418 | ||
5419 | The final statement denies access, giving a specific error message. Reaching | |
5420 | the end of the ACL also causes access to be denied, but with the generic | |
5421 | message ``administrative prohibition''. | |
5422 | ||
068aaea8 PH |
5423 | acl_check_data: |
5424 | ||
5425 | [revisionflag="changed"] | |
5426 | This line marks the start of the second ACL, and names it. Most of the contents | |
5427 | of this ACL are commented out: | |
5428 | ||
5429 | [revisionflag="changed"] | |
5430 | .... | |
5431 | # deny malware = * | |
5432 | # message = This message contains a virus \ | |
5433 | # ($malware_name). | |
5434 | .... | |
5435 | ||
5436 | [revisionflag="changed"] | |
5437 | These lines are examples of how to arrange for messages to be scanned for | |
5438 | viruses when Exim has been compiled with the content-scanning extension, and a | |
5439 | suitable virus scanner is installed. If the message is found to contain a | |
5440 | virus, it is rejected with the given custom error message. | |
5441 | ||
5442 | [revisionflag="changed"] | |
5443 | .... | |
5444 | # warn spam = nobody | |
5445 | # message = X-Spam_score: $spam_score\n\ | |
5446 | # X-Spam_score_int: $spam_score_int\n\ | |
5447 | # X-Spam_bar: $spam_bar\n\ | |
5448 | # X-Spam_report: $spam_report | |
5449 | .... | |
5450 | ||
5451 | [revisionflag="changed"] | |
5452 | These lines are an example of how to arrange for messages to be scanned by | |
5453 | SpamAssassin when Exim has been compiled with the content-scanning extension, | |
5454 | and SpamAssassin has been installed. The SpamAssassin check is run with | |
5455 | `nobody` as its user parameter, and the results are added to the message as a | |
5456 | series of extra header line. In this case, the message is not rejected, | |
5457 | whatever the spam score. | |
5458 | ||
5459 | accept | |
5460 | ||
5461 | [revisionflag="changed"] | |
5462 | This final line in the DATA ACL accepts the message unconditionally. | |
5463 | ||
168e428f PH |
5464 | |
5465 | ||
5466 | Router configuration | |
5467 | ~~~~~~~~~~~~~~~~~~~~ | |
5468 | cindex:[default,routers] | |
5469 | cindex:[routers,default] | |
5470 | The router configuration comes next in the default configuration, introduced | |
5471 | by the line | |
5472 | ||
5473 | begin routers | |
5474 | ||
5475 | Routers are the modules in Exim that make decisions about where to send | |
5476 | messages. An address is passed to each router in turn, until it is either | |
5477 | accepted, or failed. This means that the order in which you define the routers | |
5478 | matters. Each router is fully described in its own chapter later in this | |
5479 | manual. Here we give only brief overviews. | |
5480 | ||
5481 | # domain_literal: | |
5482 | # driver = ipliteral | |
5483 | # domains = !+local_domains | |
5484 | # transport = remote_smtp | |
5485 | ||
5486 | cindex:[domain literal,default router] | |
5487 | This router is commented out because the majority of sites do not want to | |
5488 | support domain literal addresses (those of the form 'user@[10.9.8.7]'). If | |
5489 | you uncomment this router, you also need to uncomment the setting of | |
5490 | %allow_domain_literals% in the main part of the configuration. | |
5491 | ||
5492 | dnslookup: | |
5493 | driver = dnslookup | |
5494 | domains = ! +local_domains | |
5495 | transport = remote_smtp | |
5496 | ignore_target_hosts = 0.0.0.0 : 127.0.0.0/8 | |
5497 | no_more | |
5498 | ||
5499 | The first uncommented router handles addresses that do not involve any local | |
5500 | domains. This is specified by the line | |
5501 | ||
5502 | domains = ! +local_domains | |
5503 | ||
5504 | The %domains% option lists the domains to which this router applies, but the | |
5505 | exclamation mark is a negation sign, so the router is used only for domains | |
5506 | that are not in the domain list called 'local_domains' (which was defined at | |
5507 | the start of the configuration). The plus sign before 'local_domains' | |
5508 | indicates that it is referring to a named list. Addresses in other domains are | |
5509 | passed on to the following routers. | |
5510 | ||
5511 | The name of the router driver is ^dnslookup^, | |
5512 | and is specified by the %driver% option. Do not be confused by the fact that | |
5513 | the name of this router instance is the same as the name of the driver. The | |
5514 | instance name is arbitrary, but the name set in the %driver% option must be one | |
5515 | of the driver modules that is in the Exim binary. | |
5516 | ||
5517 | The ^dnslookup^ router routes addresses by looking up their domains in the | |
5518 | DNS in order to obtain a list of hosts to which the address is routed. If the | |
5519 | router succeeds, the address is queued for the ^remote_smtp^ transport, as | |
5520 | specified by the %transport% option. If the router does not find the domain in | |
5521 | the DNS, no further routers are tried because of the %no_more% setting, so the | |
5522 | address fails and is bounced. | |
5523 | ||
5524 | The %ignore_target_hosts% option specifies a list of IP addresses that are to | |
5525 | be entirely ignored. This option is present because a number of cases have been | |
5526 | encountered where MX records in the DNS point to host names | |
5527 | whose IP addresses are 0.0.0.0 or are in the 127 subnet (typically 127.0.0.1). | |
5528 | Completely ignoring these IP addresses causes Exim to fail to route the | |
5529 | email address, so it bounces. Otherwise, Exim would log a routing problem, and | |
5530 | continue to try to deliver the message periodically until the address timed | |
5531 | out. | |
5532 | ||
5533 | system_aliases: | |
5534 | driver = redirect | |
5535 | allow_fail | |
5536 | allow_defer | |
5537 | data = ${lookup{$local_part}lsearch{/etc/aliases}} | |
5538 | # user = exim | |
5539 | file_transport = address_file | |
5540 | pipe_transport = address_pipe | |
5541 | ||
5542 | Control reaches this and subsequent routers only for addresses in the local | |
5543 | domains. This router checks to see whether the local part is defined as an | |
5544 | alias in the _/etc/aliases_ file, and if so, redirects it according to the | |
5545 | data that it looks up from that file. If no data is found for the local part, | |
5546 | the value of the %data% option is empty, causing the address to be passed to | |
5547 | the next router. | |
5548 | ||
5549 | _/etc/aliases_ is a conventional name for the system aliases file that is | |
5550 | often used. That is why it is referenced by from the default configuration | |
5551 | file. However, you can change this by setting SYSTEM_ALIASES_FILE in | |
5552 | _Local/Makefile_ before building Exim. | |
5553 | ||
5554 | userforward: | |
5555 | driver = redirect | |
5556 | check_local_user | |
068aaea8 PH |
5557 | # local_part_suffix = +* : -* |
5558 | # local_part_suffix_optional | |
168e428f | 5559 | file = $home/.forward |
068aaea8 | 5560 | # allow_filter |
168e428f PH |
5561 | no_verify |
5562 | no_expn | |
5563 | check_ancestor | |
168e428f PH |
5564 | file_transport = address_file |
5565 | pipe_transport = address_pipe | |
5566 | reply_transport = address_reply | |
5567 | ||
068aaea8 | 5568 | [revisionflag="changed"] |
168e428f PH |
5569 | This is the most complicated router in the default configuration. It is another |
5570 | redirection router, but this time it is looking for forwarding data set up by | |
068aaea8 PH |
5571 | individual users. The %check_local_user% setting specifies a check that the |
5572 | local part of the address is the login name of a local user. If it is not, the | |
5573 | router is skipped. The two commented options that follow %check_local_user%, | |
5574 | namely: | |
5575 | ||
5576 | [revisionflag="changed"] | |
5577 | .... | |
5578 | # local_part_suffix = +* : -* | |
5579 | # local_part_suffix_optional | |
5580 | .... | |
5581 | ||
5582 | [revisionflag="changed"] | |
5583 | cindex:[$local_part_suffix$] | |
5584 | show how you can specify the recognition of local part suffixes. If the first | |
5585 | is uncommented, a suffix beginning with either a plus or a minus sign, followed | |
5586 | by any sequence of characters, is removed from the local part and placed in the | |
5587 | variable $local_part_suffix$. The second suffix option specifies that the | |
5588 | presence of a suffix in the local part is optional. When a suffix is present, | |
5589 | the check for a local login uses the local part with the suffix removed. | |
5590 | ||
5591 | When a local user account is found, the file called _.forward_ in the user's | |
5592 | home directory is consulted. If it does not exist, or is empty, the router | |
5593 | declines. Otherwise, the contents of _.forward_ are interpreted as redirection | |
5594 | data (see chapter <<CHAPredirect>> for more details). | |
168e428f PH |
5595 | |
5596 | cindex:[Sieve filter,enabling in default router] | |
5597 | Traditional _.forward_ files contain just a list of addresses, pipes, or | |
5598 | files. Exim supports this by default. However, if %allow_filter% is set (it is | |
5599 | commented out by default), the contents of the file are interpreted as a set of | |
5600 | Exim or Sieve filtering instructions, provided the file begins with ``#Exim | |
5601 | filter'' or ``#Sieve filter'', respectively. User filtering is discussed in the | |
5602 | separate document entitled 'Exim's interfaces to mail filtering'. | |
5603 | ||
5604 | The %no_verify% and %no_expn% options mean that this router is skipped when | |
068aaea8 | 5605 | verifying addresses, or when running as a consequence of an SMTP EXPN command. |
168e428f PH |
5606 | There are two reasons for doing this: |
5607 | ||
5608 | . Whether or not a local user has a _.forward_ file is not really relevant when | |
5609 | checking an address for validity; it makes sense not to waste resources doing | |
5610 | unnecessary work. | |
5611 | ||
5612 | . More importantly, when Exim is verifying addresses or handling an EXPN | |
5613 | command during an SMTP session, it is running as the Exim user, not as root. | |
5614 | The group is the Exim group, and no additional groups are set up. | |
5615 | It may therefore not be possible for Exim to read users' _.forward_ files at | |
5616 | this time. | |
5617 | ||
168e428f PH |
5618 | The setting of %check_ancestor% prevents the router from generating a new |
5619 | address that is the same as any previous address that was redirected. (This | |
5620 | works round a problem concerning a bad interaction between aliasing and | |
5621 | forwarding -- see section <<SECTredlocmai>>). | |
5622 | ||
5623 | The final three option settings specify the transports that are to be used when | |
5624 | forwarding generates a direct delivery to a file, or to a pipe, or sets up an | |
5625 | auto-reply, respectively. For example, if a _.forward_ file contains | |
5626 | ||
5627 | a.nother@elsewhere.example, /home/spqr/archive | |
5628 | ||
5629 | the delivery to _/home/spqr/archive_ is done by running the %address_file% | |
5630 | transport. | |
5631 | ||
5632 | localuser: | |
5633 | driver = accept | |
5634 | check_local_user | |
068aaea8 PH |
5635 | # local_part_suffix = +* : -* |
5636 | # local_part_suffix_optional | |
168e428f PH |
5637 | transport = local_delivery |
5638 | ||
068aaea8 | 5639 | [revisionflag="changed"] |
168e428f | 5640 | The final router sets up delivery into local mailboxes, provided that the local |
068aaea8 | 5641 | part is the name of a local login, by accepting the address and assigning it to |
168e428f | 5642 | the ^local_delivery^ transport. Otherwise, we have reached the end of the |
068aaea8 PH |
5643 | routers, so the address is bounced. The commented suffix settings fulfil the |
5644 | same purpose as they do for the ^userforward^ router. | |
168e428f PH |
5645 | |
5646 | ||
5647 | ||
5648 | Transport configuration | |
5649 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
5650 | cindex:[default,transports] | |
5651 | cindex:[transports,default] | |
5652 | Transports define mechanisms for actually delivering messages. They operate | |
5653 | only when referenced from routers, so the order in which they are defined does | |
5654 | not matter. The transports section of the configuration starts with | |
5655 | ||
5656 | begin transports | |
5657 | ||
5658 | One remote transport and four local transports are defined. | |
5659 | ||
5660 | remote_smtp: | |
5661 | driver = smtp | |
5662 | ||
5663 | This transport is used for delivering messages over SMTP connections. All its | |
5664 | options are defaulted. The list of remote hosts comes from the router. | |
5665 | ||
5666 | local_delivery: | |
5667 | driver = appendfile | |
5668 | file = /var/mail/$local_part | |
5669 | delivery_date_add | |
5670 | envelope_to_add | |
5671 | return_path_add | |
5672 | # group = mail | |
5673 | # mode = 0660 | |
5674 | ||
5675 | This ^appendfile^ transport is used for local delivery to user mailboxes in | |
5676 | traditional BSD mailbox format. By default it runs under the uid and gid of the | |
5677 | local user, which requires the sticky bit to be set on the _/var/mail_ | |
5678 | directory. Some systems use the alternative approach of running mail deliveries | |
5679 | under a particular group instead of using the sticky bit. The commented options | |
5680 | show how this can be done. | |
5681 | ||
5682 | Exim adds three headers to the message as it delivers it: 'Delivery-date:', | |
5683 | 'Envelope-to:' and 'Return-path:'. This action is requested by the three | |
5684 | similarly-named options above. | |
5685 | ||
5686 | address_pipe: | |
5687 | driver = pipe | |
5688 | return_output | |
5689 | ||
5690 | This transport is used for handling deliveries to pipes that are generated by | |
5691 | redirection (aliasing or users' _.forward_ files). The %return_output% | |
5692 | option specifies that any output generated by the pipe is to be returned to the | |
5693 | sender. | |
5694 | ||
5695 | address_file: | |
5696 | driver = appendfile | |
5697 | delivery_date_add | |
5698 | envelope_to_add | |
5699 | return_path_add | |
5700 | ||
5701 | This transport is used for handling deliveries to files that are generated by | |
5702 | redirection. The name of the file is not specified in this instance of | |
5703 | ^appendfile^, because it comes from the ^redirect^ router. | |
5704 | ||
5705 | address_reply: | |
5706 | driver = autoreply | |
5707 | ||
5708 | This transport is used for handling automatic replies generated by users' | |
5709 | filter files. | |
5710 | ||
5711 | ||
5712 | ||
5713 | Default retry rule | |
5714 | ~~~~~~~~~~~~~~~~~~ | |
5715 | cindex:[retry,default rule] | |
5716 | cindex:[default,retry rule] | |
5717 | The retry section of the configuration file contains rules which affect the way | |
5718 | Exim retries deliveries that cannot be completed at the first attempt. It is | |
5719 | introduced by the line | |
5720 | ||
5721 | begin retry | |
5722 | ||
5723 | In the default configuration, there is just one rule, which applies to all | |
5724 | errors: | |
5725 | ||
5726 | &&& | |
5727 | `\* \* F,2h,15m; G,16h,1h,1.5; F,4d,6h` | |
5728 | &&& | |
5729 | ||
5730 | This causes any temporarily failing address to be retried every 15 minutes for | |
5731 | 2 hours, then at intervals starting at one hour and increasing by a factor of | |
5732 | 1.5 until 16 hours have passed, then every 6 hours up to 4 days. If an address | |
5733 | is not delivered after 4 days of failure, it is bounced. | |
5734 | ||
5735 | ||
5736 | ||
5737 | Rewriting configuration | |
5738 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
5739 | The rewriting section of the configuration, introduced by | |
5740 | ||
5741 | begin rewrite | |
5742 | ||
5743 | contains rules for rewriting addresses in messages as they arrive. There are no | |
5744 | rewriting rules in the default configuration file. | |
5745 | ||
5746 | ||
5747 | ||
5748 | Authenticators configuration | |
5749 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
5750 | cindex:[AUTH,configuration] | |
5751 | The authenticators section of the configuration, introduced by | |
5752 | ||
5753 | begin authenticators | |
5754 | ||
5755 | defines mechanisms for the use of the SMTP AUTH command. No authenticators | |
5756 | are specified in the default configuration file. | |
5757 | ||
5758 | ||
5759 | ||
5760 | //////////////////////////////////////////////////////////////////////////// | |
5761 | //////////////////////////////////////////////////////////////////////////// | |
5762 | ||
5763 | [[CHAPregexp]] | |
5764 | Regular expressions | |
5765 | ------------------- | |
5766 | ||
5767 | cindex:[regular expressions,library] | |
5768 | cindex:[PCRE] | |
5769 | Exim supports the use of regular expressions in many of its options. It | |
5770 | uses the PCRE regular expression library; this provides regular expression | |
5771 | matching that is compatible with Perl 5. The syntax and semantics of | |
5772 | regular expressions is discussed in many Perl reference books, and also in | |
5773 | Jeffrey Friedl's 'Mastering Regular Expressions', which is published by | |
5774 | O'Reilly (*http://www.oreilly.com/catalog/regex/[]*). | |
5775 | ||
5776 | The documentation for the syntax and semantics of the regular expressions that | |
5777 | are supported by PCRE is included in plain text in the file | |
068aaea8 PH |
5778 | _doc/pcrepattern.txt_ in the Exim distribution, and also in the HTML tarbundle |
5779 | of Exim documentation. It describes in detail the features of the regular | |
5780 | expressions that PCRE supports, so no further description is included here. The | |
5781 | PCRE functions are called from Exim using the default option settings (that is, | |
5782 | with no PCRE options set), except that the PCRE_CASELESS option is set when the | |
168e428f PH |
5783 | matching is required to be case-insensitive. |
5784 | ||
5785 | In most cases, when a regular expression is required in an Exim configuration, | |
5786 | it has to start with a circumflex, in order to distinguish it from plain text | |
5787 | or an ``ends with'' wildcard. In this example of a configuration setting, the | |
5788 | second item in the colon-separated list is a regular expression. | |
5789 | ||
5790 | domains = a.b.c : ^\\d{3} : *.y.z : ... | |
5791 | ||
5792 | The doubling of the backslash is required because of string expansion that | |
5793 | precedes interpretation -- see section <<SECTlittext>> for more discussion of | |
5794 | this issue, and a way of avoiding the need for doubling backslashes. The | |
5795 | regular expression that is eventually used in this example contains just one | |
5796 | backslash. The circumflex is included in the regular expression, and has the | |
5797 | normal effect of ``anchoring'' it to the start of the string that is being | |
5798 | matched. | |
5799 | ||
5800 | There are, however, two cases where a circumflex is not required for the | |
5801 | recognition of a regular expression: these are the %match% condition in a | |
5802 | string expansion, and the %matches% condition in an Exim filter file. In these | |
5803 | cases, the relevant string is always treated as a regular expression; if it | |
5804 | does not start with a circumflex, the expression is not anchored, and can match | |
5805 | anywhere in the subject string. | |
5806 | ||
5807 | In all cases, if you want a regular expression to match at the end of a string, | |
5808 | you must code the \$ metacharacter to indicate this. For example: | |
5809 | ||
5810 | domains = ^\\d{3}\\.example | |
5811 | ||
5812 | matches the domain '123.example', but it also matches '123.example.com'. | |
5813 | You need to use: | |
5814 | ||
5815 | domains = ^\\d{3}\\.example\$ | |
5816 | ||
068aaea8 PH |
5817 | if you want 'example' to be the top-level domain. The backslash before the |
5818 | \$ is needed because string expansion also interprets dollar characters. | |
168e428f PH |
5819 | |
5820 | ||
5821 | ||
5822 | Testing regular expressions | |
5823 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
5824 | cindex:[testing,regular expressions] | |
5825 | cindex:[regular expressions,testing] | |
5826 | cindex:['pcretest'] | |
5827 | A program called 'pcretest' forms part of the PCRE distribution and is built | |
5828 | with PCRE during the process of building Exim. It is primarily intended for | |
5829 | testing PCRE itself, but it can also be used for experimenting with regular | |
5830 | expressions. After building Exim, the binary can be found in the build | |
5831 | directory (it is not installed anywhere automatically). There is documentation | |
5832 | of various options in _doc/pcretest.txt_, but for simple testing, none are | |
5833 | needed. This is the output of a sample run of 'pcretest': | |
5834 | ||
5835 | &&& | |
5836 | ` re> `*`/^([^@]+)@.+\.(ac|edu)\.(?!kr)[a-z]{2}$/`* | |
5837 | `data> `*`x@y.ac.uk`* | |
5838 | ` 0: x@y.ac.uk` | |
5839 | ` 1: x` | |
5840 | ` 2: ac` | |
5841 | `data> `*`x@y.ac.kr`* | |
5842 | `No match` | |
5843 | `data> `*`x@y.edu.com`* | |
5844 | `No match` | |
5845 | `data> `*`x@y.edu.co`* | |
5846 | ` 0: x@y.edu.co` | |
5847 | ` 1: x` | |
5848 | ` 2: edu` | |
5849 | &&& | |
5850 | ||
5851 | Input typed by the user is shown in bold face. After the ``re>'' prompt, a | |
5852 | regular expression enclosed in delimiters is expected. If this compiles without | |
5853 | error, ``data>'' prompts are given for strings against which the expression is | |
5854 | matched. An empty data line causes a new regular expression to be read. If the | |
5855 | match is successful, the captured substring values (that is, what would be in | |
5856 | the variables $0$, $1$, $2$, etc.) are shown. The above example tests for an | |
5857 | email address whose domain ends with either ``ac'' or ``edu'' followed by a | |
5858 | two-character top-level domain that is not ``kr''. The local part is captured | |
5859 | in $1$ and the ``ac'' or ``edu'' in $2$. | |
5860 | ||
5861 | ||
5862 | ||
5863 | ||
5864 | ||
5865 | ||
5866 | //////////////////////////////////////////////////////////////////////////// | |
5867 | //////////////////////////////////////////////////////////////////////////// | |
5868 | ||
5869 | [[CHAPfdlookup]] | |
5870 | File and database lookups | |
5871 | ------------------------- | |
5872 | cindex:[file,lookup] | |
5873 | cindex:[database lookups] | |
5874 | cindex:[lookup,description of] | |
5875 | Exim can be configured to look up data in files or databases as it processes | |
5876 | messages. Two different kinds of syntax are used: | |
5877 | ||
5878 | . A string that is to be expanded may contain explicit lookup requests. These | |
5879 | cause parts of the string to be replaced by data that is obtained from the | |
068aaea8 | 5880 | lookup. String expansions are described in detail in chapter <<CHAPexpand>>. |
168e428f PH |
5881 | |
5882 | . Lists of domains, hosts, and email addresses can contain lookup requests as a | |
5883 | way of avoiding excessively long linear lists. In this case, the data that is | |
5884 | returned by the lookup is often (but not always) discarded; whether the lookup | |
5885 | succeeds or fails is what really counts. These kinds of list are described in | |
5886 | chapter <<CHAPdomhosaddlists>>. | |
5887 | ||
068aaea8 PH |
5888 | [revisionflag="changed"] |
5889 | String expansions, lists, and lookups interact with each other in such a way | |
5890 | that there is no order in which to describe any one of them that does not | |
5891 | involve references to the others. Each of these three chapters makes more sense | |
5892 | if you have read the other two first. If you are reading this for the first | |
5893 | time, be aware that some of it will make a lot more sense after you have read | |
5894 | chapters <<CHAPdomhosaddlists>> and <<CHAPexpand>>. | |
5895 | ||
5896 | ||
5897 | Examples of different lookup syntax | |
5898 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
168e428f PH |
5899 | It is easy to confuse the two different kinds of lookup, especially as the |
5900 | lists that may contain the second kind are always expanded before being | |
5901 | processed as lists. Therefore, they may also contain lookups of the first kind. | |
5902 | Be careful to distinguish between the following two examples: | |
5903 | ||
5904 | domains = ${lookup{$sender_host_address}lsearch{/some/file}} | |
5905 | domains = lsearch;/some/file | |
5906 | ||
5907 | The first uses a string expansion, the result of which must be a domain list. | |
068aaea8 PH |
5908 | The expansion takes place before the string is processed as a list, and the |
5909 | file that is searched could contain lines like this: | |
168e428f | 5910 | |
068aaea8 PH |
5911 | 192.168.3.4: domain1:domain2:... |
5912 | 192.168.1.9: domain3:domain4:... | |
168e428f | 5913 | |
068aaea8 PH |
5914 | The result of the expansion (assuming the lookup succeeds) is a list of domains |
5915 | (and possibly other types of item that are allowed in domain lists). | |
168e428f | 5916 | |
068aaea8 | 5917 | In the second example, the lookup is a single item in a domain list. It causes |
168e428f PH |
5918 | Exim to use a lookup to see if the domain that is being processed can be found |
5919 | in the file. The file could contains lines like this: | |
5920 | ||
5921 | domain1: | |
5922 | domain2: | |
5923 | ||
5924 | Any data that follows the keys is not relevant when checking that the domain | |
5925 | matches the list item. | |
5926 | ||
068aaea8 PH |
5927 | It is possible, though no doubt confusing, to use both kinds of lookup at once. |
5928 | Consider a file containing lines like this: | |
168e428f PH |
5929 | |
5930 | 192.168.5.6: lsearch;/another/file | |
5931 | ||
5932 | If the value of $sender_host_address$ is 192.168.5.6, expansion of the | |
5933 | first %domains% setting above generates the second setting, which therefore | |
5934 | causes a second lookup to occur. | |
5935 | ||
5936 | The rest of this chapter describes the different lookup types that are | |
068aaea8 PH |
5937 | available. Any of them can be used in any part of the configuration where a |
5938 | lookup is permitted. | |
168e428f PH |
5939 | |
5940 | ||
5941 | Lookup types | |
5942 | ~~~~~~~~~~~~ | |
5943 | cindex:[lookup,types of] | |
5944 | cindex:[single-key lookup,definition of] | |
068aaea8 | 5945 | Two different types of data lookup are implemented: |
168e428f | 5946 | |
068aaea8 | 5947 | - The 'single-key' type requires the specification of a file in which to look, |
168e428f PH |
5948 | and a single key to search for. The key must be a non-empty string for the |
5949 | lookup to succeed. The lookup type determines how the file is searched. | |
5950 | ||
5951 | - cindex:[query-style lookup,definition of] | |
068aaea8 PH |
5952 | The 'query-style' type accepts a generalized database query. No particular key |
5953 | value is assumed by Exim for query-style lookups. You can use whichever Exim | |
5954 | variables you need to construct the database query. | |
168e428f PH |
5955 | |
5956 | The code for each lookup type is in a separate source file that is included in | |
5957 | the binary of Exim only if the corresponding compile-time option is set. The | |
5958 | default settings in _src/EDITME_ are: | |
5959 | ||
5960 | LOOKUP_DBM=yes | |
5961 | LOOKUP_LSEARCH=yes | |
5962 | ||
5963 | which means that only linear searching and DBM lookups are included by default. | |
5964 | For some types of lookup (e.g. SQL databases), you need to install appropriate | |
5965 | libraries and header files before building Exim. | |
5966 | ||
5967 | ||
5968 | ||
5969 | ||
5970 | [[SECTsinglekeylookups]] | |
5971 | Single-key lookup types | |
5972 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
5973 | cindex:[lookup,single-key types] | |
5974 | cindex:[single-key lookup,list of types] | |
5975 | The following single-key lookup types are implemented: | |
5976 | ||
5977 | - cindex:[cdb,description of] | |
5978 | cindex:[lookup,cdb] | |
5979 | cindex:[binary zero,in lookup key] | |
5980 | ^cdb^: The given file is searched as a Constant DataBase file, using the key | |
5981 | string without a terminating binary zero. The cdb format is designed for | |
5982 | indexed files that are read frequently and never updated, except by total | |
5983 | re-creation. As such, it is particulary suitable for large files containing | |
5984 | aliases or other indexed data referenced by an MTA. Information about cdb can | |
5985 | be found in several places: | |
5986 | + | |
5987 | &&& | |
5988 | *http://www.pobox.com/~djb/cdb.html[]* | |
5989 | *ftp://ftp.corpit.ru/pub/tinycdb/[]* | |
5990 | *http://packages.debian.org/stable/utils/freecdb.html[]* | |
5991 | &&& | |
5992 | + | |
5993 | A cdb distribution is not needed in order to build Exim with cdb support, | |
5994 | because the code for reading cdb files is included directly in Exim itself. | |
5995 | However, no means of building or testing cdb files is provided with Exim, so | |
5996 | you need to obtain a cdb distribution in order to do this. | |
5997 | ||
5998 | - cindex:[DBM,lookup type] | |
5999 | cindex:[lookup,dbm] | |
6000 | cindex:[binary zero,in lookup key] | |
6001 | ^dbm^: Calls to DBM library functions are used to extract data from the given | |
6002 | DBM file by looking up the record with the given key. A terminating binary | |
6003 | zero is included in the key that is passed to the DBM library. See section | |
6004 | <<SECTdb>> for a discussion of DBM libraries. | |
6005 | + | |
6006 | cindex:[Berkeley DB library,file format] | |
6007 | For all versions of Berkeley DB, Exim uses the DB_HASH style of database | |
6008 | when building DBM files using the %exim_dbmbuild% utility. However, when using | |
6009 | Berkeley DB versions 3 or 4, it opens existing databases for reading with the | |
6010 | DB_UNKNOWN option. This enables it to handle any of the types of database | |
6011 | that the library supports, and can be useful for accessing DBM files created by | |
6012 | other applications. (For earlier DB versions, DB_HASH is always used.) | |
6013 | ||
6014 | - cindex:[lookup,dbmnz] | |
6015 | cindex:[lookup,dbm -- terminating zero] | |
6016 | cindex:[binary zero,in lookup key] | |
6017 | cindex:[Courier] | |
6018 | cindex:[_/etc/userdbshadow.dat_] | |
6019 | cindex:[dmbnz lookup type] | |
6020 | ^dbmnz^: This is the same as ^dbm^, except that a terminating binary zero | |
6021 | is not included in the key that is passed to the DBM library. You may need this | |
6022 | if you want to look up data in files that are created by or shared with some | |
6023 | other application that does not use terminating zeros. For example, you need to | |
6024 | use ^dbmnz^ rather than ^dbm^ if you want to authenticate incoming SMTP | |
6025 | calls using the passwords from Courier's _/etc/userdbshadow.dat_ file. Exim's | |
6026 | utility program for creating DBM files ('exim_dbmbuild') includes the zeros | |
6027 | by default, but has an option to omit them (see section <<SECTdbmbuild>>). | |
6028 | ||
6029 | - cindex:[lookup,dsearch] | |
6030 | cindex:[dsearch lookup type] | |
6031 | ^dsearch^: The given file must be a directory; this is searched for a file | |
6032 | whose name is the key. The key may not contain any forward slash characters. | |
6033 | The result of a successful lookup is the name of the file. An example of how | |
6034 | this lookup can be used to support virtual domains is given in section | |
6035 | <<SECTvirtualdomains>>. | |
6036 | ||
6037 | - cindex:[lookup,iplsearch] | |
6038 | cindex:[iplsearch lookup type] | |
6039 | ^iplsearch^: The given file is a text file containing keys and data. A key is | |
6040 | terminated by a colon or white space or the end of the line. The keys in the | |
6041 | file must be IP addresses, or IP addresses with CIDR masks. Keys that involve | |
6042 | IPv6 addresses must be enclosed in quotes to prevent the first internal colon | |
6043 | being interpreted as a key terminator. For example: | |
6044 | ||
6045 | 1.2.3.4: data for 1.2.3.4 | |
6046 | 192.168.0.0/16 data for 192.168.0.0/16 | |
6047 | "abcd::cdab": data for abcd::cdab | |
6048 | "abcd:abcd::/32" data for abcd:abcd::/32 | |
6049 | + | |
6050 | The key for an ^iplsearch^ lookup must be an IP address (without a mask). The | |
6051 | file is searched linearly, using the CIDR masks where present, until a matching | |
6052 | key is found. The first key that matches is used; there is no attempt to find a | |
6053 | ``best'' match. Apart from the way the keys are matched, the processing for | |
6054 | ^iplsearch^ is the same as for ^lsearch^. | |
6055 | + | |
6056 | *Warning 1*: Unlike most other single-key lookup types, a file of data for | |
6057 | ^iplsearch^ can 'not' be turned into a DBM or cdb file, because those | |
6058 | lookup types support only literal keys. | |
6059 | + | |
6060 | *Warning 2*: In a host list, you must always use ^net-iplsearch^ so that | |
6061 | the implicit key is the host's IP address rather than its name (see section | |
6062 | <<SECThoslispatsikey>>). | |
6063 | ||
6064 | - cindex:[linear search] | |
6065 | cindex:[lookup,lsearch] | |
6066 | cindex:[lsearch lookup type] | |
6067 | ^lsearch^: The given file is a text file that is searched linearly for a | |
6068 | line beginning with the search key, terminated by a colon or white space or the | |
6069 | end of the line. The first occurrence that is found in the file is used. White | |
6070 | space between the key and the colon is permitted. The remainder of the line, | |
6071 | with leading and trailing white space removed, is the data. This can be | |
6072 | continued onto subsequent lines by starting them with any amount of white | |
6073 | space, but only a single space character is included in the data at such a | |
6074 | junction. If the data begins with a colon, the key must be terminated by a | |
6075 | colon, for example: | |
6076 | ||
6077 | baduser: :fail: | |
6078 | + | |
6079 | Empty lines and lines beginning with # are ignored, even if they occur in the | |
6080 | middle of an item. This is the traditional textual format of alias files. Note | |
6081 | that the keys in an ^lsearch^ file are literal strings. There is no | |
6082 | wildcarding of any kind. | |
6083 | + | |
6084 | cindex:[lookup,lsearch -- colons in keys] | |
068aaea8 | 6085 | cindex:[white space,in lsearch key] |
168e428f | 6086 | In most ^lsearch^ files, keys are not required to contain colons or # |
068aaea8 | 6087 | characters, or white space. However, if you need this feature, it is available. |
168e428f PH |
6088 | If a key begins with a doublequote character, it is terminated only by a |
6089 | matching quote (or end of line), and the normal escaping rules apply to its | |
6090 | contents (see section <<SECTstrings>>). An optional colon is permitted after | |
6091 | quoted keys (exactly as for unquoted keys). There is no special handling of | |
6092 | quotes for the data part of an ^lsearch^ line. | |
6093 | ||
6094 | - cindex:[NIS lookup type] | |
6095 | cindex:[lookup,NIS] | |
6096 | cindex:[binary zero,in lookup key] | |
6097 | ^nis^: The given file is the name of a NIS map, and a NIS lookup is done with | |
6098 | the given key, without a terminating binary zero. There is a variant called | |
6099 | ^nis0^ which does include the terminating binary zero in the key. This is | |
6100 | reportedly needed for Sun-style alias files. Exim does not recognize NIS | |
6101 | aliases; the full map names must be used. | |
6102 | ||
6103 | - cindex:[wildlsearch lookup type] | |
6104 | cindex:[lookup,wildlsearch] | |
6105 | cindex:[nwildlsearch lookup type] | |
6106 | cindex:[lookup,nwildlsearch] | |
d1e83bff PH |
6107 | ^wildlsearch^ or ^nwildlsearch^: These search a file linearly, like ^lsearch^, |
6108 | but instead of being interpreted as a literal string, each key in the file may | |
168e428f PH |
6109 | be wildcarded. The difference between these two lookup types is that for |
6110 | ^wildlsearch^, each key in the file is string-expanded before being used, | |
6111 | whereas for ^nwildlsearch^, no expansion takes place. | |
6112 | + | |
6113 | Like ^lsearch^, the testing is done case-insensitively. The following forms | |
6114 | of wildcard are recognized: | |
6115 | + | |
6116 | -- | |
6117 | .. The string may begin with an asterisk to mean ``ends with''. For example: | |
6118 | ||
068aaea8 PH |
6119 | *.a.b.c data for anything.a.b.c |
6120 | *fish data for anythingfish | |
168e428f PH |
6121 | |
6122 | .. The string may begin with a circumflex to indicate a regular expression. For | |
6123 | example, for ^wildlsearch^: | |
6124 | ||
068aaea8 | 6125 | ^\N\d+\.a\.b\N data for <digits>.a.b |
168e428f PH |
6126 | |
6127 | Note the use of `\N` to disable expansion of the contents of the regular | |
6128 | expression. If you are using ^nwildlsearch^, where the keys are not | |
6129 | string-expanded, the equivalent entry is: | |
6130 | ||
068aaea8 | 6131 | ^\d+\.a\.b data for <digits>.a.b |
168e428f PH |
6132 | |
6133 | If the regular expression contains white space or colon characters, you must | |
6134 | either quote it (see ^lsearch^ above), or represent these characters in other | |
6135 | ways. For example, `\s` can be used for white space and `\x3A` for a | |
6136 | colon. This may be easier than quoting, because if you quote, you have to | |
6137 | escape all the backslashes inside the quotes. | |
6138 | ||
d1e83bff PH |
6139 | *Note*: It is not possible to capture substrings in a regular expression match |
6140 | for later use, because the results of all lookups are cached. If a lookup is | |
6141 | repeated, the result is taken from the cache, and no actual pattern matching | |
6142 | takes place. The values of all the numeric variables are unset after a | |
6143 | ^(n)wildlsearch^ match. | |
6144 | ||
168e428f PH |
6145 | .. Although I cannot see it being of much use, the general matching function |
6146 | that is used to implement ^(n)wildlsearch^ means that the string may begin with | |
6147 | a lookup name terminated by a semicolon, and followed by lookup data. For | |
6148 | example: | |
6149 | ||
068aaea8 | 6150 | cdb;/some/file data for keys that match the file |
168e428f PH |
6151 | |
6152 | The data that is obtained from the nested lookup is discarded. | |
6153 | -- | |
6154 | + | |
6155 | Keys that do not match any of these patterns are interpreted literally. The | |
6156 | continuation rules for the data are the same as for ^lsearch^, and keys may | |
6157 | be followed by optional colons. | |
6158 | + | |
6159 | *Warning*: Unlike most other single-key lookup types, a file of data for | |
6160 | ^(n)wildlsearch^ can 'not' be turned into a DBM or cdb file, because those | |
6161 | lookup types support only literal keys. | |
6162 | ||
6163 | ||
6164 | ||
6165 | Query-style lookup types | |
6166 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
6167 | cindex:[lookup,query-style types] | |
6168 | cindex:[query-style lookup,list of types] | |
6169 | The supported query-style lookup types are listed below. Further details about | |
6170 | many of them are given in later sections. | |
6171 | ||
6172 | - cindex:[DNS,as a lookup type] | |
6173 | cindex:[lookup,DNS] | |
6174 | ^dnsdb^: This does a DNS search for one or more records whose domain names are | |
6175 | given in the supplied query. The resulting data is the contents of the records. | |
6176 | See section <<SECTdnsdb>>. | |
6177 | ||
6178 | - cindex:[Interbase lookup type] | |
6179 | cindex:[lookup,Interbase] | |
6180 | ^ibase^: This does a lookup in an Interbase database. | |
6181 | ||
6182 | - cindex:[LDAP,lookup type] | |
6183 | cindex:[lookup,LDAP] | |
6184 | ^ldap^: This does an LDAP lookup using a query in the form of a URL, and | |
6185 | returns attributes from a single entry. There is a variant called ^ldapm^ | |
6186 | that permits values from multiple entries to be returned. A third variant | |
6187 | called ^ldapdn^ returns the Distinguished Name of a single entry instead of | |
6188 | any attribute values. See section <<SECTldap>>. | |
6189 | ||
6190 | - cindex:[MySQL,lookup type] | |
6191 | cindex:[lookup,MySQL] | |
6192 | ^mysql^: The format of the query is an SQL statement that is passed to a MySQL | |
6193 | database. See section <<SECTsql>>. | |
6194 | ||
6195 | - cindex:[NIS+ lookup type] | |
6196 | cindex:[lookup,NIS+] | |
6197 | ^nisplus^: This does a NIS+ lookup using a query that can specify the name of | |
6198 | the field to be returned. See section <<SECTnisplus>>. | |
6199 | ||
6200 | - cindex:[Oracle,lookup type] | |
6201 | cindex:[lookup,Oracle] | |
6202 | ^oracle^: The format of the query is an SQL statement that is passed to an | |
6203 | Oracle database. See section <<SECTsql>>. | |
6204 | ||
6205 | - cindex:[lookup,passwd] | |
6206 | cindex:[passwd lookup type] | |
6207 | cindex:[_/etc/passwd_] | |
6208 | ^passwd^ is a query-style lookup with queries that are just user names. The | |
6209 | lookup calls 'getpwnam()' to interrogate the system password data, and on | |
6210 | success, the result string is the same as you would get from an ^lsearch^ | |
6211 | lookup on a traditional _/etc/passwd file_, though with `*` for the | |
6212 | password value. For example: | |
6213 | ||
6214 | *:42:42:King Rat:/home/kr:/bin/bash | |
6215 | ||
6216 | - cindex:[PostgreSQL lookup type] | |
6217 | cindex:[lookup,PostgreSQL] | |
6218 | ^pgsql^: The format of the query is an SQL statement that is passed to a | |
6219 | PostgreSQL database. See section <<SECTsql>>. | |
6220 | ||
068aaea8 PH |
6221 | [revisionflag="changed"] |
6222 | - cindex:[sqlite lookup type] | |
6223 | cindex:[lookup,sqlite] | |
6224 | ^sqlite^: The format of the query is a file name followed by an SQL statement | |
6225 | that is passed to an SQLite database. See section <<SECTsqlite>>. | |
6226 | ||
168e428f PH |
6227 | - ^testdb^: This is a lookup type that is used for testing Exim. It is |
6228 | not likely to be useful in normal operation. | |
6229 | ||
6230 | - cindex:[whoson lookup type] | |
6231 | cindex:[lookup,whoson] | |
6232 | ^whoson^: 'Whoson' (*http://whoson.sourceforge.net[]*) is a proposed | |
6233 | Internet protocol that allows Internet server programs to check whether a | |
6234 | particular (dynamically allocated) IP address is currently allocated to a known | |
6235 | (trusted) user and, optionally, to obtain the identity of the said user. In | |
6236 | Exim, this can be used to implement ``POP before SMTP'' checking using ACL | |
6237 | statements such as | |
6238 | + | |
6239 | .... | |
6240 | require condition = \ | |
6241 | ${lookup whoson {$sender_host_address}{yes}{no}} | |
6242 | .... | |
6243 | + | |
6244 | The query consists of a single IP address. The value returned is the name of | |
6245 | the authenticated user. | |
6246 | ||
6247 | ||
6248 | ||
6249 | Temporary errors in lookups | |
6250 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
6251 | cindex:[lookup,temporary error in] | |
6252 | Lookup functions can return temporary error codes if the lookup cannot be | |
068aaea8 | 6253 | completed. For example, an SQL or LDAP database might be unavailable. For this |
168e428f PH |
6254 | reason, it is not advisable to use a lookup that might do this for critical |
6255 | options such as a list of local domains. | |
6256 | ||
6257 | When a lookup cannot be completed in a router or transport, delivery | |
6258 | of the message (to the relevant address) is deferred, as for any other | |
6259 | temporary error. In other circumstances Exim may assume the lookup has failed, | |
6260 | or may give up altogether. | |
6261 | ||
6262 | ||
6263 | ||
6264 | [[SECTdefaultvaluelookups]] | |
6265 | Default values in single-key lookups | |
6266 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
6267 | cindex:[wildcard lookups] | |
6268 | cindex:[lookup,default values] | |
6269 | cindex:[lookup,wildcard] | |
6270 | cindex:[lookup,\* added to type] | |
6271 | cindex:[default,in single-key lookups] | |
6272 | In this context, a ``default value'' is a value specified by the administrator | |
6273 | that is to be used if a lookup fails. | |
6274 | ||
6275 | If ``\*'' is added to a single-key lookup type (for example, %lsearch\*%) and | |
6276 | the initial lookup fails, the key ``\*'' is looked up in the file to provide | |
6277 | a default value. See also the section on partial matching below. | |
6278 | ||
6279 | cindex:[\*@ with single-key lookup] | |
6280 | cindex:[lookup,\*@ added to type] | |
6281 | cindex:[alias file,per-domain default] | |
6282 | Alternatively, if ``\*@'' is added to a single-key lookup type (for example | |
6283 | \dbm\*\) then, if the initial lookup fails and the key contains an @ | |
6284 | character, a second lookup is done with everything before the last @ replaced | |
6285 | by \*. This makes it possible to provide per-domain defaults in alias files | |
6286 | that include the domains in the keys. If the second lookup fails (or doesn't | |
6287 | take place because there is no @ in the key), ``\*'' is looked up. | |
6288 | For example, a ^redirect^ router might contain: | |
6289 | ||
6290 | data = ${lookup{$local_part@$domain}lsearch*@{/etc/mixed-aliases}} | |
6291 | ||
6292 | Suppose the address that is being processed is 'jane@eyre.example'. Exim | |
6293 | looks up these keys, in this order: | |
6294 | ||
6295 | jane@eyre.example | |
6296 | *@eyre.example | |
6297 | * | |
6298 | ||
6299 | The data is taken from whichever key it finds first. *Note*: in an | |
6300 | ^lsearch^ file, this does not mean the first of these keys in the file. A | |
6301 | complete scan is done for each key, and only if it is not found at all does | |
6302 | Exim move on to try the next key. | |
6303 | ||
6304 | ||
6305 | ||
6306 | [[SECTpartiallookup]] | |
6307 | Partial matching in single-key lookups | |
6308 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
6309 | cindex:[partial matching] | |
6310 | cindex:[wildcard lookups] | |
6311 | cindex:[lookup,partial matching] | |
6312 | cindex:[lookup,wildcard] | |
6313 | cindex:[asterisk,in search type] | |
6314 | The normal operation of a single-key lookup is to search the file for an exact | |
6315 | match with the given key. However, in a number of situations where domains are | |
6316 | being looked up, it is useful to be able to do partial matching. In this case, | |
6317 | information in the file that has a key starting with ``\*.'' is matched by any | |
6318 | domain that ends with the components that follow the full stop. For example, if | |
6319 | a key in a DBM file is | |
6320 | ||
6321 | *.dates.fict.example | |
6322 | ||
6323 | then when partial matching is enabled this is matched by (amongst others) | |
6324 | '2001.dates.fict.example' and '1984.dates.fict.example'. It is also matched | |
6325 | by 'dates.fict.example', if that does not appear as a separate key in the | |
6326 | file. | |
6327 | ||
6328 | *Note*: Partial matching is not available for query-style lookups. It is | |
6329 | also not available for any lookup items in address lists (see section | |
6330 | <<SECTaddresslist>>). | |
6331 | ||
6332 | Partial matching is implemented by doing a series of separate lookups using | |
6333 | keys constructed by modifying the original subject key. This means that it can | |
6334 | be used with any of the single-key lookup types, provided that | |
6335 | partial matching keys | |
6336 | beginning with a special prefix (default ``\*.'') are included in the data file. | |
6337 | Keys in the file that do not begin with the prefix are matched only by | |
6338 | unmodified subject keys when partial matching is in use. | |
6339 | ||
6340 | Partial matching is requested by adding the string ``partial-'' to the front of | |
6341 | the name of a single-key lookup type, for example, %partial-dbm%. When this is | |
6342 | done, the subject key is first looked up unmodified; if that fails, ``\*.'' | |
6343 | is added at the start of the subject key, and it is looked up again. If that | |
6344 | fails, further lookups are tried with dot-separated components removed | |
6345 | from the start of the subject key, one-by-one, and ``\*.'' added on the front of | |
6346 | what remains. | |
6347 | ||
6348 | A minimum number of two non-\* components are required. This can be adjusted | |
6349 | by including a number before the hyphen in the search type. For example, | |
6350 | %partial3-lsearch% specifies a minimum of three non-\* components in the | |
6351 | modified keys. Omitting the number is equivalent to ``partial2-''. If the subject | |
6352 | key is '2250.dates.fict.example' then the following keys are looked up when | |
6353 | the minimum number of non-\* components is two: | |
6354 | ||
6355 | 2250.dates.fict.example | |
6356 | *.2250.dates.fict.example | |
6357 | *.dates.fict.example | |
6358 | *.fict.example | |
6359 | ||
6360 | As soon as one key in the sequence is successfully looked up, the lookup | |
6361 | finishes. | |
6362 | ||
6363 | cindex:[lookup,partial matching -- changing prefix] | |
6364 | cindex:[prefix,for partial matching] | |
6365 | The use of ``\*.'' as the partial matching prefix is a default that can be | |
6366 | changed. The motivation for this feature is to allow Exim to operate with file | |
6367 | formats that are used by other MTAs. A different prefix can be supplied in | |
6368 | parentheses instead of the hyphen after ``partial''. For example: | |
6369 | ||
6370 | domains = partial(.)lsearch;/some/file | |
6371 | ||
6372 | In this example, if the domain is 'a.b.c', the sequence of lookups is | |
6373 | `a.b.c`, `.a.b.c`, and `.b.c` (the default minimum of 2 non-wild | |
6374 | components is unchanged). The prefix may consist of any punctuation characters | |
6375 | other than a closing parenthesis. It may be empty, for example: | |
6376 | ||
6377 | domains = partial1()cdb;/some/file | |
6378 | ||
6379 | For this example, if the domain is 'a.b.c', the sequence of lookups is | |
6380 | `a.b.c`, `b.c`, and `c`. | |
6381 | ||
6382 | If ``partial0'' is specified, what happens at the end (when the lookup with just | |
6383 | one non-wild component has failed, and the original key is shortened right down | |
6384 | to the null string) depends on the prefix: | |
6385 | ||
6386 | - If the prefix has zero length, the whole lookup fails. | |
6387 | ||
6388 | - If the prefix has length 1, a lookup for just the prefix is done. For | |
6389 | example, the final lookup for ``partial0(.)'' is for `.` alone. | |
6390 | ||
6391 | - Otherwise, if the prefix ends in a dot, the dot is removed, and the | |
6392 | remainder is looked up. With the default prefix, therefore, the final lookup is | |
6393 | for ``\*'' on its own. | |
6394 | ||
6395 | - Otherwise, the whole prefix is looked up. | |
6396 | ||
6397 | ||
6398 | If the search type ends in ``\*'' or ``\*@'' (see section | |
6399 | <<SECTdefaultvaluelookups>> above), the search for an ultimate default that this | |
6400 | implies happens after all partial lookups have failed. If ``partial0'' is | |
6401 | specified, adding ``\*'' to the search type has no effect with the default | |
6402 | prefix, because the ``\*'' key is already included in the sequence of partial | |
6403 | lookups. However, there might be a use for lookup types such as | |
6404 | ``partial0(.)lsearch\*''. | |
6405 | ||
6406 | The use of ``\*'' in lookup partial matching differs from its use as a wildcard | |
6407 | in domain lists and the like. Partial matching works only in terms of | |
6408 | dot-separated components; a key such as `*fict.example` | |
6409 | in a database file is useless, because the asterisk in a partial matching | |
6410 | subject key is always followed by a dot. | |
6411 | ||
6412 | ||
6413 | ||
6414 | ||
6415 | Lookup caching | |
6416 | ~~~~~~~~~~~~~~ | |
6417 | cindex:[lookup,caching] | |
6418 | cindex:[caching,lookup data] | |
6419 | Exim caches all lookup results in order to avoid needless repetition of | |
6420 | lookups. However, because (apart from the daemon) Exim operates as a collection | |
6421 | of independent, short-lived processes, this caching applies only within a | |
6422 | single Exim process. There is no inter-process caching facility. | |
6423 | ||
6424 | For single-key lookups, Exim keeps the relevant files open in case there is | |
6425 | another lookup that needs them. In some types of configuration this can lead to | |
6426 | many files being kept open for messages with many recipients. To avoid hitting | |
6427 | the operating system limit on the number of simultaneously open files, Exim | |
6428 | closes the least recently used file when it needs to open more files than its | |
6429 | own internal limit, which can be changed via the %lookup_open_max% option. | |
6430 | ||
6431 | The single-key lookup files are closed and the lookup caches are flushed at | |
6432 | strategic points during delivery -- for example, after all routing is complete. | |
6433 | ||
6434 | ||
6435 | ||
6436 | ||
6437 | Quoting lookup data | |
6438 | ~~~~~~~~~~~~~~~~~~~ | |
6439 | cindex:[lookup,quoting] | |
6440 | cindex:[quoting,in lookups] | |
6441 | When data from an incoming message is included in a query-style lookup, there | |
6442 | is the possibility of special characters in the data messing up the syntax of | |
6443 | the query. For example, a NIS+ query that contains | |
6444 | ||
6445 | [name=$local_part] | |
6446 | ||
6447 | will be broken if the local part happens to contain a closing square bracket. | |
6448 | For NIS+, data can be enclosed in double quotes like this: | |
6449 | ||
6450 | [name="$local_part"] | |
6451 | ||
6452 | but this still leaves the problem of a double quote in the data. The rule for | |
6453 | NIS+ is that double quotes must be doubled. Other lookup types have different | |
6454 | rules, and to cope with the differing requirements, an expansion operator | |
6455 | of the following form is provided: | |
6456 | ||
6457 | \$\{quote_<lookup-type>:<string>\} | |
6458 | ||
6459 | For example, the safest way to write the NIS+ query is | |
6460 | ||
6461 | [name="${quote_nisplus:$local_part}"] | |
6462 | ||
6463 | See chapter <<CHAPexpand>> for full coverage of string expansions. The quote | |
6464 | operator can be used for all lookup types, but has no effect for single-key | |
6465 | lookups, since no quoting is ever needed in their key strings. | |
6466 | ||
6467 | ||
6468 | ||
6469 | ||
6470 | [[SECTdnsdb]] | |
6471 | More about dnsdb | |
6472 | ~~~~~~~~~~~~~~~~ | |
6473 | cindex:[dnsdb lookup] | |
6474 | cindex:[lookup,dnsdb] | |
6475 | cindex:[DNS,as a lookup type] | |
6476 | The ^dnsdb^ lookup type uses the DNS as its database. A simple query consists | |
6477 | of a record type and a domain name, separated by an equals sign. For example, | |
6478 | an expansion string could contain: | |
6479 | ||
6480 | ${lookup dnsdb{mx=a.b.example}{$value}fail} | |
6481 | ||
6482 | The supported DNS record types are A, CNAME, MX, NS, PTR, SRV, and TXT, and, | |
6483 | when Exim is compiled with IPv6 support, AAAA (and A6 if that is also | |
6484 | configured). If no type is given, TXT is assumed. When the type is PTR, | |
6485 | the data can be an IP address, written as normal; inversion and the addition of | |
6486 | %in-addr.arpa% or %ip6.arpa% happens automatically. For example: | |
6487 | ||
6488 | ${lookup dnsdb{ptr=192.168.4.5}{$value}fail} | |
6489 | ||
6490 | If the data for a PTR record is not a syntactically valid IP address, it is not | |
6491 | altered and nothing is added. | |
6492 | ||
068aaea8 PH |
6493 | cindex:[MX record,in ^dnsdb^ lookup] |
6494 | cindex:[SRV record,in ^dnsdb^ lookup] | |
6495 | For an MX lookup, both the preference value and the host name are returned for | |
6496 | each record, separated by a space. For an SRV lookup, the priority, weight, | |
6497 | port, and host name are returned for each record, separated by spaces. | |
6498 | ||
168e428f PH |
6499 | For any record type, if multiple records are found (or, for A6 lookups, if a |
6500 | single record leads to multiple addresses), the data is returned as a | |
6501 | concatenation, with newline as the default separator. The order, of course, | |
6502 | depends on the DNS resolver. You can specify a different separator character | |
6503 | between multiple records by putting a right angle-bracket followed immediately | |
6504 | by the new separator at the start of the query. For example: | |
6505 | ||
6506 | ${lookup dnsdb{>: a=host1.example}} | |
6507 | ||
6508 | It is permitted to specify a space as the separator character. Further | |
068aaea8 | 6509 | white space is ignored. |
168e428f | 6510 | |
068aaea8 PH |
6511 | Pseudo dnsdb record types |
6512 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
168e428f | 6513 | cindex:[MX record,in ^dnsdb^ lookup] |
068aaea8 PH |
6514 | By default, both the preference value and the host name are returned for |
6515 | each MX record, separated by a space. If you want only host names, you can use | |
6516 | the pseudo-type MXH: | |
168e428f PH |
6517 | |
6518 | ${lookup dnsdb{mxh=a.b.example}} | |
6519 | ||
068aaea8 PH |
6520 | In this case, the preference values are omitted, and just the host names are |
6521 | returned. | |
168e428f PH |
6522 | |
6523 | cindex:[name server,for enclosing domain] | |
6524 | Another pseudo-type is ZNS (for ``zone NS''). It performs a lookup for NS | |
6525 | records on the given domain, but if none are found, it removes the first | |
6526 | component of the domain name, and tries again. This process continues until NS | |
6527 | records are found or there are no more components left (or there is a DNS | |
6528 | error). In other words, it may return the name servers for a top-level domain, | |
6529 | but it never returns the root name servers. If there are no NS records for the | |
6530 | top-level domain, the lookup fails. Consider these examples: | |
6531 | ||
6532 | ${lookup dnsdb{zns=xxx.quercite.com}} | |
6533 | ${lookup dnsdb{zns=xxx.edu}} | |
6534 | ||
6535 | Assuming that in each case there are no NS records for the full domain name, | |
6536 | the first returns the name servers for %quercite.com%, and the second returns | |
6537 | the name servers for %edu%. | |
6538 | ||
6539 | You should be careful about how you use this lookup because, unless the | |
6540 | top-level domain does not exist, the lookup always returns some host names. The | |
6541 | sort of use to which this might be put is for seeing if the name servers for a | |
6542 | given domain are on a blacklist. You can probably assume that the name servers | |
6543 | for the high-level domains such as %com% or %co.uk% are not going to be on such | |
6544 | a list. | |
6545 | ||
068aaea8 PH |
6546 | [revisionflag="changed"] |
6547 | cindex:[CSA,in ^dnsdb^ lookup] | |
6548 | A third pseudo-type is CSA (Client SMTP Authorization), which looks up SRV | |
6549 | records according to the CSA rules, which are described in section | |
6550 | <<SECTverifyCSA>>. Although ^dnsdb^ supports SRV lookups directly, this is not | |
6551 | sufficient because of the extra parent domain search behaviour of CSA. The | |
6552 | result of a successful lookup such as: | |
6553 | ||
6554 | [revisionflag="changed"] | |
6555 | .... | |
6556 | ${lookup dnsdb {csa=$sender_helo_name}} | |
6557 | .... | |
6558 | ||
6559 | [revisionflag="changed"] | |
6560 | has two space-separated fields: an authorization code and a target host name. | |
6561 | The authorization code can be ``Y'' for yes, ``N'' for no, ``X'' for explicit | |
6562 | authorization required but absent, or ``?'' for unknown. | |
6563 | ||
168e428f PH |
6564 | |
6565 | ||
6566 | Multiple dnsdb lookups | |
6567 | ~~~~~~~~~~~~~~~~~~~~~~ | |
068aaea8 | 6568 | In the previous sections, ^dnsdb^ lookups for a single domain are described. |
168e428f PH |
6569 | However, you can specify a list of domains or IP addresses in a single |
6570 | ^dnsdb^ lookup. The list is specified in the normal Exim way, with colon as | |
6571 | the default separator, but with the ability to change this. For example: | |
6572 | ||
6573 | ${lookup dnsdb{one.domain.com:two.domain.com}} | |
6574 | ${lookup dnsdb{a=one.host.com:two.host.com}} | |
6575 | ${lookup dnsdb{ptr = <; 1.2.3.4 ; 4.5.6.8}} | |
6576 | ||
6577 | In order to retain backwards compatibility, there is one special case: if | |
6578 | the lookup type is PTR and no change of separator is specified, Exim looks | |
6579 | to see if the rest of the string is precisely one IPv6 address. In this | |
6580 | case, it does not treat it as a list. | |
6581 | ||
6582 | The data from each lookup is concatenated, with newline separators by default, | |
6583 | in the same way that multiple DNS records for a single item are handled. A | |
6584 | different separator can be specified, as described above. | |
6585 | ||
6586 | The ^dnsdb^ lookup fails only if all the DNS lookups fail. If there is a | |
6587 | temporary DNS error for any of them, the behaviour is controlled by | |
6588 | an optional keyword followed by a comma that may appear before the record | |
6589 | type. The possible keywords are ``defer_strict'', ``defer_never'', and | |
6590 | ``defer_lax''. With ``strict'' behaviour, any temporary DNS error causes the | |
6591 | whole lookup to defer. With ``never'' behaviour, a temporary DNS error is | |
6592 | ignored, and the behaviour is as if the DNS lookup failed to find anything. | |
6593 | With ``lax'' behaviour, all the queries are attempted, but a temporary DNS | |
6594 | error causes the whole lookup to defer only if none of the other lookups | |
6595 | succeed. The default is ``lax'', so the following lookups are equivalent: | |
6596 | ||
6597 | ${lookup dnsdb{defer_lax,a=one.host.com:two.host.com}} | |
6598 | ${lookup dnsdb{a=one.host.com:two.host.com}} | |
6599 | ||
6600 | Thus, in the default case, as long as at least one of the DNS lookups | |
6601 | yields some data, the lookup succeeds. | |
6602 | ||
6603 | ||
6604 | ||
6605 | ||
6606 | [[SECTldap]] | |
6607 | More about LDAP | |
6608 | ~~~~~~~~~~~~~~~ | |
6609 | cindex:[LDAP lookup] | |
6610 | cindex:[lookup,LDAP] | |
6611 | cindex:[Solaris,LDAP] | |
6612 | The original LDAP implementation came from the University of Michigan; this has | |
6613 | become ``Open LDAP'', and there are now two different releases. Another | |
6614 | implementation comes from Netscape, and Solaris 7 and subsequent releases | |
6615 | contain inbuilt LDAP support. Unfortunately, though these are all compatible at | |
6616 | the lookup function level, their error handling is different. For this reason | |
6617 | it is necessary to set a compile-time variable when building Exim with LDAP, to | |
6618 | indicate which LDAP library is in use. One of the following should appear in | |
6619 | your _Local/Makefile_: | |
6620 | ||
6621 | LDAP_LIB_TYPE=UMICHIGAN | |
6622 | LDAP_LIB_TYPE=OPENLDAP1 | |
6623 | LDAP_LIB_TYPE=OPENLDAP2 | |
6624 | LDAP_LIB_TYPE=NETSCAPE | |
6625 | LDAP_LIB_TYPE=SOLARIS | |
6626 | ||
6627 | If LDAP_LIB_TYPE is not set, Exim assumes `OPENLDAP1`, which has the | |
6628 | same interface as the University of Michigan version. | |
6629 | ||
6630 | There are three LDAP lookup types in Exim. These behave slightly differently in | |
6631 | the way they handle the results of a query: | |
6632 | ||
6633 | - ^ldap^ requires the result to contain just one entry; if there are more, it | |
6634 | gives an error. | |
6635 | ||
6636 | - ^ldapdn^ also requires the result to contain just one entry, but it is the | |
6637 | Distinguished Name that is returned rather than any attribute values. | |
6638 | ||
6639 | - ^ldapm^ permits the result to contain more than one entry; the attributes from | |
6640 | all of them are returned. | |
6641 | ||
6642 | ||
6643 | For ^ldap^ and ^ldapm^, if a query finds only entries with no attributes, | |
6644 | Exim behaves as if the entry did not exist, and the lookup fails. The format of | |
6645 | the data returned by a successful lookup is described in the next section. | |
6646 | First we explain how LDAP queries are coded. | |
6647 | ||
6648 | ||
6649 | [[SECTforldaque]] | |
6650 | Format of LDAP queries | |
6651 | ~~~~~~~~~~~~~~~~~~~~~~ | |
6652 | cindex:[LDAP,query format] | |
6653 | An LDAP query takes the form of a URL as defined in RFC 2255. For example, in | |
6654 | the configuration of a ^redirect^ router one might have this setting: | |
6655 | ||
6656 | .... | |
6657 | data = ${lookup ldap \ | |
6658 | {ldap:///cn=$local_part,o=University%20of%20Cambridge,\ | |
6659 | c=UK?mailbox?base?}} | |
6660 | .... | |
6661 | ||
6662 | cindex:[LDAP,with TLS] | |
6663 | The URL may begin with `ldap` or `ldaps` if your LDAP library supports | |
6664 | secure (encrypted) LDAP connections. The second of these ensures that an | |
6665 | encrypted TLS connection is used. | |
6666 | ||
6667 | ||
6668 | LDAP quoting | |
6669 | ~~~~~~~~~~~~ | |
6670 | cindex:[LDAP,quoting] | |
6671 | Two levels of quoting are required in LDAP queries, the first for LDAP itself | |
6672 | and the second because the LDAP query is represented as a URL. Furthermore, | |
6673 | within an LDAP query, two different kinds of quoting are required. For this | |
6674 | reason, there are two different LDAP-specific quoting operators. | |
6675 | ||
6676 | The %quote_ldap% operator is designed for use on strings that are part of | |
6677 | filter specifications. Conceptually, it first does the following conversions on | |
6678 | the string: | |
6679 | ||
6680 | .... | |
6681 | * => \2A | |
6682 | ( => \28 | |
6683 | ) => \29 | |
6684 | \ => \5C | |
6685 | .... | |
6686 | ||
6687 | in accordance with RFC 2254. The resulting string is then quoted according | |
6688 | to the rules for URLs, that is, all characters except | |
6689 | ||
6690 | ! $ ' - . _ ( ) * + | |
6691 | ||
6692 | are converted to their hex values, preceded by a percent sign. For example: | |
6693 | ||
6694 | ${quote_ldap: a(bc)*, a<yz>; } | |
6695 | ||
6696 | yields | |
6697 | ||
6698 | %20a%5C28bc%5C29%5C2A%2C%20a%3Cyz%3E%3B%20 | |
6699 | ||
6700 | Removing the URL quoting, this is (with a leading and a trailing space): | |
6701 | ||
6702 | a\28bc\29\2A, a<yz>; | |
6703 | ||
6704 | ||
6705 | The %quote_ldap_dn% operator is designed for use on strings that are part of | |
6706 | base DN specifications in queries. Conceptually, it first converts the string | |
6707 | by inserting a backslash in front of any of the following characters: | |
6708 | ||
6709 | , + " \ < > ; | |
6710 | ||
6711 | It also inserts a backslash before any leading spaces or # characters, and | |
6712 | before any trailing spaces. (These rules are in RFC 2253.) The resulting string | |
6713 | is then quoted according to the rules for URLs. For example: | |
6714 | ||
6715 | ${quote_ldap_dn: a(bc)*, a<yz>; } | |
6716 | ||
6717 | yields | |
6718 | ||
6719 | %5C%20a(bc)*%5C%2C%20a%5C%3Cyz%5C%3E%5C%3B%5C%20 | |
6720 | ||
6721 | Removing the URL quoting, this is (with a trailing space): | |
6722 | ||
6723 | .... | |
6724 | \ a(bc)*\, a\<yz\>\;\ | |
6725 | .... | |
6726 | ||
6727 | There are some further comments about quoting in the section on LDAP | |
6728 | authentication below. | |
6729 | ||
6730 | ||
6731 | LDAP connections | |
6732 | ~~~~~~~~~~~~~~~~ | |
6733 | cindex:[LDAP,connections] | |
6734 | The connection to an LDAP server may either be over TCP/IP, or, when OpenLDAP | |
6735 | is in use, via a Unix domain socket. The example given above does not specify | |
6736 | an LDAP server. A server that is reached by TCP/IP can be specified in a query | |
6737 | by starting it with | |
6738 | ||
6739 | ldap://<hostname>:<port>/... | |
6740 | ||
6741 | If the port (and preceding colon) are omitted, the standard LDAP port (389) is | |
6742 | used. When no server is specified in a query, a list of default servers is | |
6743 | taken from the %ldap_default_servers% configuration option. This supplies a | |
6744 | colon-separated list of servers which are tried in turn until one successfully | |
6745 | handles a query, or there is a serious error. Successful handling either | |
6746 | returns the requested data, or indicates that it does not exist. Serious errors | |
6747 | are syntactical, or multiple values when only a single value is expected. | |
6748 | Errors which cause the next server to be tried are connection failures, bind | |
6749 | failures, and timeouts. | |
6750 | ||
6751 | For each server name in the list, a port number can be given. The standard way | |
6752 | of specifing a host and port is to use a colon separator (RFC 1738). Because | |
6753 | %ldap_default_servers% is a colon-separated list, such colons have to be | |
6754 | doubled. For example | |
6755 | ||
6756 | ldap_default_servers = ldap1.example.com::145:ldap2.example.com | |
6757 | ||
6758 | If %ldap_default_servers% is unset, a URL with no server name is passed | |
6759 | to the LDAP library with no server name, and the library's default (normally | |
6760 | the local host) is used. | |
6761 | ||
6762 | If you are using the OpenLDAP library, you can connect to an LDAP server using | |
6763 | a Unix domain socket instead of a TCP/IP connection. This is specified by using | |
6764 | `ldapi` instead of `ldap` in LDAP queries. What follows here applies only | |
6765 | to OpenLDAP. If Exim is compiled with a different LDAP library, this feature is | |
6766 | not available. | |
6767 | ||
6768 | For this type of connection, instead of a host name for the server, a pathname | |
6769 | for the socket is required, and the port number is not relevant. The pathname | |
6770 | can be specified either as an item in %ldap_default_servers%, or inline in | |
6771 | the query. In the former case, you can have settings such as | |
6772 | ||
6773 | ldap_default_servers = /tmp/ldap.sock : backup.ldap.your.domain | |
6774 | ||
6775 | When the pathname is given in the query, you have to escape the slashes as | |
6776 | `%2F` to fit in with the LDAP URL syntax. For example: | |
6777 | ||
6778 | ${lookup ldap {ldapi://%2Ftmp%2Fldap.sock/o=... | |
6779 | ||
6780 | When Exim processes an LDAP lookup and finds that the ``hostname'' is really | |
6781 | a pathname, it uses the Unix domain socket code, even if the query actually | |
6782 | specifies `ldap` or `ldaps`. In particular, no encryption is used for a | |
6783 | socket connection. This behaviour means that you can use a setting of | |
6784 | %ldap_default_servers% such as in the example above with traditional `ldap` | |
6785 | or `ldaps` queries, and it will work. First, Exim tries a connection via | |
6786 | the Unix domain socket; if that fails, it tries a TCP/IP connection to the | |
6787 | backup host. | |
6788 | ||
6789 | If an explicit `ldapi` type is given in a query when a host name is | |
6790 | specified, an error is diagnosed. However, if there are more items in | |
6791 | %ldap_default_servers%, they are tried. In other words: | |
6792 | ||
6793 | - Using a pathname with `ldap` or `ldaps` forces the use of the Unix domain | |
6794 | interface. | |
6795 | ||
6796 | - Using `ldapi` with a host name causes an error. | |
6797 | ||
6798 | ||
6799 | Using `ldapi` with no host or path in the query, and no setting of | |
6800 | %ldap_default_servers%, does whatever the library does by default. | |
6801 | ||
6802 | ||
6803 | ||
6804 | LDAP authentication and control information | |
6805 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
6806 | cindex:[LDAP,authentication] | |
6807 | The LDAP URL syntax provides no way of passing authentication and other control | |
6808 | information to the server. To make this possible, the URL in an LDAP query may | |
6809 | be preceded by any number of ``<''name'>=<'value'>' settings, separated by | |
6810 | spaces. If a value contains spaces it must be enclosed in double quotes, and | |
6811 | when double quotes are used, backslash is interpreted in the usual way inside | |
6812 | them. The following names are recognized: | |
6813 | ||
6814 | &&& | |
6815 | `DEREFERENCE` set the dereferencing parameter | |
6816 | `NETTIME ` set a timeout for a network operation | |
6817 | `USER ` set the DN, for authenticating the LDAP bind | |
6818 | `PASS ` set the password, likewise | |
6819 | `SIZE ` set the limit for the number of entries returned | |
6820 | `TIME ` set the maximum waiting time for a query | |
6821 | &&& | |
6822 | ||
6823 | The value of the DEREFERENCE parameter must be one of the words ``never'', | |
6824 | ``searching'', ``finding'', or ``always''. | |
6825 | ||
6826 | The name CONNECT is an obsolete name for NETTIME, retained for | |
6827 | backwards compatibility. This timeout (specified as a number of seconds) is | |
6828 | enforced from the client end for operations that can be carried out over a | |
6829 | network. Specifically, it applies to network connections and calls to the | |
6830 | 'ldap_result()' function. If the value is greater than zero, it is used if | |
6831 | LDAP_OPT_NETWORK_TIMEOUT is defined in the LDAP headers (OpenLDAP), or | |
6832 | if LDAP_X_OPT_CONNECT_TIMEOUT is defined in the LDAP headers (Netscape | |
6833 | SDK 4.1). A value of zero forces an explicit setting of ``no timeout'' for | |
6834 | Netscape SDK; for OpenLDAP no action is taken. | |
6835 | ||
6836 | The TIME parameter (also a number of seconds) is passed to the server to | |
6837 | set a server-side limit on the time taken to complete a search. | |
6838 | ||
6839 | ||
6840 | Here is an example of an LDAP query in an Exim lookup that uses some of these | |
6841 | values. This is a single line, folded for ease of reading: | |
6842 | ||
6843 | ${lookup ldap | |
6844 | {user="cn=manager,o=University of Cambridge,c=UK" pass=secret | |
6845 | ldap:///o=University%20of%20Cambridge,c=UK?sn?sub?(cn=foo)} | |
6846 | {$value}fail} | |
6847 | ||
6848 | The encoding of spaces as {pc}20 is a URL thing which should not be done for any | |
6849 | of the auxiliary data. Exim configuration settings that include lookups which | |
6850 | contain password information should be preceded by ``hide'' to prevent non-admin | |
6851 | users from using the %-bP% option to see their values. | |
6852 | ||
6853 | The auxiliary data items may be given in any order. The default is no | |
6854 | connection timeout (the system timeout is used), no user or password, no limit | |
6855 | on the number of entries returned, and no time limit on queries. | |
6856 | ||
6857 | When a DN is quoted in the USER= setting for LDAP authentication, Exim | |
6858 | removes any URL quoting that it may contain before passing it LDAP. Apparently | |
6859 | some libraries do this for themselves, but some do not. Removing the URL | |
6860 | quoting has two advantages: | |
6861 | ||
6862 | - It makes it possible to use the same %quote_ldap_dn% expansion for USER= | |
6863 | DNs as with DNs inside actual queries. | |
6864 | ||
6865 | - It permits spaces inside USER= DNs. | |
6866 | ||
6867 | For example, a setting such as | |
6868 | ||
6869 | USER=cn=${quote_ldap_dn:$1} | |
6870 | ||
6871 | should work even if $1$ contains spaces. | |
6872 | ||
6873 | Expanded data for the PASS= value should be quoted using the %quote% | |
6874 | expansion operator, rather than the LDAP quote operators. The only reason this | |
6875 | field needs quoting is to ensure that it conforms to the Exim syntax, which | |
6876 | does not allow unquoted spaces. For example: | |
6877 | ||
6878 | PASS=${quote:$3} | |
6879 | ||
6880 | ||
6881 | The LDAP authentication mechanism can be used to check passwords as part of | |
6882 | SMTP authentication. See the %ldapauth% expansion string condition in chapter | |
6883 | <<CHAPexpand>>. | |
6884 | ||
6885 | ||
6886 | ||
6887 | Format of data returned by LDAP | |
6888 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
6889 | cindex:[LDAP,returned data formats] | |
6890 | The ^ldapdn^ lookup type returns the Distinguished Name from a single entry as | |
6891 | a sequence of values, for example | |
6892 | ||
6893 | cn=manager, o=University of Cambridge, c=UK | |
6894 | ||
6895 | ||
6896 | The ^ldap^ lookup type generates an error if more than one entry matches the | |
6897 | search filter, whereas ^ldapm^ permits this case, and inserts a newline in | |
6898 | the result between the data from different entries. It is possible for multiple | |
6899 | values to be returned for both ^ldap^ and ^ldapm^, but in the former case | |
6900 | you know that whatever values are returned all came from a single entry in the | |
6901 | directory. | |
6902 | ||
6903 | In the common case where you specify a single attribute in your LDAP query, the | |
6904 | result is not quoted, and does not contain the attribute name. If the attribute | |
6905 | has multiple values, they are separated by commas. | |
6906 | ||
6907 | If you specify multiple attributes, the result contains space-separated, quoted | |
6908 | strings, each preceded by the attribute name and an equals sign. Within the | |
6909 | quotes, the quote character, backslash, and newline are escaped with | |
6910 | backslashes, and commas are used to separate multiple values for the attribute. | |
6911 | Apart from the escaping, the string within quotes takes the same form as the | |
6912 | output when a single attribute is requested. Specifying no attributes is the | |
6913 | same as specifying all of an entry's attributes. | |
6914 | ||
6915 | Here are some examples of the output format. The first line of each pair is an | |
6916 | LDAP query, and the second is the data that is returned. The attribute called | |
6917 | %attr1% has two values, whereas %attr2% has only one value: | |
6918 | ||
6919 | ldap:///o=base?attr1?sub?(uid=fred) | |
6920 | value1.1, value1.2 | |
6921 | ||
6922 | ldap:///o=base?attr2?sub?(uid=fred) | |
6923 | value two | |
6924 | ||
6925 | ldap:///o=base?attr1,attr2?sub?(uid=fred) | |
6926 | attr1="value1.1, value1.2" attr2="value two" | |
6927 | ||
6928 | ldap:///o=base??sub?(uid=fred) | |
6929 | objectClass="top" attr1="value1.1, value1.2" attr2="value two" | |
6930 | ||
6931 | The %extract% operator in string expansions can be used to pick out individual | |
6932 | fields from data that consists of 'key'='value' pairs. You can make use | |
6933 | of Exim's %-be% option to run expansion tests and thereby check the results of | |
6934 | LDAP lookups. | |
6935 | ||
6936 | ||
6937 | ||
6938 | ||
6939 | [[SECTnisplus]] | |
6940 | More about NIS+ | |
6941 | ~~~~~~~~~~~~~~~ | |
6942 | cindex:[NIS+ lookup type] | |
6943 | cindex:[lookup,NIS+] | |
6944 | NIS+ queries consist of a NIS+ 'indexed name' followed by an optional colon | |
6945 | and field name. If this is given, the result of a successful query is the | |
6946 | contents of the named field; otherwise the result consists of a concatenation | |
6947 | of 'field-name=field-value' pairs, separated by spaces. Empty values and | |
6948 | values containing spaces are quoted. For example, the query | |
6949 | ||
6950 | [name=mg1456],passwd.org_dir | |
6951 | ||
6952 | might return the string | |
6953 | ||
6954 | name=mg1456 passwd="" uid=999 gid=999 gcos="Martin Guerre" | |
6955 | home=/home/mg1456 shell=/bin/bash shadow="" | |
6956 | ||
6957 | (split over two lines here to fit on the page), whereas | |
6958 | ||
6959 | [name=mg1456],passwd.org_dir:gcos | |
6960 | ||
6961 | would just return | |
6962 | ||
6963 | Martin Guerre | |
6964 | ||
6965 | with no quotes. A NIS+ lookup fails if NIS+ returns more than one table entry | |
6966 | for the given indexed key. The effect of the %quote_nisplus% expansion | |
6967 | operator is to double any quote characters within the text. | |
6968 | ||
6969 | ||
6970 | ||
6971 | [[SECTsql]] | |
068aaea8 PH |
6972 | SQL lookups |
6973 | ~~~~~~~~~~~ | |
6974 | [revisionflag="changed"] | |
6975 | cindex:[SQL lookup types] | |
6976 | Exim can support lookups in Interbase, MySQL, Oracle, PostgreSQL, and SQLite | |
6977 | databases. Queries for these databases contain SQL statements, so an example | |
6978 | might be | |
6979 | ||
6980 | .... | |
6981 | ${lookup mysql{select mailbox from users where id='userx'}\ | |
6982 | {$value}fail} | |
6983 | .... | |
6984 | ||
6985 | If the result of the query contains more than one field, the data for each | |
6986 | field in the row is returned, preceded by its name, so the result of | |
6987 | ||
6988 | .... | |
6989 | ${lookup pgsql{select home,name from users where id='userx'}\ | |
6990 | {$value}} | |
6991 | .... | |
6992 | ||
6993 | might be | |
6994 | ||
6995 | home=/home/userx name="Mister X" | |
6996 | ||
6997 | Empty values and values containing spaces are double quoted, with embedded | |
6998 | quotes escaped by a backslash. If the result of the query contains just one | |
6999 | field, the value is passed back verbatim, without a field name, for example: | |
7000 | ||
7001 | Mister X | |
7002 | ||
7003 | If the result of the query yields more than one row, it is all concatenated, | |
7004 | with a newline between the data for each row. | |
7005 | ||
7006 | ||
168e428f PH |
7007 | More about MySQL, PostgreSQL, Oracle, and Interbase |
7008 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
7009 | cindex:[MySQL,lookup type] | |
7010 | cindex:[PostgreSQL lookup type] | |
7011 | cindex:[lookup,MySQL] | |
7012 | cindex:[lookup,PostgreSQL] | |
7013 | cindex:[Oracle,lookup type] | |
7014 | cindex:[lookup,Oracle] | |
7015 | cindex:[Interbase lookup type] | |
7016 | cindex:[lookup,Interbase] | |
7017 | If any MySQL, PostgreSQL, Oracle, or Interbase lookups are used, the | |
068aaea8 PH |
7018 | %mysql_servers%, %pgsql_servers%, %oracle_servers%, or %ibase_servers% option |
7019 | (as appropriate) must be set to a colon-separated list of server information. | |
7020 | Each item in the list is a slash-separated list of four items: host name, | |
7021 | database name, user name, and password. In the case of Oracle, the host name | |
7022 | field is used for the ``service name'', and the database name field is not used | |
7023 | and should be empty. For example: | |
168e428f | 7024 | |
068aaea8 | 7025 | hide oracle_servers = oracle.plc.example//userx/abcdwxyz |
168e428f PH |
7026 | |
7027 | Because password data is sensitive, you should always precede the setting with | |
7028 | ``hide'', to prevent non-admin users from obtaining the setting via the %-bP% | |
7029 | option. Here is an example where two MySQL servers are listed: | |
7030 | ||
7031 | .... | |
7032 | hide mysql_servers = localhost/users/root/secret:\ | |
7033 | otherhost/users/root/othersecret | |
7034 | .... | |
7035 | ||
7036 | For MySQL and PostgreSQL, a host may be specified as <'name'>:<'port'> but | |
068aaea8 PH |
7037 | because this is a colon-separated list, the colon has to be doubled. For each |
7038 | query, these parameter groups are tried in order until a connection and a query | |
7039 | succeeds. | |
168e428f PH |
7040 | |
7041 | The %quote_mysql%, %quote_pgsql%, and %quote_oracle% expansion operators | |
7042 | convert newline, tab, carriage return, and backspace to \n, \t, \r, and \b | |
7043 | respectively, and the characters single-quote, double-quote, and backslash | |
7044 | itself are escaped with backslashes. The %quote_pgsql% expansion operator, in | |
7045 | addition, escapes the percent and underscore characters. This cannot be done | |
7046 | for MySQL because these escapes are not recognized in contexts where these | |
7047 | characters are not special. | |
7048 | ||
7049 | ||
168e428f PH |
7050 | Special MySQL features |
7051 | ~~~~~~~~~~~~~~~~~~~~~~ | |
7052 | For MySQL, an empty host name or the use of ``localhost'' in %mysql_servers% | |
7053 | causes a connection to the server on the local host by means of a Unix domain | |
7054 | socket. An alternate socket can be specified in parentheses. The full syntax of | |
7055 | each item in %mysql_servers% is: | |
7056 | ||
7057 | &&& | |
7058 | <'hostname'>::<'port'>(<'socket name'>)/<'database'>/<'user'>/<'password'> | |
7059 | &&& | |
7060 | ||
7061 | Any of the three sub-parts of the first field can be omitted. For normal use on | |
7062 | the local host it can be left blank or set to just ``localhost''. | |
7063 | ||
7064 | No database need be supplied -- but if it is absent here, it must be given in | |
7065 | the queries. | |
7066 | ||
7067 | If a MySQL query is issued that does not request any data (an insert, update, | |
7068 | or delete command), the result of the lookup is the number of rows affected. | |
7069 | ||
7070 | *Warning*: this can be misleading. If an update does not actually change | |
7071 | anything (for example, setting a field to the value it already has), the result | |
7072 | is zero because no rows are affected. | |
7073 | ||
7074 | ||
168e428f PH |
7075 | Special PostgreSQL features |
7076 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
7077 | PostgreSQL lookups can also use Unix domain socket connections to the database. | |
7078 | This is usually faster and costs less CPU time than a TCP/IP connection. | |
7079 | However it can be used only if the mail server runs on the same machine as the | |
7080 | database server. A configuration line for PostgreSQL via Unix domain sockets | |
7081 | looks like this: | |
7082 | ||
7083 | hide pgsql_servers = (/tmp/.s.PGSQL.5432)/db/user/password : ... | |
7084 | ||
7085 | In other words, instead of supplying a host name, a path to the socket is | |
7086 | given. The path name is enclosed in parentheses so that its slashes aren't | |
7087 | visually confused with the delimiters for the other server parameters. | |
7088 | ||
7089 | If a PostgreSQL query is issued that does not request any data (an insert, | |
7090 | update, or delete command), the result of the lookup is the number of rows | |
7091 | affected. | |
7092 | ||
068aaea8 PH |
7093 | [[SECTsqlite]] |
7094 | More about SQLite | |
7095 | ~~~~~~~~~~~~~~~~~ | |
7096 | [revisionflag="changed"] | |
7097 | cindex:[lookup,SQLite] | |
7098 | cindex:[SQLite lookup type] | |
7099 | SQLite is different to the other SQL lookups because a file name is required in | |
7100 | addition to the SQL query. An SQLite database is a single file, and there is no | |
7101 | daemon as in the other SQL databases. The interface to Exim requires the name | |
7102 | of the file, as an absolute path, to be given at the start of the query. It is | |
7103 | separated from the query by white space. This means that the path name cannot | |
7104 | contain white space. Here is a lookup expansion example: | |
7105 | ||
7106 | .... | |
7107 | ${lookup sqlite {/some/thing/sqlitedb \ | |
7108 | select name from aliases where id='userx';}} | |
7109 | .... | |
7110 | ||
7111 | [revisionflag="changed"] | |
7112 | In a list, the syntax is similar. For example: | |
7113 | ||
7114 | .... | |
7115 | domainlist relay_domains = sqlite;/some/thing/sqlitedb \ | |
7116 | select * from relays where ip='$sender_host_address'; | |
7117 | .... | |
7118 | ||
7119 | [revisionflag="changed"] | |
7120 | The only character affected by the %quote_sqlite% operator is a single | |
7121 | quote, which it doubles. | |
7122 | ||
7123 | [revisionflag="changed"] | |
7124 | The SQLite library handles multiple simultaneous accesses to the database | |
7125 | internally. Multiple readers are permitted, but only one process can | |
7126 | update at once. Attempts to access the database while it is being updated | |
7127 | are rejected after a timeout period, during which the SQLite library | |
7128 | waits for the lock to be released. In Exim, the default timeout is set | |
7129 | to 5 seconds, but it can be changed by means of the %sqlite_lock_timeout% | |
7130 | option. | |
168e428f PH |
7131 | |
7132 | ||
7133 | ||
7134 | //////////////////////////////////////////////////////////////////////////// | |
7135 | //////////////////////////////////////////////////////////////////////////// | |
7136 | ||
7137 | [[CHAPdomhosaddlists]] | |
7138 | [titleabbrev="Domain, host, and address lists"] | |
7139 | Domain, host, address, and local part lists | |
7140 | ------------------------------------------- | |
7141 | cindex:[list of domains; hosts; etc.] | |
7142 | A number of Exim configuration options contain lists of domains, hosts, | |
7143 | email addresses, or local parts. For example, the %hold_domains% option | |
7144 | contains a list of domains whose delivery is currently suspended. These lists | |
068aaea8 PH |
7145 | are also used as data in ACL statements (see chapter <<CHAPACL>>), and as |
7146 | arguments to expansion conditions such as %match_domain%. | |
168e428f PH |
7147 | |
7148 | Each item in one of these lists is a pattern to be matched against a domain, | |
7149 | host, email address, or local part, respectively. In the sections below, the | |
7150 | different types of pattern for each case are described, but first we cover some | |
7151 | general facilities that apply to all four kinds of list. | |
7152 | ||
7153 | ||
7154 | ||
7155 | Expansion of lists | |
7156 | ~~~~~~~~~~~~~~~~~~ | |
7157 | cindex:[expansion,of lists] | |
7158 | Each list is expanded as a single string before it is used. The result of | |
7159 | expansion must be a list, possibly containing empty items, which is split up | |
7160 | into separate items for matching. By default, colon is the separator character, | |
7161 | but this can be varied if necessary. See sections <<SECTlistconstruct>> and | |
7162 | <<SECTempitelis>> for details of the list syntax; the second of these discusses | |
068aaea8 | 7163 | the way to specify empty list items. |
168e428f PH |
7164 | |
7165 | ||
7166 | If the string expansion is forced to fail, Exim behaves as if the item it is | |
7167 | testing (domain, host, address, or local part) is not in the list. Other | |
7168 | expansion failures cause temporary errors. | |
7169 | ||
7170 | If an item in a list is a regular expression, backslashes, dollars and possibly | |
7171 | other special characters in the expression must be protected against | |
7172 | misinterpretation by the string expander. The easiest way to do this is to use | |
7173 | the `\N` expansion feature to indicate that the contents of the regular | |
7174 | expression should not be expanded. For example, in an ACL you might have: | |
7175 | ||
7176 | .... | |
7177 | deny senders = \N^\d{8}\w@.*\.baddomain\.example$\N : \ | |
7178 | ${lookup{$domain}lsearch{/badsenders/bydomain}} | |
7179 | .... | |
7180 | ||
7181 | The first item is a regular expression that is protected from expansion by | |
7182 | `\N`, whereas the second uses the expansion to obtain a list of unwanted | |
7183 | senders based on the receiving domain. | |
7184 | ||
7185 | ||
7186 | ||
7187 | ||
7188 | Negated items in lists | |
7189 | ~~~~~~~~~~~~~~~~~~~~~~ | |
7190 | cindex:[list,negation] | |
7191 | cindex:[negation in lists] | |
7192 | Items in a list may be positive or negative. Negative items are indicated by a | |
7193 | leading exclamation mark, which may be followed by optional white space. A list | |
7194 | defines a set of items (domains, etc). When Exim processes one of these lists, | |
7195 | it is trying to find out whether a domain, host, address, or local part | |
7196 | (respectively) is in the set that is defined by the list. It works like this: | |
7197 | ||
7198 | The list is scanned from left to right. If a positive item is matched, the | |
7199 | subject that is being checked is in the set; if a negative item is matched, the | |
7200 | subject is not in the set. If the end of the list is reached without the | |
7201 | subject having matched any of the patterns, it is in the set if the last item | |
7202 | was a negative one, but not if it was a positive one. For example, the list in | |
7203 | ||
7204 | domainlist relay_domains = !a.b.c : *.b.c | |
7205 | ||
7206 | matches any domain ending in '.b.c' except for 'a.b.c'. Domains that match | |
7207 | neither 'a.b.c' nor '*.b.c' do not match, because the last item in the | |
7208 | list is positive. However, if the setting were | |
7209 | ||
7210 | domainlist relay_domains = !a.b.c | |
7211 | ||
7212 | then all domains other than 'a.b.c' would match because the last item in the | |
7213 | list is negative. In other words, a list that ends with a negative item behaves | |
7214 | as if it had an extra item `:*` on the end. | |
7215 | ||
7216 | Another way of thinking about positive and negative items in lists is to read | |
7217 | the connector as ``or'' after a positive item and as ``and'' after a negative | |
7218 | item. | |
7219 | ||
7220 | ||
7221 | ||
7222 | [[SECTfilnamlis]] | |
7223 | File names in lists | |
7224 | ~~~~~~~~~~~~~~~~~~~ | |
7225 | cindex:[list,file name in] | |
7226 | If an item in a domain, host, address, or local part list is an absolute file | |
7227 | name (beginning with a slash character), each line of the file is read and | |
7228 | processed as if it were an independent item in the list, except that further | |
7229 | file names are not allowed, | |
7230 | and no expansion of the data from the file takes place. | |
7231 | Empty lines in the file are ignored, and the file may also contain comment | |
7232 | lines: | |
7233 | ||
7234 | - For domain and host lists, if a # character appears anywhere in a line of the | |
7235 | file, it and all following characters are ignored. | |
7236 | ||
7237 | - Because local parts may legitimately contain # characters, a comment in an | |
7238 | address list or local part list file is recognized only if # is preceded by | |
7239 | white space or the start of the line. For example: | |
7240 | ||
7241 | not#comment@x.y.z # but this is a comment | |
7242 | ||
7243 | Putting a file name in a list has the same effect as inserting each line of the | |
7244 | file as an item in the list (blank lines and comments excepted). However, there | |
7245 | is one important difference: the file is read each time the list is processed, | |
7246 | so if its contents vary over time, Exim's behaviour changes. | |
7247 | ||
7248 | If a file name is preceded by an exclamation mark, the sense of any match | |
7249 | within the file is inverted. For example, if | |
7250 | ||
7251 | hold_domains = !/etc/nohold-domains | |
7252 | ||
7253 | and the file contains the lines | |
7254 | ||
7255 | !a.b.c | |
7256 | *.b.c | |
7257 | ||
7258 | then 'a.b.c' is in the set of domains defined by %hold_domains%, whereas any | |
7259 | domain matching `*.b.c` is not. | |
7260 | ||
7261 | ||
7262 | ||
7263 | An lsearch file is not an out-of-line list | |
7264 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
7265 | As will be described in the sections that follow, lookups can be used in lists | |
7266 | to provide indexed methods of checking list membership. There has been some | |
7267 | confusion about the way ^lsearch^ lookups work in lists. Because | |
7268 | an ^lsearch^ file contains plain text and is scanned sequentially, it is | |
7269 | sometimes thought that it is allowed to contain wild cards and other kinds of | |
7270 | non-constant pattern. This is not the case. The keys in an ^lsearch^ file are | |
7271 | always fixed strings, just as for any other single-key lookup type. | |
7272 | ||
7273 | If you want to use a file to contain wild-card patterns that form part of a | |
7274 | list, just give the file name on its own, without a search type, as described | |
7275 | in the previous section. | |
7276 | ||
7277 | ||
7278 | ||
7279 | ||
7280 | [[SECTnamedlists]] | |
7281 | Named lists | |
7282 | ~~~~~~~~~~~ | |
7283 | cindex:[named lists] | |
7284 | cindex:[list,named] | |
7285 | A list of domains, hosts, email addresses, or local parts can be given a name | |
7286 | which is then used to refer to the list elsewhere in the configuration. This is | |
7287 | particularly convenient if the same list is required in several different | |
7288 | places. It also allows lists to be given meaningful names, which can improve | |
7289 | the readability of the configuration. For example, it is conventional to define | |
7290 | a domain list called 'local_domains' for all the domains that are handled | |
7291 | locally on a host, using a configuration line such as | |
7292 | ||
7293 | domainlist local_domains = localhost:my.dom.example | |
7294 | ||
7295 | Named lists are referenced by giving their name preceded by a plus sign, so, | |
7296 | for example, a router that is intended to handle local domains would be | |
7297 | configured with the line | |
7298 | ||
7299 | domains = +local_domains | |
7300 | ||
7301 | The first router in a configuration is often one that handles all domains | |
7302 | except the local ones, using a configuration with a negated item like this: | |
7303 | ||
7304 | dnslookup: | |
7305 | driver = dnslookup | |
7306 | domains = ! +local_domains | |
7307 | transport = remote_smtp | |
7308 | no_more | |
7309 | ||
7310 | The four kinds of named list are created by configuration lines starting with | |
7311 | the words %domainlist%, %hostlist%, %addresslist%, or %localpartlist%, | |
7312 | respectively. Then there follows the name that you are defining, followed by an | |
7313 | equals sign and the list itself. For example: | |
7314 | ||
7315 | hostlist relay_hosts = 192.168.23.0/24 : my.friend.example | |
7316 | addresslist bad_senders = cdb;/etc/badsenders | |
7317 | ||
7318 | A named list may refer to other named lists: | |
7319 | ||
7320 | domainlist dom1 = first.example : second.example | |
7321 | domainlist dom2 = +dom1 : third.example | |
7322 | domainlist dom3 = fourth.example : +dom2 : fifth.example | |
7323 | ||
7324 | ||
7325 | *Warning*: If the last item in a referenced list is a negative one, the | |
7326 | effect may not be what you intended, because the negation does not propagate | |
7327 | out to the higher level. For example, consider: | |
7328 | ||
7329 | domainlist dom1 = !a.b | |
7330 | domainlist dom2 = +dom1 : *.b | |
7331 | ||
7332 | The second list specifies ``either in the %dom1% list or '*.b'##''. The first | |
7333 | list specifies just ``not 'a.b'##'', so the domain 'x.y' matches it. That means | |
7334 | it matches the second list as well. The effect is not the same as | |
7335 | ||
7336 | domainlist dom2 = !a.b : *.b | |
7337 | ||
7338 | where 'x.y' does not match. It's best to avoid negation altogether in | |
7339 | referenced lists if you can. | |
7340 | ||
7341 | Named lists may have a performance advantage. When Exim is routing an | |
7342 | address or checking an incoming message, it caches the result of tests on named | |
7343 | lists. So, if you have a setting such as | |
7344 | ||
7345 | domains = +local_domains | |
7346 | ||
7347 | on several of your routers | |
7348 | or in several ACL statements, | |
7349 | the actual test is done only for the first one. However, the caching works only | |
7350 | if there are no expansions within the list itself or any sublists that it | |
7351 | references. In other words, caching happens only for lists that are known to be | |
7352 | the same each time they are referenced. | |
7353 | ||
7354 | By default, there may be up to 16 named lists of each type. This limit can be | |
7355 | extended by changing a compile-time variable. The use of domain and host lists | |
7356 | is recommended for concepts such as local domains, relay domains, and relay | |
7357 | hosts. The default configuration is set up like this. | |
7358 | ||
7359 | ||
7360 | ||
7361 | Named lists compared with macros | |
7362 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
7363 | cindex:[list,named compared with macro] | |
7364 | cindex:[macro,compared with named list] | |
7365 | At first sight, named lists might seem to be no different from macros in the | |
7366 | configuration file. However, macros are just textual substitutions. If you | |
7367 | write | |
7368 | ||
7369 | ALIST = host1 : host2 | |
7370 | auth_advertise_hosts = !ALIST | |
7371 | ||
7372 | it probably won't do what you want, because that is exactly the same as | |
7373 | ||
7374 | auth_advertise_hosts = !host1 : host2 | |
7375 | ||
7376 | Notice that the second host name is not negated. However, if you use a host | |
7377 | list, and write | |
7378 | ||
7379 | hostlist alist = host1 : host2 | |
7380 | auth_advertise_hosts = ! +alist | |
7381 | ||
7382 | the negation applies to the whole list, and so that is equivalent to | |
7383 | ||
7384 | auth_advertise_hosts = !host1 : !host2 | |
7385 | ||
7386 | ||
7387 | ||
7388 | ||
7389 | Named list caching | |
7390 | ~~~~~~~~~~~~~~~~~~ | |
7391 | cindex:[list,caching of named] | |
7392 | cindex:[caching,named lists] | |
7393 | While processing a message, Exim caches the result of checking a named list if | |
7394 | it is sure that the list is the same each time. In practice, this means that | |
7395 | the cache operates only if the list contains no \$ characters, which guarantees | |
7396 | that it will not change when it is expanded. Sometimes, however, you may have | |
7397 | an expanded list that you know will be the same each time within a given | |
7398 | message. For example: | |
7399 | ||
7400 | .... | |
7401 | domainlist special_domains = \ | |
7402 | ${lookup{$sender_host_address}cdb{/some/file}} | |
7403 | .... | |
7404 | ||
7405 | This provides a list of domains that depends only on the sending host's IP | |
7406 | address. If this domain list is referenced a number of times (for example, | |
7407 | in several ACL lines, or in several routers) the result of the check is not | |
7408 | cached by default, because Exim does not know that it is going to be the | |
7409 | same list each time. | |
7410 | ||
7411 | By appending `_cache` to `domainlist` you can tell Exim to go ahead and | |
7412 | cache the result anyway. For example: | |
7413 | ||
7414 | domainlist_cache special_domains = ${lookup{... | |
7415 | ||
7416 | If you do this, you should be absolutely sure that caching is going to do | |
7417 | the right thing in all cases. When in doubt, leave it out. | |
7418 | ||
7419 | ||
7420 | ||
7421 | [[SECTdomainlist]] | |
7422 | Domain lists | |
7423 | ~~~~~~~~~~~~ | |
7424 | cindex:[domain list,patterns for] | |
7425 | cindex:[list,domain list] | |
7426 | Domain lists contain patterns that are to be matched against a mail domain. | |
7427 | The following types of item may appear in domain lists: | |
7428 | ||
7429 | - cindex:[primary host name] | |
7430 | cindex:[host name, matched in domain list] | |
7431 | cindex:[%primary_hostname%] | |
7432 | cindex:[domain list,matching primary host name] | |
7433 | cindex:[@ in a domain list] | |
7434 | If a pattern consists of a single @ character, it matches the local host name, | |
7435 | as set by the %primary_hostname% option (or defaulted). This makes it possible | |
7436 | to use the same configuration file on several different hosts that differ only | |
7437 | in their names. | |
7438 | ||
7439 | - cindex:[@{bk} in a domain list] | |
7440 | cindex:[domain list,matching local IP interfaces] | |
7441 | cindex:[domain literal] | |
7442 | If a pattern consists of the string `@[]` it matches any local IP interface | |
7443 | address, enclosed in square brackets, as in an email address that contains a | |
7444 | domain literal. | |
7445 | In today's Internet, the use of domain literals is controversial. | |
7446 | ||
7447 | - cindex:[@mx_any] | |
7448 | cindex:[@mx_primary] | |
7449 | cindex:[@mx_secondary] | |
7450 | cindex:[domain list,matching MX pointers to local host] | |
7451 | If a pattern consists of the string `@mx_any` it matches any domain that | |
7452 | has an MX record pointing to the local host or to any host that is listed in | |
7453 | cindex:[%hosts_treat_as_local%] | |
7454 | %hosts_treat_as_local%. The items `@mx_primary` and `@mx_secondary` | |
7455 | are similar, except that the first matches only when a primary MX target is the | |
7456 | local host, and the second only when no primary MX target is the local host, | |
7457 | but a secondary MX target is. ``Primary'' means an MX record with the lowest | |
7458 | preference value -- there may of course be more than one of them. | |
7459 | + | |
7460 | The MX lookup that takes place when matching a pattern of this type is | |
7461 | performed with the resolver options for widening names turned off. Thus, for | |
7462 | example, a single-component domain will 'not' be expanded by adding the | |
7463 | resolver's default domain. See the %qualify_single% and %search_parents% | |
7464 | options of the ^dnslookup^ router for a discussion of domain widening. | |
7465 | + | |
7466 | Sometimes you may want to ignore certain IP addresses when using one of these | |
7467 | patterns. You can specify this by following the pattern with `/ignore=`<'ip | |
7468 | list'>, where <'ip list'> is a list of IP addresses. These addresses are | |
7469 | ignored when processing the pattern (compare the %ignore_target_hosts% option | |
7470 | on a router). For example: | |
7471 | ||
7472 | domains = @mx_any/ignore=127.0.0.1 | |
7473 | + | |
7474 | This example matches any domain that has an MX record pointing to one of | |
7475 | the local host's IP addresses other than 127.0.0.1. | |
7476 | + | |
7477 | The list of IP addresses is in fact processed by the same code that processes | |
7478 | host lists, so it may contain CIDR-coded network specifications and it may also | |
7479 | contain negative items. | |
7480 | + | |
7481 | Because the list of IP addresses is a sublist within a domain list, you have to | |
7482 | be careful about delimiters if there is more than one address. Like any other | |
7483 | list, the default delimiter can be changed. Thus, you might have: | |
7484 | + | |
7485 | .... | |
7486 | domains = @mx_any/ignore=<;127.0.0.1;0.0.0.0 : \ | |
7487 | an.other.domain : ... | |
7488 | .... | |
7489 | + | |
7490 | so that the sublist uses semicolons for delimiters. When IPv6 addresses are | |
7491 | involved, it is easiest to change the delimiter for the main list as well: | |
7492 | + | |
7493 | .... | |
7494 | domains = <? @mx_any/ignore=<;127.0.0.1;::1 ? \ | |
7495 | an.other.domain ? ... | |
7496 | .... | |
7497 | ||
7498 | - cindex:[asterisk,in domain list] | |
7499 | cindex:[domain list,asterisk in] | |
7500 | cindex:[domain list,matching ``ends with''] | |
7501 | If a pattern starts with an asterisk, the remaining characters of the pattern | |
7502 | are compared with the terminating characters of the domain. The use of ``\*'' in | |
7503 | domain lists differs from its use in partial matching lookups. In a domain | |
7504 | list, the character following the asterisk need not be a dot, whereas partial | |
7505 | matching works only in terms of dot-separated components. For example, a domain | |
7506 | list item such as `*key.ex` matches 'donkey.ex' as well as | |
7507 | 'cipher.key.ex'. | |
7508 | ||
7509 | - cindex:[regular expressions,in domain list] | |
7510 | cindex:[domain list,matching regular expression] | |
7511 | If a pattern starts with a circumflex character, it is treated as a regular | |
7512 | expression, and matched against the domain using a regular expression matching | |
7513 | function. The circumflex is treated as part of the regular expression. | |
7514 | References to descriptions of the syntax of regular expressions are given in | |
7515 | chapter <<CHAPregexp>>. | |
7516 | + | |
7517 | *Warning*: Because domain lists are expanded before being processed, you | |
7518 | must escape any backslash and dollar characters in the regular expression, or | |
7519 | use the special `\N` sequence (see chapter <<CHAPexpand>>) to specify that it | |
7520 | is not to be expanded (unless you really do want to build a regular expression | |
7521 | by expansion, of course). | |
7522 | ||
7523 | - cindex:[lookup,in domain list] | |
7524 | cindex:[domain list,matching by lookup] | |
7525 | If a pattern starts with the name of a single-key lookup type followed by a | |
7526 | semicolon (for example, ``dbm;'' or ``lsearch;''), the remainder of the pattern | |
7527 | must be a file name in a suitable format for the lookup type. For example, for | |
7528 | ``cdb;'' it must be an absolute path: | |
7529 | ||
7530 | domains = cdb;/etc/mail/local_domains.cdb | |
7531 | + | |
7532 | The appropriate type of lookup is done on the file using the domain name as the | |
7533 | key. In most cases, the data that is looked up is not used; Exim is interested | |
7534 | only in whether or not the key is present in the file. However, when a lookup | |
7535 | is used for the %domains% option on a router | |
7536 | or a %domains% condition in an ACL statement, the data is preserved in the | |
7537 | $domain_data$ variable and can be referred to in other router options or | |
7538 | other statements in the same ACL. | |
7539 | ||
7540 | - Any of the single-key lookup type names may be preceded by ``partial<''n'>-', | |
7541 | where the <'n'> is optional, for example, | |
7542 | ||
7543 | domains = partial-dbm;/partial/domains | |
7544 | + | |
7545 | This causes partial matching logic to be invoked; a description of how this | |
7546 | works is given in section <<SECTpartiallookup>>. | |
7547 | ||
7548 | - cindex:[asterisk,in lookup type] | |
7549 | Any of the single-key lookup types may be followed by an asterisk. This causes | |
7550 | a default lookup for a key consisting of a single asterisk to be done if the | |
7551 | original lookup fails. This is not a useful feature when using a domain list to | |
7552 | select particular domains (because any domain would match), but it might have | |
7553 | value if the result of the lookup is being used via the $domain_data$ | |
7554 | expansion variable. | |
7555 | ||
7556 | - If the pattern starts with the name of a query-style lookup type followed by a | |
7557 | semicolon (for example, ``nisplus;'' or ``ldap;''), the remainder of the pattern | |
7558 | must be an appropriate query for the lookup type, as described in chapter | |
7559 | <<CHAPfdlookup>>. For example: | |
7560 | + | |
7561 | .... | |
7562 | hold_domains = mysql;select domain from holdlist \ | |
7563 | where domain = '$domain'; | |
7564 | .... | |
7565 | + | |
7566 | In most cases, the data that is looked up is not used (so for an SQL query, for | |
7567 | example, it doesn't matter what field you select). Exim is interested only in | |
7568 | whether or not the query succeeds. However, when a lookup is used for the | |
7569 | %domains% option on a router, the data is preserved in the $domain_data$ | |
7570 | variable and can be referred to in other options. | |
7571 | ||
7572 | - cindex:[domain list,matching literal domain name] | |
7573 | If none of the above cases apply, a caseless textual comparison is made | |
7574 | between the pattern and the domain. | |
7575 | ||
7576 | ||
7577 | Here is an example that uses several different kinds of pattern: | |
7578 | ||
7579 | .... | |
7580 | domainlist funny_domains = \ | |
7581 | @ : \ | |
7582 | lib.unseen.edu : \ | |
7583 | *.foundation.fict.example : \ | |
7584 | \N^[1-2]\d{3}\.fict\.example$\N : \ | |
7585 | partial-dbm;/opt/data/penguin/book : \ | |
7586 | nis;domains.byname : \ | |
7587 | nisplus;[name=$domain,status=local],domains.org_dir | |
7588 | .... | |
7589 | ||
7590 | There are obvious processing trade-offs among the various matching modes. Using | |
7591 | an asterisk is faster than a regular expression, and listing a few names | |
7592 | explicitly probably is too. The use of a file or database lookup is expensive, | |
7593 | but may be the only option if hundreds of names are required. Because the | |
7594 | patterns are tested in order, it makes sense to put the most commonly matched | |
7595 | patterns earlier. | |
7596 | ||
7597 | ||
7598 | ||
7599 | [[SECThostlist]] | |
7600 | Host lists | |
7601 | ~~~~~~~~~~ | |
7602 | cindex:[host list,patterns in] | |
7603 | cindex:[list,host list] | |
7604 | Host lists are used to control what remote hosts are allowed to do. For | |
7605 | example, some hosts may be allowed to use the local host as a relay, and some | |
7606 | may be permitted to use the SMTP ETRN command. Hosts can be identified in | |
7607 | two different ways, by name or by IP address. In a host list, some types of | |
7608 | pattern are matched to a host name, and some are matched to an IP address. | |
7609 | You need to be particularly careful with this when single-key lookups are | |
7610 | involved, to ensure that the right value is being used as the key. | |
7611 | ||
7612 | ||
7613 | Special host list patterns | |
7614 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
7615 | cindex:[empty item in hosts list] | |
7616 | cindex:[host list,empty string in] | |
7617 | If a host list item is the empty string, it matches only when no remote host is | |
7618 | involved. This is the case when a message is being received from a local | |
7619 | process using SMTP on the standard input, that is, when a TCP/IP connection is | |
7620 | not used. | |
7621 | ||
7622 | cindex:[asterisk,in host list] | |
7623 | The special pattern ``\*'' in a host list matches any host or no host. Neither | |
7624 | the IP address nor the name is actually inspected. | |
7625 | ||
7626 | ||
7627 | ||
7628 | [[SECThoslispatip]] | |
7629 | Host list patterns that match by IP address | |
7630 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
7631 | cindex:[host list,matching IP addresses] | |
7632 | If an IPv4 host calls an IPv6 host and the call is accepted on an IPv6 socket, | |
7633 | the incoming address actually appears in the IPv6 host as | |
7634 | ``::`ffff`:<''v4address'>'. When such an address is tested against a host | |
7635 | list, it is converted into a traditional IPv4 address first. (Not all operating | |
7636 | systems accept IPv4 calls on IPv6 sockets, as there have been some security | |
7637 | concerns.) | |
7638 | ||
7639 | The following types of pattern in a host list check the remote host by | |
7640 | inspecting its IP address: | |
7641 | ||
7642 | - If the pattern is a plain domain name (not a regular expression, not starting | |
7643 | with \*, not a lookup of any kind), Exim calls the operating system function | |
7644 | to find the associated IP address(es). Exim uses the newer | |
7645 | 'getipnodebyname()' function when available, otherwise 'gethostbyname()'. | |
7646 | This typically causes a forward DNS lookup of the name. The result is compared | |
7647 | with the IP address of the subject host. | |
7648 | + | |
7649 | If there is a temporary problem (such as a DNS timeout) with the host name | |
7650 | lookup, a temporary error occurs. For example, if the list is being used in an | |
7651 | ACL condition, the ACL gives a ``defer'' response, usually leading to a temporary | |
7652 | SMTP error code. If no IP address can be found for the host name, what happens | |
7653 | is described in section <<SECTbehipnot>> below. | |
7654 | ||
7655 | - cindex:[@ in a host list] | |
7656 | If the pattern is ``@'', the primary host name is substituted and used as a | |
7657 | domain name, as just described. | |
7658 | ||
7659 | - If the pattern is an IP address, it is matched against the IP address of the | |
7660 | subject host. IPv4 addresses are given in the normal ``dotted-quad'' notation. | |
7661 | IPv6 addresses can be given in colon-separated format, but the colons have to | |
7662 | be doubled so as not to be taken as item separators when the default list | |
7663 | separator is used. IPv6 addresses are recognized even when Exim is compiled | |
7664 | without IPv6 support. This means that if they appear in a host list on an | |
7665 | IPv4-only host, Exim will not treat them as host names. They are just addresses | |
7666 | that can never match a client host. | |
7667 | ||
7668 | - cindex:[@{bk} in a host list] | |
7669 | If the pattern is ``@[]'', it matches the IP address of any IP interface on | |
7670 | the local host. For example, if the local host is an IPv4 host with one | |
7671 | interface address 10.45.23.56, these two ACL statements have the same effect: | |
7672 | ||
7673 | accept hosts = 127.0.0.1 : 10.45.23.56 | |
7674 | accept hosts = @[] | |
7675 | ||
7676 | - cindex:[CIDR notation] | |
7677 | If the pattern is an IP address followed by a slash and a mask length (for | |
7678 | example 10.11.42.0/24), it is matched against the IP address of the subject | |
7679 | host under the given mask. This allows, an entire network of hosts to be | |
7680 | included (or excluded) by a single item. The mask uses CIDR notation; it | |
7681 | specifies the number of address bits that must match, starting from the most | |
7682 | significant end of the address. | |
7683 | + | |
7684 | *Note*: the mask is 'not' a count of addresses, nor is it the high number | |
7685 | of a range of addresses. It is the number of bits in the network portion of the | |
7686 | address. The above example specifies a 24-bit netmask, so it matches all 256 | |
7687 | addresses in the 10.11.42.0 network. An item such as | |
7688 | ||
7689 | 192.168.23.236/31 | |
7690 | + | |
7691 | matches just two addresses, 192.168.23.236 and 192.168.23.237. A mask value of | |
7692 | 32 for an IPv4 address is the same as no mask at all; just a single address | |
7693 | matches. | |
7694 | + | |
7695 | Here is another example which shows an IPv4 and an IPv6 network: | |
7696 | + | |
7697 | .... | |
7698 | recipient_unqualified_hosts = 192.168.0.0/16: \ | |
7699 | 3ffe::ffff::836f::::/48 | |
7700 | .... | |
7701 | + | |
7702 | The doubling of list separator characters applies only when these items | |
7703 | appear inline in a host list. It is not required when indirecting via a file. | |
7704 | For example, | |
7705 | ||
7706 | recipient_unqualified_hosts = /opt/exim/unqualnets | |
7707 | + | |
7708 | could make use of a file containing | |
7709 | ||
7710 | 172.16.0.0/12 | |
7711 | 3ffe:ffff:836f::/48 | |
7712 | + | |
7713 | to have exactly the same effect as the previous example. When listing IPv6 | |
7714 | addresses inline, it is usually more convenient to use the facility for | |
7715 | changing separator characters. This list contains the same two networks: | |
7716 | + | |
7717 | .... | |
7718 | recipient_unqualified_hosts = <; 172.16.0.0/12; \ | |
7719 | 3ffe:ffff:836f::/48 | |
7720 | .... | |
7721 | + | |
7722 | The separator is changed to semicolon by the leading ``<;'' at the start of the | |
7723 | list. | |
7724 | ||
7725 | ||
7726 | ||
7727 | ||
7728 | [[SECThoslispatsikey]] | |
7729 | Host list patterns for single-key lookups by host address | |
7730 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
7731 | cindex:[host list,lookup of IP address] | |
7732 | When a host is to be identified by a single-key lookup of its complete IP | |
7733 | address, the pattern takes this form: | |
7734 | ||
7735 | net-<single-key-search-type>;<search-data> | |
7736 | ||
7737 | For example: | |
7738 | ||
7739 | hosts_lookup = net-cdb;/hosts-by-ip.db | |
7740 | ||
7741 | The text form of the IP address of the subject host is used as the lookup key. | |
7742 | IPv6 addresses are converted to an unabbreviated form, using lower case | |
7743 | letters, with dots as separators because colon is the key terminator in | |
7744 | ^lsearch^ files. [Colons can in fact be used in keys in ^lsearch^ files by | |
7745 | quoting the keys, but this is a facility that was added later.] The data | |
7746 | returned by the lookup is not used. | |
7747 | ||
7748 | cindex:[IP address,masking] | |
7749 | cindex:[host list,masked IP address] | |
7750 | Single-key lookups can also be performed using masked IP addresses, using | |
7751 | patterns of this form: | |
7752 | ||
7753 | net<number>-<single-key-search-type>;<search-data> | |
7754 | ||
7755 | For example: | |
7756 | ||
7757 | net24-dbm;/networks.db | |
7758 | ||
7759 | The IP address of the subject host is masked using <'number'> as the mask | |
7760 | length. A textual string is constructed from the masked value, followed by the | |
7761 | mask, and this is used as the lookup key. For example, if the host's IP address | |
7762 | is 192.168.34.6, the key that is looked up for the above example is | |
7763 | ``192.168.34.0/24''. IPv6 addresses are converted to a text value using lower | |
7764 | case letters and dots as separators instead of the more usual colon, because | |
7765 | colon is the key terminator in ^lsearch^ files. Full, unabbreviated IPv6 | |
7766 | addresses are always used. | |
7767 | ||
7768 | *Warning*: Specifing %net32-% (for an IPv4 address) or %net128-% (for an | |
7769 | IPv6 address) is not the same as specifing just %net-% without a number. In | |
7770 | the former case the key strings include the mask value, whereas in the latter | |
7771 | case the IP address is used on its own. | |
7772 | ||
7773 | ||
7774 | ||
7775 | [[SECThoslispatnam]] | |
7776 | Host list patterns that match by host name | |
7777 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
7778 | cindex:[host,lookup failures] | |
7779 | cindex:[unknown host name] | |
7780 | cindex:[host list,matching host name] | |
7781 | There are several types of pattern that require Exim to know the name of the | |
7782 | remote host. These are either wildcard patterns or lookups by name. (If a | |
7783 | complete hostname is given without any wildcarding, it is used to find an IP | |
7784 | address to match against, as described in the section <<SECThoslispatip>> above.) | |
7785 | ||
7786 | If the remote host name is not already known when Exim encounters one of these | |
7787 | patterns, it has to be found from the IP address. | |
7788 | Although many sites on the Internet are conscientious about maintaining reverse | |
7789 | DNS data for their hosts, there are also many that do not do this. | |
7790 | Consequently, a name cannot always be found, and this may lead to unwanted | |
7791 | effects. Take care when configuring host lists with wildcarded name patterns. | |
7792 | Consider what will happen if a name cannot be found. | |
7793 | ||
7794 | Because of the problems of determining host names from IP addresses, matching | |
7795 | against host names is not as common as matching against IP addresses. | |
7796 | ||
7797 | By default, in order to find a host name, Exim first does a reverse DNS lookup; | |
7798 | if no name is found in the DNS, the system function ('gethostbyaddr()' or | |
7799 | 'getipnodebyaddr()' if available) is tried. The order in which these lookups | |
7800 | are done can be changed by setting the %host_lookup_order% option. | |
7801 | ||
7802 | There are some options that control what happens if a host name cannot be | |
7803 | found. These are described in section <<SECTbehipnot>> below. | |
7804 | ||
7805 | cindex:[host,alias for] | |
7806 | cindex:[alias for host] | |
7807 | As a result of aliasing, hosts may have more than one name. When processing any | |
7808 | of the following types of pattern, all the host's names are checked: | |
7809 | ||
7810 | - cindex:[asterisk,in host list] | |
7811 | If a pattern starts with ``\*'' the remainder of the item must match the end of | |
7812 | the host name. For example, `*.b.c` matches all hosts whose names end in | |
7813 | '.b.c'. This special simple form is provided because this is a very common | |
7814 | requirement. Other kinds of wildcarding require the use of a regular | |
7815 | expression. | |
7816 | ||
7817 | - cindex:[regular expressions,in host list] | |
7818 | cindex:[host list,regular expression in] | |
7819 | If the item starts with ``^'' it is taken to be a regular expression which is | |
7820 | matched against the host name. For example, | |
7821 | ||
7822 | ^(a|b)\.c\.d$ | |
7823 | + | |
7824 | is a regular expression that matches either of the two hosts 'a.c.d' or | |
7825 | 'b.c.d'. When a regular expression is used in a host list, you must take care | |
7826 | that backslash and dollar characters are not misinterpreted as part of the | |
7827 | string expansion. The simplest way to do this is to use `\N` to mark that | |
7828 | part of the string as non-expandable. For example: | |
7829 | ||
7830 | sender_unqualified_hosts = \N^(a|b)\.c\.d$\N : .... | |
7831 | + | |
7832 | *Warning*: If you want to match a complete host name, you must include the | |
7833 | `\$` terminating metacharacter in the regular expression, as in the above | |
7834 | example. Without it, a match at the start of the host name is all that is | |
7835 | required. | |
7836 | ||
7837 | ||
7838 | ||
7839 | ||
7840 | [[SECTbehipnot]] | |
7841 | Behaviour when an IP address or name cannot be found | |
7842 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
7843 | cindex:[host,lookup failures] | |
7844 | While processing a host list, Exim may need to look up an IP address from a | |
7845 | name (see section <<SECThoslispatip>>), or it may need to look up a host name | |
7846 | from an IP address (see section <<SECThoslispatnam>>). In either case, the | |
7847 | behaviour when it fails to find the information it is seeking is the same. | |
7848 | ||
7849 | cindex:[`+include_unknown`] | |
7850 | cindex:[`+ignore_unknown`] | |
7851 | By default, Exim behaves as if the host does not match the list. This may not | |
7852 | always be what you want to happen. To change Exim's behaviour, the special | |
7853 | items `+include_unknown` or `+ignore_unknown` may appear in the list (at | |
7854 | top level -- they are not recognized in an indirected file). | |
7855 | ||
7856 | - If any item that follows `+include_unknown` requires information that | |
7857 | cannot found, Exim behaves as if the host does match the list. For example, | |
7858 | ||
7859 | host_reject_connection = +include_unknown:*.enemy.ex | |
7860 | + | |
7861 | rejects connections from any host whose name matches `*.enemy.ex`, and also | |
7862 | any hosts whose name it cannot find. | |
7863 | ||
7864 | - If any item that follows `+ignore_unknown` requires information that cannot | |
7865 | be found, Exim ignores that item and proceeds to the rest of the list. For | |
7866 | example: | |
7867 | + | |
7868 | .... | |
7869 | accept hosts = +ignore_unknown : friend.example : \ | |
7870 | 192.168.4.5 | |
7871 | .... | |
7872 | + | |
7873 | accepts from any host whose name is 'friend.example' and from 192.168.4.5, | |
7874 | whether or not its host name can be found. Without `+ignore_unknown`, if no | |
7875 | name can be found for 192.168.4.5, it is rejected. | |
7876 | ||
7877 | Both `+include_unknown` and `+ignore_unknown` may appear in the same | |
7878 | list. The effect of each one lasts until the next, or until the end of the | |
7879 | list. | |
7880 | ||
7881 | *Note*: This section applies to permanent lookup failures. It does 'not' | |
7882 | apply to temporary DNS errors. They always cause a defer action. | |
7883 | ||
7884 | ||
7885 | ||
7886 | [[SECThoslispatnamsk]] | |
7887 | Host list patterns for single-key lookups by host name | |
7888 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
7889 | cindex:[host,lookup failures] | |
7890 | cindex:[unknown host name] | |
7891 | cindex:[host list,matching host name] | |
7892 | If a pattern is of the form | |
7893 | ||
7894 | <single-key-search-type>;<search-data> | |
7895 | ||
7896 | for example | |
7897 | ||
7898 | dbm;/host/accept/list | |
7899 | ||
7900 | a single-key lookup is performend, using the host name as its key. If the | |
7901 | lookup succeeds, the host matches the item. The actual data that is looked up | |
7902 | is not used. | |
7903 | ||
7904 | *Reminder*: With this kind of pattern, you must have host 'names' as | |
7905 | keys in the file, not IP addresses. If you want to do lookups based on IP | |
7906 | addresses, you must precede the search type with ``net-'' (see section | |
7907 | <<SECThoslispatsikey>>). There is, however, no reason why you could not use two | |
7908 | items in the same list, one doing an address lookup and one doing a name | |
7909 | lookup, both using the same file. | |
7910 | ||
7911 | ||
7912 | ||
7913 | Host list patterns for query-style lookups | |
7914 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
7915 | If a pattern is of the form | |
7916 | ||
7917 | <query-style-search-type>;<query> | |
7918 | ||
7919 | the query is obeyed, and if it succeeds, the host matches the item. The actual | |
7920 | data that is looked up is not used. The variables $sender_host_address$ and | |
7921 | $sender_host_name$ can be used in the query. For example: | |
7922 | ||
7923 | .... | |
7924 | hosts_lookup = pgsql;\ | |
7925 | select ip from hostlist where ip='$sender_host_address' | |
7926 | .... | |
7927 | ||
7928 | The value of $sender_host_address$ for an IPv6 address contains colons. You | |
7929 | can use the %sg% expansion item to change this if you need to. If you want to | |
7930 | use masked IP addresses in database queries, you can use the %mask% expansion | |
7931 | operator. | |
7932 | ||
7933 | If the query contains a reference to $sender_host_name$, Exim automatically | |
7934 | looks up the host name if has not already done so. (See section | |
7935 | <<SECThoslispatnam>> for comments on finding host names.) | |
7936 | ||
7937 | Historical note: prior to release 4.30, Exim would always attempt to find a | |
7938 | host name before running the query, unless the search type was preceded by | |
7939 | `net-`. This is no longer the case. For backwards compatibility, `net-` is | |
7940 | still recognized for query-style lookups, but its presence or absence has no | |
7941 | effect. (Of course, for single-key lookups, `net-` 'is' important. | |
7942 | See section <<SECThoslispatsikey>>.) | |
7943 | ||
7944 | ||
7945 | ||
7946 | [[SECTmixwilhos]] | |
7947 | Mixing wildcarded host names and addresses in host lists | |
7948 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
7949 | cindex:[host list,mixing names and addresses in] | |
7950 | If you have name lookups or wildcarded host names and IP addresses in the same | |
7951 | host list, you should normally put the IP addresses first. For example, in an | |
7952 | ACL you could have: | |
7953 | ||
7954 | accept hosts = 10.9.8.7 : *.friend.example | |
7955 | ||
7956 | The reason for this lies in the left-to-right way that Exim processes lists. | |
7957 | It can test IP addresses without doing any DNS lookups, but when it reaches an | |
7958 | item that requires a host name, it fails if it cannot find a host name to | |
7959 | compare with the pattern. If the above list is given in the opposite order, the | |
7960 | %accept% statement fails for a host whose name cannot be found, even if its | |
7961 | IP address is 10.9.8.7. | |
7962 | ||
7963 | If you really do want to do the name check first, and still recognize the IP | |
7964 | address, you can rewrite the ACL like this: | |
7965 | ||
7966 | accept hosts = *.friend.example | |
7967 | accept hosts = 10.9.8.7 | |
7968 | ||
7969 | If the first %accept% fails, Exim goes on to try the second one. See chapter | |
7970 | <<CHAPACL>> for details of ACLs. | |
7971 | ||
7972 | ||
7973 | ||
7974 | ||
7975 | ||
7976 | [[SECTaddresslist]] | |
7977 | Address lists | |
7978 | ~~~~~~~~~~~~~ | |
7979 | cindex:[list,address list] | |
7980 | cindex:[address list,empty item] | |
7981 | cindex:[address list,patterns] | |
7982 | Address lists contain patterns that are matched against mail addresses. There | |
7983 | is one special case to be considered: the sender address of a bounce message is | |
7984 | always empty. You can test for this by providing an empty item in an address | |
7985 | list. For example, you can set up a router to process bounce messages by | |
7986 | using this option setting: | |
7987 | ||
7988 | senders = : | |
7989 | ||
7990 | The presence of the colon creates an empty item. If you do not provide any | |
7991 | data, the list is empty and matches nothing. The empty sender can also be | |
7992 | detected by a regular expression that matches an empty string, | |
7993 | ||
7994 | and by a query-style lookup that succeeds when $sender_address$ is empty. | |
7995 | ||
7996 | The following kinds of address list pattern can match any address, including | |
7997 | the empty address that is characteristic of bounce message senders: | |
7998 | ||
7999 | - As explained above, if a pattern item is empty, it matches the empty address | |
8000 | (and no others). | |
8001 | ||
8002 | - cindex:[regular expressions,in address list] | |
8003 | cindex:[address list,regular expression in] | |
8004 | If (after expansion) a pattern starts with ``^'', a regular expression match is | |
8005 | done against the complete address, with the pattern as the regular expression. | |
8006 | You must take care that backslash and dollar characters are not misinterpreted | |
8007 | as part of the string expansion. The simplest way to do this is to use `\N` | |
8008 | to mark that part of the string as non-expandable. For example: | |
8009 | ||
8010 | deny senders = \N^\d{8}.+@spamhaus.example$\N : ... | |
8011 | + | |
8012 | The `\N` sequences are removed by the expansion, so the item does start | |
8013 | with ``^'' by the time it is being interpreted as an address pattern. | |
8014 | ||
8015 | - cindex:[address list,lookup for complete address] | |
8016 | Complete addresses can be looked up by using a pattern that starts with a | |
8017 | lookup type terminated by a semicolon, followed by the data for the lookup. For | |
8018 | example: | |
8019 | + | |
8020 | .... | |
8021 | deny senders = cdb;/etc/blocked.senders : \ | |
8022 | mysql;select address from blocked where \ | |
8023 | address='${quote_mysql:$sender_address}' | |
8024 | .... | |
8025 | + | |
8026 | Both query-style and single-key lookup types can be used. For a single-key | |
8027 | lookup type, Exim uses the complete address as the key. However, empty keys are | |
8028 | not supported for single-key lookups, so a match against the empty address | |
8029 | always fails. This restriction does not apply to query-style lookups. | |
8030 | + | |
8031 | Partial matching for single-key lookups (section <<SECTpartiallookup>>) cannot | |
8032 | be used, and is ignored if specified, with an entry being written to the panic | |
8033 | log. | |
8034 | + | |
8035 | cindex:[\*@ with single-key lookup] | |
8036 | However, you can configure lookup defaults, as described in section | |
8037 | <<SECTdefaultvaluelookups>>, but this is useful only for the ``\*@'' type of | |
8038 | default. For example, with this lookup: | |
8039 | ||
8040 | accept senders = lsearch*@;/some/file | |
8041 | + | |
8042 | the file could contains lines like this: | |
8043 | ||
8044 | user1@domain1.example | |
8045 | *@domain2.example | |
8046 | + | |
8047 | and for the sender address 'nimrod@jaeger.example', the sequence of keys | |
8048 | that are tried is: | |
8049 | ||
8050 | nimrod@jaeger.example | |
8051 | *@jaeger.example | |
8052 | * | |
8053 | + | |
8054 | *Warning 1*: Do not include a line keyed by ``\*'' in the file, because that | |
8055 | would mean that every address matches, thus rendering the test useless. | |
8056 | + | |
8057 | *Warning 2*: Do not confuse these two kinds of item: | |
8058 | ||
8059 | deny recipients = dbm*@;/some/file | |
8060 | deny recipients = *@dbm;/some/file | |
8061 | + | |
8062 | The first does a whole address lookup, with defaulting, as just described, | |
8063 | because it starts with a lookup type. The second matches the local part and | |
8064 | domain independently, as described in a bullet point below. | |
8065 | ||
8066 | ||
8067 | ||
8068 | The following kinds of address list pattern can match only non-empty addresses. | |
8069 | If the subject address is empty, a match against any of these pattern types | |
8070 | always fails. | |
8071 | ||
8072 | ||
8073 | - cindex:[@@ with single-key lookup] | |
8074 | cindex:[address list,@@ lookup type] | |
8075 | cindex:[address list,split local part and domain] | |
8076 | If a pattern starts with ``@@'' followed by a single-key lookup item | |
8077 | (for example, `@@lsearch;/some/file`), the address that is being checked is | |
8078 | split into a local part and a domain. The domain is looked up in the file. If | |
8079 | it is not found, there is no match. If it is found, the data that is looked up | |
8080 | from the file is treated as a colon-separated list of local part patterns, each | |
8081 | of which is matched against the subject local part in turn. | |
8082 | + | |
8083 | cindex:[asterisk,in address list] | |
8084 | The lookup may be a partial one, and/or one involving a search for a default | |
8085 | keyed by ``\*'' (see section <<SECTdefaultvaluelookups>>). The local part patterns | |
8086 | that are looked up can be regular expressions or begin with ``\*'', or even be | |
8087 | further lookups. They may also be independently negated. For example, with | |
8088 | ||
8089 | deny senders = @@dbm;/etc/reject-by-domain | |
8090 | + | |
8091 | the data from which the DBM file is built could contain lines like | |
8092 | ||
8093 | baddomain.com: !postmaster : * | |
8094 | + | |
8095 | to reject all senders except %postmaster% from that domain. | |
8096 | + | |
8097 | cindex:[local part,starting with !] | |
8098 | If a local part that actually begins with an exclamation mark is required, it | |
8099 | has to be specified using a regular expression. In ^lsearch^ files, an entry | |
8100 | may be split over several lines by indenting the second and subsequent lines, | |
8101 | but the separating colon must still be included at line breaks. White space | |
8102 | surrounding the colons is ignored. For example: | |
8103 | ||
8104 | aol.com: spammer1 : spammer2 : ^[0-9]+$ : | |
8105 | spammer3 : spammer4 | |
8106 | + | |
8107 | As in all colon-separated lists in Exim, a colon can be included in an item by | |
8108 | doubling. | |
8109 | + | |
8110 | If the last item in the list starts with a right angle-bracket, the remainder | |
8111 | of the item is taken as a new key to look up in order to obtain a continuation | |
8112 | list of local parts. The new key can be any sequence of characters. Thus one | |
8113 | might have entries like | |
8114 | ||
8115 | aol.com: spammer1 : spammer 2 : >* | |
8116 | xyz.com: spammer3 : >* | |
8117 | *: ^\d{8}$ | |
8118 | + | |
8119 | in a file that was searched with %@@dbm\*%, to specify a match for 8-digit | |
8120 | local parts for all domains, in addition to the specific local parts listed for | |
8121 | each domain. Of course, using this feature costs another lookup each time a | |
8122 | chain is followed, but the effort needed to maintain the data is reduced. | |
8123 | + | |
8124 | cindex:[loop,in lookups] | |
8125 | It is possible to construct loops using this facility, and in order to catch | |
8126 | them, the chains may be no more than fifty items long. | |
8127 | ||
8128 | - The @@<'lookup'> style of item can also be used with a query-style | |
8129 | lookup, but in this case, the chaining facility is not available. The lookup | |
8130 | can only return a single list of local parts. | |
8131 | ||
8132 | - If a pattern contains an @ character, but is not a regular expression and does | |
8133 | not begin with a lookup type as described above, the local part of the subject | |
8134 | address is compared with the local part of the pattern, which may start with an | |
8135 | asterisk. If the local parts match, the domain is checked in exactly the same | |
8136 | way as for a pattern in a domain list. For example, the domain can be | |
8137 | wildcarded, refer to a named list, or be a lookup: | |
8138 | + | |
8139 | .... | |
8140 | deny senders = *@*.spamming.site:\ | |
8141 | *@+hostile_domains:\ | |
8142 | bozo@partial-lsearch;/list/of/dodgy/sites:\ | |
8143 | *@dbm;/bad/domains.db | |
8144 | .... | |
8145 | + | |
8146 | cindex:[local part,starting with !] | |
8147 | cindex:[address list,local part starting with !] | |
8148 | If a local part that begins with an exclamation mark is required, it has to be | |
8149 | specified using a regular expression, because otherwise the exclamation mark is | |
8150 | treated as a sign of negation. | |
8151 | ||
8152 | - If a pattern is not one of the above syntax forms, that is, if a | |
8153 | non-empty pattern that is not a regular expression or a lookup does not contain | |
8154 | an @ character, it is matched against the domain part of the subject address. | |
8155 | The only two formats that are recognized this way are a literal domain, or a | |
8156 | domain pattern that starts with \*. In both these cases, the effect is the same | |
8157 | as if `*@` preceded the pattern. | |
8158 | ||
8159 | *Warning*: there is an important difference between the address list items | |
8160 | in these two examples: | |
8161 | ||
8162 | senders = +my_list | |
8163 | senders = *@+my_list | |
8164 | ||
8165 | In the first one, `my_list` is a named address list, whereas in the second | |
8166 | example it is a named domain list. | |
8167 | ||
8168 | ||
8169 | ||
8170 | ||
8171 | [[SECTcasletadd]] | |
8172 | Case of letters in address lists | |
8173 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
8174 | cindex:[case of local parts] | |
8175 | cindex:[address list,case forcing] | |
8176 | cindex:[case forcing in address lists] | |
8177 | Domains in email addresses are always handled caselessly, but for local parts | |
8178 | case may be significant on some systems (see %caseful_local_part% for how | |
8179 | Exim deals with this when routing addresses). However, RFC 2505 ('Anti-Spam | |
8180 | Recommendations for SMTP MTAs') suggests that matching of addresses to blocking | |
8181 | lists should be done in a case-independent manner. Since most address lists in | |
8182 | Exim are used for this kind of control, Exim attempts to do this by default. | |
8183 | ||
8184 | The domain portion of an address is always lowercased before matching it to an | |
8185 | address list. The local part is lowercased by default, and any string | |
8186 | comparisons that take place are done caselessly. This means that the data in | |
8187 | the address list itself, in files included as plain file names, and in any file | |
8188 | that is looked up using the ``@@'' mechanism, can be in any case. However, the | |
8189 | keys in files that are looked up by a search type other than ^lsearch^ (which | |
8190 | works caselessly) must be in lower case, because these lookups are not | |
8191 | case-independent. | |
8192 | ||
8193 | cindex:[`+caseful`] | |
8194 | To allow for the possibility of caseful address list matching, if an item in | |
8195 | an address list is the string ``+caseful'', the original case of the local | |
8196 | part is restored for any comparisons that follow, and string comparisons are no | |
8197 | longer case-independent. This does not affect the domain, which remains in | |
8198 | lower case. However, although independent matches on the domain alone are still | |
8199 | performed caselessly, regular expressions that match against an entire address | |
8200 | become case-sensitive after ``+caseful'' has been seen. | |
8201 | ||
8202 | ||
8203 | ||
8204 | [[SECTlocparlis]] | |
8205 | Local part lists | |
8206 | ~~~~~~~~~~~~~~~~ | |
8207 | cindex:[list,local part list] | |
8208 | cindex:[local part,list] | |
8209 | Case-sensitivity in local part lists is handled in the same way as for address | |
8210 | lists, as just described. The ``+caseful'' item can be used if required. In a | |
8211 | setting of the %local_parts% option in a router with %caseful_local_part% | |
8212 | set false, the subject is lowercased and the matching is initially | |
8213 | case-insensitive. In this case, ``+caseful'' will restore case-sensitive matching | |
8214 | in the local part list, but not elsewhere in the router. If | |
8215 | %caseful_local_part% is set true in a router, matching in the %local_parts% | |
8216 | option is case-sensitive from the start. | |
8217 | ||
8218 | If a local part list is indirected to a file (see section <<SECTfilnamlis>>), | |
8219 | comments are handled in the same way as address lists -- they are recognized | |
8220 | only if the # is preceded by white space or the start of the line. | |
8221 | Otherwise, local part lists are matched in the same way as domain lists, except | |
8222 | that the special items that refer to the local host (`@`, `@[]`, | |
8223 | `@mx_any`, `@mx_primary`, and `@mx_secondary`) are not recognized. | |
8224 | Refer to section <<SECTdomainlist>> for details of the other available item | |
8225 | types. | |
8226 | ||
8227 | ||
8228 | ||
8229 | ||
8230 | //////////////////////////////////////////////////////////////////////////// | |
8231 | //////////////////////////////////////////////////////////////////////////// | |
8232 | ||
8233 | [[CHAPexpand]] | |
8234 | String expansions | |
8235 | ----------------- | |
8236 | cindex:[expansion,of strings] | |
8237 | Many strings in Exim's run time configuration are expanded before use. Some of | |
8238 | them are expanded every time they are used; others are expanded only once. | |
8239 | ||
8240 | When a string is being expanded it is copied verbatim from left to right except | |
8241 | when a dollar or backslash character is encountered. A dollar specifies the | |
068aaea8 | 8242 | start of a portion of the string that is interpreted and replaced as described |
168e428f PH |
8243 | below in section <<SECTexpansionitems>> onwards. Backslash is used as an escape |
8244 | character, as described in the following section. | |
8245 | ||
8246 | ||
8247 | ||
8248 | [[SECTlittext]] | |
8249 | Literal text in expanded strings | |
8250 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
8251 | cindex:[expansion,including literal text] | |
8252 | An uninterpreted dollar can be included in an expanded string by putting a | |
8253 | backslash in front of it. A backslash can be used to prevent any special | |
068aaea8 PH |
8254 | character being treated specially in an expansion, including backslash itself. |
8255 | If the string appears in quotes in the configuration file, two backslashes are | |
168e428f PH |
8256 | required because the quotes themselves cause interpretation of backslashes when |
8257 | the string is read in (see section <<SECTstrings>>). | |
8258 | ||
8259 | cindex:[expansion,non-expandable substrings] | |
8260 | A portion of the string can specified as non-expandable by placing it between | |
8261 | two occurrences of `\N`. This is particularly useful for protecting regular | |
8262 | expressions, which often contain backslashes and dollar signs. For example: | |
8263 | ||
8264 | deny senders = \N^\d{8}[a-z]@some\.site\.example$\N | |
8265 | ||
8266 | On encountering the first `\N`, the expander copies subsequent characters | |
8267 | without interpretation until it reaches the next `\N` or the end of the | |
8268 | string. | |
8269 | ||
8270 | ||
8271 | ||
8272 | Character escape sequences in expanded strings | |
8273 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
8274 | cindex:[expansion,escape sequences] | |
8275 | A backslash followed by one of the letters ``n'', ``r'', or ``t'' in an expanded | |
8276 | string is recognized as an escape sequence for the character newline, carriage | |
8277 | return, or tab, respectively. A backslash followed by up to three octal digits | |
8278 | is recognized as an octal encoding for a single character, and a backslash | |
8279 | followed by ``x'' and up to two hexadecimal digits is a hexadecimal encoding. | |
8280 | ||
8281 | These escape sequences are also recognized in quoted strings when they are read | |
8282 | in. Their interpretation in expansions as well is useful for unquoted strings, | |
8283 | and for other cases such as looked-up strings that are then expanded. | |
8284 | ||
8285 | ||
8286 | Testing string expansions | |
8287 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
8288 | cindex:[expansion,testing] | |
8289 | cindex:[testing,string expansion] | |
8290 | cindex:[%-be% option] | |
8291 | Many expansions can be tested by calling Exim with the %-be% option. This takes | |
8292 | the command arguments, or lines from the standard input if there are no | |
8293 | arguments, runs them through the string expansion code, and writes the results | |
8294 | to the standard output. Variables based on configuration values are set up, but | |
8295 | since no message is being processed, variables such as $local_part$ have no | |
8296 | value. Nevertheless the %-be% option can be useful for checking out file and | |
8297 | database lookups, and the use of expansion operators such as %sg%, %substr% and | |
8298 | %nhash%. | |
8299 | ||
8300 | Exim gives up its root privilege when it is called with the %-be% option, and | |
8301 | instead runs under the uid and gid it was called with, to prevent users from | |
8302 | using %-be% for reading files to which they do not have access. | |
8303 | ||
8304 | ||
8305 | ||
8306 | [[SECTforexpfai]] | |
8307 | Forced expansion failure | |
8308 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
8309 | cindex:[expansion,forced failure] | |
8310 | A number of expansions that are described in the following section have | |
068aaea8 PH |
8311 | alternative ``true'' and ``false'' substrings, enclosed in brace characters |
8312 | (which are sometimes called ``curly brackets''). Which of the two strings is | |
8313 | used depends on some condition that is evaluated as part of the expansion. If, | |
8314 | instead of a ``false'' substring, the word ``fail'' is used (not in braces), | |
8315 | the entire string expansion fails in a way that can be detected by the code | |
8316 | that requested the expansion. This is called ``forced expansion failure'', and | |
8317 | its consequences depend on the circumstances. In some cases it is no different | |
8318 | from any other expansion failure, but in others a different action may be | |
8319 | taken. Such variations are mentioned in the documentation of the option that is | |
8320 | being expanded. | |
168e428f PH |
8321 | |
8322 | ||
8323 | ||
8324 | ||
8325 | [[SECTexpansionitems]] | |
8326 | Expansion items | |
8327 | ~~~~~~~~~~~~~~~ | |
8328 | The following items are recognized in expanded strings. White space may be used | |
8329 | between sub-items that are keywords or substrings enclosed in braces inside an | |
8330 | outer set of braces, to improve readability. *Warning*: Within braces, | |
8331 | white space is significant. | |
8332 | ||
8333 | *\$*<'variable~name'>~or~*\$\{*<'variable~name'>*\}*:: | |
8334 | cindex:[expansion,variables] | |
8335 | Substitute the contents of the named variable, for example | |
8336 | ||
8337 | $local_part | |
8338 | ${domain} | |
8339 | + | |
8340 | The second form can be used to separate the name from subsequent alphanumeric | |
068aaea8 PH |
8341 | characters. This form (using braces) is available only for variables; it does |
8342 | 'not' apply to message headers. The names of the variables are given in section | |
8343 | <<SECTexpvar>> below. If the name of a non-existent variable is given, the | |
8344 | expansion fails. | |
168e428f PH |
8345 | |
8346 | *\$\{*<'op'>*:*<'string'>*\}*:: | |
8347 | cindex:[expansion,operators] | |
8348 | The string is first itself expanded, and then the operation specified by <'op'> | |
8349 | is applied to it. For example, | |
8350 | ||
8351 | ${lc:$local_part} | |
8352 | + | |
8353 | The string starts with the first character after the colon, which may be | |
8354 | leading white space. A list of operators is given in section <<SECTexpop>> | |
8355 | below. The operator notation is used for simple expansion items that have just | |
8356 | one argument, because it reduces the number of braces and therefore makes the | |
8357 | string easier to understand. | |
8358 | ||
068aaea8 | 8359 | *\$\{dlfunc\{*<'file'>*\}\{*<'function'>*\}\{*<'arg'>*\}\{*<'arg'>*\}...\}*:: |
168e428f | 8360 | + |
068aaea8 PH |
8361 | [revisionflag="changed"] |
8362 | This expansion dynamically loads and then calls a locally-written C function. | |
8363 | This functionality is available only if Exim is compiled with | |
8364 | + | |
8365 | [revisionflag="changed"] | |
8366 | .... | |
8367 | EXPAND_DLFUNC=yes | |
8368 | .... | |
8369 | + | |
8370 | [revisionflag="changed"] | |
8371 | set in _Local/Makefile_. Once loaded, Exim remembers the dynamically loaded | |
8372 | object so that it doesn't reload the same object file in the same Exim process | |
8373 | (but of course Exim does start new processes frequently). | |
8374 | + | |
8375 | [revisionflag="changed"] | |
8376 | There may be from zero to eight arguments to the function. When compiling | |
8377 | a local function that is to be called in this way, _local_scan.h_ should be | |
8378 | included. The Exim variables and functions that are defined by that API | |
8379 | are also available for dynamically loaded functions. The function itself | |
8380 | must have the following type: | |
8381 | + | |
8382 | [revisionflag="changed"] | |
8383 | .... | |
8384 | int dlfunction(uschar **yield, int argc, uschar *argv[]) | |
8385 | .... | |
8386 | + | |
8387 | [revisionflag="changed"] | |
8388 | Where `uschar` is a typedef for `unsigned char` in _local_scan.h_. The | |
8389 | function should return one of the following values: | |
8390 | + | |
8391 | [revisionflag="changed"] | |
8392 | `OK`: Success. The string that is placed in the variable 'yield' is put into | |
8393 | the expanded string that is being built. | |
8394 | + | |
8395 | [revisionflag="changed"] | |
8396 | `FAIL`: A non-forced expansion failure occurs, with the error message taken | |
8397 | from 'yield', if it is set. | |
8398 | + | |
8399 | [revisionflag="changed"] | |
8400 | `FAIL_FORCED`: A forced expansion failure occurs, with the error message | |
8401 | taken from 'yield' if it is set. | |
8402 | + | |
8403 | [revisionflag="changed"] | |
8404 | `ERROR`: Same as `FAIL`, except that a panic log entry is written. | |
8405 | + | |
8406 | [revisionflag="changed"] | |
8407 | When compiling a function that is to be used in this way with gcc, | |
8408 | you need to add %-shared% to the gcc command. Also, in the Exim build-time | |
8409 | configuration, you must add %-export-dynamic% to EXTRALIBS. | |
8410 | ||
8411 | ||
8412 | *\$\{extract\{*<'key'>*\}\{*<'string1'>*\}\{*<'string2'>*\}\{*<'string3'>*\}\}*:: | |
8413 | cindex:[expansion,extracting substrings by key] | |
8414 | The key and <'string1'> are first expanded separately. Leading and trailing | |
8415 | white space is removed from the key (but not from any of the strings). The key | |
8416 | must not consist entirely of digits. The expanded <'string1'> must be of the | |
8417 | form: | |
8418 | ||
8419 | <key1> = <value1> <key2> = <value2> ... | |
8420 | + | |
8421 | cindex:[$value$] | |
8422 | where the equals signs and spaces (but not both) are optional. If any of the | |
8423 | values contain white space, they must be enclosed in double quotes, and any | |
8424 | values that are enclosed in double quotes are subject to escape processing as | |
8425 | described in section <<SECTstrings>>. The expanded <'string1'> is searched for | |
8426 | the value that corresponds to the key. The search is case-insensitive. If the | |
8427 | key is found, <'string2'> is expanded, and replaces the whole item; otherwise | |
8428 | <'string3'> is used. During the expansion of <'string2'> the variable $value$ | |
8429 | contains the value that has been extracted. Afterwards, it is restored to any | |
8430 | previous value it might have had. | |
168e428f PH |
8431 | + |
8432 | If \{<'string3'>\} is omitted, the item is replaced by an empty string if the | |
8433 | key is not found. If \{<'string2'>\} is also omitted, the value that was | |
8434 | extracted is used. Thus, for example, these two expansions are identical, and | |
8435 | yield ``2001'': | |
8436 | ||
8437 | ${extract{gid}{uid=1984 gid=2001}} | |
8438 | ${extract{gid}{uid=1984 gid=2001}{$value}} | |
8439 | + | |
8440 | Instead of \{<'string3'>\} the word ``fail'' (not in curly brackets) can | |
8441 | appear, for example: | |
8442 | ||
8443 | ${extract{Z}{A=... B=...}{$value} fail } | |
8444 | + | |
8445 | This forces an expansion failure (see section <<SECTforexpfai>>); | |
8446 | {<'string2'>\} must be present for ``fail'' to be recognized. | |
8447 | ||
8448 | ||
8449 | *\$\{extract\{*<'number'>*\}\{*<'separators'>*\}\{*<'string1'>*\}\{*<'string2'>*\}\{*<'string3'>*\}\}*:: | |
8450 | cindex:[expansion,extracting substrings by number] | |
8451 | The <'number'> argument must consist entirely of decimal digits, | |
068aaea8 | 8452 | apart from leading and trailing white space, which is ignored. |
168e428f PH |
8453 | This is what distinguishes this form of %extract% from the previous kind. It |
8454 | behaves in the same way, except that, instead of extracting a named field, it | |
8455 | extracts from <'string1'> the field whose number is given as the first | |
8456 | argument. You can use $value$ in <'string2'> or `fail` instead of | |
8457 | <'string3'> as before. | |
8458 | + | |
8459 | The fields in the string are separated by any one of the characters in the | |
8460 | separator string. These may include space or tab characters. | |
8461 | The first field is numbered one. If the number is negative, the fields are | |
8462 | counted from the end of the string, with the rightmost one numbered -1. If the | |
8463 | number given is zero, the entire string is returned. If the modulus of the | |
8464 | number is greater than the number of fields in the string, the result is the | |
8465 | expansion of <'string3'>, or the empty string if <'string3'> is not provided. | |
8466 | For example: | |
8467 | ||
8468 | ${extract{2}{:}{x:42:99:& Mailer::/bin/bash}} | |
8469 | + | |
8470 | yields ``42'', and | |
8471 | ||
8472 | ${extract{-4}{:}{x:42:99:& Mailer::/bin/bash}} | |
8473 | + | |
8474 | yields ``99''. Two successive separators mean that the field between them is | |
8475 | empty (for example, the fifth field above). | |
8476 | ||
8477 | ||
8478 | *\$\{hash\{*<'string1'>*\}\{*<'string2'>*\}\{*<'string3'>*\}\}*:: | |
8479 | cindex:[hash function,textual] | |
8480 | cindex:[expansion,textual hash] | |
8481 | This is a textual hashing function, and was the first to be implemented in | |
8482 | early versions of Exim. In current releases, there are other hashing functions | |
8483 | (numeric, MD5, and SHA-1), which are described below. | |
8484 | + | |
8485 | The first two strings, after expansion, must be numbers. Call them <'m'> and | |
8486 | <'n'>. If you are using fixed values for these numbers, that is, if <'string1'> | |
8487 | and <'string2'> do not change when they are expanded, you can use the | |
8488 | simpler operator notation that avoids some of the braces: | |
8489 | ||
8490 | ${hash_<n>_<m>:<string>} | |
8491 | + | |
8492 | The second number is optional (in both notations). | |
8493 | + | |
8494 | If <'n'> is greater than or equal to the length of the string, the expansion | |
8495 | item returns the string. Otherwise it computes a new string of length <'n'> by | |
8496 | applying a hashing function to the string. The new string consists of | |
8497 | characters taken from the first <'m'> characters of the string | |
8498 | ||
8499 | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQWRSTUVWXYZ0123456789 | |
8500 | + | |
8501 | If <'m'> is not present the value 26 is used, so that only lower case | |
8502 | letters appear. For example: | |
8503 | + | |
8504 | &&& | |
8505 | `\${hash{3}{monty}} ` yields `jmg` | |
8506 | `\${hash{5}{monty}} ` yields `monty` | |
8507 | `\${hash{4}{62}{monty python}}` yields `fbWx` | |
8508 | &&& | |
8509 | ||
8510 | ||
8511 | *\$header_*<'header~name'>*:*~or~*\$h_*<'header~name'>*:*:: | |
8512 | See *\$rheader* below. | |
8513 | ||
8514 | *\$bheader_*<'header~name'>*:*~or~*\$bh_*<'header~name'>*:*:: | |
8515 | See *\$rheader* below. | |
8516 | ||
8517 | *\$rheader_*<'header~name'>*:*~or~*\$rh_*<'header~name'>*:*:: | |
8518 | cindex:[expansion,header insertion] | |
8519 | cindex:[$header_$] | |
8520 | cindex:[$bheader_$] | |
8521 | cindex:[$rheader_$] | |
8522 | cindex:[header lines,in expansion strings] | |
8523 | cindex:[header lines,character sets] | |
8524 | cindex:[header lines,decoding] | |
8525 | Substitute the contents of the named message header line, for example | |
8526 | ||
8527 | $header_reply-to: | |
8528 | + | |
8529 | The newline that terminates a header line is not included in the expansion, but | |
8530 | internal newlines (caused by splitting the header line over several physical | |
8531 | lines) may be present. | |
8532 | + | |
8533 | The difference between %rheader%, %bheader%, and %header% is in the way the | |
8534 | data in the header line is interpreted. | |
8535 | + | |
8536 | -- | |
068aaea8 | 8537 | - cindex:[white space,in header lines] |
168e428f | 8538 | %rheader% gives the original ``raw'' content of the header line, with no |
068aaea8 | 8539 | processing at all, and without the removal of leading and trailing white space. |
168e428f PH |
8540 | |
8541 | - cindex:[base64 encoding,in header lines] | |
068aaea8 | 8542 | %bheader% removes leading and trailing white space, and then decodes base64 or |
168e428f PH |
8543 | quoted-printable MIME ``words'' within the header text, but does no character |
8544 | set translation. If decoding of what looks superficially like a MIME ``word'' | |
8545 | fails, the raw string is returned. If decoding | |
8546 | cindex:[binary zero,in header line] | |
8547 | produces a binary zero character, it is replaced by a question mark -- this is | |
8548 | what Exim does for binary zeros that are actually received in header lines. | |
8549 | ||
8550 | - %header% tries to translate the string as decoded by %bheader% to a standard | |
8551 | character set. This is an attempt to produce the same string as would be | |
8552 | displayed on a user's MUA. If translation fails, the %bheader% string is | |
8553 | returned. Translation is attempted only on operating systems that support the | |
8554 | 'iconv()' function. This is indicated by the compile-time macro | |
8555 | HAVE_ICONV in a system Makefile or in _Local/Makefile_. | |
8556 | -- | |
8557 | + | |
8558 | In a filter file, the target character set for %header% can be specified by a | |
8559 | command of the following form: | |
8560 | ||
8561 | headers charset "UTF-8" | |
8562 | + | |
8563 | This command affects all references to $h_$ (or $header_$) expansions in | |
8564 | subsequently obeyed filter commands. In the absence of this command, the target | |
8565 | character set in a filter is taken from the setting of the %headers_charset% | |
8566 | option in the runtime configuration. The value of this option defaults to the | |
8567 | value of HEADERS_CHARSET in _Local/Makefile_. The ultimate default is | |
8568 | ISO-8859-1. | |
8569 | + | |
8570 | Header names follow the syntax of RFC 2822, which states that they may contain | |
8571 | any printing characters except space and colon. Consequently, curly brackets | |
8572 | 'do not' terminate header names, and should not be used to enclose them as | |
8573 | if they were variables. Attempting to do so causes a syntax error. | |
8574 | + | |
8575 | Only header lines that are common to all copies of a message are visible to | |
8576 | this mechanism. These are the original header lines that are received with the | |
8577 | message, and any that are added by an ACL %warn% statement or by a system | |
8578 | filter. Header lines that are added to a particular copy of a message by a | |
8579 | router or transport are not accessible. | |
8580 | + | |
8581 | For incoming SMTP messages, no header lines are visible in ACLs that are obeyed | |
8582 | before the DATA ACL, because the header structure is not set up until the | |
8583 | message is received. Header lines that are added by %warn% statements in a | |
8584 | RCPT ACL (for example) are saved until the message's incoming header lines | |
8585 | are available, at which point they are added. When a DATA ACL is running, | |
8586 | however, header lines added by earlier ACLs are visible. | |
8587 | + | |
8588 | Upper case and lower case letters are synonymous in header names. If the | |
8589 | following character is white space, the terminating colon may be omitted, but | |
8590 | this is not recommended, because you may then forget it when it is needed. When | |
8591 | white space terminates the header name, it is included in the expanded string. | |
8592 | If the message does not contain the given header, the expansion item is | |
8593 | replaced by an empty string. (See the %def% condition in section <<SECTexpcond>> | |
8594 | for a means of testing for the existence of a header.) | |
8595 | + | |
8596 | If there is more than one header with the same name, they are all | |
8597 | concatenated to form the substitution string, up to a maximum length of 64K. A | |
8598 | newline character is inserted between each line. For the %header% expansion, | |
8599 | for those headers that contain lists of addresses, a comma is also inserted at | |
8600 | the junctions between lines. This does not happen for the %rheader% expansion. | |
8601 | ||
8602 | ||
8603 | ||
8604 | *\$\{hmac\{*<'hashname'>*\}\{*<'secret'>*\}\{*<'string'>*\}\}*:: | |
8605 | cindex:[expansion,hmac hashing] | |
8606 | This function uses cryptographic hashing (either MD5 or SHA-1) to convert a | |
8607 | shared secret and some text into a message authentication code, as specified in | |
8608 | RFC 2104. This differs from `\$\{md5:secret_text...\}` or | |
8609 | `\$\{sha1:secret_text...\}` in that the hmac step adds a signature to the | |
8610 | cryptographic hash, allowing for authentication that is not possible with MD5 | |
8611 | or SHA-1 alone. The hash name must expand to either `md5` or `sha1` at present. | |
8612 | For example: | |
8613 | ||
8614 | ${hmac{md5}{somesecret}{$primary_hostname $tod_log}} | |
8615 | + | |
8616 | For the hostname 'mail.example.com' and time 2002-10-17 11:30:59, this | |
8617 | produces: | |
8618 | ||
8619 | dd97e3ba5d1a61b5006108f8c8252953 | |
8620 | + | |
8621 | As an example of how this might be used, you might put in the main part of | |
8622 | an Exim configuration: | |
8623 | ||
8624 | SPAMSCAN_SECRET=cohgheeLei2thahw | |
8625 | + | |
8626 | In a router or a transport you could then have: | |
8627 | + | |
8628 | .... | |
8629 | headers_add = \ | |
d1e83bff | 8630 | X-Spam-Scanned: ${primary_hostname} ${message_exim_id} \ |
168e428f | 8631 | ${hmac{md5}{SPAMSCAN_SECRET}\ |
d1e83bff | 8632 | {${primary_hostname},${message_exim_id},$h_message-id:}} |
168e428f PH |
8633 | .... |
8634 | + | |
8635 | Then given a message, you can check where it was scanned by looking at the | |
8636 | 'X-Spam-Scanned:' header line. If you know the secret, you can check that this | |
8637 | header line is authentic by recomputing the authentication code from the host | |
8638 | name, message ID and the 'Message-id:' header line. This can be done using | |
8639 | Exim's %-be% option, or by other means, for example by using the | |
8640 | 'hmac_md5_hex()' function in Perl. | |
8641 | ||
8642 | ||
8643 | *\$\{if~*<'condition'>*~\{*<'string1'>*\}\{*<'string2'>*\}\}*:: | |
8644 | cindex:[expansion,conditional] | |
8645 | If <'condition'> is true, <'string1'> is expanded and replaces the whole item; | |
8646 | otherwise <'string2'> is used. The available conditions are described in | |
8647 | section <<SECTexpcond>> below. For example: | |
8648 | ||
8649 | ${if eq {$local_part}{postmaster} {yes}{no} } | |
8650 | + | |
8651 | The second string need not be present; if it is not and the condition is not | |
8652 | true, the item is replaced with nothing. Alternatively, the word ``fail'' may be | |
8653 | present instead of the second string (without any curly brackets). In this | |
8654 | case, the expansion is forced to fail if the condition is not true (see section | |
8655 | <<SECTforexpfai>>). | |
8656 | + | |
8657 | If both strings are omitted, the result is the string `true` if the condition | |
8658 | is true, and the empty string if the condition is false. This makes it less | |
8659 | cumbersome to write custom ACL and router conditions. For example, instead of | |
8660 | ||
8661 | condition = ${if >{$acl_m4}{3}{true}{false}} | |
8662 | + | |
8663 | you can use | |
8664 | ||
8665 | condition = ${if >{$acl_m4}{3}} | |
8666 | ||
8667 | ||
8668 | ||
8669 | *\$\{length\{*<'string1'>*\}\{*<'string2'>*\}\}*:: | |
8670 | cindex:[expansion,string truncation] | |
8671 | The %length% item is used to extract the initial portion of a string. Both | |
8672 | strings are expanded, and the first one must yield a number, <'n'>, say. If you | |
8673 | are using a fixed value for the number, that is, if <'string1'> does not change | |
8674 | when expanded, you can use the simpler operator notation that avoids some of | |
8675 | the braces: | |
8676 | ||
8677 | ${length_<n>:<string>} | |
8678 | + | |
8679 | The result of this item is either the first <'n'> characters or the whole | |
8680 | of <'string2'>, whichever is the shorter. Do not confuse %length% with | |
8681 | %strlen%, which gives the length of a string. | |
8682 | ||
8683 | ||
8684 | *\$\{lookup\{*<'key'>*\}~*<'search~type'>*~\{*<'file'>*\}~\{*<'string1'>*\}~\{*<'string2'>*\}\}*:: | |
8685 | This is the first of one of two different types of lookup item, which are both | |
8686 | described in the next item. | |
8687 | ||
8688 | *\$\{lookup~*<'search~type'>*~\{*<'query'>*\}~\{*<'string1'>*\}~\{*<'string2'>*\}\}*:: | |
8689 | cindex:[expansion,lookup in] | |
8690 | cindex:[file,lookup] | |
8691 | cindex:[lookup,in expanded string] | |
8692 | The two forms of lookup item specify data lookups in files and databases, as | |
8693 | discussed in chapter <<CHAPfdlookup>>. The first form is used for single-key | |
8694 | lookups, and the second is used for query-style lookups. The <'key'>, <'file'>, | |
8695 | and <'query'> strings are expanded before use. | |
8696 | + | |
8697 | If there is any white space in a lookup item which is part of a filter command, | |
8698 | a retry or rewrite rule, a routing rule for the ^manualroute^ router, or any | |
8699 | other place where white space is significant, the lookup item must be enclosed | |
8700 | in double quotes. The use of data lookups in users' filter files may be locked | |
8701 | out by the system administrator. | |
8702 | + | |
8703 | cindex:[$value$] | |
8704 | If the lookup succeeds, <'string1'> is expanded and replaces the entire item. | |
8705 | During its expansion, the variable $value$ contains the data returned by the | |
8706 | lookup. Afterwards it reverts to the value it had previously (at the outer | |
8707 | level it is empty). If the lookup fails, <'string2'> is expanded and replaces | |
8708 | the entire item. If \{<'string2'>\} is omitted, the replacement is the empty | |
8709 | string on failure. If <'string2'> is provided, it can itself be a nested | |
8710 | lookup, thus providing a mechanism for looking up a default value when the | |
8711 | original lookup fails. | |
8712 | + | |
8713 | If a nested lookup is used as part of <'string1'>, $value$ contains the data | |
8714 | for the outer lookup while the parameters of the second lookup are expanded, | |
8715 | and also while <'string2'> of the second lookup is expanded, should the second | |
8716 | lookup fail. + Instead of \{<'string2'>\} the word ``fail'' can appear, and in | |
8717 | this case, if the lookup fails, the entire expansion is forced to fail (see | |
8718 | section <<SECTforexpfai>>). If both \{<'string1'>\} and \{<'string2'>\} are | |
8719 | omitted, the result is the looked up value in the case of a successful lookup, | |
8720 | and nothing in the case of failure. | |
8721 | + | |
8722 | For single-key lookups, the string ``partial'' is permitted to precede the | |
8723 | search type in order to do partial matching, and \* or \*@ may follow a search | |
8724 | type to request default lookups if the key does not match (see sections | |
8725 | <<SECTdefaultvaluelookups>> and <<SECTpartiallookup>> for details). | |
8726 | + | |
8727 | cindex:[numerical variables ($1$ $2$ etc),in lookup expansion] | |
8728 | If a partial search is used, the variables $1$ and $2$ contain the wild | |
8729 | and non-wild parts of the key during the expansion of the replacement text. | |
8730 | They return to their previous values at the end of the lookup item. | |
8731 | + | |
8732 | This example looks up the postmaster alias in the conventional alias file: | |
8733 | ||
8734 | ${lookup {postmaster} lsearch {/etc/aliases} {$value}} | |
8735 | + | |
8736 | This example uses NIS+ to look up the full name of the user corresponding to | |
8737 | the local part of an address, forcing the expansion to fail if it is not found: | |
8738 | + | |
8739 | .... | |
8740 | ${lookup nisplus {[name=$local_part],passwd.org_dir:gcos} \ | |
8741 | {$value}fail} | |
8742 | .... | |
8743 | ||
8744 | ||
8745 | *\$\{nhash\{*<'string1'>*\}\{*<'string2'>*\}\{*<'string3'>*\}\}*:: | |
8746 | cindex:[expansion,numeric hash] | |
8747 | cindex:[hash function,numeric] | |
8748 | The three strings are expanded; the first two must yield numbers. Call them | |
8749 | <'n'> and <'m'>. If you are using fixed values for these numbers, that is, if | |
8750 | <'string1'> and <'string2'> do not change when they are expanded, you can use | |
8751 | the simpler operator notation that avoids some of the braces: | |
8752 | ||
8753 | ${nhash_<n>_<m>:<string>} | |
8754 | + | |
8755 | The second number is optional (in both notations). If there is only one number, | |
8756 | the result is a number in the range 0--<'n'>-1. Otherwise, the string is | |
8757 | processed by a div/mod hash function that returns two numbers, separated by a | |
8758 | slash, in the ranges 0 to <'n'>-1 and 0 to <'m'>-1, respectively. For example, | |
8759 | ||
8760 | ${nhash{8}{64}{supercalifragilisticexpialidocious}} | |
8761 | + | |
8762 | returns the string ``6/33''. | |
8763 | ||
8764 | ||
8765 | ||
8766 | *\$\{perl\{*<'subroutine'>*\}\{*<'arg'>*\}\{*<'arg'>*\}...\}*:: | |
8767 | cindex:[Perl,use in expanded string] | |
8768 | cindex:[expansion,calling Perl from] | |
8769 | This item is available only if Exim has been built to include an embedded Perl | |
8770 | interpreter. The subroutine name and the arguments are first separately | |
8771 | expanded, and then the Perl subroutine is called with those arguments. No | |
8772 | additional arguments need be given; the maximum number permitted, including the | |
8773 | name of the subroutine, is nine. | |
8774 | + | |
8775 | The return value of the subroutine is inserted into the expanded string, unless | |
8776 | the return value is %undef%. In that case, the expansion fails in the same way | |
8777 | as an explicit ``fail'' on a lookup item. | |
8778 | The return value is a scalar. Whatever you return is evaluated in a scalar | |
8779 | context. For example, if you return the name of a Perl vector, the | |
8780 | return value is the size of the vector, not its contents. | |
8781 | + | |
8782 | If the subroutine exits by calling Perl's %die% function, the expansion fails | |
8783 | with the error message that was passed to %die%. More details of the embedded | |
8784 | Perl facility are given in chapter <<CHAPperl>>. | |
8785 | + | |
8786 | The ^redirect^ router has an option called %forbid_filter_perl% which locks | |
8787 | out the use of this expansion item in filter files. | |
8788 | ||
8789 | ||
068aaea8 PH |
8790 | *\$\{prvs\{*<'address'>*\}\{*<'secret'>*\}\{*<'keynumber'>*\}\}*:: |
8791 | + | |
8792 | [revisionflag="changed"] | |
8793 | cindex:[prvs,expansion item] | |
8794 | The first argument is a complete email address and the second is secret | |
8795 | keystring. The third argument, specifying a key number, is optional. If absent, | |
8796 | it defaults to 0. The result of the expansion is a prvs-signed email address, | |
8797 | to be typically used with the %return_path% option on an ^smtp^ transport as | |
8798 | part of a bounce address tag validation (BATV) scheme. For more discussion and | |
8799 | an example, see section <<SECTverifyPRVS>>. | |
8800 | ||
8801 | ||
8802 | *\$\{prvscheck\{*<'address'>*\}\{*<'secret'>*\}\{*<'string'>*\}\}*:: | |
8803 | + | |
8804 | [revisionflag="changed"] | |
8805 | cindex:[prvscheck,expansion item] | |
8806 | This expansion item is the complement of the %prvs% item. It is used for | |
8807 | checking prvs-signed addresses. If the expansion of the first argument does not | |
8808 | yield a syntactically valid prvs-signed address, the whole item expands to the | |
8809 | empty string. When the first argument does expand to a syntactically valid | |
8810 | prvs-signed address, the second argument is expanded, with the prvs-decoded | |
8811 | version of the address and the key number extracted from the address in the | |
8812 | variables $prvscheck_address$ and $prvscheck_keynum$, respectively. | |
8813 | + | |
8814 | [revisionflag="changed"] | |
8815 | These two variables can be used in the expansion of the second argument to | |
8816 | retrieve the secret. The validity of the prvs-signed address is then checked | |
8817 | against the secret. The result is stored in the variable $prvscheck_result$, | |
8818 | which is empty for failure or ``1'' for success. | |
8819 | + | |
8820 | [revisionflag="changed"] | |
8821 | The third argument is optional; if it is missing, it defaults to an empty | |
8822 | string. This argument is now expanded. If the result is an empty string, the | |
8823 | result of the expansion is the decoded version of the address. This is the case | |
8824 | whether or not the signature was valid. Otherwise, the result of the expansion | |
8825 | is the expansion of the third argument. | |
8826 | + | |
8827 | [revisionflag="changed"] | |
8828 | All three variables can be used in the expansion of the third argument. | |
8829 | However, once the expansion is complete, only $prvscheck_result$ remains set. | |
8830 | For more discussion and an example, see section <<SECTverifyPRVS>>. | |
8831 | ||
8832 | ||
168e428f PH |
8833 | *\$\{readfile\{*<'file~name'>*\}\{*<'eol~string'>*\}\}*:: |
8834 | cindex:[expansion,inserting an entire file] | |
8835 | cindex:[file,inserting into expansion] | |
8836 | The file name and end-of-line string are first expanded separately. The file is | |
8837 | then read, and its contents replace the entire item. All newline characters in | |
8838 | the file are replaced by the end-of-line string if it is present. Otherwise, | |
8839 | newlines are left in the string. | |
8840 | String expansion is not applied to the contents of the file. If you want this, | |
8841 | you must wrap the item in an %expand% operator. If the file cannot be read, the | |
8842 | string expansion fails. | |
8843 | + | |
8844 | The ^redirect^ router has an option called %forbid_filter_readfile% which | |
8845 | locks out the use of this expansion item in filter files. | |
8846 | ||
8847 | ||
8848 | ||
8849 | *\$\{readsocket\{*<'name'>*\}\{*<'request'>*\}\{*<'timeout'>*\}\{*<'eol~string'>*\}\{*<'fail~string'>*\}\}*:: | |
8850 | cindex:[expansion,inserting from a socket] | |
8851 | cindex:[socket, use of in expansion] | |
8852 | This item inserts data that is read from a Unix domain socket into the expanded | |
8853 | string. The minimal way of using it uses just two arguments: | |
8854 | ||
8855 | ${readsocket{/socket/name}{request string}} | |
8856 | + | |
8857 | Exim connects to the socket, writes the request string (unless it is an | |
8858 | empty string) and reads from the socket until an end-of-file is read. A timeout | |
8859 | of 5 seconds is applied. Additional, optional arguments extend what can be | |
8860 | done. Firstly, you can vary the timeout. For example: | |
8861 | ||
8862 | ${readsocket{/socket/name}{request-string}{3s}} | |
8863 | + | |
8864 | A fourth argument allows you to change any newlines that are in the data | |
8865 | that is read, in the same way as for %readfile% (see above). This example turns | |
8866 | them into spaces: | |
8867 | ||
8868 | ${readsocket{/socket/name}{request-string}{3s}{ }} | |
8869 | + | |
8870 | As with all expansions, the substrings are expanded before the processing | |
8871 | happens. Errors in these sub-expansions cause the expansion to fail. In | |
8872 | addition, the following errors can occur: | |
8873 | + | |
8874 | -- | |
8875 | - Failure to create a socket file descriptor; | |
8876 | ||
8877 | - Failure to connect the socket; | |
8878 | ||
8879 | - Failure to write the request-string; | |
8880 | ||
8881 | - Timeout on reading from the socket. | |
8882 | -- | |
8883 | + | |
8884 | By default, any of these errors causes the expansion to fail. However, if | |
8885 | you supply a fifth substring, it is expanded and used when any of the above | |
8886 | errors occurs. For example: | |
8887 | + | |
8888 | .... | |
8889 | ${readsocket{/socket/name}{request-string}{3s}{\n}\ | |
8890 | {socket failure}} | |
8891 | .... | |
8892 | + | |
8893 | You can test for the existence of the socket by wrapping this expansion in | |
8894 | `\$\{if exists`, but there is a race condition between that test and the | |
8895 | actual opening of the socket, so it is safer to use the fifth argument if you | |
8896 | want to be absolutely sure of avoiding an expansion error for a non-existent | |
8897 | socket. | |
8898 | + | |
8899 | The ^redirect^ router has an option called %forbid_filter_readsocket% which | |
8900 | locks out the use of this expansion item in filter files. | |
8901 | ||
8902 | *\$rheader_*<'header~name'>*:~or~\$rh_*<'header~name'>*:*:: | |
8903 | This item inserts ``raw'' header lines. It is described with the %header% | |
8904 | expansion item above. | |
8905 | ||
8906 | ||
8907 | ||
8908 | *\$\{run\{*<'command'>*~*<'args'>*\}\{*<'string1'>*\}\{*<'string2'>*\}\}*:: | |
8909 | cindex:[expansion,running a command] | |
8910 | The command and its arguments are first expanded separately, and then the | |
8911 | command is run in a separate process, but under the same uid and gid. As in | |
8912 | other command executions from Exim, a shell is not used by default. If you want | |
8913 | a shell, you must explicitly code it. | |
8914 | + | |
068aaea8 | 8915 | [revisionflag="changed"] |
168e428f | 8916 | cindex:[return code,from %run% expansion] |
068aaea8 | 8917 | cindex:[$value$] |
168e428f PH |
8918 | If the command succeeds (gives a zero return code) <'string1'> is expanded and |
8919 | replaces the entire item; during this expansion, the standard output from the | |
8920 | command is in the variable $value$. If the command fails, <'string2'>, if | |
068aaea8 PH |
8921 | present, is expanded and used. Once again, during the expansion, the standard |
8922 | output from the command is in the variable $value$. If <'string2'> is absent, | |
8923 | the result is empty. Alternatively, <'string2'> can be the word ``fail'' (not | |
8924 | in braces) to force expansion failure if the command does not succeed. If both | |
8925 | strings are omitted, the result is contents of the standard output on success, | |
8926 | and nothing on failure. | |
8927 | + | |
8928 | cindex:[$runrc$] | |
168e428f PH |
8929 | The return code from the command is put in the variable $runrc$, and this |
8930 | remains set afterwards, so in a filter file you can do things like this: | |
8931 | ||
8932 | if "${run{x y z}{}}$runrc" is 1 then ... | |
8933 | elif $runrc is 2 then ... | |
8934 | ... | |
8935 | endif | |
8936 | + | |
8937 | If execution of the command fails (for example, the command does not exist), | |
8938 | the return code is 127 -- the same code that shells use for non-existent | |
8939 | commands. | |
8940 | + | |
8941 | *Warning*: In a router or transport, you cannot assume the order in which | |
8942 | option values are expanded, except for those pre-conditions whose order of | |
8943 | testing is documented. Therefore, you cannot reliably expect to set $runrc$ | |
8944 | by the expansion of one option, and use it in another. | |
8945 | + | |
8946 | The ^redirect^ router has an option called %forbid_filter_run% which locks | |
8947 | out the use of this expansion item in filter files. | |
8948 | ||
8949 | ||
8950 | *\$\{sg\{*<'subject'>*\}\{*<'regex'>*\}\{*<'replacement'>*\}\}*:: | |
8951 | cindex:[expansion,string substitution] | |
8952 | This item works like Perl's substitution operator (s) with the global (/g) | |
8953 | option; hence its name. However, unlike the Perl equivalent, Exim does not | |
8954 | modify the subject string; instead it returns the modified string for insertion | |
8955 | into the overall expansion. The item takes three arguments: the subject string, | |
8956 | a regular expression, and a substitution string. For example | |
8957 | ||
8958 | ${sg{abcdefabcdef}{abc}{xyz}} | |
8959 | + | |
8960 | yields ``xyzdefxyzdef''. Because all three arguments are expanded before use, if | |
8961 | any \$ or \ characters are required in the regular expression or in the | |
8962 | substitution string, they have to be escaped. For example | |
8963 | ||
8964 | ${sg{abcdef}{^(...)(...)\$}{\$2\$1}} | |
8965 | + | |
8966 | yields ``defabc'', and | |
8967 | ||
8968 | ${sg{1=A 4=D 3=C}{\N(\d+)=\N}{K\$1=}} | |
8969 | + | |
8970 | yields ``K1=A K4=D K3=C''. Note the use of `\N` to protect the contents of | |
8971 | the regular expression from string expansion. | |
8972 | ||
8973 | ||
8974 | ||
8975 | *\$\{substr\{*<'string1'>*\}\{*<'string2'>*\}\{*<'string3'>*\}\}*:: | |
8976 | cindex:[%substr%] | |
8977 | cindex:[substring extraction] | |
8978 | cindex:[expansion,substring extraction] | |
8979 | The three strings are expanded; the first two must yield numbers. Call them | |
8980 | <'n'> and <'m'>. If you are using fixed values for these numbers, that is, if | |
8981 | <'string1'> and <'string2'> do not change when they are expanded, you can use | |
8982 | the simpler operator notation that avoids some of the braces: | |
8983 | ||
8984 | ${substr_<n>_<m>:<string>} | |
8985 | + | |
8986 | The second number is optional (in both notations). | |
8987 | If it is absent in the simpler format, the preceding underscore must also be | |
8988 | omitted. | |
8989 | + | |
8990 | The %substr% item can be used to extract more general substrings than | |
8991 | %length%. The first number, <'n'>, is a starting offset, and <'m'> is the | |
8992 | length required. For example | |
8993 | ||
8994 | ${substr{3}{2}{$local_part}} | |
8995 | + | |
8996 | If the starting offset is greater than the string length the result is the | |
8997 | null string; if the length plus starting offset is greater than the string | |
8998 | length, the result is the right-hand part of the string, starting from the | |
8999 | given offset. The first character in the string has offset zero. | |
9000 | + | |
9001 | The %substr% expansion item can take negative offset values to count | |
9002 | from the right-hand end of its operand. The last character is offset -1, the | |
9003 | second-last is offset -2, and so on. Thus, for example, | |
9004 | ||
9005 | ${substr{-5}{2}{1234567}} | |
9006 | + | |
9007 | yields ``34''. If the absolute value of a negative offset is greater than the | |
9008 | length of the string, the substring starts at the beginning of the string, and | |
9009 | the length is reduced by the amount of overshoot. Thus, for example, | |
9010 | ||
9011 | ${substr{-5}{2}{12}} | |
9012 | + | |
9013 | yields an empty string, but | |
9014 | ||
9015 | ${substr{-3}{2}{12}} | |
9016 | + | |
9017 | yields ``1''. | |
9018 | + | |
9019 | When the second number is omitted from %substr%, the remainder of the string | |
9020 | is taken if the offset is positive. If it is negative, all characters in the | |
9021 | string preceding the offset point are taken. For example, an offset of -1 and | |
9022 | no length, as in these semantically identical examples: | |
9023 | ||
9024 | ${substr_-1:abcde} | |
9025 | ${substr{-1}{abcde}} | |
9026 | + | |
9027 | yields all but the last character of the string, that is, ``abcd''. | |
9028 | ||
9029 | ||
9030 | ||
9031 | *\$\{tr\{*<'subject'>*\}\{*<'characters'>*\}\{*<'replacements'>*\}\}*:: | |
9032 | cindex:[expansion,character translation] | |
9033 | This item does single-character translation on its subject string. The second | |
9034 | argument is a list of characters to be translated in the subject string. Each | |
9035 | matching character is replaced by the corresponding character from the | |
9036 | replacement list. For example | |
9037 | ||
9038 | ${tr{abcdea}{ac}{13}} | |
9039 | + | |
9040 | yields `1b3de1`. If there are duplicates in the second character string, the | |
9041 | last occurrence is used. If the third string is shorter than the second, its | |
9042 | last character is replicated. However, if it is empty, no translation takes | |
9043 | place. | |
9044 | ||
9045 | ||
9046 | ||
9047 | [[SECTexpop]] | |
9048 | Expansion operators | |
9049 | ~~~~~~~~~~~~~~~~~~~ | |
9050 | cindex:[expansion,operators] | |
9051 | For expansion items that perform transformations on a single argument string, | |
9052 | the ``operator'' notation is used because it is simpler and uses fewer braces. | |
9053 | The substring is first expanded before the operation is applied to it. The | |
9054 | following operations can be performed: | |
9055 | ||
9056 | *\$\{address:*<'string'>*\}*:: | |
9057 | cindex:[expansion,RFC 2822 address handling] | |
9058 | The string is interpreted as an RFC 2822 address, as it might appear in a | |
9059 | header line, and the effective address is extracted from it. If the string does | |
9060 | not parse successfully, the result is empty. | |
9061 | ||
9062 | ||
9063 | *\$\{base62:*<'digits'>*\}*:: | |
068aaea8 PH |
9064 | + |
9065 | [revisionflag="changed"] | |
168e428f PH |
9066 | cindex:[base62] |
9067 | cindex:[expansion,conversion to base 62] | |
9068 | The string must consist entirely of decimal digits. The number is converted to | |
068aaea8 PH |
9069 | base 62 and output as a string of six characters, including leading zeros. In |
9070 | the few operating environments where Exim uses base 36 instead of base 62 for | |
9071 | its message identifiers (because those systems do not have case-sensitive file | |
9072 | names), base 36 is used by this operator, despite its name. *Note*: Just to be | |
9073 | absolutely clear: this is 'not' base64 encoding. | |
168e428f PH |
9074 | |
9075 | *\$\{base62d:*<'base-62~digits'>*\}*:: | |
068aaea8 PH |
9076 | + |
9077 | [revisionflag="changed"] | |
168e428f PH |
9078 | cindex:[base62] |
9079 | cindex:[expansion,conversion to base 62] | |
068aaea8 PH |
9080 | The string must consist entirely of base-62 digits, or, in operating |
9081 | environments where Exim uses base 36 instead of base 62 for its message | |
9082 | identifiers, base-36 digits. The number is converted to decimal and output as a | |
9083 | string. | |
168e428f PH |
9084 | |
9085 | ||
9086 | *\$\{domain:*<'string'>*\}*:: | |
9087 | cindex:[domain,extraction] | |
9088 | cindex:[expansion,domain extraction] | |
9089 | The string is interpreted as an RFC 2822 address and the domain is extracted | |
9090 | from it. If the string does not parse successfully, the result is empty. | |
9091 | ||
9092 | ||
9093 | *\$\{escape:*<'string'>*\}*:: | |
9094 | cindex:[expansion,escaping non-printing characters] | |
9095 | If the string contains any non-printing characters, they are converted to | |
9096 | escape sequences starting with a backslash. Whether characters with the most | |
9097 | significant bit set (so-called ``8-bit characters'') count as printing or not is | |
9098 | controlled by the %print_topbitchars% option. | |
9099 | ||
9100 | ||
9101 | *\$\{eval:*<'string'>*\}*:: | |
9102 | *\$\{eval10:*<'string'>*\}*:: | |
068aaea8 PH |
9103 | + |
9104 | [revisionflag="changed"] | |
168e428f PH |
9105 | cindex:[expansion,expression evaluation] |
9106 | cindex:[expansion,arithmetic expression] | |
9107 | These items supports simple arithmetic in expansion strings. The string (after | |
9108 | expansion) must be a conventional arithmetic expression, but it is limited to | |
068aaea8 PH |
9109 | five basic operators (plus, minus, times, divide, remainder) and parentheses. |
9110 | All operations are carried out using integer arithmetic. Plus and minus have a | |
9111 | lower priority than times, divide, and remainder; operators with the same | |
9112 | priority are evaluated from left to right. | |
168e428f PH |
9113 | + |
9114 | For %eval%, numbers may be decimal, octal (starting with ``0'') or hexadecimal | |
9115 | (starting with ``0x''). For %eval10%, all numbers are taken as decimal, even if | |
9116 | they start with a leading zero. This can be useful when processing numbers | |
9117 | extracted from dates or times, which often do have leading zeros. | |
9118 | + | |
9119 | A number may be followed by ``K'' or ``M'' to multiply it by 1024 or 1024\*1024, | |
9120 | respectively. Negative numbers are supported. The result of the computation is | |
9121 | a decimal representation of the answer (without ``K'' or ``M''). For example: | |
9122 | + | |
068aaea8 | 9123 | [revisionflag="changed"] |
168e428f PH |
9124 | &&& |
9125 | `\${eval:1+1} ` yields 2 | |
9126 | `\${eval:1+2*3} ` yields 7 | |
9127 | `\${eval:(1+2)*3} ` yields 9 | |
068aaea8 | 9128 | `\${eval:2+42%5} ` yields 4 |
168e428f PH |
9129 | &&& |
9130 | + | |
9131 | As a more realistic example, in an ACL you might have | |
9132 | + | |
9133 | .... | |
9134 | deny message = Too many bad recipients | |
9135 | condition = \ | |
9136 | ${if and { \ | |
9137 | {>{$rcpt_count}{10}} \ | |
9138 | { \ | |
9139 | < \ | |
9140 | {$recipients_count} \ | |
9141 | {${eval:$rcpt_count/2}} \ | |
9142 | } \ | |
9143 | }{yes}{no}} | |
9144 | .... | |
9145 | + | |
9146 | The condition is true if there have been more than 10 RCPT commands and | |
9147 | fewer than half of them have resulted in a valid recipient. | |
9148 | ||
9149 | ||
9150 | *\$\{expand:*<'string'>*\}*:: | |
9151 | cindex:[expansion,re-expansion of substring] | |
9152 | The %expand% operator causes a string to be expanded for a second time. For | |
9153 | example, | |
9154 | ||
9155 | ${expand:${lookup{$domain}dbm{/some/file}{$value}}} | |
9156 | + | |
9157 | first looks up a string in a file while expanding the operand for %expand%, and | |
9158 | then re-expands what it has found. | |
9159 | ||
9160 | ||
9161 | *\$\{from_utf8:*<'string'>*\}*:: | |
9162 | cindex:[Unicode] | |
9163 | cindex:[UTF-8,conversion from] | |
9164 | cindex:[expansion,UTF-8 conversion] | |
9165 | The world is slowly moving towards Unicode, although there are no standards for | |
9166 | email yet. However, other applications (including some databases) are starting | |
9167 | to store data in Unicode, using UTF-8 encoding. This operator converts from a | |
9168 | UTF-8 string to an ISO-8859-1 string. UTF-8 code values greater than 255 are | |
9169 | converted to underscores. The input must be a valid UTF-8 string. If it is not, | |
9170 | the result is an undefined sequence of bytes. | |
9171 | + | |
9172 | Unicode code points with values less than 256 are compatible with ASCII and | |
9173 | ISO-8859-1 (also known as Latin-1). | |
9174 | For example, character 169 is the copyright symbol in both cases, though the | |
9175 | way it is encoded is different. In UTF-8, more than one byte is needed for | |
9176 | characters with code values greater than 127, whereas ISO-8859-1 is a | |
9177 | single-byte encoding (but thereby limited to 256 characters). This makes | |
9178 | translation from UTF-8 to ISO-8859-1 straightforward. | |
9179 | ||
9180 | ||
9181 | *\$\{hash_*<'n'>*_*<'m'>*:*<'string'>*\}*:: | |
9182 | cindex:[hash function,textual] | |
9183 | cindex:[expansion,textual hash] | |
9184 | The %hash% operator is a simpler interface to the hashing function that can be | |
9185 | used when the two parameters are fixed numbers (as opposed to strings that | |
9186 | change when expanded). The effect is the same as | |
9187 | ||
9188 | ${hash{<n>}{<m>}{<string>}} | |
9189 | + | |
9190 | See the description of the general %hash% item above for details. The | |
9191 | abbreviation %h% can be used when %hash% is used as an operator. | |
9192 | ||
9193 | ||
9194 | ||
9195 | *\$\{hex2b64:*<'hexstring'>*\}*:: | |
9196 | cindex:[base64 encoding,conversion from hex] | |
9197 | cindex:[expansion,hex to base64] | |
9198 | This operator converts a hex string into one that is base64 encoded. This can | |
9199 | be useful for processing the output of the MD5 and SHA-1 hashing functions. | |
9200 | ||
9201 | ||
9202 | *\$\{lc:*<'string'>*\}*:: | |
9203 | cindex:[case forcing in strings] | |
9204 | cindex:[string,case forcing] | |
9205 | cindex:[lower casing] | |
9206 | cindex:[expansion,case forcing] | |
9207 | This forces the letters in the string into lower-case, for example: | |
9208 | ||
9209 | ${lc:$local_part} | |
9210 | ||
9211 | ||
9212 | ||
9213 | *\$\{length_*<'number'>*:*<'string'>*\}*:: | |
9214 | cindex:[expansion,string truncation] | |
9215 | The %length% operator is a simpler interface to the %length% function that can | |
9216 | be used when the parameter is a fixed number (as opposed to a string that | |
9217 | changes when expanded). The effect is the same as | |
9218 | ||
9219 | ${length{<number>}{<string>}} | |
9220 | + | |
9221 | See the description of the general %length% item above for details. Note that | |
9222 | %length% is not the same as %strlen%. The abbreviation %l% can be used when | |
9223 | %length% is used as an operator. | |
9224 | ||
9225 | ||
9226 | *\$\{local_part:*<'string'>*\}*:: | |
9227 | cindex:[expansion,local part extraction] | |
9228 | The string is interpreted as an RFC 2822 address and the local part is | |
9229 | extracted from it. If the string does not parse successfully, the result is | |
9230 | empty. | |
9231 | ||
9232 | ||
9233 | *\$\{mask:*<'IP~address'>*/*<'bit~count'>*\}*:: | |
9234 | cindex:[masked IP address] | |
9235 | cindex:[IP address,masking] | |
9236 | cindex:[CIDR notation] | |
9237 | cindex:[expansion,IP address masking] | |
9238 | If the form of the string to be operated on is not an IP address followed by a | |
9239 | slash and an integer (that is, a network address in CIDR notation), the | |
9240 | expansion fails. Otherwise, this operator converts the IP address to binary, | |
9241 | masks off the least significant bits according to the bit count, and converts | |
9242 | the result back to text, with mask appended. For example, | |
9243 | ||
9244 | ${mask:10.111.131.206/28} | |
9245 | + | |
9246 | returns the string ``10.111.131.192/28''. Since this operation is expected to be | |
9247 | mostly used for looking up masked addresses in files, the result for an IPv6 | |
9248 | address uses dots to separate components instead of colons, because colon | |
9249 | terminates a key string in lsearch files. So, for example, | |
9250 | ||
9251 | ${mask:3ffe:ffff:836f:0a00:000a:0800:200a:c031/99} | |
9252 | + | |
9253 | returns the string | |
9254 | ||
9255 | 3ffe.ffff.836f.0a00.000a.0800.2000.0000/99 | |
9256 | + | |
9257 | Letters in IPv6 addresses are always output in lower case. | |
9258 | ||
9259 | ||
9260 | *\$\{md5:*<'string'>*\}*:: | |
9261 | cindex:[MD5 hash] | |
9262 | cindex:[expansion,MD5 hash] | |
9263 | The %md5% operator computes the MD5 hash value of the string, and returns it as | |
9264 | a 32-digit hexadecimal number, | |
9265 | in which any letters are in lower case. | |
9266 | ||
9267 | ||
9268 | *\$\{nhash_*<'n'>*_*<'m'>*:*<'string'>*\}*:: | |
9269 | cindex:[expansion,numeric hash] | |
9270 | cindex:[hash function,numeric] | |
9271 | The %nhash% operator is a simpler interface to the numeric hashing function | |
9272 | that can be used when the two parameters are fixed numbers (as opposed to | |
9273 | strings that change when expanded). The effect is the same as | |
9274 | ||
9275 | ${nhash{<n>}{<m>}{<string>}} | |
9276 | + | |
9277 | See the description of the general %nhash% item above for details. | |
9278 | ||
9279 | ||
9280 | *\$\{quote:*<'string'>*\}*:: | |
9281 | cindex:[quoting,in string expansions] | |
9282 | cindex:[expansion,quoting] | |
9283 | The %quote% operator puts its argument into double quotes if it | |
9284 | is an empty string or | |
9285 | contains anything other than letters, digits, underscores, dots, and hyphens. | |
9286 | Any occurrences of double quotes and backslashes are escaped with a backslash. | |
9287 | Newlines and carriage returns are converted to `\n` and `\r`, | |
9288 | respectively For example, | |
9289 | ||
9290 | ${quote:ab"*"cd} | |
9291 | + | |
9292 | becomes | |
9293 | ||
9294 | "ab\"*\"cd" | |
9295 | + | |
9296 | The place where this is useful is when the argument is a substitution from a | |
9297 | variable or a message header. | |
9298 | ||
9299 | *\$\{quote_local_part:*<'string'>*\}*:: | |
9300 | This operator is like %quote%, except that it quotes the string only if | |
9301 | required to do so by the rules of RFC 2822 for quoting local parts. For | |
9302 | example, a plus sign would not cause quoting (but it would for %quote%). | |
9303 | If you are creating a new email address from the contents of $local_part$ | |
9304 | (or any other unknown data), you should always use this operator. | |
9305 | ||
9306 | ||
9307 | *\$\{quote_*<'lookup-type'>*:*<'string'>*\}*:: | |
9308 | cindex:[quoting,lookup-specific] | |
9309 | This operator applies lookup-specific quoting rules to the string. Each | |
9310 | query-style lookup type has its own quoting rules which are described with | |
9311 | the lookups in chapter <<CHAPfdlookup>>. For example, | |
9312 | ||
9313 | ${quote_ldap:two * two} | |
9314 | + | |
9315 | returns | |
9316 | ||
9317 | two%20%5C2A%20two | |
9318 | + | |
9319 | For single-key lookup types, no quoting is ever necessary and this operator | |
9320 | yields an unchanged string. | |
9321 | ||
9322 | ||
9323 | *\$\{rxquote:*<'string'>*\}*:: | |
9324 | cindex:[quoting,in regular expressions] | |
9325 | cindex:[regular expressions,quoting] | |
9326 | The %rxquote% operator inserts a backslash before any non-alphanumeric | |
9327 | characters in its argument. This is useful when substituting the values of | |
9328 | variables or headers inside regular expressions. | |
9329 | ||
9330 | ||
9331 | *\$\{rfc2047:*<'string'>*\}*:: | |
9332 | cindex:[expansion,RFC 2047] | |
d1e83bff | 9333 | cindex:[RFC 2047,expansion operator] |
168e428f PH |
9334 | This operator encodes text according to the rules of RFC 2047. This is an |
9335 | encoding that is used in header lines to encode non-ASCII characters. It is | |
9336 | assumed that the input string is in the encoding specified by the | |
9337 | %headers_charset% option, which defaults to ISO-8859-1. If the string contains | |
9338 | only characters in the range 33--126, and no instances of the characters | |
9339 | ||
9340 | ? = ( ) < > @ , ; : \ " . [ ] _ | |
9341 | + | |
9342 | it is not modified. Otherwise, the result is the RFC 2047 encoding of the | |
d1e83bff | 9343 | string, using as many ``encoded words'' as necessary to encode all the |
168e428f PH |
9344 | characters. |
9345 | ||
9346 | ||
9347 | ||
9348 | *\$\{sha1:*<'string'>*\}*:: | |
9349 | cindex:[SHA-1 hash] | |
9350 | cindex:[expansion,SHA-1 hashing] | |
9351 | The %sha1% operator computes the SHA-1 hash value of the string, and returns it | |
9352 | as a 40-digit hexadecimal number, in which any letters are in upper case. | |
9353 | ||
9354 | ||
9355 | *\$\{stat:*<'string'>*\}*:: | |
9356 | cindex:[expansion,statting a file] | |
9357 | cindex:[file,extracting characteristics] | |
9358 | The string, after expansion, must be a file path. A call to the 'stat()' | |
9359 | function is made for this path. If 'stat()' fails, an error occurs and the | |
9360 | expansion fails. If it succeeds, the data from the stat replaces the item, as a | |
068aaea8 PH |
9361 | series of <'name'>=<'value'> pairs, where the values are all numerical, except |
9362 | for the value of ``smode''. The names are: ``mode'' (giving the mode as a | |
168e428f | 9363 | 4-digit octal number), ``smode'' (giving the mode in symbolic format as a |
068aaea8 PH |
9364 | 10-character string, as for the 'ls' command), ``inode'', ``device'', |
9365 | ``links'', ``uid'', ``gid'', ``size'', ``atime'', ``mtime'', and ``ctime''. You | |
9366 | can extract individual fields using the %extract% expansion item. | |
9367 | + | |
9368 | [revisionflag="changed"] | |
9369 | The use of the %stat% expansion in users' filter files can be locked out by the | |
9370 | system administrator. *Warning*: The file size may be incorrect on 32-bit | |
9371 | systems for files larger than 2GB. | |
168e428f PH |
9372 | |
9373 | ||
9374 | *\$\{str2b64:*<'string'>*\}*:: | |
9375 | cindex:[expansion,base64 encoding] | |
9376 | cindex:[base64 encoding,in string expansion] | |
9377 | This operator converts a string into one that is base64 encoded. | |
9378 | ||
9379 | ||
9380 | ||
9381 | *\$\{strlen:*<'string'>*\}*:: | |
9382 | cindex:[expansion,string length] | |
9383 | cindex:[string,length in expansion] | |
9384 | The item is replace by the length of the expanded string, expressed as a | |
9385 | decimal number. *Note*: Do not confuse %strlen% with %length%. | |
9386 | ||
9387 | ||
9388 | *\$\{substr_*<'start'>*_*<'length'>*:*<'string'>*\}*:: | |
9389 | cindex:[%substr%] | |
9390 | cindex:[substring extraction] | |
9391 | cindex:[expansion,substring expansion] | |
9392 | The %substr% operator is a simpler interface to the %substr% function that can | |
9393 | be used when the two parameters are fixed numbers (as opposed to strings that | |
9394 | change when expanded). The effect is the same as | |
9395 | ||
9396 | ${substr{<start>}{<length>}{<string>}} | |
9397 | + | |
9398 | See the description of the general %substr% item above for details. The | |
9399 | abbreviation %s% can be used when %substr% is used as an operator. | |
9400 | ||
9401 | *\$\{time_interval:*<'string'>*\}*:: | |
9402 | cindex:[%time_interval%] | |
9403 | cindex:[time interval,formatting] | |
9404 | The argument (after sub-expansion) must be a sequence of decimal digits that | |
9405 | represents an interval of time as a number of seconds. It is converted into a | |
9406 | number of larger units and output in Exim's normal time format, for example, | |
9407 | `1w3d4h2m6s`. | |
9408 | ||
9409 | *\$\{uc:*<'string'>*\}*:: | |
9410 | cindex:[case forcing in strings] | |
9411 | cindex:[string,case forcing] | |
9412 | cindex:[upper casing] | |
9413 | cindex:[expansion,case forcing] | |
9414 | This forces the letters in the string into upper-case. | |
9415 | ||
9416 | ||
9417 | ||
9418 | ||
9419 | ||
9420 | ||
9421 | [[SECTexpcond]] | |
9422 | Expansion conditions | |
9423 | ~~~~~~~~~~~~~~~~~~~~ | |
9424 | cindex:[expansion,conditions] | |
9425 | The following conditions are available for testing by the %\$\{if% construct | |
9426 | while expanding strings: | |
9427 | ||
9428 | *!*<'condition'>:: | |
9429 | cindex:[expansion,negating a condition] | |
9430 | Preceding any condition with an exclamation mark negates the result of the | |
9431 | condition. | |
9432 | ||
9433 | <'symbolic~operator'>~*\{*<'string1'>*\}\{*<'string2'>*\}*:: | |
9434 | cindex:[numeric comparison] | |
9435 | cindex:[expansion,numeric comparison] | |
9436 | There are a number of symbolic operators for doing numeric comparisons. They | |
9437 | are: | |
9438 | + | |
9439 | &&& | |
9440 | `= ` equal | |
9441 | `== ` equal | |
9442 | `> ` greater | |
9443 | `>= ` greater or equal | |
9444 | `< ` less | |
9445 | `<= ` less or equal | |
9446 | &&& | |
9447 | + | |
9448 | For example, | |
9449 | ||
9450 | ${if >{$message_size}{10M} ... | |
9451 | + | |
9452 | Note that the general negation operator provides for inequality testing. The | |
9453 | two strings must take the form of optionally signed decimal integers, | |
9454 | optionally followed by one of the letters ``K'' or ``M'' (in either upper or | |
9455 | lower case), signifying multiplication by 1024 or 1024\*1024, respectively. | |
9456 | ||
9457 | *crypteq~\{*<'string1'>*\}\{*<'string2'>*\}*:: | |
9458 | cindex:[expansion,encrypted comparison] | |
9459 | cindex:[encrypted strings, comparing] | |
9460 | This condition is included in the Exim binary if it is built to support any | |
9461 | authentication mechanisms (see chapter <<CHAPSMTPAUTH>>). Otherwise, it is | |
9462 | necessary to define SUPPORT_CRYPTEQ in _Local/Makefile_ to get %crypteq% | |
9463 | included in the binary. | |
9464 | + | |
9465 | The %crypteq% condition has two arguments. The first is encrypted and compared | |
9466 | against the second, which is already encrypted. The second string may be in the | |
9467 | LDAP form for storing encrypted strings, which starts with the encryption type | |
9468 | in curly brackets, followed by the data. If the second string does not begin | |
9469 | with ``\{'' it is assumed to be encrypted with 'crypt()' or 'crypt16()' (see | |
9470 | below), since such strings cannot begin with ``\{''. Typically this will be a | |
9471 | field from a password file. | |
9472 | + | |
9473 | An example of an encrypted string in LDAP form is: | |
9474 | ||
9475 | {md5}CY9rzUYh03PK3k6DJie09g== | |
9476 | + | |
9477 | If such a string appears directly in an expansion, the curly brackets have to | |
9478 | be quoted, because they are part of the expansion syntax. For example: | |
9479 | ||
9480 | ${if crypteq {test}{\{md5\}CY9rzUYh03PK3k6DJie09g==}{yes}{no}} | |
9481 | + | |
9482 | The following encryption types (whose names are matched case-independently) are | |
9483 | supported: | |
9484 | + | |
9485 | -- | |
9486 | - cindex:[MD5 hash] | |
9487 | cindex:[base64 encoding,in encrypted password] | |
9488 | %\{md5\}% computes the MD5 digest of the first string, and expresses this as | |
9489 | printable characters to compare with the remainder of the second string. If the | |
9490 | length of the comparison string is 24, Exim assumes that it is base64 encoded | |
9491 | (as in the above example). If the length is 32, Exim assumes that it is a | |
9492 | hexadecimal encoding of the MD5 digest. If the length not 24 or 32, the | |
9493 | comparison fails. | |
9494 | ||
9495 | - cindex:[SHA-1 hash] | |
9496 | %\{sha1\}% computes the SHA-1 digest of the first string, and expresses this as | |
9497 | printable characters to compare with the remainder of the second string. If the | |
9498 | length of the comparison string is 28, Exim assumes that it is base64 encoded. | |
9499 | If the length is 40, Exim assumes that it is a hexadecimal encoding of the | |
9500 | SHA-1 digest. If the length is not 28 or 40, the comparison fails. | |
9501 | ||
9502 | - cindex:['crypt()'] | |
9503 | %\{crypt\}% calls the 'crypt()' function, which traditionally used to use only | |
9504 | the first eight characters of the password. However, in modern operating | |
9505 | systems this is no longer true, and in many cases the entire password is used, | |
9506 | whatever its length. | |
9507 | ||
9508 | - cindex:['crypt16()'] | |
9509 | %\{crypt16\}% calls the 'crypt16()' function (also known as 'bigcrypt()'), | |
9510 | which was orginally created to use up to 16 characters of the password. Again, | |
9511 | in modern operating systems, more characters may be used. | |
9512 | -- | |
9513 | + | |
9514 | Exim has its own version of 'crypt16()' (which is just a double call to | |
9515 | 'crypt()'). For operating systems that have their own version, setting | |
9516 | HAVE_CRYPT16 in _Local/Makefile_ when building Exim causes it to use the | |
9517 | operating system version instead of its own. This option is set by default in | |
9518 | the OS-dependent _Makefile_ for those operating systems that are known to | |
9519 | support 'crypt16()'. | |
9520 | + | |
9521 | If you do not put any curly bracket encryption type in a %crypteq% comparison, | |
9522 | the default is either `\{crypt\}` or `\{crypt16\}`, as determined by the | |
9523 | setting of DEFAULT_CRYPT in _Local/Makefile_. The default default is | |
9524 | `\{crypt\}`. Whatever the default, you can always use either function by | |
9525 | specifying it explicitly in curly brackets. | |
9526 | + | |
9527 | Note that if a password is no longer than 8 characters, the results of | |
9528 | encrypting it with 'crypt()' and 'crypt16()' are identical. That means that | |
9529 | 'crypt16()' is backwards compatible, as long as nobody feeds it a password | |
9530 | longer than 8 characters. | |
9531 | ||
9532 | ||
9533 | *def:*<'variable~name'>*:: | |
9534 | cindex:[expansion,checking for empty variable] | |
9535 | The %def% condition must be followed by the name of one of the expansion | |
9536 | variables defined in section <<SECTexpvar>>. The condition is true if the named | |
9537 | expansion variable does not contain the empty string, for example | |
9538 | ||
9539 | ${if def:sender_ident {from $sender_ident}} | |
9540 | + | |
9541 | Note that the variable name is given without a leading %\$% character. If the | |
9542 | variable does not exist, the expansion fails. | |
9543 | ||
9544 | *def:header_*<'header~name'>*:*~~or~~*def:h_*<'header~name'>*:*:: | |
9545 | cindex:[expansion,checking header line existence] | |
9546 | This condition is true if a message is being processed and the named header | |
9547 | exists in the message. For example, | |
9548 | ||
9549 | ${if def:header_reply-to:{$h_reply-to:}{$h_from:}} | |
9550 | + | |
068aaea8 PH |
9551 | *Note*: no %\$% appears before %header_% or %h_% in the condition, and the |
9552 | header name must be terminated by a colon if white space does not follow. | |
168e428f PH |
9553 | |
9554 | *eq~\{*<'string1'>*\}\{*<'string2'>*\}*:: | |
9555 | cindex:[string,comparison] | |
9556 | cindex:[expansion,string comparison] | |
9557 | The two substrings are first expanded. The condition is true if the two | |
9558 | resulting strings are identical, including the case of letters. | |
9559 | ||
9560 | *eqi~\{*<'string1'>*\}\{*<'string2'>*\}*:: | |
9561 | cindex:[string,comparison] | |
9562 | cindex:[expansion,string comparison] | |
9563 | The two substrings are first expanded. The condition is true if the two | |
9564 | resulting strings are identical when compared in a case-independent way. | |
9565 | ||
9566 | *exists~\{*<'file~name'>*\}*:: | |
9567 | cindex:[expansion,file existence test] | |
9568 | cindex:[file,existence test] | |
9569 | The substring is first expanded and then interpreted as an absolute path. The | |
9570 | condition is true if the named file (or directory) exists. The existence test | |
9571 | is done by calling the 'stat()' function. The use of the %exists% test in | |
9572 | users' filter files may be locked out by the system administrator. | |
9573 | ||
9574 | *first_delivery*:: | |
9575 | cindex:[delivery,first] | |
9576 | cindex:[first delivery] | |
9577 | cindex:[expansion,first delivery test] | |
9578 | This condition, which has no data, is true during a message's first delivery | |
9579 | attempt. It is false during any subsequent delivery attempts. | |
9580 | ||
9581 | *ge~\{*<'string1'>*\}\{*<'string2'>*\}*:: | |
9582 | See *gei*. | |
9583 | ||
9584 | *gei~\{*<'string1'>*\}\{*<'string2'>*\}*:: | |
9585 | cindex:[string,comparison] | |
9586 | cindex:[expansion,string comparison] | |
9587 | The two substrings are first expanded. The condition is true if the first | |
9588 | string is lexically greater than or equal to the second string: for %ge% the | |
9589 | comparison includes the case of letters, whereas for %gei% the comparison is | |
9590 | case-independent. | |
9591 | ||
9592 | *gt~\{*<'string1'>*\}\{*<'string2'>*\}*:: | |
9593 | See *gti*. | |
9594 | ||
9595 | *gti~\{*<'string1'>*\}\{*<'string2'>*\}*:: | |
9596 | cindex:[string,comparison] | |
9597 | cindex:[expansion,string comparison] | |
9598 | The two substrings are first expanded. The condition is true if the first | |
9599 | string is lexically greater than the second string: for %gt% the comparison | |
9600 | includes the case of letters, whereas for %gti% the comparison is | |
9601 | case-independent. | |
9602 | ||
9603 | *isip~\{*<'string'>*\}*:: | |
9604 | See *isip6*. | |
9605 | ||
9606 | *isip4~\{*<'string'>*\}*:: | |
9607 | See *isip6*. | |
9608 | ||
9609 | *isip6~\{*<'string'>*\}*:: | |
9610 | cindex:[IP address,testing string format] | |
9611 | cindex:[string,testing for IP address] | |
9612 | The substring is first expanded, and then tested to see if it has the form of | |
9613 | an IP address. Both IPv4 and IPv6 addresses are valid for %isip%, whereas | |
9614 | %isip4% and %isip6% test just for IPv4 or IPv6 addresses, respectively. For | |
9615 | example, you could use | |
9616 | ||
9617 | ${if isip4{$sender_host_address}... | |
9618 | + | |
9619 | to test which version of IP an incoming SMTP connection is using. | |
9620 | ||
9621 | ||
9622 | *ldapauth~\{*<'ldap~query'>*\}*:: | |
9623 | cindex:[LDAP,use for authentication] | |
9624 | cindex:[expansion,LDAP authentication test] | |
9625 | This condition supports user authentication using LDAP. See section | |
9626 | <<SECTldap>> for details of how to use LDAP in lookups and the syntax of | |
9627 | queries. For this use, the query must contain a user name and password. The | |
9628 | query itself is not used, and can be empty. The condition is true if the | |
9629 | password is not empty, and the user name and password are accepted by the LDAP | |
9630 | server. An empty password is rejected without calling LDAP because LDAP binds | |
9631 | with an empty password are considered anonymous regardless of the username, and | |
9632 | will succeed in most configurations. See chapter <<CHAPSMTPAUTH>> for details | |
9633 | of SMTP authentication, and chapter <<CHAPplaintext>> for an example of how | |
9634 | this can be used. | |
9635 | ||
9636 | ||
9637 | *le~\{*<'string1'>*\}\{*<'string2'>*\}*:: | |
9638 | See *lei*. | |
9639 | ||
9640 | *lei~\{*<'string1'>*\}\{*<'string2'>*\}*:: | |
9641 | cindex:[string,comparison] | |
9642 | cindex:[expansion,string comparison] | |
9643 | The two substrings are first expanded. The condition is true if the first | |
9644 | string is lexically less than or equal to the second string: for %le% the | |
9645 | comparison includes the case of letters, whereas for %lei% the comparison is | |
9646 | case-independent. | |
9647 | ||
9648 | *lt~\{*<'string1'>*\}\{*<'string2'>*\}*:: | |
9649 | See *lti*. | |
9650 | ||
9651 | *lti~\{*<'string1'>*\}\{*<'string2'>*\}*:: | |
9652 | cindex:[string,comparison] | |
9653 | cindex:[expansion,string comparison] | |
9654 | The two substrings are first expanded. The condition is true if the first | |
9655 | string is lexically less than the second string: for %lt% the comparison | |
9656 | includes the case of letters, whereas for %lti% the comparison is | |
9657 | case-independent. | |
9658 | ||
9659 | ||
9660 | *match~\{*<'string1'>*\}\{*<'string2'>*\}*:: | |
9661 | cindex:[expansion,regular expression comparison] | |
9662 | cindex:[regular expressions,match in expanded string] | |
9663 | The two substrings are first expanded. The second is then treated as a regular | |
9664 | expression and applied to the first. Because of the pre-expansion, if the | |
9665 | regular expression contains dollar, or backslash characters, they must be | |
9666 | escaped. Care must also be taken if the regular expression contains braces | |
9667 | (curly brackets). A closing brace must be escaped so that it is not taken as a | |
9668 | premature termination of <'string2'>. The easiest approach is to use the | |
9669 | `\N` feature to disable expansion of the regular expression. | |
9670 | For example, | |
9671 | ||
9672 | ${if match {$local_part}{\N^\d{3}\N} ... | |
9673 | + | |
9674 | If the whole expansion string is in double quotes, further escaping of | |
9675 | backslashes is also required. | |
9676 | + | |
9677 | The condition is true if the regular expression match succeeds. | |
9678 | The regular expression is not required to begin with a circumflex | |
9679 | metacharacter, but if there is no circumflex, the expression is not anchored, | |
9680 | and it may match anywhere in the subject, not just at the start. If you want | |
9681 | the pattern to match at the end of the subject, you must include the `\$` | |
9682 | metacharacter at an appropriate point. | |
9683 | + | |
9684 | cindex:[numerical variables ($1$ $2$ etc),in %if% expansion] | |
9685 | At the start of an %if% expansion the values of the numeric variable | |
9686 | substitutions $1$ etc. are remembered. Obeying a %match% condition that | |
9687 | succeeds causes them to be reset to the substrings of that condition and they | |
9688 | will have these values during the expansion of the success string. At the end | |
9689 | of the %if% expansion, the previous values are restored. After testing a | |
9690 | combination of conditions using %or%, the subsequent values of the numeric | |
9691 | variables are those of the condition that succeeded. | |
9692 | ||
068aaea8 | 9693 | *match_address~\{*<'string1'>*\}\{*<'string2'>*\}*:: |
168e428f PH |
9694 | See *match_local_part*. |
9695 | ||
068aaea8 | 9696 | *match_domain~\{*<'string1'>*\}\{*<'string2'>*\}*:: |
168e428f PH |
9697 | See *match_local_part*. |
9698 | ||
068aaea8 PH |
9699 | *match_ip~\{*<'string1'>*\}\{*<'string2'>*\}*:: |
9700 | + | |
9701 | [revisionflag="changed"] | |
9702 | This condition matches an IP address to a list of IP address patterns. It must | |
9703 | be followed by two argument strings. The first (after expansion) must be an IP | |
9704 | address or an empty string. The second (after expansion) is a restricted host | |
9705 | list that can match only an IP address, not a host name. For example: | |
9706 | + | |
9707 | [revisionflag="changed"] | |
9708 | .... | |
9709 | ${if match_ip{$sender_host_address}{1.2.3.4:5.6.7.8}{...}{...}} | |
9710 | .... | |
9711 | + | |
9712 | [revisionflag="changed"] | |
9713 | The specific types of host list item that are permitted in the list are: | |
9714 | + | |
9715 | -- | |
9716 | - An IP address, optionally with a CIDR mask. | |
9717 | ||
9718 | - A single asterisk, which matches any IP address. | |
9719 | ||
9720 | - An empty item, which matches only if the IP address is empty. This could be | |
9721 | useful for testing for a locally submitted message or one from specific hosts | |
9722 | in a single test such as | |
9723 | ||
9724 | .... | |
9725 | ${if match_ip{$sender_host_address}{:4.3.2.1:...}{...}{...}} | |
9726 | .... | |
9727 | ||
9728 | where the first item in the list is the empty string. | |
9729 | ||
9730 | - The item @[] matches any of the local host's interface addresses. | |
9731 | ||
9732 | - Lookups are assumed to be ``net-'' style lookups, even if `net-` is not | |
9733 | specified. Thus, the following are equivalent: | |
9734 | ||
9735 | .... | |
9736 | ${if match_ip{$sender_host_address}{lsearch;/some/file}... | |
9737 | ${if match_ip{$sender_host_address}{net-lsearch;/some/file}... | |
9738 | .... | |
9739 | ||
9740 | You do need to specify the `net-` prefix if you want to specify a | |
9741 | specific address mask, for example, by using `net24-`. | |
9742 | -- | |
9743 | + | |
9744 | [revisionflag="changed"] | |
9745 | Consult section <<SECThoslispatip>> for further details of these patterns. | |
9746 | ||
9747 | ||
9748 | ||
168e428f PH |
9749 | *match_local_part~\{*<'string1'>*\}\{*<'string2'>*\}*:: |
9750 | cindex:[domain list,in expansion condition] | |
9751 | cindex:[address list,in expansion condition] | |
9752 | cindex:[local part list,in expansion condition] | |
068aaea8 PH |
9753 | This condition, together with %match_address% and %match_domain%, make it |
9754 | possible to test domain, address, and local part lists within expansions. Each | |
9755 | condition requires two arguments: an item and a list to match. A trivial | |
9756 | example is: | |
168e428f PH |
9757 | |
9758 | ${if match_domain{a.b.c}{x.y.z:a.b.c:p.q.r}{yes}{no}} | |
9759 | + | |
9760 | In each case, the second argument may contain any of the allowable items for a | |
9761 | list of the appropriate type. Also, because the second argument (after | |
9762 | expansion) is a standard form of list, it is possible to refer to a named list. | |
9763 | Thus, you can use conditions like this: | |
9764 | ||
9765 | ${if match_domain{$domain}{+local_domains}{... | |
9766 | + | |
9767 | cindex:[`+caseful`] | |
9768 | For address lists, the matching starts off caselessly, but the `+caseful` | |
9769 | item can be used, as in all address lists, to cause subsequent items to | |
9770 | have their local parts matched casefully. Domains are always matched | |
9771 | caselessly. | |
9772 | + | |
9773 | *Note*: Host lists are 'not' supported in this way. This is because | |
9774 | hosts have two identities: a name and an IP address, and it is not clear | |
068aaea8 PH |
9775 | how to specify cleanly how such a test would work. However, IP addresses can be |
9776 | matched using %match_ip%. | |
168e428f PH |
9777 | |
9778 | *pam~\{*<'string1'>*:*<'string2'>*:...\}*:: | |
9779 | cindex:[PAM authentication] | |
9780 | cindex:[AUTH,with PAM] | |
9781 | cindex:[Solaris,PAM support] | |
9782 | cindex:[expansion,PAM authentication test] | |
9783 | 'Pluggable Authentication Modules' | |
9784 | (*http://www.kernel.org/pub/linux/libs/pam/[]*) | |
9785 | are a facility that is available in the latest releases of Solaris and in some | |
9786 | GNU/Linux distributions. The Exim support, which is intended for use in | |
9787 | conjunction with the SMTP AUTH command, is available only if Exim is | |
9788 | compiled with | |
9789 | ||
9790 | SUPPORT_PAM=yes | |
9791 | + | |
9792 | in _Local/Makefile_. You probably need to add %-lpam% to EXTRALIBS, and | |
9793 | in some releases of GNU/Linux %-ldl% is also needed. | |
9794 | + | |
9795 | The argument string is first expanded, and the result must be a | |
068aaea8 | 9796 | colon-separated list of strings. Leading and trailing white space is ignored. |
168e428f PH |
9797 | The PAM module is initialized with the service name ``exim'' and the user name |
9798 | taken from the first item in the colon-separated data string (<'string1'>). The | |
9799 | remaining items in the data string are passed over in response to requests from | |
9800 | the authentication function. In the simple case there will only be one request, | |
9801 | for a password, so the data consists of just two strings. | |
9802 | + | |
9803 | There can be problems if any of the strings are permitted to contain colon | |
9804 | characters. In the usual way, these have to be doubled to avoid being taken as | |
9805 | separators. If the data is being inserted from a variable, the %sg% expansion | |
9806 | item can be used to double any existing colons. For example, the configuration | |
9807 | of a LOGIN authenticator might contain this setting: | |
9808 | ||
9809 | server_condition = ${if pam{$1:${sg{$2}{:}{::}}}{yes}{no}} | |
9810 | + | |
9811 | For a PLAIN authenticator you could use: | |
9812 | ||
9813 | server_condition = ${if pam{$2:${sg{$3}{:}{::}}}{yes}{no}} | |
9814 | + | |
9815 | In some operating systems, PAM authentication can be done only from a process | |
9816 | running as root. Since Exim is running as the Exim user when receiving | |
9817 | messages, this means that PAM cannot be used directly in those systems. | |
9818 | A patched version of the 'pam_unix' module that comes with the | |
9819 | Linux PAM package is available from *http://www.e-admin.de/pam_exim/[]*. | |
9820 | The patched module allows one special uid/gid combination, in addition to root, | |
9821 | to authenticate. If you build the patched module to allow the Exim user and | |
9822 | group, PAM can then be used from an Exim authenticator. | |
9823 | ||
9824 | ||
9825 | *pwcheck~\{*<'string1'>*:*<'string2'>*\}*:: | |
9826 | cindex:['pwcheck' daemon] | |
9827 | cindex:[Cyrus] | |
9828 | cindex:[expansion,'pwcheck' authentication test] | |
9829 | This condition supports user authentication using the Cyrus 'pwcheck' daemon. | |
9830 | This is one way of making it possible for passwords to be checked by a process | |
9831 | that is not running as root. *Note:* The use of 'pwcheck' is now deprecated. | |
9832 | Its replacement is 'saslauthd' (see below). | |
9833 | + | |
9834 | The pwcheck support is not included in Exim by default. You need to specify | |
9835 | the location of the pwcheck daemon's socket in _Local/Makefile_ before | |
9836 | building Exim. For example: | |
9837 | ||
9838 | CYRUS_PWCHECK_SOCKET=/var/pwcheck/pwcheck | |
9839 | + | |
9840 | You do not need to install the full Cyrus software suite in order to use | |
9841 | the pwcheck daemon. You can compile and install just the daemon alone | |
9842 | from the Cyrus SASL library. Ensure that 'exim' is the only user that has | |
9843 | access to the _/var/pwcheck_ directory. | |
9844 | + | |
9845 | The %pwcheck% condition takes one argument, which must be the user name and | |
9846 | password, separated by a colon. For example, in a LOGIN authenticator | |
9847 | configuration, you might have this: | |
9848 | ||
9849 | server_condition = ${if pwcheck{$1:$2}{1}{0}} | |
9850 | ||
9851 | ||
9852 | *queue_running*:: | |
9853 | cindex:[queue runner,detecting when delivering from] | |
9854 | cindex:[expansion,queue runner test] | |
9855 | This condition, which has no data, is true during delivery attempts that are | |
9856 | initiated by queue runner processes, and false otherwise. | |
9857 | ||
9858 | ||
9859 | *radius~\{*<'authentication~string'>*\}*:: | |
9860 | cindex:[Radius] | |
9861 | cindex:[expansion,Radius authentication] | |
9862 | Radius authentication (RFC 2865) is supported in a similar way to PAM. You must | |
9863 | set RADIUS_CONFIG_FILE in _Local/Makefile_ to specify the location of | |
9864 | the Radius client configuration file in order to build Exim with Radius | |
9865 | support. | |
9866 | + | |
068aaea8 | 9867 | [revisionflag="changed"] |
168e428f | 9868 | With just that one setting, Exim expects to be linked with the %radiusclient% |
068aaea8 PH |
9869 | library, using the original API. If you are using release 0.4.0 or later of |
9870 | this library, you need to set | |
9871 | + | |
9872 | [revisionflag="changed"] | |
9873 | .... | |
9874 | RADIUS_LIB_TYPE=RADIUSCLIENTNEW | |
9875 | .... | |
9876 | + | |
9877 | [revisionflag="changed"] | |
9878 | in _Local/Makefile_ when building Exim. You can also link Exim with the | |
9879 | %libradius% library that comes with FreeBSD. To do this, set | |
168e428f PH |
9880 | |
9881 | RADIUS_LIB_TYPE=RADLIB | |
9882 | + | |
9883 | in _Local/Makefile_, in addition to setting RADIUS_CONFIGURE_FILE. | |
9884 | You may also have to supply a suitable setting in EXTRALIBS so that the | |
9885 | Radius library can be found when Exim is linked. | |
9886 | + | |
9887 | The string specified by RADIUS_CONFIG_FILE is expanded and passed to the | |
9888 | Radius client library, which calls the Radius server. The condition is true if | |
9889 | the authentication is successful. For example | |
9890 | ||
9891 | server_condition = \$\{if radius\{<arguments>\}\{yes\}\{no\}\} | |
9892 | ||
9893 | ||
9894 | ||
9895 | ||
9896 | *saslauthd~\{\{*<'user'>*\}\{*<'password'>*\}\{*<'service'>*\}\{*<'realm'>*\}\}*:: | |
9897 | cindex:['saslauthd' daemon] | |
9898 | cindex:[Cyrus] | |
9899 | cindex:[expansion,'saslauthd' authentication test] | |
9900 | This condition supports user authentication using the Cyrus 'saslauthd' | |
9901 | daemon. This replaces the older 'pwcheck' daemon, which is now deprecated. | |
9902 | Using this daemon is one way of making it possible for passwords to be checked | |
9903 | by a process that is not running as root. | |
9904 | + | |
9905 | The saslauthd support is not included in Exim by default. You need to specify | |
9906 | the location of the saslauthd daemon's socket in _Local/Makefile_ before | |
9907 | building Exim. For example: | |
9908 | ||
9909 | CYRUS_SASLAUTHD_SOCKET=/var/state/saslauthd/mux | |
9910 | + | |
9911 | You do not need to install the full Cyrus software suite in order to use | |
9912 | the saslauthd daemon. You can compile and install just the daemon alone | |
9913 | from the Cyrus SASL library. | |
9914 | + | |
9915 | Up to four arguments can be supplied to the %saslauthd% condition, but only two | |
9916 | are mandatory. For example: | |
9917 | ||
9918 | server_condition = ${if saslauthd{{$1}{$2}}{1}{0}} | |
9919 | + | |
9920 | The service and the realm are optional (which is why the arguments are enclosed | |
9921 | in their own set of braces). For details of the meaning of the service and | |
9922 | realm, and how to run the daemon, consult the Cyrus documentation. | |
9923 | ||
9924 | ||
9925 | ||
9926 | Combining expansion conditions | |
9927 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
9928 | cindex:[expansion,combining conditions] | |
9929 | Several conditions can be tested at once by combining them using the %and% and | |
9930 | %or% combination conditions. Note that %and% and %or% are complete conditions | |
9931 | on their own, and precede their lists of sub-conditions. Each sub-condition | |
9932 | must be enclosed in braces within the overall braces that contain the list. No | |
9933 | repetition of %if% is used. | |
9934 | ||
9935 | ||
9936 | *or~\{\{*<'cond1'>*\}\{*<'cond2'>*\}...\}*:: | |
9937 | cindex:[``or'' expansion condition] | |
9938 | cindex:[expansion,``or'' of conditions] | |
9939 | The sub-conditions are evaluated from left to right. The condition is true if | |
9940 | any one of the sub-conditions is true. | |
9941 | For example, | |
9942 | ||
9943 | ${if or {{eq{$local_part}{spqr}}{eq{$domain}{testing.com}}}... | |
9944 | + | |
9945 | When a true sub-condition is found, the following ones are parsed but not | |
9946 | evaluated. If there are several ``match'' sub-conditions the values of the | |
9947 | numeric variables afterwards are taken from the first one that succeeds. | |
9948 | ||
9949 | *and~\{\{*<'cond1'>*\}\{*<'cond2'>*\}...\}*:: | |
9950 | cindex:[``and'' expansion condition] | |
9951 | cindex:[expansion,``and'' of conditions] | |
9952 | The sub-conditions are evaluated from left to right. The condition is true if | |
9953 | all of the sub-conditions are true. If there are several ``match'' | |
9954 | sub-conditions, the values of the numeric variables afterwards are taken from | |
9955 | the last one. When a false sub-condition is found, the following ones are | |
9956 | parsed but not evaluated. | |
9957 | ||
9958 | ||
9959 | ||
9960 | ||
9961 | [[SECTexpvar]] | |
9962 | Expansion variables | |
9963 | ~~~~~~~~~~~~~~~~~~~ | |
9964 | cindex:[expansion variables, list of] | |
9965 | This section contains an alphabetical list of all the expansion variables. Some | |
9966 | of them are available only when Exim is compiled with specific options such as | |
9967 | support for TLS or the content scanning extension. | |
9968 | ||
9969 | $0$, $1$, etc:: | |
9970 | cindex:[numerical variables ($1$ $2$ etc)] | |
9971 | When a %match% expansion condition succeeds, these variables contain the | |
9972 | captured substrings identified by the regular expression during subsequent | |
9973 | processing of the success string of the containing %if% expansion item. They | |
9974 | may also be set externally by some other matching process which precedes the | |
9975 | expansion of the string. For example, the commands available in Exim filter | |
9976 | files include an %if% command with its own regular expression matching | |
9977 | condition. | |
9978 | ||
9979 | $acl_c0$ -- $acl_c9$:: | |
9980 | Values can be placed in these variables by the %set% modifier in an ACL. The | |
9981 | values persist throughout the lifetime of an SMTP connection. They can be used | |
9982 | to pass information between ACLs and different invocations of the same ACL. | |
9983 | When a message is received, the values of these variables are saved with the | |
9984 | message, and can be accessed by filters, routers, and transports during | |
9985 | subsequent delivery. | |
9986 | ||
9987 | $acl_m0$ -- $acl_m9$:: | |
9988 | Values can be placed in these variables by the %set% modifier in an ACL. They | |
9989 | retain their values while a message is being received, but are reset | |
9990 | afterwards. They are also reset by MAIL, RSET, EHLO, HELO, and after starting a | |
9991 | TLS session. When a message is received, the values of these variables are | |
9992 | saved with the message, and can be accessed by filters, routers, and transports | |
9993 | during subsequent delivery. | |
9994 | ||
9995 | $acl_verify_message$:: | |
068aaea8 PH |
9996 | + |
9997 | [revisionflag="changed"] | |
9998 | cindex:[$acl_verify_message$] | |
9999 | After an address verification has failed, this variable contains the failure | |
10000 | message. It retains its value for use in subsequent modifiers. The message can | |
10001 | be preserved by coding like this: | |
10002 | + | |
10003 | [revisionflag="changed"] | |
10004 | .... | |
10005 | warn !verify = sender | |
10006 | set acl_m0 = $acl_verify_message | |
10007 | .... | |
10008 | + | |
10009 | [revisionflag="changed"] | |
10010 | You can use $acl_verify_message$ during the expansion of the %message% or | |
10011 | %log_message% modifiers, to include information about the verification failure. | |
10012 | ||
168e428f PH |
10013 | |
10014 | $address_data$:: | |
068aaea8 | 10015 | cindex:[$address_data$] |
168e428f PH |
10016 | This variable is set by means of the %address_data% option in routers. The |
10017 | value then remains with the address while it is processed by subsequent routers | |
10018 | and eventually a transport. If the transport is handling multiple addresses, | |
10019 | the value from the first address is used. See chapter <<CHAProutergeneric>> for | |
10020 | more details. *Note*: the contents of $address_data$ are visible in user filter | |
10021 | files. | |
10022 | + | |
10023 | If $address_data$ is set when the routers are called from an ACL to verify | |
10024 | a recipient address, the final value is still in the variable for subsequent | |
10025 | conditions and modifiers of the ACL statement. If routing the address caused it | |
10026 | to be redirected to just one address, the child address is also routed as part | |
10027 | of the verification, and in this case the final value of $address_data$ is | |
10028 | from the child's routing. | |
10029 | + | |
10030 | If $address_data$ is set when the routers are called from an ACL to verify a | |
10031 | sender address, the final value is also preserved, but this time in | |
10032 | $sender_address_data$, to distinguish it from data from a recipient | |
10033 | address. | |
10034 | + | |
10035 | In both cases (recipient and sender verification), the value does not persist | |
10036 | after the end of the current ACL statement. If you want to preserve | |
10037 | these values for longer, you can save them in ACL variables. | |
10038 | ||
10039 | $address_file$:: | |
068aaea8 | 10040 | cindex:[$address_file$] |
168e428f PH |
10041 | When, as a result of aliasing, forwarding, or filtering, a message is directed |
10042 | to a specific file, this variable holds the name of the file when the transport | |
10043 | is running. At other times, the variable is empty. For example, using the | |
10044 | default configuration, if user %r2d2% has a _.forward_ file containing | |
10045 | ||
10046 | /home/r2d2/savemail | |
10047 | + | |
10048 | then when the ^address_file^ transport is running, $address_file$ | |
10049 | contains ``/home/r2d2/savemail''. | |
10050 | + | |
10051 | cindex:[Sieve filter,value of $address_file$] | |
10052 | For Sieve filters, the value may be ``inbox'' or a relative folder name. It is | |
10053 | then up to the transport configuration to generate an appropriate absolute path | |
10054 | to the relevant file. | |
10055 | ||
10056 | $address_pipe$:: | |
068aaea8 | 10057 | cindex:[$address_pipe$] |
168e428f PH |
10058 | When, as a result of aliasing or forwarding, a message is directed to a pipe, |
10059 | this variable holds the pipe command when the transport is running. | |
10060 | ||
10061 | $authenticated_id$:: | |
10062 | cindex:[authentication,id] | |
068aaea8 | 10063 | cindex:[$authenticated_id$] |
168e428f PH |
10064 | When a server successfully authenticates a client it may be configured to |
10065 | preserve some of the authentication information in the variable | |
10066 | $authenticated_id$ (see chapter <<CHAPSMTPAUTH>>). For example, a user/password | |
10067 | authenticator configuration might preserve the user name for use in the | |
068aaea8 PH |
10068 | routers. Note that this is not the same information that is saved in |
10069 | $sender_host_authenticated$. When a message is submitted locally (that is, not | |
10070 | over a TCP connection), the value of $authenticated_id$ is the login name of | |
10071 | the calling process. | |
168e428f PH |
10072 | |
10073 | $authenticated_sender$:: | |
10074 | cindex:[sender,authenticated] | |
10075 | cindex:[authentication,sender] | |
10076 | cindex:[AUTH,on MAIL command] | |
068aaea8 | 10077 | cindex:[$authenticated_sender$] |
168e428f PH |
10078 | When acting as a server, Exim takes note of the AUTH= parameter on an incoming |
10079 | SMTP MAIL command if it believes the sender is sufficiently trusted, as | |
10080 | described in section <<SECTauthparamail>>. Unless the data is the string | |
10081 | ``<>'', it is set as the authenticated sender of the message, and the value is | |
10082 | available during delivery in the $authenticated_sender$ variable. If the sender | |
10083 | is not trusted, Exim accepts the syntax of AUTH=, but ignores the data. | |
10084 | + | |
068aaea8 | 10085 | cindex:[$qualify_domain$] |
168e428f PH |
10086 | When a message is submitted locally (that is, not over a TCP connection), the |
10087 | value of $authenticated_sender$ is an address constructed from the login | |
10088 | name of the calling process and $qualify_domain$. | |
10089 | ||
10090 | ||
10091 | $authentication_failed$:: | |
10092 | cindex:[authentication,failure] | |
068aaea8 | 10093 | cindex:[$authentication_failed$] |
168e428f PH |
10094 | This variable is set to ``1'' in an Exim server if a client issues an AUTH |
10095 | command that does not succeed. Otherwise it is set to ``0''. This makes it | |
10096 | possible to distinguish between ``did not try to authenticate'' | |
10097 | ($sender_host_authenticated$ is empty and $authentication_failed$ is set to | |
10098 | ``0'') and ``tried to authenticate but failed'' ($sender_host_authenticated$ is | |
10099 | empty and $authentication_failed$ is set to ``1''). Failure includes any | |
10100 | negative response to an AUTH command, including (for example) an attempt to use | |
10101 | an undefined mechanism. | |
10102 | ||
10103 | $body_linecount$:: | |
10104 | cindex:[message body, line count] | |
10105 | cindex:[body of message,line count] | |
068aaea8 | 10106 | cindex:[$body_linecount$] |
168e428f | 10107 | When a message is being received or delivered, this variable contains the |
068aaea8 | 10108 | number of lines in the message's body. See also $message_linecount$. |
168e428f PH |
10109 | |
10110 | $body_zerocount$:: | |
10111 | cindex:[message body, binary zero count] | |
10112 | cindex:[body of message,binary zero count] | |
10113 | cindex:[binary zero,in message body] | |
068aaea8 | 10114 | cindex:[$body_zerocount$] |
168e428f PH |
10115 | When a message is being received or delivered, this variable contains the |
10116 | number of binary zero bytes in the message's body. | |
10117 | ||
10118 | $bounce_recipient$:: | |
068aaea8 | 10119 | cindex:[$bounce_recipient$] |
168e428f PH |
10120 | This is set to the recipient address of a bounce message while Exim is creating |
10121 | it. It is useful if a customized bounce message text file is in use (see | |
10122 | chapter <<CHAPemsgcust>>). | |
10123 | ||
10124 | $bounce_return_size_limit$:: | |
068aaea8 | 10125 | cindex:[$bounce_return_size_limit$] |
168e428f PH |
10126 | This contains the value set in the %bounce_return_size_limit% option, rounded |
10127 | up to a multiple of 1000. It is useful when a customized error message text | |
10128 | file is in use (see chapter <<CHAPemsgcust>>). | |
10129 | ||
10130 | $caller_gid$:: | |
10131 | cindex:[gid (group id),caller] | |
068aaea8 | 10132 | cindex:[$caller_gid$] |
168e428f PH |
10133 | The real group id under which the process that called Exim was running. This is |
10134 | not the same as the group id of the originator of a message (see | |
10135 | $originator_gid$). If Exim re-execs itself, this variable in the new | |
10136 | incarnation normally contains the Exim gid. | |
10137 | ||
10138 | $caller_uid$:: | |
10139 | cindex:[uid (user id),caller] | |
068aaea8 | 10140 | cindex:[$caller_uid$] |
168e428f PH |
10141 | The real user id under which the process that called Exim was running. This is |
10142 | not the same as the user id of the originator of a message (see | |
10143 | $originator_uid$). If Exim re-execs itself, this variable in the new | |
10144 | incarnation normally contains the Exim uid. | |
10145 | ||
10146 | $compile_date$:: | |
068aaea8 | 10147 | cindex:[$compile_date$] |
168e428f PH |
10148 | The date on which the Exim binary was compiled. |
10149 | ||
10150 | $compile_number$:: | |
068aaea8 | 10151 | cindex:[$compile_number$] |
168e428f PH |
10152 | The building process for Exim keeps a count of the number |
10153 | of times it has been compiled. This serves to distinguish different | |
10154 | compilations of the same version of the program. | |
10155 | ||
10156 | $demime_errorlevel$:: | |
068aaea8 | 10157 | cindex:[$demime_errorlevel$] |
168e428f PH |
10158 | This variable is available when Exim is compiled with |
10159 | the content-scanning extension and the obsolete %demime% condition. For | |
10160 | details, see section <<SECTdemimecond>>. | |
10161 | ||
10162 | $demime_reason$:: | |
068aaea8 | 10163 | cindex:[$demime_reason$] |
168e428f PH |
10164 | This variable is available when Exim is compiled with the |
10165 | content-scanning extension and the obsolete %demime% condition. For details, | |
10166 | see section <<SECTdemimecond>>. | |
10167 | ||
10168 | ||
10169 | $dnslist_domain$:: | |
10170 | cindex:[black list (DNS)] | |
068aaea8 | 10171 | cindex:[$dnslist_domain$] |
168e428f PH |
10172 | When a client host is found to be on a DNS (black) list, |
10173 | the list's domain name is put into this variable so that it can be included in | |
10174 | the rejection message. | |
10175 | ||
10176 | $dnslist_text$:: | |
068aaea8 | 10177 | cindex:[$dnslist_text$] |
168e428f PH |
10178 | When a client host is found to be on a DNS (black) list, the |
10179 | contents of any associated TXT record are placed in this variable. | |
10180 | ||
10181 | $dnslist_value$:: | |
068aaea8 | 10182 | cindex:[$dnslist_value$] |
168e428f PH |
10183 | When a client host is found to be on a DNS (black) list, |
10184 | the IP address from the resource record is placed in this variable. | |
10185 | If there are multiple records, all the addresses are included, comma-space | |
10186 | separated. | |
10187 | ||
10188 | $domain$:: | |
068aaea8 PH |
10189 | cindex:[$domain$] |
10190 | When an address is being routed, or delivered on its own, this variable | |
10191 | contains the domain. Global address rewriting happens when a message is | |
10192 | received, so the value of $domain$ during routing and delivery is the value | |
10193 | after rewriting. $domain$ is set during user filtering, but not during system | |
10194 | filtering, because a message may have many recipients and the system filter is | |
10195 | called just once. | |
168e428f PH |
10196 | + |
10197 | When more than one address is being delivered at once (for example, several | |
10198 | RCPT commands in one SMTP delivery), $domain$ is set only if they all | |
10199 | have the same domain. Transports can be restricted to handling only one domain | |
10200 | at a time if the value of $domain$ is required at transport time -- this is | |
10201 | the default for local transports. For further details of the environment in | |
10202 | which local transports are run, see chapter <<CHAPenvironment>>. | |
10203 | + | |
10204 | cindex:[%delay_warning_condition%] | |
10205 | At the end of a delivery, if all deferred addresses have the same domain, it is | |
10206 | set in $domain$ during the expansion of %delay_warning_condition%. | |
10207 | + | |
10208 | The $domain$ variable is also used in some other circumstances: | |
068aaea8 PH |
10209 | + |
10210 | -- | |
10211 | - When an ACL is running for a RCPT command, $domain$ contains the domain of | |
10212 | the recipient address. The domain of the 'sender' address is in | |
10213 | $sender_address_domain$ at both MAIL time and at RCPT time. $domain$ is not | |
10214 | normally set during the running of the MAIL ACL. However, if the sender address | |
10215 | is verified with a callout during the MAIL ACL, the sender domain is placed in | |
10216 | $domain$ during the expansions of %hosts%, %interface%, and %port% in the | |
10217 | ^smtp^ transport. | |
168e428f PH |
10218 | |
10219 | - When a rewrite item is being processed (see chapter <<CHAPrewrite>>), $domain$ | |
10220 | contains the domain portion of the address that is being rewritten; it can be | |
10221 | used in the expansion of the replacement address, for example, to rewrite | |
10222 | domains by file lookup. | |
10223 | ||
10224 | - With one important exception, whenever a domain list is being scanned, | |
10225 | $domain$ contains the subject domain. *Exception*: When a domain list in | |
10226 | a %sender_domains% condition in an ACL is being processed, the subject domain | |
10227 | is in $sender_address_domain$ and not in $domain$. It works this way so | |
10228 | that, in a RCPT ACL, the sender domain list can be dependent on the | |
10229 | recipient domain (which is what is in $domain$ at this time). | |
10230 | ||
10231 | - cindex:[ETRN,value of $domain$] | |
10232 | cindex:[%smtp_etrn_command%] | |
10233 | When the %smtp_etrn_command% option is being expanded, $domain$ contains | |
10234 | the complete argument of the ETRN command (see section <<SECTETRN>>). | |
068aaea8 | 10235 | -- |
168e428f PH |
10236 | |
10237 | ||
10238 | $domain_data$:: | |
068aaea8 | 10239 | cindex:[$domain_data$] |
168e428f PH |
10240 | When the %domains% option on a router matches a domain by |
10241 | means of a lookup, the data read by the lookup is available during the running | |
10242 | of the router as $domain_data$. In addition, if the driver routes the | |
10243 | address to a transport, the value is available in that transport. If the | |
10244 | transport is handling multiple addresses, the value from the first address is | |
10245 | used. | |
10246 | + | |
10247 | $domain_data$ is also set when the %domains% condition in an ACL matches a | |
10248 | domain by means of a lookup. The data read by the lookup is available during | |
10249 | the rest of the ACL statement. In all other situations, this variable expands | |
10250 | to nothing. | |
10251 | ||
10252 | $exim_gid$:: | |
068aaea8 | 10253 | cindex:[$exim_gid$] |
168e428f PH |
10254 | This variable contains the numerical value of the Exim group id. |
10255 | ||
10256 | $exim_path$:: | |
068aaea8 | 10257 | cindex:[$exim_path$] |
168e428f PH |
10258 | This variable contains the path to the Exim binary. |
10259 | ||
10260 | $exim_uid$:: | |
068aaea8 | 10261 | cindex:[$exim_uid$] |
168e428f PH |
10262 | This variable contains the numerical value of the Exim user id. |
10263 | ||
10264 | $found_extension$:: | |
068aaea8 | 10265 | cindex:[$found_extension$] |
168e428f PH |
10266 | This variable is available when Exim is compiled with the |
10267 | content-scanning extension and the obsolete %demime% condition. For details, | |
10268 | see section <<SECTdemimecond>>. | |
10269 | ||
10270 | $header_$<'name'>:: | |
068aaea8 PH |
10271 | This is not strictly an expansion variable. It is expansion syntax for |
10272 | inserting the message header line with the given name. Note that the name must | |
10273 | be terminated by colon or white space, because it may contain a wide variety of | |
10274 | characters. Note also that braces must 'not' be used. | |
168e428f PH |
10275 | |
10276 | $home$:: | |
068aaea8 | 10277 | cindex:[$home$] |
168e428f PH |
10278 | When the %check_local_user% option is set for a router, the user's home |
10279 | directory is placed in $home$ when the check succeeds. In particular, this | |
10280 | means it is set during the running of users' filter files. A router may also | |
10281 | explicitly set a home directory for use by a transport; this can be overridden | |
10282 | by a setting on the transport itself. | |
10283 | + | |
10284 | When running a filter test via the %-bf% option, $home$ is set to the value | |
10285 | of the environment variable HOME. | |
10286 | ||
10287 | $host$:: | |
068aaea8 | 10288 | cindex:[$host$] |
168e428f PH |
10289 | When the ^smtp^ transport is expanding its options for encryption using TLS, |
10290 | $host$ contains the name of the host to which it is connected. Likewise, when | |
10291 | used in the client part of an authenticator configuration (see chapter | |
10292 | <<CHAPSMTPAUTH>>), $host$ contains the name of the server to which the client | |
10293 | is connected. | |
10294 | + | |
10295 | cindex:[transport,filter] | |
10296 | cindex:[filter,transport filter] | |
10297 | When used in a transport filter (see chapter <<CHAPtransportgeneric>>) $host$ | |
10298 | refers to the host involved in the current connection. When a local transport | |
10299 | is run as a result of a router that sets up a host list, $host$ contains the | |
10300 | name of the first host. | |
10301 | ||
10302 | $host_address$:: | |
068aaea8 | 10303 | cindex:[$host_address$] |
168e428f PH |
10304 | This variable is set to the remote host's IP address whenever $host$ is set for |
10305 | a remote connection. It is also set to the IP address that is being checked | |
10306 | when the %ignore_target_hosts% option is being processed. | |
10307 | ||
10308 | $host_data$:: | |
068aaea8 | 10309 | cindex:[$host_data$] |
168e428f PH |
10310 | If a %hosts% condition in an ACL is satisfied by means of a lookup, the result |
10311 | of the lookup is made available in the $host_data$ variable. This | |
10312 | allows you, for example, to do things like this: | |
10313 | ||
10314 | deny hosts = net-lsearch;/some/file | |
10315 | message = $host_data | |
10316 | ||
10317 | ||
10318 | $host_lookup_deferred$:: | |
10319 | cindex:[host name lookup, failure of] | |
068aaea8 | 10320 | cindex:[$host_lookup_deferred$] |
168e428f PH |
10321 | This variable normally contains ``0'', as does $host_lookup_failed$. When a |
10322 | message comes from a remote host and there is an attempt to look up the host's | |
10323 | name from its IP address, and the attempt is not successful, one of these | |
10324 | variables is set to ``1''. | |
10325 | + | |
10326 | -- | |
10327 | - If the lookup receives a definite negative response (for example, a DNS lookup | |
10328 | succeeded, but no records were found), $host_lookup_failed$ is set to ``1''. | |
10329 | ||
10330 | - If there is any kind of problem during the lookup, such that Exim cannot | |
10331 | tell whether or not the host name is defined (for example, a timeout for a DNS | |
10332 | lookup), $host_lookup_deferred$ is set to ``1''. | |
10333 | -- | |
10334 | + | |
10335 | Looking up a host's name from its IP address consists of more than just a | |
10336 | single reverse lookup. Exim checks that a forward lookup of at least one of the | |
10337 | names it receives from a reverse lookup yields the original IP address. If this | |
10338 | is not the case, Exim does not accept the looked up name(s), and | |
10339 | $host_lookup_failed$ is set to ``1''. Thus, being able to find a name from an | |
10340 | IP address (for example, the existence of a PTR record in the DNS) is not | |
10341 | sufficient on its own for the success of a host name lookup. If the reverse | |
10342 | lookup succeeds, but there is a lookup problem such as a timeout when checking | |
10343 | the result, the name is not accepted, and $host_lookup_deferred$ is set to | |
10344 | ``1''. See also $sender_host_name$. | |
10345 | ||
10346 | $host_lookup_failed$:: | |
068aaea8 | 10347 | cindex:[$host_lookup_failed$] |
168e428f PH |
10348 | See $host_lookup_deferred$. |
10349 | ||
10350 | ||
10351 | $inode$:: | |
068aaea8 | 10352 | cindex:[$inode$] |
168e428f PH |
10353 | The only time this variable is set is while expanding the %directory_file% |
10354 | option in the ^appendfile^ transport. The variable contains the inode number | |
10355 | of the temporary file which is about to be renamed. It can be used to construct | |
10356 | a unique name for the file. | |
10357 | ||
10358 | $interface_address$:: | |
068aaea8 PH |
10359 | + |
10360 | [revisionflag="changed"] | |
10361 | cindex:[$interface_address$] | |
10362 | As soon as a server starts processing a TCP/IP connection, this variable is set | |
10363 | to the address of the local IP interface, and $interface_port$ is set to the | |
10364 | port number. These values are therefore available for use in the ``connect'' | |
10365 | ACL. See also the %-oMi% command line option. As well as being used in ACLs, | |
10366 | these variable could be used, for example, to make the file name for a TLS | |
10367 | certificate depend on which interface and/or port is being used. | |
168e428f PH |
10368 | |
10369 | $interface_port$:: | |
068aaea8 PH |
10370 | cindex:[$interface_port$] |
10371 | See $interface_address$. | |
168e428f PH |
10372 | |
10373 | $ldap_dn$:: | |
068aaea8 | 10374 | cindex:[$ldap_dn$] |
168e428f PH |
10375 | This variable, which is available only when Exim is compiled with LDAP support, |
10376 | contains the DN from the last entry in the most recently successful LDAP | |
10377 | lookup. | |
10378 | ||
10379 | $load_average$:: | |
068aaea8 | 10380 | cindex:[$load_average$] |
168e428f PH |
10381 | This variable contains the system load average, multiplied by 1000 to that it |
10382 | is an integer. For example, if the load average is 0.21, the value of the | |
10383 | variable is 210. The value is recomputed every time the variable is referenced. | |
10384 | ||
10385 | $local_part$:: | |
068aaea8 | 10386 | cindex:[$local_part$] |
168e428f PH |
10387 | When an address is being routed, or delivered on its own, this |
10388 | variable contains the local part. When a number of addresses are being | |
10389 | delivered together (for example, multiple RCPT commands in an SMTP | |
10390 | session), $local_part$ is not set. | |
10391 | + | |
10392 | Global address rewriting happens when a message is received, so the value of | |
10393 | $local_part$ during routing and delivery is the value after rewriting. | |
10394 | $local_part$ is set during user filtering, but not during system filtering, | |
10395 | because a message may have many recipients and the system filter is called just | |
10396 | once. | |
10397 | + | |
068aaea8 PH |
10398 | cindex:[$local_part_prefix$] |
10399 | cindex:[$local_part_suffix$] | |
168e428f PH |
10400 | If a local part prefix or suffix has been recognized, it is not included in the |
10401 | value of $local_part$ during routing and subsequent delivery. The values of | |
10402 | any prefix or suffix are in $local_part_prefix$ and | |
10403 | $local_part_suffix$, respectively. | |
10404 | + | |
10405 | When a message is being delivered to a file, pipe, or autoreply transport as a | |
10406 | result of aliasing or forwarding, $local_part$ is set to the local part of | |
10407 | the parent address, not to the file name or command (see $address_file$ and | |
10408 | $address_pipe$). | |
10409 | + | |
10410 | When an ACL is running for a RCPT command, $local_part$ contains the | |
10411 | local part of the recipient address. | |
10412 | + | |
10413 | When a rewrite item is being processed (see chapter <<CHAPrewrite>>), | |
10414 | $local_part$ contains the local part of the address that is being rewritten; | |
10415 | it can be used in the expansion of the replacement address, for example. | |
10416 | + | |
10417 | In all cases, all quoting is removed from the local part. For example, for both | |
10418 | the addresses | |
10419 | ||
10420 | "abc:xyz"@test.example | |
10421 | abc\:xyz@test.example | |
10422 | + | |
10423 | the value of $local_part$ is | |
10424 | ||
10425 | abc:xyz | |
10426 | + | |
10427 | If you use $local_part$ to create another address, you should always wrap it | |
10428 | inside a quoting operator. For example, in a ^redirect^ router you could have: | |
10429 | ||
10430 | data = ${quote_local_part:$local_part}@new.domain.example | |
10431 | + | |
10432 | *Note*: The value of $local_part$ is normally lower cased. If you want | |
10433 | to process local parts in a case-dependent manner in a router, you can set the | |
10434 | %caseful_local_part% option (see chapter <<CHAProutergeneric>>). | |
10435 | ||
10436 | $local_part_data$:: | |
068aaea8 | 10437 | cindex:[$local_part_data$] |
168e428f PH |
10438 | When the %local_parts% option on a router matches a local part by means of a |
10439 | lookup, the data read by the lookup is available during the running of the | |
10440 | router as $local_part_data$. In addition, if the driver routes the address | |
10441 | to a transport, the value is available in that transport. If the transport is | |
10442 | handling multiple addresses, the value from the first address is used. | |
10443 | + | |
10444 | $local_part_data$ is also set when the %local_parts% condition in an ACL | |
10445 | matches a local part by means of a lookup. The data read by the lookup is | |
10446 | available during the rest of the ACL statement. In all other situations, this | |
10447 | variable expands to nothing. | |
10448 | ||
10449 | $local_part_prefix$:: | |
068aaea8 | 10450 | cindex:[$local_part_prefix$] |
168e428f PH |
10451 | When an address is being routed or delivered, and a |
10452 | specific prefix for the local part was recognized, it is available in this | |
10453 | variable, having been removed from $local_part$. | |
10454 | ||
10455 | $local_part_suffix$:: | |
068aaea8 | 10456 | cindex:[$local_part_suffix$] |
168e428f PH |
10457 | When an address is being routed or delivered, and a |
10458 | specific suffix for the local part was recognized, it is available in this | |
10459 | variable, having been removed from $local_part$. | |
10460 | ||
10461 | $local_scan_data$:: | |
068aaea8 | 10462 | cindex:[$local_scan_data$] |
168e428f PH |
10463 | This variable contains the text returned by the 'local_scan()' function when a |
10464 | message is received. See chapter <<CHAPlocalscan>> for more details. | |
10465 | ||
10466 | $local_user_gid$:: | |
068aaea8 | 10467 | cindex:[$local_user_gid$] |
168e428f PH |
10468 | See $local_user_uid$. |
10469 | ||
10470 | $local_user_uid$:: | |
068aaea8 PH |
10471 | cindex:[$local_user_uid$] |
10472 | This variable and $local_user_gid$ are set to the uid and gid after the | |
10473 | %check_local_user% router precondition succeeds. This means that their values | |
10474 | are available for the remaining preconditions (%senders%, %require_files%, and | |
10475 | %condition%), for the %address_data% expansion, and for any router-specific | |
10476 | expansions. At all other times, the values in these variables are `(uid_t)(-1)` | |
10477 | and `(gid_t)(-1)`, respectively. | |
168e428f PH |
10478 | |
10479 | $localhost_number$:: | |
068aaea8 | 10480 | cindex:[$localhost_number$] |
168e428f PH |
10481 | This contains the expanded value of the |
10482 | %localhost_number% option. The expansion happens after the main options have | |
10483 | been read. | |
10484 | ||
10485 | $log_inodes$:: | |
068aaea8 | 10486 | cindex:[$log_inodes$] |
168e428f PH |
10487 | The number of free inodes in the disk partition where Exim's |
10488 | log files are being written. The value is recalculated whenever the variable is | |
10489 | referenced. If the relevant file system does not have the concept of inodes, | |
10490 | the value of is -1. See also the %check_log_inodes% option. | |
10491 | ||
10492 | $log_space$:: | |
068aaea8 | 10493 | cindex:[$log_space$] |
168e428f PH |
10494 | The amount of free space (as a number of kilobytes) in the disk |
10495 | partition where Exim's log files are being written. The value is recalculated | |
10496 | whenever the variable is referenced. If the operating system does not have the | |
10497 | ability to find the amount of free space (only true for experimental systems), | |
10498 | the space value is -1. See also the %check_log_space% option. | |
10499 | ||
10500 | ||
10501 | $mailstore_basename$:: | |
068aaea8 PH |
10502 | cindex:[$mailstore_basename$] |
10503 | This variable is set only when doing deliveries in ``mailstore'' format in the | |
10504 | ^appendfile^ transport. During the expansion of the %mailstore_prefix%, | |
10505 | %mailstore_suffix%, %message_prefix%, and %message_suffix% options, it contains | |
10506 | the basename of the files that are being written, that is, the name without the | |
10507 | ``.tmp'', ``.env'', or ``.msg'' suffix. At all other times, this variable is | |
10508 | empty. | |
168e428f PH |
10509 | |
10510 | $malware_name$:: | |
068aaea8 | 10511 | cindex:[$malware_name$] |
168e428f PH |
10512 | This variable is available when Exim is compiled with the |
10513 | content-scanning extension. It is set to the name of the virus that was found | |
10514 | when the ACL %malware% condition is true (see section <<SECTscanvirus>>). | |
10515 | ||
10516 | ||
10517 | $message_age$:: | |
10518 | cindex:[message,age of] | |
068aaea8 PH |
10519 | cindex:[$message_age$] |
10520 | This variable is set at the start of a delivery attempt to contain the number | |
10521 | of seconds since the message was received. It does not change during a single | |
10522 | delivery attempt. | |
168e428f PH |
10523 | |
10524 | $message_body$:: | |
10525 | cindex:[body of message,expansion variable] | |
10526 | cindex:[message body, in expansion] | |
10527 | cindex:[binary zero,in message body] | |
068aaea8 | 10528 | cindex:[$message_body$] |
168e428f PH |
10529 | This variable contains the initial portion of a message's |
10530 | body while it is being delivered, and is intended mainly for use in filter | |
10531 | files. The maximum number of characters of the body that are put into the | |
10532 | variable is set by the %message_body_visible% configuration option; the | |
10533 | default is 500. Newlines are converted into spaces to make it easier to search | |
10534 | for phrases that might be split over a line break. | |
10535 | Binary zeros are also converted into spaces. | |
10536 | ||
10537 | $message_body_end$:: | |
10538 | cindex:[body of message,expansion variable] | |
10539 | cindex:[message body, in expansion] | |
068aaea8 | 10540 | cindex:[$message_body_end$] |
168e428f PH |
10541 | This variable contains the final portion of a message's |
10542 | body while it is being delivered. The format and maximum size are as for | |
10543 | $message_body$. | |
10544 | ||
10545 | $message_body_size$:: | |
10546 | cindex:[body of message,size] | |
10547 | cindex:[message body, size] | |
068aaea8 PH |
10548 | cindex:[$message_body_size$] |
10549 | When a message is being delivered, this variable contains the size of the body | |
10550 | in bytes. The count starts from the character after the blank line that | |
10551 | separates the body from the header. Newlines are included in the count. See | |
10552 | also $message_size$, $body_linecount$, and $body_zerocount$. | |
10553 | ||
10554 | $message_exim_id$:: | |
10555 | + | |
10556 | [revisionflag="changed"] | |
10557 | cindex:[$message_exim_id$] | |
10558 | When a message is being received or delivered, this variable contains the | |
10559 | unique message id that is generated and used by Exim to identify the message. | |
10560 | An id is not created for a message until after its header has been successfully | |
10561 | received. *Note*: This is 'not' the contents of the 'Message-ID:' header line; | |
10562 | it is the local id that Exim assigns to the message, for example: | |
10563 | `1BXTIK-0001yO-VA`. | |
168e428f PH |
10564 | |
10565 | $message_headers$:: | |
10566 | This variable contains a concatenation of all the header lines when a message | |
10567 | is being processed, except for lines added by routers or transports. The header | |
10568 | lines are separated by newline characters. | |
10569 | ||
10570 | $message_id$:: | |
068aaea8 PH |
10571 | + |
10572 | [revisionflag="changed"] | |
10573 | This is an old name for $message_exim_id$, which is now deprecated. | |
10574 | ||
10575 | $message_linecount$:: | |
10576 | + | |
10577 | [revisionflag="changed"] | |
10578 | cindex:[$message_linecount$] | |
10579 | This variable contains the total number of lines in the header and body of the | |
10580 | message. Compare $body_linecount$, which is the count for the body only. During | |
10581 | the DATA and content-scanning ACLs, $message_linecount$ contains the number of | |
10582 | lines received. Before delivery happens (that is, before filters, routers, and | |
10583 | transports run) the count is increased to include the 'Received:' header line | |
10584 | that Exim standardly adds, and also any other header lines that are added by | |
10585 | ACLs. The blank line that separates the message header from the body is not | |
10586 | counted. Here is an example of the use of this variable in a DATA ACL: | |
10587 | + | |
10588 | [revisionflag="changed"] | |
10589 | .... | |
10590 | deny message = Too many lines in message header | |
10591 | condition = \ | |
10592 | ${if <{250}{${eval: $message_linecount - $body_linecount}}} | |
10593 | .... | |
10594 | + | |
10595 | [revisionflag="changed"] | |
10596 | In the MAIL and RCPT ACLs, the value is zero because at that stage the | |
10597 | message has not yet been received. | |
168e428f PH |
10598 | |
10599 | $message_size$:: | |
10600 | cindex:[size,of message] | |
10601 | cindex:[message,size] | |
068aaea8 | 10602 | cindex:[$message_size$] |
168e428f PH |
10603 | When a message is being processed, this variable contains its size in bytes. In |
10604 | most cases, the size includes those headers that were received with the | |
10605 | message, but not those (such as 'Envelope-to:') that are added to individual | |
10606 | deliveries as they are written. However, there is one special case: during the | |
10607 | expansion of the %maildir_tag% option in the ^appendfile^ transport while | |
10608 | doing a delivery in maildir format, the value of $message_size$ is the | |
10609 | precise size of the file that has been written. See also | |
10610 | $message_body_size$, $body_linecount$, and $body_zerocount$. | |
10611 | + | |
10612 | cindex:[RCPT,value of $message_size$] | |
10613 | While running an ACL at the time of an SMTP RCPT command, $message_size$ | |
10614 | contains the size supplied on the MAIL command, or -1 if no size was given. The | |
10615 | value may not, of course, be truthful. | |
10616 | ||
10617 | $mime_$'xxx':: | |
10618 | A number of variables whose names start with $mime$ are | |
10619 | available when Exim is compiled with the content-scanning extension. For | |
10620 | details, see section <<SECTscanmimepart>>. | |
10621 | ||
168e428f PH |
10622 | $n0$ -- $n9$:: |
10623 | These variables are counters that can be incremented by means | |
10624 | of the %add% command in filter files. | |
10625 | ||
10626 | $original_domain$:: | |
068aaea8 PH |
10627 | cindex:[$domain$] |
10628 | cindex:[$original_domain$] | |
10629 | When a top-level address is being processed for delivery, this contains the | |
10630 | same value as $domain$. However, if a ``child'' address (for example, generated | |
10631 | by an alias, forward, or filter file) is being processed, this variable | |
10632 | contains the domain of the original address. This differs from $parent_domain$ | |
10633 | only when there is more than one level of aliasing or forwarding. When more | |
10634 | than one address is being delivered in a single transport run, | |
10635 | $original_domain$ is not set. | |
168e428f PH |
10636 | + |
10637 | If new an address is created by means of a %deliver% command in a system | |
10638 | filter, it is set up with an artificial ``parent'' address. This has the local | |
10639 | part 'system-filter' and the default qualify domain. | |
10640 | ||
10641 | $original_local_part$:: | |
068aaea8 PH |
10642 | cindex:[$local_part$] |
10643 | cindex:[$original_local_part$] | |
10644 | When a top-level address is being processed for delivery, this contains the | |
10645 | same value as $local_part$, unless a prefix or suffix was removed from the | |
10646 | local part, because $original_local_part$ always contains the full local part. | |
10647 | When a ``child'' address (for example, generated by an alias, forward, or | |
10648 | filter file) is being processed, this variable contains the full local part of | |
10649 | the original address. | |
168e428f PH |
10650 | + |
10651 | If the router that did the redirection processed the local part | |
10652 | case-insensitively, the value in $original_local_part$ is in lower case. | |
10653 | This variable differs from $parent_local_part$ only when there is more than | |
10654 | one level of aliasing or forwarding. When more than one address is being | |
10655 | delivered in a single transport run, $original_local_part$ is not set. | |
10656 | + | |
10657 | If new an address is created by means of a %deliver% command in a system | |
10658 | filter, it is set up with an artificial ``parent'' address. This has the local | |
10659 | part 'system-filter' and the default qualify domain. | |
10660 | ||
168e428f PH |
10661 | $originator_gid$:: |
10662 | cindex:[gid (group id),of originating user] | |
10663 | cindex:[sender,gid] | |
068aaea8 PH |
10664 | cindex:[$caller_gid$] |
10665 | cindex:[$originator_gid$] | |
10666 | This variable contains the value of $caller_gid$ that was set when the message | |
168e428f PH |
10667 | was received. For messages received via the command line, this is the gid of |
10668 | the sending user. For messages received by SMTP over TCP/IP, this is normally | |
10669 | the gid of the Exim user. | |
10670 | ||
10671 | $originator_uid$:: | |
10672 | cindex:[uid (user id),of originating user] | |
10673 | cindex:[sender,uid] | |
068aaea8 PH |
10674 | cindex:[$caller_uid$] |
10675 | cindex:[$originaltor_uid$] | |
10676 | The value of $caller_uid$ that was set when the message was received. For | |
10677 | messages received via the command line, this is the uid of the sending user. | |
10678 | For messages received by SMTP over TCP/IP, this is normally the uid of the Exim | |
10679 | user. | |
168e428f PH |
10680 | |
10681 | $parent_domain$:: | |
068aaea8 | 10682 | cindex:[$parent_domain$] |
168e428f PH |
10683 | This variable is similar to $original_domain$ (see |
10684 | above), except that it refers to the immediately preceding parent address. | |
10685 | ||
10686 | $parent_local_part$:: | |
068aaea8 | 10687 | cindex:[$parent_local_part$] |
168e428f PH |
10688 | This variable is similar to $original_local_part$ |
10689 | (see above), except that it refers to the immediately preceding parent address. | |
10690 | ||
10691 | $pid$:: | |
10692 | cindex:[pid (process id),of current process] | |
068aaea8 | 10693 | cindex:[$pid$] |
168e428f PH |
10694 | This variable contains the current process id. |
10695 | ||
10696 | $pipe_addresses$:: | |
10697 | cindex:[filter,transport filter] | |
10698 | cindex:[transport,filter] | |
068aaea8 PH |
10699 | cindex:[$pipe_addresses$] |
10700 | This is not an expansion variable, but is mentioned here because the string | |
10701 | ``\$pipe_addresses'' is handled specially in the command specification for the | |
10702 | ^pipe^ transport (chapter <<CHAPpipetransport>>) and in transport filters | |
10703 | (described under %transport_filter% in chapter <<CHAPtransportgeneric>>). It | |
10704 | cannot be used in general expansion strings, and provokes an ``unknown | |
10705 | variable'' error if encountered. | |
168e428f PH |
10706 | |
10707 | $primary_hostname$:: | |
068aaea8 PH |
10708 | cindex:[$primary_hostname$] |
10709 | This variable contains the value set by %primary_hostname% in the configuration | |
10710 | file, or read by the 'uname()' function. If 'uname()' returns a | |
10711 | single-component name, Exim calls 'gethostbyname()' (or 'getipnodebyname()' | |
10712 | where available) in an attempt to acquire a fully qualified host name. See also | |
10713 | $smtp_active_hostname$. | |
10714 | ||
10715 | ||
10716 | $prvscheck_address$:: | |
10717 | + | |
10718 | [revisionflag="changed"] | |
10719 | This variable is used in conjunction with the %prvscheck% expansion item, which | |
10720 | is described in sections <<SECTexpansionitems>> and <<SECTverifyPRVS>>. | |
10721 | ||
10722 | $prvscheck_keynum$:: | |
10723 | + | |
10724 | [revisionflag="changed"] | |
10725 | This variable is used in conjunction with the %prvscheck% expansion item, which | |
10726 | is described in sections <<SECTexpansionitems>> and <<SECTverifyPRVS>>. | |
10727 | ||
10728 | $prvscheck_result$:: | |
10729 | + | |
10730 | [revisionflag="changed"] | |
10731 | This variable is used in conjunction with the %prvscheck% expansion item, which | |
10732 | is described in sections <<SECTexpansionitems>> and <<SECTverifyPRVS>>. | |
168e428f PH |
10733 | |
10734 | $qualify_domain$:: | |
068aaea8 PH |
10735 | cindex:[$qualify_domain$] |
10736 | The value set for the %qualify_domain% option in the configuration file. | |
168e428f PH |
10737 | |
10738 | $qualify_recipient$:: | |
068aaea8 PH |
10739 | cindex:[$qualify_recipient$] |
10740 | The value set for the %qualify_recipient% option in the configuration file, | |
168e428f PH |
10741 | or if not set, the value of $qualify_domain$. |
10742 | ||
10743 | $rcpt_count$:: | |
068aaea8 PH |
10744 | cindex:[$rcpt_count$] |
10745 | When a message is being received by SMTP, this variable contains the number of | |
10746 | RCPT commands received for the current message. If this variable is used in a | |
10747 | RCPT ACL, its value includes the current command. | |
168e428f PH |
10748 | |
10749 | $rcpt_defer_count$:: | |
068aaea8 PH |
10750 | cindex:[$rcpt_defer_count$] |
10751 | When a message is being received by SMTP, this variable contains the number of | |
10752 | RCPT commands in the current message that have previously been rejected with a | |
10753 | temporary (4##'xx') response. | |
168e428f PH |
10754 | |
10755 | $rcpt_fail_count$:: | |
068aaea8 PH |
10756 | cindex:[$rcpt_fail_count$] |
10757 | When a message is being received by SMTP, this variable contains the number of | |
10758 | RCPT commands in the current message that have previously been rejected with a | |
10759 | permanent (5##'xx') response. | |
168e428f PH |
10760 | |
10761 | $received_count$:: | |
068aaea8 PH |
10762 | cindex:[$received_count$] |
10763 | This variable contains the number of 'Received:' header lines in the message, | |
10764 | including the one added by Exim (so its value is always greater than zero). It | |
10765 | is available in the DATA ACL, the non-SMTP ACL, and while routing and | |
10766 | delivering. | |
168e428f PH |
10767 | |
10768 | $received_for$:: | |
068aaea8 PH |
10769 | cindex:[$received_for$] |
10770 | If there is only a single recipient address in an incoming message, this | |
10771 | variable contains that address when the 'Received:' header line is being built. | |
168e428f PH |
10772 | The value is copied after recipient rewriting has happened, but before the |
10773 | 'local_scan()' function is run. | |
10774 | ||
10775 | $received_protocol$:: | |
068aaea8 PH |
10776 | cindex:[$received_protocol$] |
10777 | When a message is being processed, this variable contains the name of the | |
10778 | protocol by which it was received. Most of the names used by Exim are defined | |
10779 | by RFCs 821, 2821, and 3848. They start with ``smtp'' (the client used HELO) or | |
10780 | ``esmtp'' (the client used EHLO). This can be followed by ``s'' for secure | |
10781 | (encrypted) and/or ``a'' for authenticated. Thus, for example, if the protocol | |
10782 | is set to ``esmtpsa'', the message was received over an encrypted SMTP | |
10783 | connection and the client was successfully authenticated. | |
168e428f PH |
10784 | + |
10785 | Exim uses the protocol name ``smtps'' for the case when encryption is | |
10786 | automatically set up on connection without the use of STARTTLS (see | |
10787 | %tls_on_connect_ports%), and the client uses HELO to initiate the | |
10788 | encrypted SMTP session. The name ``smtps'' is also used for the rare situation | |
10789 | where the client initially uses EHLO, sets up an encrypted connection using | |
10790 | STARTTLS, and then uses HELO afterwards. | |
10791 | + | |
10792 | The %-oMr% option provides a way of specifying a custom protocol name for | |
10793 | messages that are injected locally by trusted callers. This is commonly used to | |
10794 | identify messages that are being re-injected after some kind of scanning. | |
10795 | ||
068aaea8 PH |
10796 | $received_time$:: |
10797 | + | |
10798 | [revisionflag="changed"] | |
10799 | cindex:[$received_time$] | |
10800 | This variable contains the date and time when the current message was received, | |
10801 | as a number of seconds since the start of the Unix epoch. | |
168e428f PH |
10802 | |
10803 | $recipient_data$:: | |
068aaea8 PH |
10804 | cindex:[$recipient_data$] |
10805 | This variable is set after an indexing lookup success in an ACL %recipients% | |
10806 | condition. It contains the data from the lookup, and the value remains set | |
10807 | until the next %recipients% test. Thus, you can do things like this: | |
168e428f PH |
10808 | + |
10809 | &&& | |
10810 | `require recipients = cdb*@;/some/file` | |
10811 | `deny `'some further test involving' `\$recipient_data` | |
10812 | &&& | |
10813 | + | |
10814 | *Warning*: This variable is set only when a lookup is used as an indexing | |
10815 | method in the address list, using the semicolon syntax as in the example above. | |
10816 | The variable is not set for a lookup that is used as part of the string | |
10817 | expansion that all such lists undergo before being interpreted. | |
10818 | ||
10819 | $recipient_verify_failure$:: | |
068aaea8 PH |
10820 | cindex:[$recipient_verify_failure$] |
10821 | In an ACL, when a recipient verification fails, this variable contains | |
10822 | information about the failure. It is set to one of the following words: | |
168e428f PH |
10823 | + |
10824 | -- | |
10825 | - ``qualify'': The address was unqualified (no domain), and the message | |
10826 | was neither local nor came from an exempted host. | |
10827 | ||
10828 | - ``route'': Routing failed. | |
10829 | ||
10830 | - ``mail'': Routing succeeded, and a callout was attempted; rejection occurred at | |
10831 | or before the MAIL command (that is, on initial connection, HELO, or | |
10832 | MAIL). | |
10833 | ||
10834 | - ``recipient'': The RCPT command in a callout was rejected. | |
10835 | ||
10836 | - ``postmaster'': The postmaster check in a callout was rejected. | |
10837 | -- | |
10838 | + | |
10839 | The main use of this variable is expected to be to distinguish between | |
10840 | rejections of MAIL and rejections of RCPT. | |
10841 | ||
10842 | ||
10843 | $recipients$:: | |
068aaea8 | 10844 | cindex:[$recipients$] |
168e428f PH |
10845 | This variable contains a list of envelope recipients for a |
10846 | message. A comma and a space separate the addresses in the replacement text. | |
10847 | However, the variable is not generally available, to prevent exposure of Bcc | |
10848 | recipients in unprivileged users' filter files. You can use $recipients$ only | |
10849 | in these two cases: | |
10850 | ||
10851 | . In a system filter file. | |
10852 | ||
10853 | . In the ACLs associated with the DATA command, that is, the ACLs defined by | |
10854 | %acl_smtp_predata% and %acl_smtp_data%. | |
10855 | ||
10856 | ||
10857 | $recipients_count$:: | |
068aaea8 PH |
10858 | cindex:[$recipients_count$] |
10859 | When a message is being processed, this variable contains the number of | |
10860 | envelope recipients that came with the message. Duplicates are not excluded | |
10861 | from the count. While a message is being received over SMTP, the number | |
10862 | increases for each accepted recipient. It can be referenced in an ACL. | |
168e428f PH |
10863 | |
10864 | $reply_address$:: | |
068aaea8 PH |
10865 | cindex:[$reply_address$] |
10866 | When a message is being processed, this variable contains the contents of the | |
10867 | 'Reply-To:' header line if one exists and it is not empty, or otherwise the | |
10868 | contents of the 'From:' header line. | |
168e428f PH |
10869 | |
10870 | $return_path$:: | |
068aaea8 | 10871 | cindex:[$return_path$] |
168e428f PH |
10872 | When a message is being delivered, this variable contains the return path -- |
10873 | the sender field that will be sent as part of the envelope. It is not enclosed | |
10874 | in <> characters. At the start of routing an address, $return_path$ has the | |
10875 | same value as $sender_address$, but if, for example, an incoming message to a | |
10876 | mailing list has been expanded by a router which specifies a different address | |
10877 | for bounce messages, $return_path$ subsequently contains the new bounce | |
10878 | address, whereas $sender_address$ always contains the original sender address | |
10879 | that was received with the message. In other words, $sender_address$ contains | |
10880 | the incoming envelope sender, and $return_path$ contains the outgoing envelope | |
10881 | sender. | |
10882 | ||
10883 | $return_size_limit$:: | |
068aaea8 | 10884 | cindex:[$return_size_limit$] |
168e428f PH |
10885 | This is an obsolete name for $bounce_return_size_limit$. |
10886 | ||
10887 | $runrc$:: | |
10888 | cindex:[return code,from %run% expansion] | |
068aaea8 | 10889 | cindex:[$runrc$] |
168e428f PH |
10890 | This variable contains the return code from a command that is run by the |
10891 | %\$\{run...\}% expansion item. *Warning*: In a router or transport, you cannot | |
10892 | assume the order in which option values are expanded, except for those | |
10893 | pre-conditions whose order of testing is documented. Therefore, you cannot | |
10894 | reliably expect to set $runrc$ by the expansion of one option, and use it in | |
10895 | another. | |
10896 | ||
10897 | $self_hostname$:: | |
168e428f | 10898 | cindex:[%self% option,value of host name] |
068aaea8 PH |
10899 | cindex:[$self_hostname$] |
10900 | When an address is routed to a supposedly remote host that turns out to be the | |
10901 | local host, what happens is controlled by the %self% generic router option. One | |
10902 | of its values causes the address to be passed to another router. When this | |
10903 | happens, $self_hostname$ is set to the name of the local host that the original | |
10904 | router encountered. In other circumstances its contents are null. | |
168e428f PH |
10905 | |
10906 | $sender_address$:: | |
068aaea8 PH |
10907 | cindex:[$sender_address$] |
10908 | When a message is being processed, this variable contains the sender's address | |
10909 | that was received in the message's envelope. For bounce messages, the value of | |
10910 | this variable is the empty string. See also $return_path$. | |
168e428f PH |
10911 | |
10912 | $sender_address_data$:: | |
068aaea8 PH |
10913 | cindex:[$address_data$] |
10914 | cindex:[$sender_address_data$] | |
168e428f PH |
10915 | If $address_data$ is set when the routers are called from an ACL to verify a |
10916 | sender address, the final value is preserved in $sender_address_data$, to | |
10917 | distinguish it from data from a recipient address. The value does not persist | |
10918 | after the end of the current ACL statement. If you want to preserve it for | |
10919 | longer, you can save it in an ACL variable. | |
10920 | ||
168e428f | 10921 | $sender_address_domain$:: |
068aaea8 | 10922 | cindex:[$sender_address_domain$] |
168e428f PH |
10923 | The domain portion of $sender_address$. |
10924 | ||
10925 | $sender_address_local_part$:: | |
068aaea8 | 10926 | cindex:[$sender_address_local_part$] |
168e428f PH |
10927 | The local part portion of $sender_address$. |
10928 | ||
10929 | $sender_data$:: | |
068aaea8 | 10930 | cindex:[$sender_data$] |
168e428f PH |
10931 | This variable is set after a lookup success in an ACL %senders% condition or in |
10932 | a router %senders% option. It contains the data from the lookup, and the value | |
10933 | remains set until the next %senders% test. Thus, you can do things like this: | |
10934 | + | |
10935 | &&& | |
10936 | `require senders = cdb*@;/some/file` | |
10937 | `deny `'some further test involving' `\$sender_data` | |
10938 | &&& | |
10939 | + | |
10940 | *Warning*: This variable is set only when a lookup is used as an indexing | |
10941 | method in the address list, using the semicolon syntax as in the example above. | |
10942 | The variable is not set for a lookup that is used as part of the string | |
10943 | expansion that all such lists undergo before being interpreted. | |
10944 | ||
10945 | $sender_fullhost$:: | |
068aaea8 | 10946 | cindex:[$sender_fullhost$] |
168e428f PH |
10947 | When a message is received from a remote host, this variable contains the host |
10948 | name and IP address in a single string. It ends with the IP address in square | |
10949 | brackets, followed by a colon and a port number if the logging of ports is | |
10950 | enabled. The format of the rest of the string depends on whether the host | |
10951 | issued a HELO or EHLO SMTP command, and whether the host name was verified by | |
10952 | looking up its IP address. (Looking up the IP address can be forced by the | |
10953 | %host_lookup% option, independent of verification.) A plain host name at the | |
10954 | start of the string is a verified host name; if this is not present, | |
10955 | verification either failed or was not requested. A host name in parentheses is | |
10956 | the argument of a HELO or EHLO command. This is omitted if it is identical to | |
10957 | the verified host name or to the host's IP address in square brackets. | |
10958 | ||
10959 | $sender_helo_name$:: | |
068aaea8 PH |
10960 | cindex:[$sender_hslo_name$] |
10961 | When a message is received from a remote host that has issued a HELO or EHLO | |
10962 | command, the argument of that command is placed in this variable. It is also | |
10963 | set if HELO or EHLO is used when a message is received using SMTP locally via | |
10964 | the %-bs% or %-bS% options. | |
168e428f PH |
10965 | |
10966 | $sender_host_address$:: | |
068aaea8 PH |
10967 | cindex:[$sender_host_address$] |
10968 | When a message is received from a remote host, this variable contains that | |
10969 | host's IP address. For locally submitted messages, it is empty. | |
168e428f PH |
10970 | |
10971 | $sender_host_authenticated$:: | |
068aaea8 | 10972 | cindex:[$sender_host_authenticated$] |
168e428f | 10973 | This variable contains the name (not the public name) of the authenticator |
068aaea8 PH |
10974 | driver that successfully authenticated the client from which the message was |
10975 | received. It is empty if there was no successful authentication. See also | |
10976 | $authenticated_id$. | |
168e428f PH |
10977 | |
10978 | $sender_host_name$:: | |
068aaea8 | 10979 | cindex:[$sender_host_name$] |
168e428f PH |
10980 | When a message is received from a remote host, this variable contains the |
10981 | host's name as obtained by looking up its IP address. For messages received by | |
10982 | other means, this variable is empty. | |
10983 | + | |
068aaea8 | 10984 | cindex:[$host_lookup_failed$] |
168e428f PH |
10985 | If the host name has not previously been looked up, a reference to |
10986 | $sender_host_name$ triggers a lookup (for messages from remote hosts). | |
10987 | A looked up name is accepted only if it leads back to the original IP address | |
10988 | via a forward lookup. If either the reverse or the forward lookup fails to find | |
10989 | any data, or if the forward lookup does not yield the original IP address, | |
10990 | $sender_host_name$ remains empty, and $host_lookup_failed$ is set to ``1''. | |
10991 | + | |
068aaea8 | 10992 | cindex:[$host_lookup_deferred$] |
168e428f PH |
10993 | However, if either of the lookups cannot be completed (for example, there is a |
10994 | DNS timeout), $host_lookup_deferred$ is set to ``1'', and | |
10995 | $host_lookup_failed$ remains set to ``0''. | |
10996 | + | |
10997 | Once $host_lookup_failed$ is set to ``1'', Exim does not try to look up the | |
10998 | host name again if there is a subsequent reference to $sender_host_name$ | |
10999 | in the same Exim process, but it does try again if $sender_host_deferred$ | |
11000 | is set to ``1''. | |
11001 | + | |
11002 | Exim does not automatically look up every calling host's name. If you want | |
11003 | maximum efficiency, you should arrange your configuration so that it avoids | |
11004 | these lookups altogether. The lookup happens only if one or more of the | |
11005 | following are true: | |
11006 | ||
11007 | - A string containing $sender_host_name$ is expanded. | |
11008 | ||
11009 | - The calling host matches the list in %host_lookup%. In the default | |
11010 | configuration, this option is set to \*, so it must be changed if lookups are | |
11011 | to be avoided. (In the code, the default for %host_lookup% is unset.) | |
11012 | ||
11013 | - Exim needs the host name in order to test an item in a host list. The items | |
11014 | that require this are described in sections <<SECThoslispatnam>> and | |
11015 | <<SECThoslispatnamsk>>. | |
11016 | ||
11017 | - The calling host matches %helo_try_verify_hosts% or %helo_verify_hosts%. | |
11018 | In this case, the host name is required to compare with the name quoted in any | |
11019 | EHLO or HELO commands that the client issues. | |
11020 | ||
11021 | - The remote host issues a EHLO or HELO command that quotes one of the | |
11022 | domains in %helo_lookup_domains%. The default value of this option is | |
11023 | + | |
11024 | .... | |
11025 | helo_lookup_domains = @ : @[] | |
11026 | .... | |
11027 | + | |
11028 | which causes a lookup if a remote host (incorrectly) gives the server's name or | |
11029 | IP address in an EHLO or HELO command. | |
11030 | ||
11031 | ||
11032 | $sender_host_port$:: | |
068aaea8 PH |
11033 | cindex:[$sender_host_port$] |
11034 | When a message is received from a remote host, this variable contains the port | |
11035 | number that was used on the remote host. | |
168e428f PH |
11036 | |
11037 | $sender_ident$:: | |
068aaea8 | 11038 | cindex:[$sender_ident$] |
168e428f PH |
11039 | When a message is received from a remote host, this variable contains the |
11040 | identification received in response to an RFC 1413 request. When a message has | |
11041 | been received locally, this variable contains the login name of the user that | |
11042 | called Exim. | |
11043 | ||
068aaea8 PH |
11044 | $sender_rate_$'xxx':: |
11045 | + | |
11046 | [revisionflag="changed"] | |
11047 | A number of variables whose names begin $sender_rate_$ are set as part of the | |
11048 | %ratelimit% ACL condition. Details are given in section <<SECTratelimiting>>. | |
11049 | ||
168e428f | 11050 | $sender_rcvhost$:: |
168e428f PH |
11051 | cindex:[DNS,reverse lookup] |
11052 | cindex:[reverse DNS lookup] | |
068aaea8 PH |
11053 | cindex:[$sender_rcvhost$] |
11054 | This is provided specifically for use in 'Received:' headers. It starts with | |
11055 | either the verified host name (as obtained from a reverse DNS lookup) or, if | |
11056 | there is no verified host name, the IP address in square brackets. After that | |
11057 | there may be text in parentheses. When the first item is a verified host name, | |
11058 | the first thing in the parentheses is the IP address in square brackets, | |
11059 | followed by a colon and a port number if port logging is enabled. When the | |
11060 | first item is an IP address, the port is recorded as ``port='xxxx'##'' inside | |
11061 | the parentheses. | |
168e428f PH |
11062 | + |
11063 | There may also be items of the form ``helo='xxxx'##'' if HELO or EHLO | |
11064 | was used and its argument was not identical to the real host name or IP | |
11065 | address, and ``ident='xxxx'##'' if an RFC 1413 ident string is available. If all | |
11066 | three items are present in the parentheses, a newline and tab are inserted into | |
11067 | the string, to improve the formatting of the 'Received:' header. | |
11068 | ||
11069 | $sender_verify_failure$:: | |
068aaea8 | 11070 | cindex:[$sender_verify_failure$] |
168e428f PH |
11071 | In an ACL, when a sender verification fails, this variable contains information |
11072 | about the failure. The details are the same as for $recipient_verify_failure$. | |
11073 | ||
11074 | $smtp_active_hostname$:: | |
068aaea8 | 11075 | cindex:[$smtp_active_hostname$] |
168e428f PH |
11076 | During an SMTP session, this variable contains the value of the active host |
11077 | name, as specified by the %smtp_active_hostname% option. The value of | |
11078 | $smtp_active_hostname$ is saved with any message that is received, so its value | |
11079 | can be consulted during routing and delivery. | |
11080 | ||
068aaea8 PH |
11081 | $smtp_command$:: |
11082 | + | |
11083 | [revisionflag="changed"] | |
11084 | cindex:[$smtp_command$] | |
11085 | During the processing of an incoming SMTP command, this variable contains the | |
11086 | entire command. This makes it possible to distinguish between HELO and EHLO in | |
11087 | the HELO ACL, and also to distinguish between commands such as these: | |
11088 | + | |
11089 | .... | |
11090 | MAIL FROM:<> | |
11091 | MAIL FROM: <> | |
11092 | .... | |
11093 | + | |
11094 | For a MAIL command, extra parameters such as SIZE can be inspected. For a RCPT | |
11095 | command, the address in $smtp_command$ is the original address before any | |
11096 | rewriting, whereas the values in $local_part$ and $domain$ are taken from the | |
11097 | address after SMTP-time rewriting. | |
11098 | ||
168e428f PH |
11099 | |
11100 | $smtp_command_argument$:: | |
068aaea8 PH |
11101 | + |
11102 | [revisionflag="changed"] | |
11103 | cindex:[SMTP command,argument for] | |
11104 | cindex:[$smtp_command_argument$] | |
11105 | While an ACL is running to check an SMTP command, this variable contains the | |
11106 | argument, that is, the text that follows the command name, with leading white | |
11107 | space removed. Following the introduction of $smtp_command$, this variable is | |
11108 | somewhat redundant, but is retained for backwards compatibility. | |
168e428f PH |
11109 | |
11110 | $sn0$ -- $sn9$:: | |
11111 | These variables are copies of the values of the $n0$ -- $n9$ accumulators that | |
11112 | were current at the end of the system filter file. This allows a system filter | |
11113 | file to set values that can be tested in users' filter files. For example, a | |
11114 | system filter could set a value indicating how likely it is that a message is | |
11115 | junk mail. | |
11116 | ||
11117 | $spam_$'xxx':: | |
11118 | A number of variables whose names start with $spam$ are available when Exim is | |
11119 | compiled with the content-scanning extension. For details, see section | |
11120 | <<SECTscanspamass>>. | |
11121 | ||
11122 | ||
11123 | $spool_directory$:: | |
068aaea8 | 11124 | cindex:[$spool_directory$] |
168e428f PH |
11125 | The name of Exim's spool directory. |
11126 | ||
11127 | $spool_inodes$:: | |
068aaea8 | 11128 | cindex:[$spool_inodes$] |
168e428f PH |
11129 | The number of free inodes in the disk partition where Exim's spool files are |
11130 | being written. The value is recalculated whenever the variable is referenced. | |
11131 | If the relevant file system does not have the concept of inodes, the value of | |
11132 | is -1. See also the %check_spool_inodes% option. | |
11133 | ||
11134 | $spool_space$:: | |
068aaea8 | 11135 | cindex:[$spool_space$] |
168e428f PH |
11136 | The amount of free space (as a number of kilobytes) in the disk partition where |
11137 | Exim's spool files are being written. The value is recalculated whenever the | |
11138 | variable is referenced. If the operating system does not have the ability to | |
11139 | find the amount of free space (only true for experimental systems), the space | |
11140 | value is -1. For example, to check in an ACL that there is at least 50 | |
11141 | megabytes free on the spool, you could write: | |
11142 | ||
11143 | condition = ${if > {$spool_space}{50000}} | |
11144 | + | |
11145 | See also the %check_spool_space% option. | |
11146 | ||
11147 | ||
11148 | $thisaddress$:: | |
068aaea8 | 11149 | cindex:[$thisaddress$] |
168e428f | 11150 | This variable is set only during the processing of the %foranyaddress% command |
068aaea8 PH |
11151 | in a filter file. Its use is explained in the description of that command, |
11152 | which can be found in the separate document entitled 'Exim's interfaces to mail | |
11153 | filtering'. | |
168e428f PH |
11154 | |
11155 | $tls_certificate_verified$:: | |
068aaea8 PH |
11156 | cindex:[$tls_certificate_verified$] |
11157 | This variable is set to ``1'' if a TLS certificate was verified when the | |
11158 | message was received, and ``0'' otherwise. | |
168e428f PH |
11159 | |
11160 | $tls_cipher$:: | |
068aaea8 | 11161 | cindex:[$tls_cipher$] |
168e428f PH |
11162 | When a message is received from a remote host over an encrypted SMTP |
11163 | connection, this variable is set to the cipher suite that was negotiated, for | |
11164 | example DES-CBC3-SHA. In other circumstances, in particular, for message | |
11165 | received over unencrypted connections, the variable is empty. See chapter | |
11166 | <<CHAPTLS>> for details of TLS support. | |
11167 | ||
11168 | $tls_peerdn$:: | |
068aaea8 PH |
11169 | cindex:[$tls_peerdn$] |
11170 | When a message is received from a remote host over an encrypted SMTP | |
168e428f PH |
11171 | connection, and Exim is configured to request a certificate from the client, |
11172 | the value of the Distinguished Name of the certificate is made available in the | |
11173 | $tls_peerdn$ during subsequent processing. | |
11174 | ||
11175 | $tod_bsdinbox$:: | |
068aaea8 | 11176 | cindex:[$tod_bsdinbox$] |
168e428f PH |
11177 | The time of day and date, in the format required for BSD-style mailbox files, |
11178 | for example: Thu Oct 17 17:14:09 1995. | |
11179 | ||
11180 | $tod_epoch$:: | |
068aaea8 | 11181 | cindex:[$tod_epoch$] |
168e428f PH |
11182 | The time and date as a number of seconds since the start of the Unix epoch. |
11183 | ||
11184 | $tod_full$:: | |
068aaea8 | 11185 | cindex:[$tod_full$] |
168e428f PH |
11186 | A full version of the time and date, for example: Wed, 16 Oct 1995 09:51:40 |
11187 | +0100. The timezone is always given as a numerical offset from UTC, with | |
11188 | positive values used for timezones that are ahead (east) of UTC, and negative | |
11189 | values for those that are behind (west). | |
11190 | ||
11191 | $tod_log$:: | |
068aaea8 | 11192 | cindex:[$tod_log$] |
168e428f PH |
11193 | The time and date in the format used for writing Exim's log files, for example: |
11194 | 1995-10-12 15:32:29, but without a timezone. | |
11195 | ||
11196 | $tod_logfile$:: | |
068aaea8 | 11197 | cindex:[$tod_logfile$] |
168e428f PH |
11198 | This variable contains the date in the format yyyymmdd. This is the format that |
11199 | is used for datestamping log files when %log_file_path% contains the `%D` | |
11200 | flag. | |
11201 | ||
11202 | $tod_zone$:: | |
068aaea8 | 11203 | cindex:[$tod_zone$] |
168e428f PH |
11204 | This variable contains the numerical value of the local timezone, for example: |
11205 | -0500. | |
11206 | ||
11207 | $tod_zulu$:: | |
068aaea8 | 11208 | cindex:[$tod_zulu$] |
168e428f PH |
11209 | This variable contains the UTC date and time in ``Zulu'' format, as specified by |
11210 | ISO 8601, for example: 20030221154023Z. | |
11211 | ||
11212 | $value$:: | |
11213 | cindex:[$value$] | |
11214 | This variable contains the result of an expansion lookup, extraction operation, | |
11215 | or external command, as described above. | |
11216 | ||
11217 | $version_number$:: | |
068aaea8 | 11218 | cindex:[$version_number$] |
168e428f PH |
11219 | The version number of Exim. |
11220 | ||
11221 | $warn_message_delay$:: | |
068aaea8 | 11222 | cindex:[$warn_message_delay$] |
168e428f PH |
11223 | This variable is set only during the creation of a message warning about a |
11224 | delivery delay. Details of its use are explained in section <<SECTcustwarn>>. | |
11225 | ||
11226 | $warn_message_recipients$:: | |
068aaea8 | 11227 | cindex:[$warn_message_recipients$] |
168e428f PH |
11228 | This variable is set only during the creation of a message warning about a |
11229 | delivery delay. Details of its use are explained in section <<SECTcustwarn>>. | |
11230 | ||
11231 | ||
11232 | ||
11233 | //////////////////////////////////////////////////////////////////////////// | |
11234 | //////////////////////////////////////////////////////////////////////////// | |
11235 | ||
11236 | [[CHAPperl]] | |
11237 | Embedded Perl | |
11238 | ------------- | |
11239 | cindex:[Perl,calling from Exim] | |
11240 | Exim can be built to include an embedded Perl interpreter. When this is done, | |
11241 | Perl subroutines can be called as part of the string expansion process. To make | |
11242 | use of the Perl support, you need version 5.004 or later of Perl installed on | |
11243 | your system. To include the embedded interpreter in the Exim binary, include | |
11244 | the line | |
11245 | ||
11246 | EXIM_PERL = perl.o | |
11247 | ||
11248 | in your _Local/Makefile_ and then build Exim in the normal way. | |
11249 | ||
11250 | ||
11251 | Setting up so Perl can be used | |
11252 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
11253 | cindex:[%perl_startup%] | |
11254 | Access to Perl subroutines is via a global configuration option called | |
11255 | %perl_startup% and an expansion string operator %\$\{perl ...\}%. If there is | |
11256 | no %perl_startup% option in the Exim configuration file then no Perl | |
11257 | interpreter is started and there is almost no overhead for Exim (since none of | |
11258 | the Perl library will be paged in unless used). If there is a %perl_startup% | |
11259 | option then the associated value is taken to be Perl code which is executed in | |
11260 | a newly created Perl interpreter. | |
11261 | ||
11262 | The value of %perl_startup% is not expanded in the Exim sense, so you do not | |
11263 | need backslashes before any characters to escape special meanings. The option | |
11264 | should usually be something like | |
11265 | ||
11266 | perl_startup = do '/etc/exim.pl' | |
11267 | ||
11268 | where _/etc/exim.pl_ is Perl code which defines any subroutines you want to | |
11269 | use from Exim. Exim can be configured either to start up a Perl interpreter as | |
11270 | soon as it is entered, or to wait until the first time it is needed. Starting | |
11271 | the interpreter at the beginning ensures that it is done while Exim still has | |
11272 | its setuid privilege, but can impose an unnecessary overhead if Perl is not in | |
11273 | fact used in a particular run. Also, note that this does not mean that Exim is | |
11274 | necessarily running as root when Perl is called at a later time. By default, | |
11275 | the interpreter is started only when it is needed, but this can be changed in | |
11276 | two ways: | |
11277 | ||
11278 | - cindex:[%perl_at_start%] | |
11279 | Setting %perl_at_start% (a boolean option) in the configuration requests | |
11280 | a startup when Exim is entered. | |
11281 | ||
11282 | - The command line option %-ps% also requests a startup when Exim is entered, | |
11283 | overriding the setting of %perl_at_start%. | |
11284 | ||
11285 | There is also a command line option %-pd% (for delay) which suppresses the | |
11286 | initial startup, even if %perl_at_start% is set. | |
11287 | ||
11288 | ||
11289 | Calling Perl subroutines | |
11290 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
11291 | When the configuration file includes a %perl_startup% option you can make use | |
11292 | of the string expansion item to call the Perl subroutines that are defined | |
11293 | by the %perl_startup% code. The operator is used in any of the following | |
11294 | forms: | |
11295 | ||
11296 | ${perl{foo}} | |
11297 | ${perl{foo}{argument}} | |
11298 | ${perl{foo}{argument1}{argument2} ... } | |
11299 | ||
11300 | which calls the subroutine %foo% with the given arguments. A maximum of eight | |
11301 | arguments may be passed. Passing more than this results in an expansion failure | |
11302 | with an error message of the form | |
11303 | ||
11304 | Too many arguments passed to Perl subroutine "foo" (max is 8) | |
11305 | ||
11306 | The return value of the Perl subroutine is evaluated in a scalar context before | |
11307 | it is passed back to Exim to be inserted into the expanded string. If the | |
11308 | return value is 'undef', the expansion is forced to fail in the same way as | |
11309 | an explicit ``fail'' on an %\$\{if ...\}% or %\$\{lookup...\}% item. If the | |
11310 | subroutine aborts by obeying Perl's %die% function, the expansion fails with | |
11311 | the error message that was passed to %die%. | |
11312 | ||
11313 | ||
11314 | Calling Exim functions from Perl | |
11315 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
11316 | Within any Perl code called from Exim, the function 'Exim::expand_string' | |
11317 | is available to call back into Exim's string expansion function. For example, | |
11318 | the Perl code | |
11319 | ||
11320 | my $lp = Exim::expand_string('$local_part'); | |
11321 | ||
11322 | makes the current Exim $local_part$ available in the Perl variable $lp$. | |
11323 | Note those are single quotes and not double quotes to protect against | |
11324 | $local_part$ being interpolated as a Perl variable. | |
11325 | ||
11326 | If the string expansion is forced to fail by a ``fail'' item, the result of | |
11327 | 'Exim::expand_string' is %undef%. If there is a syntax error in the | |
11328 | expansion string, the Perl call from the original expansion string fails with | |
11329 | an appropriate error message, in the same way as if %die% were used. | |
11330 | ||
11331 | cindex:[debugging,from embedded Perl] | |
11332 | cindex:[log,writing from embedded Perl] | |
11333 | Two other Exim functions are available for use from within Perl code. | |
11334 | 'Exim::debug_write(<'string'>)' writes the string to the standard error | |
11335 | stream if Exim's debugging is enabled. If you want a newline at the end, you | |
11336 | must supply it. 'Exim::log_write(<'string'>)' writes the string to Exim's | |
11337 | main log, adding a leading timestamp. In this case, you should not supply a | |
11338 | terminating newline. | |
11339 | ||
11340 | ||
11341 | Use of standard output and error by Perl | |
11342 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
11343 | cindex:[Perl,standard output and error] | |
11344 | You should not write to the standard error or output streams from within your | |
11345 | Perl code, as it is not defined how these are set up. In versions of Exim | |
11346 | before 4.50, it is possible for the standard output or error to refer to the | |
11347 | SMTP connection during message reception via the daemon. Writing to this stream | |
11348 | is certain to cause chaos. From Exim 4.50 onwards, the standard output and | |
11349 | error streams are connected to _/dev/null_ in the daemon. The chaos is | |
11350 | avoided, but the output is lost. | |
11351 | ||
11352 | cindex:[Perl,use of %warn%] | |
11353 | The Perl %warn% statement writes to the standard error stream by default. Calls | |
11354 | to %warn% may be embedded in Perl modules that you use, but over which you have | |
11355 | no control. When Exim starts up the Perl interpreter, it arranges for output | |
11356 | from the %warn% statement to be written to the Exim main log. You can change | |
11357 | this by including appropriate Perl magic somewhere in your Perl code. For | |
11358 | example, to discard %warn% output completely, you need this: | |
11359 | ||
11360 | $SIG{__WARN__} = sub { }; | |
11361 | ||
11362 | Whenever a %warn% is obeyed, the anonymous subroutine is called. In this | |
11363 | example, the code for the subroutine is empty, so it does nothing, but you can | |
11364 | include any Perl code that you like. The text of the %warn% message is passed | |
11365 | as the first subroutine argument. | |
11366 | ||
11367 | ||
11368 | ||
11369 | //////////////////////////////////////////////////////////////////////////// | |
11370 | //////////////////////////////////////////////////////////////////////////// | |
11371 | ||
11372 | [[CHAPinterfaces]] | |
11373 | [titleabbrev="Starting the daemon"] | |
11374 | Starting the daemon and the use of network interfaces | |
11375 | ----------------------------------------------------- | |
11376 | cindex:[daemon,starting] | |
11377 | cindex:[interface,listening] | |
11378 | cindex:[network interface] | |
11379 | cindex:[interface,network] | |
11380 | cindex:[IP address,for listening] | |
11381 | cindex:[daemon,listening IP addresses] | |
11382 | cindex:[TCP/IP,setting listening interfaces] | |
11383 | cindex:[TCP/IP,setting listening ports] | |
11384 | A host that is connected to a TCP/IP network may have one or more physical | |
11385 | hardware network interfaces. Each of these interfaces may be configured as one | |
11386 | or more ``logical'' interfaces, which are the entities that a program actually | |
11387 | works with. Each of these logical interfaces is associated with an IP address. | |
11388 | In addition, TCP/IP software supports ``loopback'' interfaces (127.0.0.1 in IPv4 | |
11389 | and ::1 in IPv6), which do not use any physical hardware. Exim requires | |
11390 | knowledge about the host's interfaces for use in three different circumstances: | |
11391 | ||
11392 | . When a listening daemon is started, Exim needs to know which interfaces | |
11393 | and ports to listen on. | |
11394 | ||
11395 | . When Exim is routing an address, it needs to know which IP addresses | |
11396 | are associated with local interfaces. This is required for the correct | |
11397 | processing of MX lists by removing the local host and others with the | |
11398 | same or higher priority values. Also, Exim needs to detect cases | |
11399 | when an address is routed to an IP address that in fact belongs to the | |
11400 | local host. Unless the %self% router option or the %allow_localhost% | |
11401 | option of the smtp transport is set (as appropriate), this is treated | |
11402 | as an error situation. | |
11403 | ||
11404 | . When Exim connects to a remote host, it may need to know which interface to use | |
11405 | for the outgoing connection. | |
11406 | ||
11407 | ||
11408 | Exim's default behaviour is likely to be appropriate in the vast majority | |
11409 | of cases. If your host has only one interface, and you want all its IP | |
11410 | addresses to be treated in the same way, and you are using only the | |
11411 | standard SMTP port, you should not need to take any special action. The | |
11412 | rest of this chapter does not apply to you. | |
11413 | ||
11414 | In a more complicated situation you may want to listen only on certain | |
11415 | interfaces, or on different ports, and for this reason there are a number of | |
11416 | options that can be used to influence Exim's behaviour. The rest of this | |
11417 | chapter describes how they operate. | |
11418 | ||
11419 | When a message is received over TCP/IP, the interface and port that were | |
11420 | actually used are set in $interface_address$ and $interface_port$. | |
11421 | ||
11422 | ||
11423 | ||
11424 | Starting a listening daemon | |
11425 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
11426 | When a listening daemon is started (by means of the %-bd% command line | |
11427 | option), the interfaces and ports on which it listens are controlled by the | |
11428 | following options: | |
11429 | ||
11430 | - %daemon_smtp_ports% contains a list of default ports. (For backward | |
11431 | compatibility, this option can also be specified in the singular.) | |
11432 | ||
11433 | - %local_interfaces% contains list of interface IP addresses on which to | |
11434 | listen. Each item may optionally also specify a port. | |
11435 | ||
11436 | The default list separator in both cases is a colon, but this can be changed as | |
11437 | described in section <<SECTlistconstruct>>. When IPv6 addresses are involved, it | |
11438 | is usually best to change the separator to avoid having to double all the | |
11439 | colons. For example: | |
11440 | ||
11441 | .... | |
11442 | local_interfaces = <; 127.0.0.1 ; \ | |
11443 | 192.168.23.65 ; \ | |
11444 | ::1 ; \ | |
11445 | 3ffe:ffff:836f::fe86:a061 | |
11446 | .... | |
11447 | ||
11448 | There are two different formats for specifying a port along with an IP address | |
11449 | in %local_interfaces%: | |
11450 | ||
11451 | . The port is added onto the address with a dot separator. For example, to listen | |
11452 | on port 1234 on two different IP addresses: | |
11453 | + | |
11454 | .... | |
11455 | local_interfaces = <; 192.168.23.65.1234 ; \ | |
11456 | 3ffe:ffff:836f::fe86:a061.1234 | |
11457 | .... | |
11458 | ||
11459 | . The IP address is enclosed in square brackets, and the port is added | |
11460 | with a colon separator, for example: | |
11461 | + | |
11462 | .... | |
11463 | local_interfaces = <; [192.168.23.65]:1234 ; \ | |
11464 | [3ffe:ffff:836f::fe86:a061]:1234 | |
11465 | .... | |
11466 | ||
11467 | When a port is not specified, the value of %daemon_smtp_ports% is used. The | |
11468 | default setting contains just one port: | |
11469 | ||
11470 | daemon_smtp_ports = smtp | |
11471 | ||
11472 | If more than one port is listed, each interface that does not have its own port | |
11473 | specified listens on all of them. Ports that are listed in | |
11474 | %daemon_smtp_ports% can be identified either by name (defined in | |
11475 | _/etc/services_) or by number. However, when ports are given with individual | |
11476 | IP addresses in %local_interfaces%, only numbers (not names) can be used. | |
11477 | ||
11478 | ||
11479 | ||
11480 | Special IP listening addresses | |
11481 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
11482 | The addresses 0.0.0.0 and ::0 are treated specially. They are interpreted | |
11483 | as ``all IPv4 interfaces'' and ``all IPv6 interfaces'', respectively. In each | |
11484 | case, Exim tells the TCP/IP stack to ``listen on all IPv##'x' interfaces'' | |
11485 | instead of setting up separate listening sockets for each interface. The | |
11486 | default value of %local_interfaces% is | |
11487 | ||
11488 | local_interfaces = 0.0.0.0 | |
11489 | ||
11490 | when Exim is built without IPv6 support; otherwise it is: | |
11491 | ||
11492 | local_interfaces = <; ::0 ; 0.0.0.0 | |
11493 | ||
11494 | Thus, by default, Exim listens on all available interfaces, on the SMTP port. | |
11495 | ||
11496 | ||
11497 | ||
11498 | Overriding local_interfaces and daemon_smtp_ports | |
11499 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
11500 | The %-oX% command line option can be used to override the values of | |
11501 | %daemon_smtp_ports% and/or %local_interfaces% for a particular daemon | |
11502 | instance. Another way of doing this would be to use macros and the %-D% | |
11503 | option. However, %-oX% can be used by any admin user, whereas modification of | |
11504 | the runtime configuration by %-D% is allowed only when the caller is root or | |
11505 | exim. | |
11506 | ||
11507 | The value of %-oX% is a list of items. The default colon separator can be | |
11508 | changed in the usual way if required. If there are any items that do not | |
11509 | contain dots or colons (that is, are not IP addresses), the value of | |
11510 | %daemon_smtp_ports% is replaced by the list of those items. If there are any | |
11511 | items that do contain dots or colons, the value of %local_interfaces% is | |
11512 | replaced by those items. Thus, for example, | |
11513 | ||
11514 | -oX 1225 | |
11515 | ||
11516 | overrides %daemon_smtp_ports%, but leaves %local_interfaces% unchanged, | |
11517 | whereas | |
11518 | ||
11519 | -oX 192.168.34.5.1125 | |
11520 | ||
11521 | overrides %local_interfaces%, leaving %daemon_smtp_ports% unchanged. | |
11522 | (However, since %local_interfaces% now contains no items without ports, the | |
11523 | value of %daemon_smtp_ports% is no longer relevant in this example.) | |
11524 | ||
11525 | ||
11526 | ||
11527 | [[SECTsupobssmt]] | |
11528 | Support for the obsolete SSMTP (or SMTPS) protocol | |
11529 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
11530 | cindex:[ssmtp protocol] | |
11531 | cindex:[smtps protocol] | |
11532 | cindex:[SMTP,ssmtp protocol] | |
11533 | cindex:[SMTP,smtps protocol] | |
11534 | Exim supports the obsolete SSMTP protocol (also known as SMTPS) that was used | |
11535 | before the STARTTLS command was standardized for SMTP. Some legacy clients | |
11536 | still use this protocol. If the %tls_on_connect_ports% option is set to a | |
11537 | list of port numbers, connections to those ports must use SSMTP. The most | |
11538 | common use of this option is expected to be | |
11539 | ||
11540 | tls_on_connect_ports = 465 | |
11541 | ||
11542 | because 465 is the usual port number used by the legacy clients. There is also | |
11543 | a command line option %-tls-on-connect%, which forces all ports to behave in | |
11544 | this way when a daemon is started. | |
11545 | ||
11546 | *Warning*: Setting %tls_on_connect_ports% does not of itself cause the | |
11547 | daemon to listen on those ports. You must still specify them in | |
11548 | %daemon_smtp_ports%, %local_interfaces%, or the %-oX% option. (This is | |
11549 | because %tls_on_connect_ports% applies to %inetd% connections as well as to | |
11550 | connections via the daemon.) | |
11551 | ||
11552 | ||
11553 | ||
11554 | ||
11555 | IPv6 address scopes | |
11556 | ~~~~~~~~~~~~~~~~~~~ | |
11557 | IPv6 addresses have ``scopes'', and a host with multiple hardware interfaces | |
11558 | can, in principle, have the same link-local IPv6 address on different | |
11559 | interfaces. Thus, additional information is needed, over and above the IP | |
11560 | address, to distinguish individual interfaces. A convention of using a | |
11561 | percent sign followed by something (often the interface name) has been | |
11562 | adopted in some cases, leading to addresses like this: | |
11563 | ||
11564 | fe80::202:b3ff:fe03:45c1%eth0 | |
11565 | ||
11566 | To accommodate this usage, a percent sign followed by an arbitrary string is | |
11567 | allowed at the end of an IPv6 address. By default, Exim calls 'getaddrinfo()' | |
11568 | to convert a textual IPv6 address for actual use. This function recognizes the | |
11569 | percent convention in operating systems that support it, and it processes the | |
11570 | address appropriately. Unfortunately, some older libraries have problems with | |
11571 | 'getaddrinfo()'. If | |
11572 | ||
11573 | IPV6_USE_INET_PTON=yes | |
11574 | ||
11575 | is set in _Local/Makefile_ (or an OS-dependent Makefile) when Exim is built, | |
11576 | Exim uses 'inet_pton()' to convert a textual IPv6 address for actual use, | |
11577 | instead of 'getaddrinfo()'. (Before version 4.14, it always used this | |
11578 | function.) Of course, this means that the additional functionality of | |
11579 | 'getaddrinfo()' -- recognizing scoped addresses -- is lost. | |
11580 | ||
11581 | ||
11582 | ||
11583 | Examples of starting a listening daemon | |
11584 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
11585 | The default case in an IPv6 environment is | |
11586 | ||
11587 | daemon_smtp_ports = smtp | |
11588 | local_interfaces = <; ::0 ; 0.0.0.0 | |
11589 | ||
11590 | This specifies listening on the smtp port on all IPv6 and IPv4 interfaces. | |
11591 | Either one or two sockets may be used, depending on the characteristics of | |
11592 | the TCP/IP stack. (This is complicated and messy; for more information, | |
11593 | read the comments in the _daemon.c_ source file.) | |
11594 | ||
11595 | To specify listening on ports 25 and 26 on all interfaces: | |
11596 | ||
11597 | daemon_smtp_ports = 25 : 26 | |
11598 | ||
11599 | (leaving %local_interfaces% at the default setting) or, more explicitly: | |
11600 | ||
11601 | .... | |
11602 | local_interfaces = <; ::0.25 ; ::0.26 \ | |
11603 | 0.0.0.0.25 ; 0.0.0.0.26 | |
11604 | .... | |
11605 | ||
11606 | To listen on the default port on all IPv4 interfaces, and on port 26 on the | |
11607 | IPv4 loopback address only: | |
11608 | ||
11609 | local_interfaces = 0.0.0.0 : 127.0.0.1.26 | |
11610 | ||
11611 | To specify listening on the default port on specific interfaces only: | |
11612 | ||
11613 | local_interfaces = 192.168.34.67 : 192.168.34.67 | |
11614 | ||
11615 | *Warning*: such a setting excludes listening on the loopback interfaces. | |
11616 | ||
11617 | ||
11618 | ||
11619 | [[SECTreclocipadd]] | |
11620 | Recognising the local host | |
11621 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
11622 | The %local_interfaces% option is also used when Exim needs to determine | |
11623 | whether or not an IP address refers to the local host. That is, the IP | |
11624 | addresses of all the interfaces on which a daemon is listening are always | |
11625 | treated as local. | |
11626 | ||
11627 | For this usage, port numbers in %local_interfaces% are ignored. If either of | |
11628 | the items 0.0.0.0 or ::0 are encountered, Exim gets a complete list of | |
11629 | available interfaces from the operating system, and extracts the relevant | |
11630 | (that is, IPv4 or IPv6) addresses to use for checking. | |
11631 | ||
11632 | Some systems set up large numbers of virtual interfaces in order to provide | |
11633 | many virtual web servers. In this situation, you may want to listen for | |
11634 | email on only a few of the available interfaces, but nevertheless treat all | |
11635 | interfaces as local when routing. You can do this by setting | |
11636 | %extra_local_interfaces% to a list of IP addresses, possibly including the | |
11637 | ``all'' wildcard values. These addresses are recognized as local, but are not | |
11638 | used for listening. Consider this example: | |
11639 | ||
11640 | .... | |
11641 | local_interfaces = <; 127.0.0.1 ; ::1 ; \ | |
11642 | 192.168.53.235 ; \ | |
11643 | 3ffe:2101:12:1:a00:20ff:fe86:a061 | |
11644 | ||
11645 | extra_local_interfaces = <; ::0 ; 0.0.0.0 | |
11646 | .... | |
11647 | ||
11648 | The daemon listens on the loopback interfaces and just one IPv4 and one IPv6 | |
11649 | address, but all available interface addresses are treated as local when | |
11650 | Exim is routing. | |
11651 | ||
11652 | In some environments the local host name may be in an MX list, but with an IP | |
11653 | address that is not assigned to any local interface. In other cases it may be | |
11654 | desirable to treat other host names as if they referred to the local host. Both | |
11655 | these cases can be handled by setting the %hosts_treat_as_local% option. | |
11656 | This contains host names rather than IP addresses. When a host is referenced | |
11657 | during routing, either via an MX record or directly, it is treated as the local | |
11658 | host if its name matches %hosts_treat_as_local%, or if any of its IP | |
11659 | addresses match %local_interfaces% or %extra_local_interfaces%. | |
11660 | ||
11661 | ||
11662 | ||
11663 | Delivering to a remote host | |
11664 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
11665 | Delivery to a remote host is handled by the smtp transport. By default, it | |
11666 | allows the system's TCP/IP functions to choose which interface to use (if | |
11667 | there is more than one) when connecting to a remote host. However, the | |
11668 | %interface% option can be set to specify which interface is used. See the | |
11669 | description of the smtp transport in chapter <<CHAPsmtptrans>> for more details. | |
11670 | ||
11671 | ||
11672 | ||
11673 | ||
11674 | //////////////////////////////////////////////////////////////////////////// | |
11675 | //////////////////////////////////////////////////////////////////////////// | |
11676 | ||
11677 | [[CHAPmainconfig]] | |
11678 | Main configuration | |
11679 | ------------------ | |
11680 | cindex:[configuration file,main section] | |
11681 | cindex:[main configuration] | |
11682 | The first part of the run time configuration file contains three types of item: | |
11683 | ||
11684 | - Macro definitions: These lines start with an upper case letter. See section | |
11685 | <<SECTmacrodefs>> for details of macro processing. | |
11686 | ||
11687 | - Named list definitions: These lines start with one of the words ``domainlist'', | |
11688 | ``hostlist'', ``addresslist'', or ``localpartlist''. Their use is described in | |
11689 | section <<SECTnamedlists>>. | |
11690 | ||
11691 | - Main configuration settings: Each setting occupies one line of the file | |
11692 | (with possible continuations). If any setting is preceded by the word | |
11693 | ``hide'', the %-bP% command line option displays its value to admin users only. | |
11694 | See section <<SECTcos>> for a description of the syntax of these option settings. | |
11695 | ||
11696 | This chapter specifies all the main configuration options, along with their | |
11697 | types and default values. For ease of finding a particular option, they appear | |
11698 | in alphabetical order in section <<SECTalomo>> below. However, because there are | |
11699 | now so many options, they are first listed briefly in functional groups, as an | |
11700 | aid to finding the name of the option you are looking for. Some options are | |
11701 | listed in more than one group. | |
11702 | ||
11703 | Miscellaneous | |
11704 | ~~~~~~~~~~~~~ | |
11705 | [frame="none"] | |
11706 | `-----------------------------------`------------------------------------- | |
11707 | %bi_command% to run for %-bi% command line option | |
11708 | %keep_malformed% for broken files -- should not happen | |
11709 | %localhost_number% for unique message ids in clusters | |
11710 | %message_body_visible% how much to show in $message_body$ | |
11711 | %mua_wrapper% run in ``MUA wrapper'' mode | |
11712 | %print_topbitchars% top-bit characters are printing | |
11713 | %timezone% force time zone | |
11714 | -------------------------------------------------------------------------- | |
11715 | ||
11716 | ||
11717 | Exim parameters | |
11718 | ~~~~~~~~~~~~~~~ | |
11719 | [frame="none"] | |
11720 | `-----------------------------------`------------------------------------- | |
11721 | %exim_group% override compiled-in value | |
11722 | %exim_path% override compiled-in value | |
11723 | %exim_user% override compiled-in value | |
11724 | %primary_hostname% default from 'uname()' | |
11725 | %split_spool_directory% use multiple directories | |
11726 | %spool_directory% override compiled-in value | |
11727 | -------------------------------------------------------------------------- | |
11728 | ||
11729 | ||
11730 | ||
11731 | Privilege controls | |
11732 | ~~~~~~~~~~~~~~~~~~ | |
11733 | [frame="none"] | |
11734 | `-----------------------------------`------------------------------------- | |
11735 | %admin_groups% groups that are Exim admin users | |
11736 | %deliver_drop_privilege% drop root for delivery processes | |
11737 | %local_from_check% insert 'Sender:' if necessary | |
11738 | %local_from_prefix% for testing 'From:' for local sender | |
11739 | %local_from_suffix% for testing 'From:' for local sender | |
11740 | %local_sender_retain% keep 'Sender:' from untrusted user | |
11741 | %never_users% do not run deliveries as these | |
11742 | %prod_requires_admin% forced delivery requires admin user | |
11743 | %queue_list_requires_admin% queue listing requires admin user | |
11744 | %trusted_groups% groups that are trusted | |
11745 | %trusted_users% users that are trusted | |
11746 | -------------------------------------------------------------------------- | |
11747 | ||
11748 | ||
11749 | ||
11750 | Logging | |
11751 | ~~~~~~~ | |
11752 | [frame="none"] | |
11753 | `-----------------------------------`------------------------------------- | |
11754 | %hosts_connection_nolog% exemption from connect logging | |
11755 | %log_file_path% override compiled-in value | |
11756 | %log_selector% set/unset optional logging | |
11757 | %log_timezone% add timezone to log lines | |
11758 | %message_logs% create per-message logs | |
11759 | %preserve_message_logs% after message completion | |
11760 | %process_log_path% for SIGUSR1 and 'exiwhat' | |
11761 | %syslog_duplication% controls duplicate log lines on syslog | |
11762 | %syslog_facility% set syslog ``facility'' field | |
11763 | %syslog_processname% set syslog ``ident'' field | |
11764 | %syslog_timestamp% timestamp syslog lines | |
11765 | %write_rejectlog% control use of message log | |
11766 | -------------------------------------------------------------------------- | |
11767 | ||
11768 | ||
11769 | ||
11770 | Frozen messages | |
11771 | ~~~~~~~~~~~~~~~ | |
11772 | [frame="none"] | |
11773 | `-----------------------------------`------------------------------------- | |
11774 | %auto_thaw% sets time for retrying frozen messages | |
11775 | %freeze_tell% send message when freezing | |
11776 | %move_frozen_messages% to another directory | |
11777 | %timeout_frozen_after% keep frozen messages only so long | |
11778 | -------------------------------------------------------------------------- | |
11779 | ||
11780 | ||
11781 | ||
11782 | Data lookups | |
11783 | ~~~~~~~~~~~~ | |
11784 | [frame="none"] | |
11785 | `-----------------------------------`------------------------------------- | |
11786 | %ldap_default_servers% used if no server in query | |
11787 | %ldap_version% set protocol version | |
11788 | %lookup_open_max% lookup files held open | |
11789 | %mysql_servers% as it says | |
11790 | %oracle_servers% as it says | |
11791 | %pgsql_servers% as it says | |
068aaea8 | 11792 | %sqlite_lock_timeout% as it says |
168e428f PH |
11793 | -------------------------------------------------------------------------- |
11794 | ||
11795 | ||
11796 | ||
11797 | Message ids | |
11798 | ~~~~~~~~~~~ | |
11799 | [frame="none"] | |
11800 | `-----------------------------------`------------------------------------- | |
11801 | %message_id_header_domain% used to build 'Message-ID:' header | |
11802 | %message_id_header_text% ditto | |
11803 | -------------------------------------------------------------------------- | |
11804 | ||
11805 | ||
11806 | ||
11807 | Embedded Perl Startup | |
11808 | ~~~~~~~~~~~~~~~~~~~~~ | |
11809 | [frame="none"] | |
11810 | `-----------------------------------`------------------------------------- | |
11811 | %perl_at_start% always start the interpreter | |
11812 | %perl_startup% code to obey when starting Perl | |
11813 | -------------------------------------------------------------------------- | |
11814 | ||
11815 | ||
11816 | ||
11817 | Daemon | |
11818 | ~~~~~~ | |
11819 | [frame="none"] | |
11820 | `-----------------------------------`------------------------------------- | |
11821 | %daemon_smtp_ports% default ports | |
068aaea8 PH |
11822 | %daemon_startup_retries% number of times to retry |
11823 | %daemon_startup_sleep% time to sleep between tries | |
168e428f PH |
11824 | %extra_local_interfaces% not necessarily listened on |
11825 | %local_interfaces% on which to listen, with optional ports | |
11826 | %pid_file_path% override compiled-in value | |
11827 | %queue_run_max% maximum simultaneous queue runners | |
11828 | -------------------------------------------------------------------------- | |
11829 | ||
11830 | ||
11831 | ||
11832 | Resource control | |
11833 | ~~~~~~~~~~~~~~~~ | |
11834 | [frame="none"] | |
11835 | `-----------------------------------`------------------------------------- | |
11836 | %check_log_inodes% before accepting a message | |
11837 | %check_log_space% before accepting a message | |
11838 | %check_spool_inodes% before accepting a message | |
11839 | %check_spool_space% before accepting a message | |
11840 | %deliver_queue_load_max% no queue deliveries if load high | |
11841 | %queue_only_load% queue incoming if load high | |
11842 | %queue_run_max% maximum simultaneous queue runners | |
11843 | %remote_max_parallel% parallel SMTP delivery per message | |
11844 | %smtp_accept_max% simultaneous incoming connections | |
11845 | %smtp_accept_max_nommail% non-mail commands | |
11846 | %smtp_accept_max_nonmail_hosts% hosts to which the limit applies | |
11847 | %smtp_accept_max_per_connection% messages per connection | |
11848 | %smtp_accept_max_per_host% connections from one host | |
11849 | %smtp_accept_queue% queue mail if more connections | |
11850 | %smtp_accept_queue_per_connection% queue if more messages per connection | |
11851 | %smtp_accept_reserve% only reserve hosts if more connections | |
11852 | %smtp_check_spool_space% from SIZE on MAIL command | |
11853 | %smtp_connect_backlog% passed to TCP/IP stack | |
11854 | %smtp_load_reserve% SMTP from reserved hosts if load high | |
11855 | %smtp_reserve_hosts% these are the reserve hosts | |
11856 | -------------------------------------------------------------------------- | |
11857 | ||
11858 | ||
11859 | ||
11860 | Policy controls | |
11861 | ~~~~~~~~~~~~~~~ | |
11862 | [frame="none"] | |
11863 | `-----------------------------------`------------------------------------- | |
068aaea8 PH |
11864 | %acl_not_smtp% ACL for non-SMTP messages |
11865 | %acl_not_smtp_mime% ACL for non-SMTP MIME parts | |
11866 | %acl_smtp_auth% ACL for AUTH | |
11867 | %acl_smtp_connect% ACL for connection | |
11868 | %acl_smtp_data% ACL for DATA | |
11869 | %acl_smtp_etrn% ACL for ETRN | |
11870 | %acl_smtp_expn% ACL for EXPN | |
11871 | %acl_smtp_helo% ACL for EHLO or HELO | |
11872 | %acl_smtp_mail% ACL for MAIL | |
11873 | %acl_smtp_mailauth% ACL for AUTH on MAIL command | |
11874 | %acl_smtp_mime% ACL for MIME parts | |
11875 | %acl_smtp_predata% ACL for start of data | |
11876 | %acl_smtp_quit% ACL for QUIT | |
11877 | %acl_smtp_rcpt% ACL for RCPT | |
11878 | %acl_smtp_starttls% ACL for STARTTLS | |
11879 | %acl_smtp_vrfy% ACL for VRFY | |
168e428f | 11880 | %av_scanner% specify virus scanner |
d1e83bff | 11881 | %check_rfc2047_length% check length of RFC 2047 ``encoded words'' |
068aaea8 PH |
11882 | %dns_csa_search_limit% control CSA parent search depth |
11883 | %dns_csa_use_reverse% en/disable CSA IP reverse search | |
168e428f PH |
11884 | %header_maxsize% total size of message header |
11885 | %header_line_maxsize% individual header line limit | |
11886 | %helo_accept_junk_hosts% allow syntactic junk from these hosts | |
11887 | %helo_allow_chars% allow illegal chars in HELO names | |
11888 | %helo_lookup_domains% lookup hostname for these HELO names | |
11889 | %helo_try_verify_hosts% HELO soft-checked for these hosts | |
11890 | %helo_verify_hosts% HELO hard-checked for these hosts | |
11891 | %host_lookup% host name looked up for these hosts | |
11892 | %host_lookup_order% order of DNS and local name lookups | |
11893 | %host_reject_connection% reject connection from these hosts | |
11894 | %hosts_treat_as_local% useful in some cluster configurations | |
11895 | %local_scan_timeout% timeout for 'local_scan()' | |
11896 | %message_size_limit% for all messages | |
11897 | %percent_hack_domains% recognize %-hack for these domains | |
11898 | %spamd_address% set interface to SpamAssassin | |
11899 | -------------------------------------------------------------------------- | |
11900 | ||
11901 | ||
11902 | ||
11903 | Callout cache | |
11904 | ~~~~~~~~~~~~~ | |
11905 | [frame="none"] | |
11906 | `-----------------------------------`------------------------------------- | |
11907 | %callout_domain_negative_expire% timeout for negative domain cache item | |
11908 | %callout_domain_positive_expire% timeout for positive domain cache item | |
11909 | %callout_negative_expire% timeout for negative address cache item | |
11910 | %callout_positive_expire% timeout for positive address cache item | |
11911 | %callout_random_local_part% string to use for ``random'' testing | |
11912 | -------------------------------------------------------------------------- | |
11913 | ||
11914 | ||
11915 | ||
11916 | TLS | |
11917 | ~~~ | |
11918 | [frame="none"] | |
11919 | `-----------------------------------`------------------------------------- | |
11920 | %tls_advertise_hosts% advertise TLS to these hosts | |
11921 | %tls_certificate% location of server certificate | |
11922 | %tls_crl% certificate revocation list | |
11923 | %tls_dhparam% DH parameters for server | |
11924 | %tls_on_connect_ports% specify SSMTP (SMTPS) ports | |
11925 | %tls_privatekey% location of server private key | |
11926 | %tls_remember_esmtp% don't reset after starting TLS | |
11927 | %tls_require_ciphers% specify acceptable cipers | |
11928 | %tls_try_verify_hosts% try to verify client certificate | |
11929 | %tls_verify_certificates% expected client certificates | |
11930 | %tls_verify_hosts% insist on client certificate verify | |
11931 | -------------------------------------------------------------------------- | |
11932 | ||
11933 | ||
11934 | ||
11935 | Local user handling | |
11936 | ~~~~~~~~~~~~~~~~~~~ | |
11937 | [frame="none"] | |
11938 | `-----------------------------------`------------------------------------- | |
11939 | %finduser_retries% useful in NIS environments | |
11940 | %gecos_name% used when creating 'Sender:' | |
11941 | %gecos_pattern% ditto | |
11942 | %max_username_length% for systems that truncate | |
11943 | %unknown_login% used when no login name found | |
11944 | %unknown_username% ditto | |
11945 | %uucp_from_pattern% for recognizing ``From '' lines | |
11946 | %uucp_from_sender% ditto | |
11947 | -------------------------------------------------------------------------- | |
11948 | ||
11949 | ||
11950 | ||
11951 | All incoming messages (SMTP and non-SMTP) | |
11952 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
11953 | [frame="none"] | |
11954 | `-----------------------------------`------------------------------------- | |
11955 | %header_maxsize% total size of message header | |
11956 | %header_line_maxsize% individual header line limit | |
11957 | %message_size_limit% applies to all messages | |
11958 | %percent_hack_domains% recognize %-hack for these domains | |
11959 | %received_header_text% expanded to make 'Received:' | |
11960 | %received_headers_max% for mail loop detection | |
11961 | %recipients_max% limit per message | |
11962 | %recipients_max_reject% permanently reject excess | |
11963 | -------------------------------------------------------------------------- | |
11964 | ||
11965 | ||
11966 | ||
11967 | ||
11968 | Non-SMTP incoming messages | |
11969 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
11970 | [frame="none"] | |
11971 | `-----------------------------------`------------------------------------- | |
11972 | %receive_timeout% for non-SMTP messages | |
11973 | -------------------------------------------------------------------------- | |
11974 | ||
11975 | ||
11976 | ||
11977 | ||
11978 | ||
11979 | Incoming SMTP messages | |
11980 | ~~~~~~~~~~~~~~~~~~~~~~ | |
11981 | See also the 'Policy controls' section above. | |
11982 | ||
11983 | [frame="none"] | |
11984 | `-----------------------------------`------------------------------------- | |
11985 | %host_lookup% host name looked up for these hosts | |
11986 | %host_lookup_order% order of DNS and local name lookups | |
11987 | %recipient_unqualified_hosts% may send unqualified recipients | |
11988 | %rfc1413_hosts% make ident calls to these hosts | |
11989 | %rfc1413_query_timeout% zero disables ident calls | |
11990 | %sender_unqualified_hosts% may send unqualified senders | |
11991 | %smtp_accept_keepalive% some TCP/IP magic | |
11992 | %smtp_accept_max% simultaneous incoming connections | |
068aaea8 | 11993 | %smtp_accept_max_nonmail% non-mail commands |
168e428f PH |
11994 | %smtp_accept_max_nonmail_hosts% hosts to which the limit applies |
11995 | %smtp_accept_max_per_connection% messages per connection | |
11996 | %smtp_accept_max_per_host% connections from one host | |
11997 | %smtp_accept_queue% queue mail if more connections | |
11998 | %smtp_accept_queue_per_connection% queue if more messages per connection | |
11999 | %smtp_accept_reserve% only reserve hosts if more connections | |
12000 | %smtp_active_hostname% host name to use in messages | |
12001 | %smtp_banner% text for welcome banner | |
12002 | %smtp_check_spool_space% from SIZE on MAIL command | |
12003 | %smtp_connect_backlog% passed to TCP/IP stack | |
12004 | %smtp_enforce_sync% of SMTP command/responses | |
12005 | %smtp_etrn_command% what to run for ETRN | |
12006 | %smtp_etrn_serialize% only one at once | |
12007 | %smtp_load_reserve% only reserve hosts if this load | |
12008 | %smtp_max_unknown_commands% before dropping connection | |
12009 | %smtp_ratelimit_hosts% apply ratelimiting to these hosts | |
12010 | %smtp_ratelimit_mail% ratelimit for MAIL commands | |
12011 | %smtp_ratelimit_rcpt% ratelimit for RCPT commands | |
12012 | %smtp_receive_timeout% per command or data line | |
12013 | %smtp_reserve_hosts% these are the reserve hosts | |
12014 | %smtp_return_error_details% give detail on rejections | |
12015 | -------------------------------------------------------------------------- | |
12016 | ||
12017 | ||
12018 | ||
12019 | SMTP extensions | |
12020 | ~~~~~~~~~~~~~~~ | |
12021 | [frame="none"] | |
12022 | `-----------------------------------`------------------------------------- | |
12023 | %accept_8bitmime% advertise 8BITMIME | |
12024 | %auth_advertise_hosts% advertise AUTH to these hosts | |
12025 | %ignore_fromline_hosts% allow ``From '' from these hosts | |
12026 | %ignore_fromline_local% allow ``From '' from local SMTP | |
12027 | %pipelining_advertise_hosts% advertise pipelining to these hosts | |
12028 | %tls_advertise_hosts% advertise TLS to these hosts | |
12029 | -------------------------------------------------------------------------- | |
12030 | ||
12031 | ||
12032 | ||
12033 | Processing messages | |
12034 | ~~~~~~~~~~~~~~~~~~~ | |
12035 | [frame="none"] | |
12036 | `-----------------------------------`------------------------------------- | |
12037 | %allow_domain_literals% recognize domain literal syntax | |
12038 | %allow_mx_to_ip% allow MX to point to IP address | |
12039 | %allow_utf8_domains% in addresses | |
d1e83bff | 12040 | %check_rfc2047_length% check length of RFC 2047 ``encoded words'' |
168e428f PH |
12041 | %delivery_date_remove% from incoming messages |
12042 | %envelope_to_remote% from incoming messages | |
f9daeae0 | 12043 | %extract_addresses_remove_arguments% affects %-t% processing |
168e428f PH |
12044 | %headers_charset% default for translations |
12045 | %qualify_domain% default for senders | |
12046 | %qualify_recipient% default for recipients | |
12047 | %return_path_remove% from incoming messages | |
12048 | %strip_excess_angle_brackets% in addresses | |
12049 | %strip_trailing_dot% at end of addresses | |
12050 | %untrusted_set_sender% untrusted can set envelope sender | |
12051 | -------------------------------------------------------------------------- | |
12052 | ||
12053 | ||
12054 | ||
12055 | System filter | |
12056 | ~~~~~~~~~~~~~ | |
12057 | [frame="none"] | |
12058 | `-----------------------------------`------------------------------------- | |
12059 | %system_filter% locate system filter | |
12060 | %system_filter_directory_transport% transport for delivery to a directory | |
12061 | %system_filter_file_transport% transport for delivery to a file | |
12062 | %system_filter_group% group for filter running | |
12063 | %system_filter_pipe_transport% transport for delivery to a pipe | |
12064 | %system_filter_reply_transport% transport for autoreply delivery | |
12065 | %system_filter_user% user for filter running | |
12066 | -------------------------------------------------------------------------- | |
12067 | ||
12068 | ||
12069 | ||
12070 | Routing and delivery | |
12071 | ~~~~~~~~~~~~~~~~~~~~ | |
12072 | [frame="none"] | |
12073 | `-----------------------------------`------------------------------------- | |
12074 | %dns_again_means_nonexist% for broken domains | |
12075 | %dns_check_names_pattern% pre-DNS syntax check | |
12076 | %dns_ipv4_lookup% only v4 lookup for these domains | |
12077 | %dns_retrans% parameter for resolver | |
12078 | %dns_retry% parameter for resolver | |
12079 | %hold_domains% hold delivery for these domains | |
12080 | %local_interfaces% for routing checks | |
12081 | %queue_domains% no immediate delivery for these | |
12082 | %queue_only% no immediate delivery at all | |
068aaea8 | 12083 | %queue_only_file% no immediate delivery if file exists |
168e428f PH |
12084 | %queue_only_load% no immediate delivery if load is high |
12085 | %queue_only_override% allow command line to override | |
12086 | %queue_run_in_order% order of arrival | |
12087 | %queue_run_max% of simultaneous queue runners | |
12088 | %queue_smtp_domains% no immediate SMTP delivery for these | |
12089 | %remote_max_parallel% parallel SMTP delivery per message | |
12090 | %remote_sort_domains% order of remote deliveries | |
12091 | %retry_data_expire% timeout for retry data | |
12092 | %retry_interval_max% safety net for retry rules | |
12093 | -------------------------------------------------------------------------- | |
12094 | ||
12095 | ||
12096 | ||
12097 | Bounce and warning messages | |
12098 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
12099 | [frame="none"] | |
12100 | `-----------------------------------`------------------------------------- | |
12101 | %bounce_message_file% content of bounce | |
12102 | %bounce_message_text% content of bounce | |
12103 | %bounce_return_body% include body if returning message | |
12104 | %bounce_return_message% include original message in bounce | |
12105 | %bounce_return_size_limit% limit on returned message | |
12106 | %bounce_sender_authentication% send authenticated sender with bounce | |
12107 | %errors_copy% copy bounce messages | |
12108 | %errors_reply_to% 'Reply-to:' in bounces | |
12109 | %delay_warning% time schedule | |
12110 | %delay_warning_condition% condition for warning messages | |
12111 | %ignore_bounce_errors_after% discard undeliverable bounces | |
068aaea8 | 12112 | %smtp_return_error_details% give detail on rejections |
168e428f PH |
12113 | %warn_message_file% content of warning message |
12114 | -------------------------------------------------------------------------- | |
12115 | ||
12116 | ||
12117 | ||
12118 | [[SECTalomo]] | |
12119 | Alphabetical list of main options | |
12120 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
12121 | Those options that undergo string expansion before use are marked with !!. | |
12122 | ||
12123 | oindex:[%accept_8bitmime%] | |
12124 | `..'= | |
12125 | %accept_8bitmime%, Use: 'main', Type: 'boolean', Default: 'false' | |
12126 | === | |
12127 | ||
12128 | cindex:[8BITMIME] | |
12129 | cindex:[8-bit characters] | |
12130 | This option causes Exim to send 8BITMIME in its response to an SMTP | |
12131 | EHLO command, and to accept the BODY= parameter on MAIL commands. | |
12132 | However, though Exim is 8-bit clean, it is not a protocol converter, and it | |
12133 | takes no steps to do anything special with messages received by this route. | |
12134 | Consequently, this option is turned off by default. | |
12135 | ||
12136 | oindex:[%acl_not_smtp%] | |
12137 | `..'= | |
12138 | %acl_not_smtp%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
12139 | === | |
12140 | ||
12141 | cindex:[{ACL},for non-SMTP messages] | |
068aaea8 | 12142 | cindex:[non-SMTP messages, ACLs for] |
168e428f PH |
12143 | This option defines the ACL that is run when a non-SMTP message is on the point |
12144 | of being accepted. See chapter <<CHAPACL>> for further details. | |
12145 | ||
068aaea8 PH |
12146 | oindex:[%acl_not_smtp_mime%] |
12147 | `..'= | |
12148 | %acl_not_smtp_mime%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
12149 | === | |
12150 | ||
12151 | [revisionflag="changed"] | |
12152 | This option defines the ACL that is run for individual MIME parts of non-SMTP | |
12153 | messages. It operates in exactly the same way as %acl_smtp_mime% operates for | |
12154 | SMTP messages. | |
12155 | ||
168e428f PH |
12156 | oindex:[%acl_smtp_auth%] |
12157 | `..'= | |
12158 | %acl_smtp_auth%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
12159 | === | |
12160 | ||
12161 | cindex:[{ACL},setting up for SMTP commands] | |
12162 | cindex:[AUTH,ACL for] | |
12163 | This option defines the ACL that is run when an SMTP AUTH command is | |
12164 | received. See chapter <<CHAPACL>> for further details. | |
12165 | ||
12166 | oindex:[%acl_smtp_connect%] | |
12167 | `..'= | |
12168 | %acl_smtp_connect%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
12169 | === | |
12170 | ||
12171 | cindex:[{ACL},on SMTP connection] | |
12172 | This option defines the ACL that is run when an SMTP connection is received. | |
12173 | See chapter <<CHAPACL>> for further details. | |
12174 | ||
12175 | oindex:[%acl_smtp_data%] | |
12176 | `..'= | |
12177 | %acl_smtp_data%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
12178 | === | |
12179 | ||
12180 | cindex:[DATA, ACL for] | |
12181 | This option defines the ACL that is run after an SMTP DATA command has been | |
12182 | processed and the message itself has been received, but before the final | |
12183 | acknowledgement is sent. See chapter <<CHAPACL>> for further details. | |
12184 | ||
12185 | oindex:[%acl_smtp_etrn%] | |
12186 | `..'= | |
12187 | %acl_smtp_etrn%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
12188 | === | |
12189 | ||
12190 | cindex:[ETRN,ACL for] | |
12191 | This option defines the ACL that is run when an SMTP ETRN command is | |
12192 | received. See chapter <<CHAPACL>> for further details. | |
12193 | ||
12194 | oindex:[%acl_smtp_expn%] | |
12195 | `..'= | |
12196 | %acl_smtp_expn%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
12197 | === | |
12198 | ||
12199 | cindex:[EXPN,ACL for] | |
12200 | This option defines the ACL that is run when an SMTP EXPN command is | |
12201 | received. See chapter <<CHAPACL>> for further details. | |
12202 | ||
12203 | oindex:[%acl_smtp_helo%] | |
12204 | `..'= | |
12205 | %acl_smtp_helo%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
12206 | === | |
12207 | ||
12208 | cindex:[EHLO,ACL for] | |
12209 | cindex:[HELO,ACL for] | |
12210 | This option defines the ACL that is run when an SMTP EHLO or HELO | |
12211 | command is received. See chapter <<CHAPACL>> for further details. | |
12212 | ||
12213 | ||
12214 | oindex:[%acl_smtp_mail%] | |
12215 | `..'= | |
12216 | %acl_smtp_mail%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
12217 | === | |
12218 | ||
12219 | cindex:[MAIL,ACL for] | |
12220 | This option defines the ACL that is run when an SMTP MAIL command is | |
12221 | received. See chapter <<CHAPACL>> for further details. | |
12222 | ||
12223 | oindex:[%acl_smtp_mailauth%] | |
12224 | `..'= | |
12225 | %acl_smtp_mailauth%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
12226 | === | |
12227 | ||
12228 | cindex:[AUTH,on MAIL command] | |
12229 | This option defines the ACL that is run when there is an AUTH parameter on | |
12230 | a MAIL command. See chapter <<CHAPACL>> for details of ACLs, and chapter | |
12231 | <<CHAPSMTPAUTH>> for details of authentication. | |
12232 | ||
12233 | oindex:[%acl_smtp_mime%] | |
12234 | `..'= | |
12235 | %acl_smtp_mime%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
12236 | === | |
12237 | ||
12238 | cindex:[MIME content scanning,ACL for] | |
12239 | This option is available when Exim is built with the content-scanning | |
12240 | extension. It defines the ACL that is run for each MIME part in a message. See | |
12241 | section <<SECTscanmimepart>> for details. | |
12242 | ||
12243 | oindex:[%acl_smtp_predata%] | |
12244 | `..'= | |
12245 | %acl_smtp_predata%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
12246 | === | |
12247 | ||
12248 | This option defines the ACL that is run when an SMTP DATA command is | |
12249 | received, before the message itself is received. See chapter <<CHAPACL>> for | |
12250 | further details. | |
12251 | ||
12252 | oindex:[%acl_smtp_quit%] | |
12253 | `..'= | |
12254 | %acl_smtp_quit%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
12255 | === | |
12256 | ||
12257 | cindex:[QUIT,ACL for] | |
12258 | This option defines the ACL that is run when an SMTP QUIT command is | |
12259 | received. See chapter <<CHAPACL>> for further details. | |
12260 | ||
12261 | oindex:[%acl_smtp_rcpt%] | |
12262 | `..'= | |
12263 | %acl_smtp_rcpt%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
12264 | === | |
12265 | ||
12266 | cindex:[RCPT,ACL for] | |
12267 | This option defines the ACL that is run when an SMTP RCPT command is | |
12268 | received. See chapter <<CHAPACL>> for further details. | |
12269 | ||
12270 | oindex:[%acl_smtp_starttls%] | |
12271 | `..'= | |
12272 | %acl_smtp_starttls%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
12273 | === | |
12274 | ||
12275 | cindex:[STARTTLS, ACL for] | |
12276 | This option defines the ACL that is run when an SMTP STARTTLS command is | |
12277 | received. See chapter <<CHAPACL>> for further details. | |
12278 | ||
12279 | oindex:[%acl_smtp_vrfy%] | |
12280 | `..'= | |
12281 | %acl_smtp_vrfy%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
12282 | === | |
12283 | ||
12284 | cindex:[VRFY,ACL for] | |
12285 | This option defines the ACL that is run when an SMTP VRFY command is | |
12286 | received. See chapter <<CHAPACL>> for further details. | |
12287 | ||
12288 | oindex:[%admin_groups%] | |
12289 | `..'= | |
068aaea8 | 12290 | %admin_groups%, Use: 'main', Type: 'string list'!!, Default: 'unset' |
168e428f PH |
12291 | === |
12292 | ||
068aaea8 | 12293 | [revisionflag="changed"] |
168e428f | 12294 | cindex:[admin user] |
068aaea8 PH |
12295 | This option is expanded just once, at the start of Exim's processing. If the |
12296 | current group or any of the supplementary groups of an Exim caller is in this | |
12297 | colon-separated list, the caller has admin privileges. If all your system | |
168e428f PH |
12298 | programmers are in a specific group, for example, you can give them all Exim |
12299 | admin privileges by putting that group in %admin_groups%. However, this does | |
12300 | not permit them to read Exim's spool files (whose group owner is the Exim gid). | |
12301 | To permit this, you have to add individuals to the Exim group. | |
12302 | ||
12303 | ||
12304 | oindex:[%allow_domain_literals%] | |
12305 | `..'= | |
12306 | %allow_domain_literals%, Use: 'main', Type: 'boolean', Default: 'false' | |
12307 | === | |
12308 | ||
12309 | cindex:[domain literal] | |
12310 | If this option is set, the RFC 2822 domain literal format is permitted in | |
12311 | email addresses. The option is not set by default, because the domain literal | |
12312 | format is not normally required these days, and few people know about it. It | |
12313 | has, however, been exploited by mail abusers. | |
12314 | ||
12315 | Unfortunately, it seems that some DNS black list maintainers are using this | |
12316 | format to report black listing to postmasters. If you want to accept messages | |
12317 | addressed to your hosts by IP address, you need to set | |
12318 | %allow_domain_literals% true, and also to add `@[]` to the list of local | |
12319 | domains (defined in the named domain list %local_domains% in the default | |
12320 | configuration). This ``magic string'' matches the domain literal form of all the | |
12321 | local host's IP addresses. | |
12322 | ||
12323 | ||
12324 | oindex:[%allow_mx_to_ip%] | |
12325 | `..'= | |
12326 | %allow_mx_to_ip%, Use: 'main', Type: 'boolean', Default: 'false' | |
12327 | === | |
12328 | ||
12329 | cindex:[MX record,pointing to IP address] | |
12330 | It appears that more and more DNS zone administrators are breaking the rules | |
12331 | and putting domain names that look like IP addresses on the right hand side of | |
12332 | MX records. Exim follows the rules and rejects this, giving an error message | |
12333 | that explains the mis-configuration. However, some other MTAs support this | |
12334 | practice, so to avoid ``Why can''t Exim do this?' complaints, %allow_mx_to_ip% | |
12335 | exists, in order to enable this heinous activity. It is not recommended, except | |
12336 | when you have no other choice. | |
12337 | ||
12338 | oindex:[%allow_utf8_domains%] | |
12339 | `..'= | |
12340 | %allow_utf8_domains%, Use: 'main', Type: 'boolean', Default: 'false' | |
12341 | === | |
12342 | ||
12343 | cindex:[domain,UTF-8 characters in] | |
12344 | cindex:[UTF-8,in domain name] | |
12345 | Lots of discussion is going on about internationalized domain names. One | |
12346 | camp is strongly in favour of just using UTF-8 characters, and it seems | |
12347 | that at least two other MTAs permit this. This option allows Exim users to | |
12348 | experiment if they wish. | |
12349 | ||
12350 | If it is set true, Exim's domain parsing function allows valid | |
12351 | UTF-8 multicharacters to appear in domain name components, in addition to | |
12352 | letters, digits, and hyphens. However, just setting this option is not | |
12353 | enough; if you want to look up these domain names in the DNS, you must also | |
12354 | adjust the value of %dns_check_names_pattern% to match the extended form. A | |
12355 | suitable setting is: | |
12356 | ||
12357 | .... | |
12358 | dns_check_names_pattern = (?i)^(?>(?(1)\.|())[a-z0-9\xc0-\xff]\ | |
12359 | (?>[-a-z0-9\x80-\xff]*[a-z0-9\x80-\xbf])?)+$ | |
12360 | .... | |
12361 | ||
12362 | Alternatively, you can just disable this feature by setting | |
12363 | ||
12364 | dns_check_names_pattern = | |
12365 | ||
12366 | That is, set the option to an empty string so that no check is done. | |
12367 | ||
12368 | ||
12369 | oindex:[%auth_advertise_hosts%] | |
12370 | `..'= | |
12371 | %auth_advertise_hosts%, Use: 'main', Type: 'host list'!!, Default: '\*' | |
12372 | === | |
12373 | ||
12374 | cindex:[authentication,advertising] | |
12375 | cindex:[AUTH,advertising] | |
12376 | If any server authentication mechanisms are configured, Exim advertises them in | |
12377 | response to an EHLO command only if the calling host matches this list. | |
12378 | Otherwise, Exim does not advertise AUTH. | |
12379 | Exim does not accept AUTH commands from clients to which it has not | |
12380 | advertised the availability of AUTH. The advertising of individual | |
12381 | authentication mechanisms can be controlled by the use of the | |
12382 | %server_advertise_condition% generic authenticator option on the individual | |
12383 | authenticators. See chapter <<CHAPSMTPAUTH>> for further details. | |
12384 | ||
12385 | Certain mail clients (for example, Netscape) require the user to provide a name | |
12386 | and password for authentication if AUTH is advertised, even though it may | |
12387 | not be needed (the host may accept messages from hosts on its local LAN without | |
12388 | authentication, for example). The %auth_advertise_hosts% option can be used | |
12389 | to make these clients more friendly by excluding them from the set of hosts to | |
12390 | which Exim advertises AUTH. | |
12391 | ||
12392 | cindex:[AUTH,advertising when encrypted] | |
12393 | If you want to advertise the availability of AUTH only when the connection | |
12394 | is encrypted using TLS, you can make use of the fact that the value of this | |
12395 | option is expanded, with a setting like this: | |
12396 | ||
12397 | auth_advertise_hosts = ${if eq{$tls_cipher}{}{}{*}} | |
12398 | ||
068aaea8 | 12399 | cindex:[$tls_cipher$] |
168e428f PH |
12400 | If $tls_cipher$ is empty, the session is not encrypted, and the result of |
12401 | the expansion is empty, thus matching no hosts. Otherwise, the result of the | |
12402 | expansion is \*, which matches all hosts. | |
12403 | ||
12404 | ||
12405 | oindex:[%auto_thaw%] | |
12406 | `..'= | |
12407 | %auto_thaw%, Use: 'main', Type: 'time', Default: '0s' | |
12408 | === | |
12409 | ||
068aaea8 | 12410 | [revisionflag="changed"] |
168e428f PH |
12411 | cindex:[thawing messages] |
12412 | cindex:[unfreezing messages] | |
12413 | If this option is set to a time greater than zero, a queue runner will try a | |
068aaea8 PH |
12414 | new delivery attempt on any frozen message, other than a bounce message, if |
12415 | this much time has passed since it was frozen. This may result in the message | |
12416 | being re-frozen if nothing has changed since the last attempt. It is a way of | |
12417 | saying ``keep on trying, even though there are big problems''. | |
12418 | ||
12419 | *Note*: This is an old option, which predates %timeout_frozen_after% and | |
12420 | %ignore_bounce_errors_after%. It is retained for compatibility, but it is not | |
12421 | thought to be very useful any more, and its use should probably be avoided. | |
168e428f PH |
12422 | |
12423 | ||
12424 | oindex:[%av_scanner%] | |
12425 | `..'= | |
12426 | %av_scanner%, Use: 'main', Type: 'string', Default: 'see below' | |
12427 | === | |
12428 | ||
12429 | This option is available if Exim is built with the content-scanning extension. | |
12430 | It specifies which anti-virus scanner to use. The default value is: | |
12431 | ||
12432 | sophie:/var/run/sophie | |
12433 | ||
12434 | If the value of %av_scanner% starts with dollar character, it is expanded | |
12435 | before use. See section <<SECTscanvirus>> for further details. | |
12436 | ||
12437 | ||
12438 | ||
12439 | oindex:[%bi_command%] | |
12440 | `..'= | |
12441 | %bi_command%, Use: 'main', Type: 'string', Default: 'unset' | |
12442 | === | |
12443 | ||
12444 | cindex:[%-bi% option] | |
12445 | This option supplies the name of a command that is run when Exim is called with | |
12446 | the %-bi% option (see chapter <<CHAPcommandline>>). The string value is just the | |
12447 | command name, it is not a complete command line. If an argument is required, it | |
12448 | must come from the %-oA% command line option. | |
12449 | ||
12450 | ||
12451 | oindex:[%bounce_message_file%] | |
12452 | `..'= | |
12453 | %bounce_message_file%, Use: 'main', Type: 'string', Default: 'unset' | |
12454 | === | |
12455 | ||
12456 | cindex:[bounce message,customizing] | |
12457 | cindex:[customizing,bounce message] | |
12458 | This option defines a template file containing paragraphs of text to be used | |
12459 | for constructing bounce messages. Details of the file's contents are given in | |
12460 | chapter <<CHAPemsgcust>>. See also %warn_message_file%. | |
12461 | ||
12462 | ||
12463 | oindex:[%bounce_message_text%] | |
12464 | `..'= | |
12465 | %bounce_message_text%, Use: 'main', Type: 'string', Default: 'unset' | |
12466 | === | |
12467 | ||
12468 | When this option is set, its contents are included in the default bounce | |
12469 | message immediately after ``This message was created automatically by mail | |
12470 | delivery software.'' It is not used if %bounce_message_file% is set. | |
12471 | ||
12472 | oindex:[%bounce_return_body%] | |
12473 | `..'= | |
12474 | %bounce_return_body%, Use: 'main', Type: 'boolean', Default: 'true' | |
12475 | === | |
12476 | ||
12477 | cindex:[bounce message,including body] | |
12478 | This option controls whether the body of an incoming message is included in a | |
12479 | bounce message when %bounce_return_message% is true. If it is not set, only | |
12480 | the message header is included. | |
12481 | cindex:[bounce message,including original] | |
12482 | ||
12483 | oindex:[%bounce_return_message%] | |
12484 | `..'= | |
12485 | %bounce_return_message%, Use: 'main', Type: 'boolean', Default: 'true' | |
12486 | === | |
12487 | ||
12488 | If this option is set false, the original message is not included in bounce | |
12489 | messages generated by Exim. See also %bounce_return_size_limit%. | |
12490 | ||
12491 | ||
12492 | oindex:[%bounce_return_size_limit%] | |
12493 | `..'= | |
12494 | %bounce_return_size_limit%, Use: 'main', Type: 'integer', Default: '100K' | |
12495 | === | |
12496 | ||
12497 | cindex:[size limit, of bounce] | |
12498 | cindex:[bounce message,size limit] | |
12499 | cindex:[limit,bounce message size] | |
12500 | This option sets a limit in bytes on the size of messages that are returned to | |
12501 | senders as part of bounce messages when %bounce_return_message% is true. The | |
12502 | limit should be less than the value of the global %message_size_limit% and of | |
12503 | any %message_size_limit% settings on transports, to allow for the bounce text | |
12504 | that Exim generates. If this option is set to zero there is no limit. | |
12505 | ||
12506 | When the body of any message that is to be included in a bounce message is | |
12507 | greater than the limit, it is truncated, and a comment pointing this out is | |
12508 | added at the top. The actual cutoff may be greater than the value given, owing | |
12509 | to the use of buffering for transferring the message in chunks (typically 8K in | |
12510 | size). The idea is to save bandwidth on those undeliverable 15-megabyte | |
12511 | messages. | |
12512 | ||
12513 | oindex:[%bounce_sender_authentication%] | |
12514 | `..'= | |
12515 | %bounce_sender_authentication%, Use: 'main', Type: 'string', Default: 'unset' | |
12516 | === | |
12517 | ||
12518 | cindex:[bounce message,sender authentication] | |
12519 | cindex:[authentication,bounce message] | |
12520 | cindex:[AUTH,on bounce message] | |
12521 | This option provides an authenticated sender address that is sent with any | |
12522 | bounce messages generated by Exim that are sent over an authenticated SMTP | |
12523 | connection. A typical setting might be: | |
12524 | ||
12525 | bounce_sender_authentication = mailer-daemon@my.domain.example | |
12526 | ||
12527 | which would cause bounce messages to be sent using the SMTP command: | |
12528 | ||
12529 | MAIL FROM:<> AUTH=mailer-daemon@my.domain.example | |
12530 | ||
12531 | The value of %bounce_sender_authentication% must always be a complete email | |
12532 | address. | |
12533 | ||
12534 | oindex:[%callout_domain_negative_expire%] | |
12535 | `..'= | |
12536 | %callout_domain_negative_expire%, Use: 'main', Type: 'time', Default: '3h' | |
12537 | === | |
12538 | ||
12539 | cindex:[caching,callout timeouts] | |
12540 | cindex:[callout,caching timeouts] | |
12541 | This option specifies the expiry time for negative callout cache data for a | |
12542 | domain. See section <<SECTcallver>> for details of callout verification, and | |
12543 | section <<SECTcallvercache>> for details of the caching. | |
12544 | ||
12545 | ||
12546 | oindex:[%callout_domain_positive_expire%] | |
12547 | `..'= | |
12548 | %callout_domain_positive_expire%, Use: 'main', Type: 'time', Default: '7d' | |
12549 | === | |
12550 | ||
12551 | This option specifies the expiry time for positive callout cache data for a | |
12552 | domain. See section <<SECTcallver>> for details of callout verification, and | |
12553 | section <<SECTcallvercache>> for details of the caching. | |
12554 | ||
12555 | ||
12556 | oindex:[%callout_negative_expire%] | |
12557 | `..'= | |
12558 | %callout_negative_expire%, Use: 'main', Type: 'time', Default: '2h' | |
12559 | === | |
12560 | ||
12561 | This option specifies the expiry time for negative callout cache data for an | |
12562 | address. See section <<SECTcallver>> for details of callout verification, and | |
12563 | section <<SECTcallvercache>> for details of the caching. | |
12564 | ||
12565 | ||
12566 | oindex:[%callout_positive_expire%] | |
12567 | `..'= | |
12568 | %callout_positive_expire%, Use: 'main', Type: 'time', Default: '24h' | |
12569 | === | |
12570 | ||
12571 | This option specifies the expiry time for positive callout cache data for an | |
12572 | address. See section <<SECTcallver>> for details of callout verification, and | |
12573 | section <<SECTcallvercache>> for details of the caching. | |
12574 | ||
12575 | ||
12576 | oindex:[%callout_random_local_part%] | |
12577 | `..'= | |
12578 | %callout_random_local_part%, Use: 'main', Type: 'string'!!, Default: 'see below' | |
12579 | === | |
12580 | ||
12581 | This option defines the ``random'' local part that can be used as part of callout | |
12582 | verification. The default value is | |
12583 | ||
12584 | $primary_host_name-$tod_epoch-testing | |
12585 | ||
12586 | See section <<CALLaddparcall>> for details of how this value is used. | |
12587 | ||
12588 | ||
12589 | oindex:[%check_log_inodes%] | |
12590 | `..'= | |
12591 | %check_log_inodes%, Use: 'main', Type: 'integer', Default: '0' | |
12592 | === | |
12593 | ||
12594 | See %check_spool_space% below. | |
12595 | ||
12596 | ||
12597 | oindex:[%check_log_space%] | |
12598 | `..'= | |
12599 | %check_log_space%, Use: 'main', Type: 'integer', Default: '0' | |
12600 | === | |
12601 | ||
12602 | See %check_spool_space% below. | |
12603 | ||
d1e83bff PH |
12604 | oindex:[%check_rfc2047_length%] |
12605 | cindex:[RFC 2047,disabling length check] | |
12606 | `..'= | |
12607 | %check_rfc2047_length%, User: 'main', Type: 'boolean', Default: 'true' | |
12608 | === | |
12609 | ||
12610 | RFC 2047 defines a way of encoding non-ASCII characters in headers using a | |
12611 | system of ``encoded words''. The RFC specifies a maximum length for an encoded | |
12612 | word; strings to be encoded that exceed this length are supposed to use | |
12613 | multiple encoded words. By default, Exim does not recognize encoded words that | |
12614 | exceed the maximum length. However, it seems that some software, in violation | |
12615 | of the RFC, generates overlong encoded words. If %check_rfc2047_length% is set | |
12616 | false, Exim recognizes encoded words of any length. | |
12617 | ||
168e428f PH |
12618 | |
12619 | oindex:[%check_spool_inodes%] | |
12620 | `..'= | |
12621 | %check_spool_inodes%, Use: 'main', Type: 'integer', Default: '0' | |
12622 | === | |
12623 | ||
12624 | See %check_spool_space% below. | |
12625 | ||
12626 | ||
12627 | oindex:[%check_spool_space%] | |
12628 | `..'= | |
12629 | %check_spool_space%, Use: 'main', Type: 'integer', Default: '0' | |
12630 | === | |
12631 | ||
12632 | cindex:[checking disk space] | |
12633 | cindex:[disk space, checking] | |
12634 | cindex:[spool directory,checking space] | |
12635 | The four %check_...% options allow for checking of disk resources before a | |
12636 | message is accepted. | |
12637 | ||
068aaea8 PH |
12638 | cindex:[$log_inodes$] |
12639 | cindex:[$log_space$] | |
12640 | cindex:[$spool_inodes$] | |
12641 | cindex:[$spool_space$] | |
168e428f | 12642 | When any of these options are set, they apply to all incoming messages. If you |
068aaea8 PH |
12643 | want to apply different checks to different kinds of message, you can do so by |
12644 | testing the the variables $log_inodes$, $log_space$, $spool_inodes$, and | |
12645 | $spool_space$ in an ACL with appropriate additional conditions. | |
168e428f PH |
12646 | |
12647 | ||
12648 | %check_spool_space% and %check_spool_inodes% check the spool partition if | |
12649 | either value is greater than zero, for example: | |
12650 | ||
12651 | check_spool_space = 10M | |
12652 | check_spool_inodes = 100 | |
12653 | ||
12654 | The spool partition is the one that contains the directory defined by | |
12655 | SPOOL_DIRECTORY in _Local/Makefile_. It is used for holding messages in | |
12656 | transit. | |
12657 | ||
12658 | %check_log_space% and %check_log_inodes% check the partition in which log | |
12659 | files are written if either is greater than zero. These should be set only if | |
12660 | %log_file_path% and %spool_directory% refer to different partitions. | |
12661 | ||
12662 | If there is less space or fewer inodes than requested, Exim refuses to accept | |
12663 | incoming mail. In the case of SMTP input this is done by giving a 452 temporary | |
12664 | error response to the MAIL command. If ESMTP is in use and there was a | |
12665 | SIZE parameter on the MAIL command, its value is added to the | |
12666 | %check_spool_space% value, and the check is performed even if | |
12667 | %check_spool_space% is zero, unless %no_smtp_check_spool_space% is set. | |
12668 | ||
12669 | The values for %check_spool_space% and %check_log_space% are held as a | |
12670 | number of kilobytes. If a non-multiple of 1024 is specified, it is rounded up. | |
12671 | ||
12672 | For non-SMTP input and for batched SMTP input, the test is done at start-up; on | |
12673 | failure a message is written to stderr and Exim exits with a non-zero code, as | |
12674 | it obviously cannot send an error message of any kind. | |
12675 | ||
12676 | oindex:[%daemon_smtp_ports%] | |
12677 | `..'= | |
12678 | %daemon_smtp_ports%, Use: 'main', Type: 'string', Default: `smtp` | |
12679 | === | |
12680 | ||
12681 | cindex:[port,for daemon] | |
12682 | cindex:[TCP/IP,setting listening ports] | |
12683 | This option specifies one or more default SMTP ports on which the Exim daemon | |
12684 | listens. See chapter <<CHAPinterfaces>> for details of how it is used. For | |
12685 | backward compatibility, %daemon_smtp_port% (singular) is a synonym. | |
12686 | ||
068aaea8 PH |
12687 | oindex:[%daemon_startup_retries%] |
12688 | `..'= | |
12689 | %daemon_startup_retries%, Use: 'main', Type: 'integer', Default: '9' | |
12690 | === | |
12691 | ||
12692 | [revisionflag="changed"] | |
12693 | cindex:[daemon startup,retrying] | |
12694 | This option, along with %daemon_startup_sleep%, controls the retrying done by | |
12695 | the daemon at startup when it cannot immediately bind a listening socket | |
12696 | (typically because the socket is already in use): %daemon_startup_retries% | |
12697 | defines the number of retries after the first failure, and | |
12698 | %daemon_startup_sleep% defines the length of time to wait between retries. | |
12699 | ||
12700 | oindex:[%daemon_startup_sleep%] | |
12701 | `..'= | |
12702 | %daemon_startup_sleep%, Use: 'main', Type: 'time', Default: '30s' | |
12703 | === | |
12704 | ||
12705 | [revisionflag="changed"] | |
12706 | See %daemon_startup_retries%. | |
168e428f PH |
12707 | |
12708 | oindex:[%delay_warning%] | |
12709 | `..'= | |
12710 | %delay_warning%, Use: 'main', Type: 'time list', Default: '24h' | |
12711 | === | |
12712 | ||
12713 | cindex:[warning of delay] | |
12714 | cindex:[delay warning, specifying] | |
12715 | When a message is delayed, Exim sends a warning message to the sender at | |
12716 | intervals specified by this option. The data is a colon-separated list of times | |
12717 | after which to send warning messages. | |
12718 | ||
12719 | If the value of the option is an empty string or a zero time, no warnings are | |
12720 | sent. | |
12721 | ||
12722 | Up to 10 times may be given. If a message has been on the queue for longer than | |
12723 | the last time, the last interval between the times is used to compute | |
12724 | subsequent warning times. For example, with | |
12725 | ||
12726 | delay_warning = 4h:8h:24h | |
12727 | ||
12728 | the first message is sent after 4 hours, the second after 8 hours, and | |
12729 | the third one after 24 hours. After that, messages are sent every 16 hours, | |
12730 | because that is the interval between the last two times on the list. If you set | |
12731 | just one time, it specifies the repeat interval. For example, with: | |
12732 | ||
12733 | delay_warning = 6h | |
12734 | ||
12735 | messages are repeated every six hours. To stop warnings after a given time, set | |
12736 | a very large time at the end of the list. For example: | |
12737 | ||
12738 | delay_warning = 2h:12h:99d | |
12739 | ||
12740 | ||
12741 | ||
12742 | oindex:[%delay_warning_condition%] | |
12743 | `..'= | |
12744 | %delay_warning_condition%, Use: 'main', Type: 'string'!!, Default: 'see below' | |
12745 | === | |
12746 | ||
068aaea8 | 12747 | cindex:[$domain$] |
168e428f PH |
12748 | The string is expanded at the time a warning message might be sent. If all the |
12749 | deferred addresses have the same domain, it is set in $domain$ during the | |
12750 | expansion. Otherwise $domain$ is empty. If the result of the expansion is a | |
12751 | forced failure, an empty string, or a string matching any of ``0'', ``no'' or | |
12752 | ``false'' (the comparison being done caselessly) then the warning message is not | |
12753 | sent. The default is | |
12754 | ||
12755 | .... | |
12756 | delay_warning_condition = \ | |
12757 | ${if match{$h_precedence:}{(?i)bulk|list|junk}{no}{yes}} | |
12758 | .... | |
12759 | ||
12760 | which suppresses the sending of warnings about messages that have ``bulk'', | |
12761 | ``list'' or ``junk'' in a 'Precedence:' header. | |
12762 | ||
12763 | oindex:[%deliver_drop_privilege%] | |
12764 | `..'= | |
12765 | %deliver_drop_privilege%, Use: 'main', Type: 'boolean', Default: 'false' | |
12766 | === | |
12767 | ||
12768 | cindex:[unprivileged delivery] | |
12769 | cindex:[delivery,unprivileged] | |
12770 | If this option is set true, Exim drops its root privilege at the start of a | |
12771 | delivery process, and runs as the Exim user throughout. This severely restricts | |
12772 | the kinds of local delivery that are possible, but is viable in certain types | |
12773 | of configuration. There is a discussion about the use of root privilege in | |
12774 | chapter <<CHAPsecurity>>. | |
12775 | ||
12776 | oindex:[%deliver_queue_load_max%] | |
12777 | `..'= | |
12778 | %deliver_queue_load_max%, Use: 'main', Type: 'fixed-point', Default: 'unset' | |
12779 | === | |
12780 | ||
12781 | cindex:[load average] | |
12782 | cindex:[queue runner,abandoning] | |
12783 | When this option is set, a queue run is abandoned if the system load average | |
12784 | becomes greater than the value of the option. The option has no effect on | |
12785 | ancient operating systems on which Exim cannot determine the load average. | |
12786 | See also %queue_only_load% and %smtp_load_reserve%. | |
12787 | ||
12788 | ||
12789 | oindex:[%delivery_date_remove%] | |
12790 | `..'= | |
12791 | %delivery_date_remove%, Use: 'main', Type: 'boolean', Default: 'true' | |
12792 | === | |
12793 | ||
12794 | cindex:['Delivery-date:' header line] | |
12795 | Exim's transports have an option for adding a 'Delivery-date:' header to a | |
12796 | message when it is delivered -- in exactly the same way as 'Return-path:' is | |
12797 | handled. 'Delivery-date:' records the actual time of delivery. Such headers | |
12798 | should not be present in incoming messages, and this option causes them to be | |
12799 | removed at the time the message is received, to avoid any problems that might | |
12800 | occur when a delivered message is subsequently sent on to some other recipient. | |
12801 | ||
12802 | oindex:[%dns_again_means_nonexist%] | |
12803 | `..'= | |
12804 | %dns_again_means_nonexist%, Use: 'main', Type: 'domain list'!!, Default: 'unset' | |
12805 | === | |
12806 | ||
12807 | cindex:[DNS,``try again'' response; overriding] | |
12808 | DNS lookups give a ``try again'' response for the DNS errors ``non-authoritative | |
12809 | host not found'' and ``SERVERFAIL''. This can cause Exim to keep trying to | |
12810 | deliver a message, or to give repeated temporary errors to incoming mail. | |
12811 | Sometimes the effect is caused by a badly set up name server and may persist | |
12812 | for a long time. If a domain which exhibits this problem matches anything in | |
12813 | %dns_again_means_nonexist%, it is treated as if it did not exist. This | |
12814 | option should be used with care. | |
12815 | You can make it apply to reverse lookups by a setting such as this: | |
12816 | ||
12817 | dns_again_means_nonexist = *.in-addr.arpa | |
12818 | ||
12819 | This option applies to all DNS lookups that Exim does. The ^dnslookup^ router | |
12820 | has some options of its own for controlling what happens when lookups for MX or | |
12821 | SRV records give temporary errors. These more specific options are applied | |
12822 | after the global option. | |
12823 | ||
12824 | oindex:[%dns_check_names_pattern%] | |
12825 | `..'= | |
12826 | %dns_check_names_pattern%, Use: 'main', Type: 'string', Default: 'see below' | |
12827 | === | |
12828 | ||
12829 | cindex:[DNS,pre-check of name syntax] | |
12830 | When this option is set to a non-empty string, it causes Exim to check domain | |
12831 | names for illegal characters before handing them to the DNS resolver, because | |
12832 | some resolvers give temporary errors for malformed names. If a domain name | |
12833 | contains any illegal characters, a ``not found'' result is forced, and the | |
12834 | resolver is not called. The check is done by matching the domain name against a | |
12835 | regular expression, which is the value of this option. The default pattern is | |
12836 | ||
12837 | .... | |
12838 | dns_check_names_pattern = \ | |
12839 | (?i)^(?>(?(1)\.|())[^\W_](?>[a-z0-9-]*[^\W_])?)+$ | |
12840 | .... | |
12841 | ||
12842 | which permits only letters, digits, and hyphens in components, but they may not | |
12843 | start or end with a hyphen. | |
12844 | If you set %allow_utf8_domains%, you must modify this pattern, or set the | |
12845 | option to an empty string. | |
12846 | ||
068aaea8 PH |
12847 | oindex:[%dns_csa_search_limit%] |
12848 | `..'= | |
12849 | %dns_csa_search_limit%, Use: 'main', Type: 'integer', Default: '5' | |
12850 | === | |
12851 | ||
12852 | [revisionflag="changed"] | |
12853 | This option controls the depth of parental searching for CSA SRV records in the | |
12854 | DNS, as described in more detail in section <<SECTverifyCSA>>. | |
12855 | ||
12856 | ||
12857 | oindex:[%dns_csa_use_reverse%] | |
12858 | `..'= | |
12859 | %dns_csa_use_reverse%, Use: 'main', Type: 'boolean', Default: 'true' | |
12860 | === | |
12861 | ||
12862 | [revisionflag="changed"] | |
12863 | This option controls whether or not an IP address, given as a CSA domain, is | |
12864 | reversed and looked up in the reverse DNS, as described in more detail in | |
12865 | section <<SECTverifyCSA>>. | |
12866 | ||
168e428f PH |
12867 | |
12868 | oindex:[%dns_ipv4_lookup%] | |
12869 | `..'= | |
12870 | %dns_ipv4_lookup%, Use: 'main', Type: 'domain list'!!, Default: 'unset' | |
12871 | === | |
12872 | ||
12873 | cindex:[IPv6,DNS lookup for AAAA records] | |
12874 | cindex:[DNS,IPv6 lookup for AAAA records] | |
12875 | When Exim is compiled with IPv6 support, it looks for IPv6 address records | |
12876 | (AAAA and, if configured, A6) as well as IPv4 address records when trying to | |
12877 | find IP addresses for hosts, unless the host's domain matches this list. | |
12878 | ||
12879 | This is a fudge to help with name servers that give big delays or otherwise do | |
12880 | not work for the new IPv6 record types. If Exim is handed an IPv6 address | |
12881 | record as a result of an MX lookup, it always recognizes it, and may as a | |
12882 | result make an outgoing IPv6 connection. All this option does is to make Exim | |
12883 | look only for IPv4-style A records when it needs to find an IP address for a | |
12884 | host name. In due course, when the world's name servers have all been upgraded, | |
12885 | there should be no need for this option. | |
12886 | ||
12887 | ||
12888 | oindex:[%dns_retrans%] | |
12889 | `..'= | |
12890 | %dns_retrans%, Use: 'main', Type: 'time', Default: '0s' | |
12891 | === | |
12892 | ||
12893 | cindex:[DNS,resolver options] | |
12894 | The options %dns_retrans% and %dns_retry% can be used to set the | |
12895 | retransmission and retry parameters for DNS lookups. Values of zero (the | |
12896 | defaults) leave the system default settings unchanged. The first value is the | |
12897 | time between retries, and the second is the number of retries. It isn't | |
12898 | totally clear exactly how these settings affect the total time a DNS lookup may | |
12899 | take. I haven't found any documentation about timeouts on DNS lookups; these | |
12900 | parameter values are available in the external resolver interface structure, | |
12901 | but nowhere does it seem to describe how they are used or what you might want | |
12902 | to set in them. | |
12903 | ||
12904 | ||
12905 | oindex:[%dns_retry%] | |
12906 | `..'= | |
12907 | %dns_retry%, Use: 'main', Type: 'integer', Default: '0' | |
12908 | === | |
12909 | ||
12910 | See %dns_retrans% above. | |
12911 | ||
12912 | ||
12913 | oindex:[%drop_cr%] | |
12914 | `..'= | |
12915 | %drop_cr%, Use: 'main', Type: 'boolean', Default: 'false' | |
12916 | === | |
12917 | ||
12918 | This is an obsolete option that is now a no-op. It used to affect the way Exim | |
12919 | handled CR and LF characters in incoming messages. What happens now is | |
12920 | described in section <<SECTlineendings>>. | |
12921 | ||
12922 | ||
12923 | oindex:[%envelope_to_remove%] | |
12924 | `..'= | |
12925 | %envelope_to_remove%, Use: 'main', Type: 'boolean', Default: 'true' | |
12926 | === | |
12927 | ||
12928 | cindex:['Envelope-to:' header line] | |
12929 | Exim's transports have an option for adding an 'Envelope-to:' header to a | |
12930 | message when it is delivered -- in exactly the same way as 'Return-path:' is | |
12931 | handled. 'Envelope-to:' records the original recipient address from the | |
12932 | messages's envelope that caused the delivery to happen. Such headers should not | |
12933 | be present in incoming messages, and this option causes them to be removed at | |
12934 | the time the message is received, to avoid any problems that might occur when a | |
12935 | delivered message is subsequently sent on to some other recipient. | |
12936 | ||
12937 | ||
12938 | oindex:[%errors_copy%] | |
12939 | `..'= | |
12940 | %errors_copy%, Use: 'main', Type: 'string list'!!, Default: 'unset' | |
12941 | === | |
12942 | ||
12943 | cindex:[bounce message,copy to other address] | |
12944 | cindex:[copy of bounce message] | |
12945 | Setting this option causes Exim to send bcc copies of bounce messages that it | |
12946 | generates to other addresses. *Note*: this does not apply to bounce messages | |
12947 | coming from elsewhere. The value of the option is a colon-separated list of | |
12948 | items. Each item consists of a pattern, terminated by white space, followed by | |
12949 | a comma-separated list of email addresses. If a pattern contains spaces, it | |
12950 | must be enclosed in double quotes. | |
12951 | ||
12952 | Each pattern is processed in the same way as a single item in an address list | |
12953 | (see section <<SECTaddresslist>>). When a pattern matches the recipient of the | |
12954 | bounce message, the message is copied to the addresses on the list. The items | |
12955 | are scanned in order, and once a matching one is found, no further items are | |
12956 | examined. For example: | |
12957 | ||
12958 | .... | |
12959 | errors_copy = spqr@mydomain postmaster@mydomain.example :\ | |
12960 | rqps@mydomain hostmaster@mydomain.example,\ | |
12961 | postmaster@mydomain.example | |
12962 | .... | |
12963 | ||
068aaea8 PH |
12964 | cindex:[$domain$] |
12965 | cindex:[$local_part$] | |
168e428f PH |
12966 | The address list is expanded before use. The expansion variables |
12967 | $local_part$ and $domain$ are set from the original recipient of the error | |
12968 | message, and if there was any wildcard matching in the pattern, the expansion | |
12969 | ||
12970 | cindex:[numerical variables ($1$ $2$ etc),in %errors_copy%] | |
12971 | variables $0$, $1$, etc. are set in the normal way. | |
12972 | ||
12973 | ||
12974 | oindex:[%errors_reply_to%] | |
12975 | `..'= | |
12976 | %errors_reply_to%, Use: 'main', Type: 'string', Default: 'unset' | |
12977 | === | |
12978 | ||
12979 | cindex:[bounce message,'Reply-to:' in] | |
12980 | Exim's bounce and delivery warning messages contain the header line | |
12981 | ||
12982 | From: Mail Delivery System <Mailer-Daemon@<qualify-domain>> | |
12983 | ||
12984 | where <'qualify-domain'> is the value of the %qualify_domain% option. | |
12985 | Experience shows that people reply to bounce messages. If the | |
12986 | %errors_reply_to% option is set, a 'Reply-To:' header is added to bounce and | |
12987 | warning messages. For example: | |
12988 | ||
12989 | errors_reply_to = postmaster@my.domain.example | |
12990 | ||
12991 | The value of the option is not expanded. It must specify a valid RFC 2822 | |
12992 | address. | |
12993 | ||
12994 | ||
12995 | oindex:[%exim_group%] | |
12996 | `..'= | |
12997 | %exim_group%, Use: 'main', Type: 'string', Default: 'compile-time configured' | |
12998 | === | |
12999 | ||
13000 | cindex:[gid (group id),Exim's own] | |
13001 | cindex:[Exim group] | |
13002 | This option changes the gid under which Exim runs when it gives up root | |
13003 | privilege. The default value is compiled into the binary. The value of this | |
13004 | option is used only when %exim_user% is also set. Unless it consists entirely | |
13005 | of digits, the string is looked up using 'getgrnam()', and failure causes a | |
13006 | configuration error. See chapter <<CHAPsecurity>> for a discussion of security | |
13007 | issues. | |
13008 | ||
13009 | ||
13010 | oindex:[%exim_path%] | |
13011 | `..'= | |
13012 | %exim_path%, Use: 'main', Type: 'string', Default: 'see below' | |
13013 | === | |
13014 | ||
13015 | cindex:[Exim binary, path name] | |
13016 | This option specifies the path name of the Exim binary, which is used when Exim | |
13017 | needs to re-exec itself. The default is set up to point to the file 'exim' in | |
13018 | the directory configured at compile time by the BIN_DIRECTORY setting. It | |
13019 | is necessary to change %exim_path% if, exceptionally, Exim is run from some | |
13020 | other place. | |
13021 | *Warning*: Do not use a macro to define the value of this option, because | |
13022 | you will break those Exim utilities that scan the configuration file to find | |
13023 | where the binary is. (They then use the %-bP% option to extract option | |
13024 | settings such as the value of %spool_directory%.) | |
13025 | ||
13026 | ||
13027 | oindex:[%exim_user%] | |
13028 | `..'= | |
13029 | %exim_user%, Use: 'main', Type: 'string', Default: 'compile-time configured' | |
13030 | === | |
13031 | ||
13032 | cindex:[uid (user id),Exim's own] | |
13033 | cindex:[Exim user] | |
13034 | This option changes the uid under which Exim runs when it gives up root | |
13035 | privilege. The default value is compiled into the binary. Ownership of the run | |
13036 | time configuration file and the use of the %-C% and %-D% command line options | |
13037 | is checked against the values in the binary, not what is set here. | |
13038 | ||
13039 | Unless it consists entirely of digits, the string is looked up using | |
13040 | 'getpwnam()', and failure causes a configuration error. If %exim_group% is | |
13041 | not also supplied, the gid is taken from the result of 'getpwnam()' if it is | |
13042 | used. See chapter <<CHAPsecurity>> for a discussion of security issues. | |
13043 | ||
13044 | ||
13045 | oindex:[%extra_local_interfaces%] | |
13046 | `..'= | |
13047 | %extra_local_interfaces%, Use: 'main', Type: 'string list', Default: 'unset' | |
13048 | === | |
13049 | ||
13050 | This option defines network interfaces that are to be considered local when | |
13051 | routing, but which are not used for listening by the daemon. See section | |
13052 | <<SECTreclocipadd>> for details. | |
13053 | ||
13054 | ||
13055 | oindex:[%extract_addresses_remove_arguments%] | |
13056 | `..'= | |
13057 | %extract_addresses_remove_ ~arguments%, Use: 'main', Type: 'boolean', Default: 'true' | |
13058 | === | |
13059 | ||
13060 | cindex:[%-t% option] | |
13061 | cindex:[command line,addresses with %-t%] | |
13062 | cindex:[Sendmail compatibility,%-t% option] | |
13063 | According to some Sendmail documentation (Sun, IRIX, HP-UX), if any addresses | |
13064 | are present on the command line when the %-t% option is used to build an | |
13065 | envelope from a message's 'To:', 'Cc:' and 'Bcc:' headers, the command line | |
13066 | addresses are removed from the recipients list. This is also how Smail behaves. | |
13067 | However, other Sendmail documentation (the O'Reilly book) states that command | |
13068 | line addresses are added to those obtained from the header lines. When | |
13069 | %extract_addresses_remove_arguments% is true (the default), Exim subtracts | |
13070 | argument headers. If it is set false, Exim adds rather than removes argument | |
13071 | addresses. | |
13072 | ||
13073 | ||
13074 | oindex:[%finduser_retries%] | |
13075 | `..'= | |
13076 | %finduser_retries%, Use: 'main', Type: 'integer', Default: '0' | |
13077 | === | |
13078 | ||
13079 | cindex:[NIS, looking up users; retrying] | |
13080 | On systems running NIS or other schemes in which user and group information is | |
13081 | distributed from a remote system, there can be times when 'getpwnam()' and | |
13082 | related functions fail, even when given valid data, because things time out. | |
13083 | Unfortunately these failures cannot be distinguished from genuine ``not found'' | |
13084 | errors. If %finduser_retries% is set greater than zero, Exim will try that | |
13085 | many extra times to find a user or a group, waiting for one second between | |
13086 | retries. | |
13087 | ||
13088 | cindex:[_/etc/passwd_, multiple reading of] | |
13089 | You should not set this option greater than zero if your user information is in | |
13090 | a traditional _/etc/passwd_ file, because it will cause Exim needlessly to | |
13091 | search the file multiple times for non-existent users, and also cause delay. | |
13092 | ||
13093 | ||
13094 | ||
13095 | oindex:[%freeze_tell%] | |
13096 | `..'= | |
13097 | %freeze_tell%, Use: 'main', "Type: 'string list, comma separated'", Default: 'unset' | |
13098 | === | |
13099 | ||
13100 | cindex:[freezing messages,sending a message when freezing] | |
13101 | On encountering certain errors, or when configured to do so in a system filter, | |
13102 | or in an ACL, | |
13103 | Exim freezes a message. This means that no further delivery attempts take place | |
13104 | until an administrator (or the %auto_thaw% feature) thaws the message. If | |
13105 | %freeze_tell% is set, Exim generates a warning message whenever it freezes | |
13106 | something, unless the message it is freezing is a | |
13107 | locally-generated | |
13108 | bounce message. (Without this exception there is the possibility of looping.) | |
13109 | The warning message is sent to the addresses supplied as the comma-separated | |
13110 | value of this option. If several of the message's addresses cause freezing, | |
13111 | only a single message is sent. | |
13112 | If the freezing was automatic, the reason(s) for freezing can be found in the | |
13113 | message log. If you configure freezing in a filter or ACL, you must arrange for | |
13114 | any logging that you require. | |
13115 | ||
13116 | ||
13117 | oindex:[%gecos_name%] | |
13118 | `..'= | |
13119 | %gecos_name%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
13120 | === | |
13121 | ||
13122 | cindex:[HP-UX] | |
13123 | cindex:[``gecos'' field, parsing] | |
13124 | Some operating systems, notably HP-UX, use the ``gecos'' field in the system | |
13125 | password file to hold other information in addition to users' real names. Exim | |
13126 | looks up this field for use when it is creating 'Sender:' or 'From:' headers. | |
13127 | If either %gecos_pattern% or %gecos_name% are unset, the contents of the | |
13128 | field are used unchanged, except that, if an ampersand is encountered, it is | |
13129 | replaced by the user's login name with the first character forced to | |
13130 | upper case, since this is a convention that is observed on many systems. | |
13131 | ||
13132 | When these options are set, %gecos_pattern% is treated as a regular expression | |
13133 | that is to be applied to the field (again with & replaced by the login name), | |
13134 | and if it matches, %gecos_name% is expanded and used as the user's name. | |
13135 | ||
13136 | cindex:[numerical variables ($1$ $2$ etc),in %gecos_name%] | |
13137 | Numeric variables such as $1$, $2$, etc. can be used in the expansion to | |
13138 | pick up sub-fields that were matched by the pattern. In HP-UX, where the user's | |
13139 | name terminates at the first comma, the following can be used: | |
13140 | ||
13141 | gecos_pattern = ([^,]*) | |
13142 | gecos_name = $1 | |
13143 | ||
13144 | ||
13145 | ||
13146 | oindex:[%gecos_pattern%] | |
13147 | `..'= | |
13148 | %gecos_pattern%, Use: 'main', Type: 'string', Default: 'unset' | |
13149 | === | |
13150 | ||
13151 | See %gecos_name% above. | |
13152 | ||
13153 | ||
13154 | oindex:[%headers_charset%] | |
13155 | `..'= | |
13156 | %headers_charset%, Use: 'main', Type: 'string', Default: 'see below' | |
13157 | === | |
13158 | ||
13159 | This option sets a default character set for translating from encoded MIME | |
13160 | ``words'' in header lines, when referenced by an $h_xxx$ expansion item. The | |
13161 | default is the value of HEADERS_CHARSET in _Local/Makefile_. The | |
13162 | ultimate default is ISO-8859-1. For more details see the description of header | |
13163 | insertions in section <<SECTexpansionitems>>. | |
13164 | ||
13165 | ||
13166 | ||
13167 | oindex:[%header_maxsize%] | |
13168 | `..'= | |
13169 | %header_maxsize%, Use: 'main', Type: 'integer', Default: 'see below' | |
13170 | === | |
13171 | ||
13172 | cindex:[header section,maximum size of] | |
13173 | cindex:[limit,size of message header section] | |
13174 | This option controls the overall maximum size of a message's header | |
13175 | section. The default is the value of HEADER_MAXSIZE in | |
13176 | _Local/Makefile_; the default for that is 1M. Messages with larger header | |
13177 | sections are rejected. | |
13178 | ||
13179 | ||
13180 | oindex:[%header_line_maxsize%] | |
13181 | `..'= | |
13182 | %header_line_maxsize%, Use: 'main', Type: 'integer', Default: '0' | |
13183 | === | |
13184 | ||
13185 | cindex:[header lines,maximum size of] | |
13186 | cindex:[limit,size of one header line] | |
13187 | This option limits the length of any individual header line in a message, after | |
13188 | all the continuations have been joined together. Messages with individual | |
13189 | header lines that are longer than the limit are rejected. The default value of | |
13190 | zero means ``no limit''. | |
13191 | ||
13192 | ||
13193 | ||
13194 | ||
13195 | oindex:[%helo_accept_junk_hosts%] | |
13196 | `..'= | |
13197 | %helo_accept_junk_hosts%, Use: 'main', Type: 'host list'!!, Default: 'unset' | |
13198 | === | |
13199 | ||
13200 | cindex:[HELO,accepting junk data] | |
13201 | cindex:[EHLO,accepting junk data] | |
13202 | Exim checks the syntax of HELO and EHLO commands for incoming SMTP | |
13203 | mail, and gives an error response for invalid data. Unfortunately, there are | |
13204 | some SMTP clients that send syntactic junk. They can be accommodated by setting | |
13205 | this option. Note that this is a syntax check only. See %helo_verify_hosts% | |
13206 | if you want to do semantic checking. | |
13207 | See also %helo_allow_chars% for a way of extending the permitted character | |
13208 | set. | |
13209 | ||
13210 | ||
13211 | oindex:[%helo_allow_chars%] | |
13212 | `..'= | |
13213 | %helo_allow_chars%, Use: 'main', Type: 'string', Default: 'unset' | |
13214 | === | |
13215 | ||
13216 | cindex:[HELO,underscores in] | |
13217 | cindex:[EHLO,underscores in] | |
13218 | cindex:[underscore in EHLO/HELO] | |
13219 | This option can be set to a string of rogue characters that are permitted in | |
13220 | all EHLO and HELO names in addition to the standard letters, digits, | |
13221 | hyphens, and dots. If you really must allow underscores, you can set | |
13222 | ||
13223 | helo_allow_chars = _ | |
13224 | ||
13225 | Note that the value is one string, not a list. | |
13226 | ||
13227 | ||
13228 | oindex:[%helo_lookup_domains%] | |
13229 | `..'= | |
13230 | %helo_lookup_domains%, Use: 'main', Type: 'domain list'!!, Default: `@:@[]` | |
13231 | === | |
13232 | ||
13233 | cindex:[HELO,forcing reverse lookup] | |
13234 | cindex:[EHLO,forcing reverse lookup] | |
13235 | If the domain given by a client in a HELO or EHLO command matches this | |
13236 | list, a reverse lookup is done in order to establish the host's true name. The | |
13237 | default forces a lookup if the client host gives the server's name or any of | |
13238 | its IP addresses (in brackets), something that broken clients have been seen to | |
13239 | do. | |
13240 | ||
13241 | ||
13242 | oindex:[%helo_try_verify_hosts%] | |
13243 | `..'= | |
13244 | %helo_try_verify_hosts%, Use: 'main', Type: 'host list'!!, Default: 'unset' | |
13245 | === | |
13246 | ||
068aaea8 | 13247 | [revisionflag="changed"] |
168e428f PH |
13248 | cindex:[HELO verifying, optional] |
13249 | cindex:[EHLO verifying, optional] | |
068aaea8 PH |
13250 | By default, Exim just checks the syntax of HELO and EHLO commands (see |
13251 | %helo_accept_junk_hosts% and %helo_allow_chars%). However, some sites like to | |
13252 | do more extensive checking of the data supplied by these commands. The ACL | |
13253 | condition `verify = helo` is provided to make this possible. Formerly, it was | |
13254 | necessary also to set this option (%helo_try_verify_hosts%) to force the check | |
13255 | to occur. From release 4.53 onwards, this is no longer necessary. If the check | |
13256 | has not been done before `verify = helo` is encountered, it is done at that | |
13257 | time. Consequently, this option is obsolete. Its specification is retained here | |
13258 | for backwards compatibility. | |
13259 | ||
13260 | [revisionflag="changed"] | |
13261 | When an EHLO or HELO command is received, if the calling host matches | |
13262 | %helo_try_verify_hosts%, Exim checks that the host name given in the HELO or | |
13263 | EHLO command either: | |
168e428f | 13264 | |
068aaea8 | 13265 | - is an IP literal matching the calling address of the host, or |
168e428f PH |
13266 | |
13267 | - cindex:[DNS,reverse lookup] | |
13268 | cindex:[reverse DNS lookup] | |
13269 | matches the host name that Exim obtains by doing a reverse lookup of the | |
13270 | calling host address, or | |
13271 | ||
13272 | - when looked up using 'gethostbyname()' (or 'getipnodebyname()' when | |
13273 | available) yields the calling host address. | |
13274 | ||
13275 | However, the EHLO or HELO command is not rejected if any of the checks | |
13276 | fail. Processing continues, but the result of the check is remembered, and can | |
068aaea8 | 13277 | be detected later in an ACL by the `verify = helo` condition. |
168e428f PH |
13278 | |
13279 | ||
13280 | oindex:[%helo_verify_hosts%] | |
13281 | `..'= | |
13282 | %helo_verify_hosts%, Use: 'main', Type: 'host list'!!, Default: 'unset' | |
13283 | === | |
13284 | ||
068aaea8 | 13285 | [revisionflag="changed"] |
168e428f PH |
13286 | cindex:[HELO verifying, mandatory] |
13287 | cindex:[EHLO verifying, mandatory] | |
068aaea8 PH |
13288 | Like %helo_try_verify_hosts%, this option is obsolete, and retained only for |
13289 | backwards compatibility. For hosts that match this option, Exim checks the host | |
13290 | name given in the HELO or EHLO in the same way as for %helo_try_verify_hosts%. | |
13291 | If the check fails, the HELO or EHLO command is rejected with a 550 error, and | |
13292 | entries are written to the main and reject logs. If a MAIL command is received | |
13293 | before EHLO or HELO, it is rejected with a 503 error. | |
168e428f PH |
13294 | |
13295 | ||
13296 | oindex:[%hold_domains%] | |
13297 | `..'= | |
13298 | %hold_domains%, Use: 'main', Type: 'domain list'!!, Default: 'unset' | |
13299 | === | |
13300 | ||
13301 | cindex:[domain,delaying delivery] | |
13302 | cindex:[delivery,delaying certain domains] | |
13303 | This option allows mail for particular domains to be held on the queue | |
13304 | manually. The option is overridden if a message delivery is forced with the | |
13305 | %-M%, %-qf%, %-Rf% or %-Sf% options, and also while testing or verifying | |
13306 | addresses using %-bt% or %-bv%. Otherwise, if a domain matches an item in | |
13307 | %hold_domains%, no routing or delivery for that address is done, and it is | |
13308 | deferred every time the message is looked at. | |
13309 | ||
13310 | This option is intended as a temporary operational measure for delaying the | |
13311 | delivery of mail while some problem is being sorted out, or some new | |
13312 | configuration tested. If you just want to delay the processing of some | |
13313 | domains until a queue run occurs, you should use %queue_domains% or | |
13314 | %queue_smtp_domains%, not %hold_domains%. | |
13315 | ||
13316 | A setting of %hold_domains% does not override Exim's code for removing | |
13317 | messages from the queue if they have been there longer than the longest retry | |
13318 | time in any retry rule. If you want to hold messages for longer than the normal | |
13319 | retry times, insert a dummy retry rule with a long retry time. | |
13320 | ||
13321 | ||
13322 | oindex:[%host_lookup%] | |
13323 | `..'= | |
13324 | %host_lookup%, Use: 'main', Type: 'host list'!!, Default: 'unset' | |
13325 | === | |
13326 | ||
13327 | cindex:[host name lookup, forcing] | |
13328 | Exim does not look up the name of a calling host from its IP address unless it | |
13329 | is required to compare against some host list, or the host matches | |
13330 | %helo_try_verify_hosts% or %helo_verify_hosts%, or the host matches this | |
13331 | option (which normally contains IP addresses rather than host names). The | |
13332 | default configuration file contains | |
13333 | ||
13334 | host_lookup = * | |
13335 | ||
13336 | which causes a lookup to happen for all hosts. If the expense of these lookups | |
13337 | is felt to be too great, the setting can be changed or removed. | |
13338 | ||
13339 | After a successful reverse lookup, Exim does a forward lookup on the name it | |
13340 | has obtained, to verify that it yields the IP address that it started with. If | |
13341 | this check fails, Exim behaves as if the name lookup failed. | |
13342 | ||
068aaea8 PH |
13343 | cindex:[$host_lookup_failed$] |
13344 | cindex:[$sender_host_name$] | |
168e428f PH |
13345 | After any kind of failure, the host name (in $sender_host_name$) remains |
13346 | unset, and $host_lookup_failed$ is set to the string ``1''. See also | |
13347 | %dns_again_means_nonexist%, %helo_lookup_domains%, and `verify = | |
13348 | reverse_host_lookup` in ACLs. | |
13349 | ||
13350 | ||
13351 | oindex:[%host_lookup_order%] | |
13352 | `..'= | |
13353 | %host_lookup_order%, Use: 'main', Type: 'string list', Default: `bydns:byaddr` | |
13354 | === | |
13355 | ||
13356 | This option specifies the order of different lookup methods when Exim is trying | |
13357 | to find a host name from an IP address. The default is to do a DNS lookup | |
13358 | first, and then to try a local lookup (using 'gethostbyaddr()' or equivalent) | |
13359 | if that fails. You can change the order of these lookups, or omit one entirely, | |
13360 | if you want. | |
13361 | ||
13362 | *Warning*: the ``byaddr'' method does not always yield aliases when there are | |
13363 | multiple PTR records in the DNS and the IP address is not listed in | |
13364 | _/etc/hosts_. Different operating systems give different results in this | |
13365 | case. That is why the default tries a DNS lookup first. | |
13366 | ||
13367 | ||
13368 | ||
13369 | oindex:[%host_reject_connection%] | |
13370 | `..'= | |
13371 | %host_reject_connection%, Use: 'main', Type: 'host list'!!, Default: 'unset' | |
13372 | === | |
13373 | ||
13374 | cindex:[host,rejecting connections from] | |
13375 | If this option is set, incoming SMTP calls from the hosts listed are rejected | |
13376 | as soon as the connection is made. | |
13377 | This option is obsolete, and retained only for backward compatibility, because | |
13378 | nowadays the ACL specified by %acl_smtp_connect% can also reject incoming | |
13379 | connections immediately. | |
13380 | ||
13381 | The ability to give an immediate rejection (either by this option or using an | |
13382 | ACL) is provided for use in unusual cases. Many hosts will just try again, | |
13383 | sometimes without much delay. Normally, it is better to use an ACL to reject | |
13384 | incoming messages at a later stage, such as after RCPT commands. See | |
13385 | chapter <<CHAPACL>>. | |
13386 | ||
13387 | ||
13388 | oindex:[%hosts_connection_nolog%] | |
13389 | `..'= | |
13390 | %hosts_connection_nolog%, Use: 'main', Type: 'host list'!!, Default: 'unset' | |
13391 | === | |
13392 | ||
13393 | cindex:[host,not logging connections from] | |
13394 | This option defines a list of hosts for which connection logging does not | |
13395 | happen, even though the %smtp_connection% log selector is set. For example, | |
13396 | you might want not to log SMTP connections from local processes, or from | |
13397 | 127.0.0.1, or from your local LAN. This option is consulted in the main loop of | |
13398 | the daemon; you should therefore strive to restrict its value to a short inline | |
13399 | list of IP addresses and networks. To disable logging SMTP connections from | |
13400 | local processes, you must create a host list with an empty item. For example: | |
13401 | ||
13402 | hosts_connection_nolog = : | |
13403 | ||
13404 | If the %smtp_connection% log selector is not set, this option has no effect. | |
13405 | ||
13406 | ||
13407 | ||
13408 | oindex:[%hosts_treat_as_local%] | |
13409 | `..'= | |
13410 | %hosts_treat_as_local%, Use: 'main', Type: 'domain list'!!, Default: 'unset' | |
13411 | === | |
13412 | ||
13413 | cindex:[local host,domains treated as] | |
13414 | cindex:[host,treated as local] | |
13415 | If this option is set, any host names that match the domain list are treated as | |
13416 | if they were the local host when Exim is scanning host lists obtained from MX | |
13417 | records | |
13418 | or other sources. Note that the value of this option is a domain list, not a | |
13419 | host list, because it is always used to check host names, not IP addresses. | |
13420 | ||
13421 | This option also applies when Exim is matching the special items | |
13422 | `@mx_any`, `@mx_primary`, and `@mx_secondary` in a domain list (see | |
13423 | section <<SECTdomainlist>>), and when checking the %hosts% option in the ^smtp^ | |
13424 | transport for the local host (see the %allow_localhost% option in that | |
13425 | transport). | |
13426 | See also %local_interfaces%, %extra_local_interfaces%, and chapter | |
13427 | <<CHAPinterfaces>>, which contains a discussion about local network interfaces | |
13428 | and recognising the local host. | |
13429 | ||
13430 | ||
13431 | oindex:[%ignore_bounce_errors_after%] | |
13432 | `..'= | |
13433 | %ignore_bounce_errors_after%, Use: 'main', Type: 'time', Default: '10w' | |
13434 | === | |
13435 | ||
13436 | cindex:[bounce message,discarding] | |
13437 | cindex:[discarding bounce message] | |
13438 | This option affects the processing of bounce messages that cannot be delivered, | |
13439 | that is, those that suffer a permanent delivery failure. (Bounce messages that | |
13440 | suffer temporary delivery failures are of course retried in the usual way.) | |
13441 | ||
13442 | After a permanent delivery failure, bounce messages are frozen, | |
13443 | because there is no sender to whom they can be returned. When a frozen bounce | |
13444 | message has been on the queue for more than the given time, it is unfrozen at | |
13445 | the next queue run, and a further delivery is attempted. If delivery fails | |
13446 | again, the bounce message is discarded. This makes it possible to keep failed | |
13447 | bounce messages around for a shorter time than the normal maximum retry time | |
13448 | for frozen messages. For example, | |
13449 | ||
13450 | ignore_bounce_errors_after = 12h | |
13451 | ||
13452 | retries failed bounce message deliveries after 12 hours, discarding any further | |
13453 | failures. If the value of this option is set to a zero time period, bounce | |
13454 | failures are discarded immediately. Setting a very long time (as in the default | |
13455 | value) has the effect of disabling this option. For ways of automatically | |
13456 | dealing with other kinds of frozen message, see %auto_thaw% and | |
13457 | %timeout_frozen_after%. | |
13458 | ||
13459 | ||
13460 | oindex:[%ignore_fromline_hosts%] | |
13461 | `..'= | |
13462 | %ignore_fromline_hosts%, Use: 'main', Type: 'host list'!!, Default: 'unset' | |
13463 | === | |
13464 | ||
13465 | cindex:[``From'' line] | |
13466 | cindex:[UUCP,``From'' line] | |
13467 | Some broken SMTP clients insist on sending a UUCP-like ``From'' line before the | |
13468 | headers of a message. By default this is treated as the start of the message's | |
13469 | body, which means that any following headers are not recognized as such. Exim | |
13470 | can be made to ignore it by setting %ignore_fromline_hosts% to match those | |
13471 | hosts that insist on sending it. If the sender is actually a local process | |
13472 | rather than a remote host, and is using %-bs% to inject the messages, | |
13473 | %ignore_fromline_local% must be set to achieve this effect. | |
13474 | ||
13475 | ||
13476 | oindex:[%ignore_fromline_local%] | |
13477 | `..'= | |
13478 | %ignore_fromline_local%, Use: 'main', Type: 'boolean', Default: 'false' | |
13479 | === | |
13480 | ||
13481 | See %ignore_fromline_hosts% above. | |
13482 | ||
13483 | ||
13484 | oindex:[%keep_malformed%] | |
13485 | `..'= | |
13486 | %keep_malformed%, Use: 'main', Type: 'time', Default: '4d' | |
13487 | === | |
13488 | ||
13489 | This option specifies the length of time to keep messages whose spool files | |
13490 | have been corrupted in some way. This should, of course, never happen. At the | |
13491 | next attempt to deliver such a message, it gets removed. The incident is | |
13492 | logged. | |
13493 | ||
13494 | ||
13495 | oindex:[%ldap_default_servers%] | |
13496 | `..'= | |
13497 | %ldap_default_servers%, Use: 'main', Type: 'string list', Default: 'unset' | |
13498 | === | |
13499 | ||
13500 | cindex:[LDAP,default servers] | |
13501 | This option provides a list of LDAP servers which are tried in turn when an | |
13502 | LDAP query does not contain a server. See section <<SECTforldaque>> for details | |
13503 | of LDAP queries. This option is available only when Exim has been built with | |
13504 | LDAP support. | |
13505 | ||
13506 | ||
13507 | oindex:[%ldap_version%] | |
13508 | `..'= | |
13509 | %ldap_version%, Use: 'main', Type: 'integer', Default: 'unset' | |
13510 | === | |
13511 | ||
13512 | cindex:[LDAP protocol version, forcing] | |
13513 | This option can be used to force Exim to set a specific protocol version for | |
13514 | LDAP. If it option is unset, it is shown by the %-bP% command line option as | |
13515 | -1. When this is the case, the default is 3 if LDAP_VERSION3 is defined in | |
13516 | the LDAP headers; otherwise it is 2. This option is available only when Exim | |
13517 | has been built with LDAP support. | |
13518 | ||
13519 | ||
13520 | ||
13521 | oindex:[%local_from_check%] | |
13522 | `..'= | |
13523 | %local_from_check%, Use: 'main', Type: 'boolean', Default: 'true' | |
13524 | === | |
13525 | ||
13526 | cindex:['Sender:' header line,disabling addition of] | |
13527 | cindex:['From:' header line,disabling checking of] | |
13528 | When a message is submitted locally (that is, not over a TCP/IP connection) by | |
13529 | an untrusted user, Exim removes any existing 'Sender:' header line, and checks | |
13530 | that the 'From:' header line matches the login of the calling user and the | |
13531 | domain specified by %qualify_domain%. | |
13532 | ||
13533 | *Note*: An unqualified address (no domain) in the 'From:' header in a | |
13534 | locally submitted message is automatically qualified by Exim, unless the | |
13535 | %-bnq% command line option is used. | |
13536 | ||
13537 | You can use %local_from_prefix% and %local_from_suffix% to permit affixes | |
13538 | on the local part. If the 'From:' header line does not match, Exim adds a | |
13539 | 'Sender:' header with an address constructed from the calling user's login and | |
13540 | the default qualify domain. | |
13541 | ||
13542 | If %local_from_check% is set false, the 'From:' header check is disabled, | |
13543 | and no 'Sender:' header is ever added. If, in addition, you want to retain | |
13544 | 'Sender:' header lines supplied by untrusted users, you must also set | |
13545 | %local_sender_retain% to be true. | |
13546 | ||
13547 | cindex:[envelope sender] | |
13548 | These options affect only the header lines in the message. The envelope sender | |
13549 | is still forced to be the login id at the qualify domain unless | |
13550 | %untrusted_set_sender% permits the user to supply an envelope sender. | |
13551 | ||
13552 | For messages received over TCP/IP, an ACL can specify ``submission mode'' to | |
13553 | request similar header line checking. See section <<SECTthesenhea>>, which has | |
13554 | more details about 'Sender:' processing. | |
13555 | ||
13556 | ||
13557 | ||
13558 | ||
13559 | oindex:[%local_from_prefix%] | |
13560 | `..'= | |
13561 | %local_from_prefix%, Use: 'main', Type: 'string', Default: 'unset' | |
13562 | === | |
13563 | ||
13564 | When Exim checks the 'From:' header line of locally submitted messages for | |
13565 | matching the login id (see %local_from_check% above), it can be configured to | |
13566 | ignore certain prefixes and suffixes in the local part of the address. This is | |
13567 | done by setting %local_from_prefix% and/or %local_from_suffix% to | |
13568 | appropriate lists, in the same form as the %local_part_prefix% and | |
13569 | %local_part_suffix% router options (see chapter <<CHAProutergeneric>>). For | |
13570 | example, if | |
13571 | ||
13572 | local_from_prefix = *- | |
13573 | ||
13574 | is set, a 'From:' line containing | |
13575 | ||
13576 | From: anything-user@your.domain.example | |
13577 | ||
13578 | will not cause a 'Sender:' header to be added if 'user@your.domain.example' | |
13579 | matches the actual sender address that is constructed from the login name and | |
13580 | qualify domain. | |
13581 | ||
13582 | ||
13583 | oindex:[%local_from_suffix%] | |
13584 | `..'= | |
13585 | %local_from_suffix%, Use: 'main', Type: 'string', Default: 'unset' | |
13586 | === | |
13587 | ||
13588 | See %local_from_prefix% above. | |
13589 | ||
13590 | ||
13591 | oindex:[%local_interfaces%] | |
13592 | `..'= | |
13593 | %local_interfaces%, Use: 'main', Type: 'string list', Default: 'see below' | |
13594 | === | |
13595 | ||
13596 | This option controls which network interfaces are used by the daemon for | |
13597 | listening; they are also used to identify the local host when routing. Chapter | |
13598 | <<CHAPinterfaces>> contains a full description of this option and the related | |
13599 | options | |
13600 | ||
13601 | %daemon_smtp_ports%, %extra_local_interfaces%, %hosts_treat_as_local%, | |
13602 | and %tls_on_connect_ports%. | |
13603 | ||
13604 | The default value for %local_interfaces% is | |
13605 | ||
13606 | local_interfaces = 0.0.0.0 | |
13607 | ||
13608 | when Exim is built without IPv6 support; otherwise it is | |
13609 | ||
13610 | local_interfaces = <; ::0 ; 0.0.0.0 | |
13611 | ||
13612 | ||
13613 | ||
13614 | oindex:[%local_scan_timeout%] | |
13615 | `..'= | |
13616 | %local_scan_timeout%, Use: 'main', Type: 'time', Default: '5m' | |
13617 | === | |
13618 | ||
13619 | cindex:[timeout,for 'local_scan()' function] | |
13620 | cindex:['local_scan()' function,timeout] | |
13621 | This timeout applies to the 'local_scan()' function (see chapter | |
13622 | <<CHAPlocalscan>>). Zero means ``no timeout''. If the timeout is exceeded, the | |
13623 | incoming message is rejected with a temporary error if it is an SMTP message. | |
13624 | For a non-SMTP message, the message is dropped and Exim ends with a non-zero | |
13625 | code. The incident is logged on the main and reject logs. | |
13626 | ||
13627 | ||
13628 | ||
13629 | oindex:[%local_sender_retain%] | |
13630 | `..'= | |
13631 | %local_sender_retain%, Use: 'main', Type: 'boolean', Default: 'false' | |
13632 | === | |
13633 | ||
13634 | cindex:['Sender:' header line,retaining from local submission] | |
13635 | When a message is submitted locally (that is, not over a TCP/IP connection) by | |
13636 | an untrusted user, Exim removes any existing 'Sender:' header line. If you | |
13637 | do not want this to happen, you must set %local_sender_retain%, and you must | |
13638 | also set %local_from_check% to be false (Exim will complain if you do not). | |
068aaea8 PH |
13639 | See also the ACL modifier `control = suppress_local_fixups`. Section |
13640 | <<SECTthesenhea>> has more details about 'Sender:' processing. | |
168e428f PH |
13641 | |
13642 | ||
13643 | ||
13644 | ||
13645 | oindex:[%localhost_number%] | |
13646 | `..'= | |
13647 | %localhost_number%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
13648 | === | |
13649 | ||
13650 | cindex:[host,locally unique number for] | |
13651 | cindex:[message ids, with multiple hosts] | |
068aaea8 | 13652 | cindex:[$localhost_number$] |
168e428f PH |
13653 | Exim's message ids are normally unique only within the local host. If |
13654 | uniqueness among a set of hosts is required, each host must set a different | |
13655 | value for the %localhost_number% option. The string is expanded immediately | |
13656 | after reading the configuration file (so that a number can be computed from the | |
13657 | host name, for example) and the result of the expansion must be a number in the | |
13658 | range 0--16 (or 0--10 on operating systems with case-insensitive file systems). | |
13659 | This is available in subsequent string expansions via the variable | |
13660 | $localhost_number$. When %localhost_number is set%, the final two | |
13661 | characters of the message id, instead of just being a fractional part of the | |
13662 | time, are computed from the time and the local host number as described in | |
13663 | section <<SECTmessiden>>. | |
13664 | ||
13665 | ||
13666 | ||
13667 | oindex:[%log_file_path%] | |
13668 | `..'= | |
13669 | %log_file_path%, Use: 'main', Type: 'string list'!!, Default: 'set at compile time' | |
13670 | === | |
13671 | ||
13672 | cindex:[log,file path for] | |
13673 | This option sets the path which is used to determine the names of Exim's log | |
13674 | files, or indicates that logging is to be to syslog, or both. It is expanded | |
13675 | when Exim is entered, so it can, for example, contain a reference to the host | |
13676 | name. If no specific path is set for the log files at compile or run time, they | |
13677 | are written in a sub-directory called _log_ in Exim's spool directory. | |
13678 | Chapter <<CHAPlog>> contains further details about Exim's logging, and section | |
13679 | <<SECTwhelogwri>> describes how the contents of %log_file_path% are used. If | |
13680 | this string is fixed at your installation (contains no expansion variables) it | |
13681 | is recommended that you do not set this option in the configuration file, but | |
13682 | instead supply the path using LOG_FILE_PATH in _Local/Makefile_ so that | |
13683 | it is available to Exim for logging errors detected early on -- in particular, | |
13684 | failure to read the configuration file. | |
13685 | ||
13686 | ||
13687 | oindex:[%log_selector%] | |
13688 | `..'= | |
13689 | %log_selector%, Use: 'main', Type: 'string', Default: 'unset' | |
13690 | === | |
13691 | ||
13692 | cindex:[log,selectors] | |
13693 | This option can be used to reduce or increase the number of things that Exim | |
13694 | writes to its log files. Its argument is made up of names preceded by plus or | |
13695 | minus characters. For example: | |
13696 | ||
13697 | log_selector = +arguments -retry_defer | |
13698 | ||
13699 | A list of possible names and what they control is given in the chapter on | |
13700 | logging, in section <<SECTlogselector>>. | |
13701 | ||
13702 | ||
13703 | oindex:[%log_timezone%] | |
13704 | `..'= | |
13705 | %log_timezone%, Use: 'main', Type: 'boolean', Default: 'false' | |
13706 | === | |
13707 | ||
13708 | cindex:[log,timezone for entries] | |
068aaea8 PH |
13709 | cindex:[$tod_log$] |
13710 | cindex:[$tod_zone$] | |
168e428f PH |
13711 | By default, the timestamps on log lines are in local time without the |
13712 | timezone. This means that if your timezone changes twice a year, the timestamps | |
13713 | in log lines are ambiguous for an hour when the clocks go back. One way of | |
13714 | avoiding this problem is to set the timezone to UTC. An alternative is to set | |
13715 | %log_timezone% true. This turns on the addition of the timezone offset to | |
13716 | timestamps in log lines. Turning on this option can add quite a lot to the size | |
13717 | of log files because each line is extended by 6 characters. Note that the | |
13718 | $tod_log$ variable contains the log timestamp without the zone, but there is | |
13719 | another variable called $tod_zone$ that contains just the timezone offset. | |
13720 | ||
13721 | ||
13722 | oindex:[%lookup_open_max%] | |
13723 | `..'= | |
13724 | %lookup_open_max%, Use: 'main', Type: 'integer', Default: '25' | |
13725 | === | |
13726 | ||
13727 | cindex:[too many open files] | |
13728 | cindex:[open files, too many] | |
13729 | cindex:[file,too many open] | |
13730 | cindex:[lookup,maximum open files] | |
13731 | cindex:[limit,open files for lookups] | |
13732 | This option limits the number of simultaneously open files for single-key | |
13733 | lookups that use regular files (that is, ^lsearch^, ^dbm^, and ^cdb^). Exim | |
13734 | normally keeps these files open during routing, because often the same file is | |
13735 | required several times. If the limit is reached, Exim closes the least recently | |
13736 | used file. Note that if you are using the 'ndbm' library, it actually opens | |
13737 | two files for each logical DBM database, though it still counts as one for the | |
13738 | purposes of %lookup_open_max%. If you are getting ``too many open files'' | |
13739 | errors with NDBM, you need to reduce the value of %lookup_open_max%. | |
13740 | ||
13741 | ||
13742 | oindex:[%max_username_length%] | |
13743 | `..'= | |
13744 | %max_username_length%, Use: 'main', Type: 'integer', Default: '0' | |
13745 | === | |
13746 | ||
13747 | cindex:[length of login name] | |
13748 | cindex:[user name,maximum length] | |
13749 | cindex:[limit,user name length] | |
13750 | Some operating systems are broken in that they truncate long arguments to | |
13751 | 'getpwnam()' to eight characters, instead of returning ``no such user''. If | |
13752 | this option is set greater than zero, any attempt to call 'getpwnam()' with | |
13753 | an argument that is longer behaves as if 'getpwnam()' failed. | |
13754 | ||
13755 | ||
13756 | ||
13757 | oindex:[%message_body_visible%] | |
13758 | `..'= | |
13759 | %message_body_visible%, Use: 'main', Type: 'integer', Default: '500' | |
13760 | === | |
13761 | ||
13762 | cindex:[body of message,visible size] | |
13763 | cindex:[message body, visible size] | |
068aaea8 PH |
13764 | cindex:[$message_body$] |
13765 | cindex:[$message_body_end$] | |
168e428f PH |
13766 | This option specifies how much of a message's body is to be included in the |
13767 | $message_body$ and $message_body_end$ expansion variables. | |
13768 | ||
13769 | ||
13770 | oindex:[%message_id_header_domain%] | |
13771 | `..'= | |
13772 | %message_id_header_domain%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
13773 | === | |
13774 | ||
13775 | cindex:['Message-ID:' header line] | |
13776 | If this option is set, the string is expanded and used as the right hand side | |
13777 | (domain) of the 'Message-ID:' header that Exim creates if a | |
13778 | locally-originated incoming message does not have one. ``Locally-originated'' | |
13779 | means ``not received over TCP/IP.'' | |
13780 | Otherwise, the primary host name is used. | |
13781 | Only letters, digits, dot and hyphen are accepted; any other characters are | |
13782 | replaced by hyphens. If the expansion is forced to fail, or if the result is an | |
13783 | empty string, the option is ignored. | |
13784 | ||
13785 | ||
13786 | oindex:[%message_id_header_text%] | |
13787 | `..'= | |
13788 | %message_id_header_text%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
13789 | === | |
13790 | ||
13791 | If this variable is set, the string is expanded and used to augment the text of | |
068aaea8 PH |
13792 | the 'Message-id:' header that Exim creates if a locally-originated incoming |
13793 | message does not have one. The text of this header is required by RFC 2822 to | |
13794 | take the form of an address. By default, Exim uses its internal message id as | |
13795 | the local part, and the primary host name as the domain. If this option is set, | |
13796 | it is expanded, and provided the expansion is not forced to fail, and does not | |
13797 | yield an empty string, the result is inserted into the header immediately | |
13798 | before the @, separated from the internal message id by a dot. Any characters | |
13799 | that are illegal in an address are automatically converted into hyphens. This | |
13800 | means that variables such as $tod_log$ can be used, because the spaces and | |
13801 | colons will become hyphens. | |
168e428f PH |
13802 | |
13803 | ||
13804 | oindex:[%message_logs%] | |
13805 | `..'= | |
13806 | %message_logs%, Use: 'main', Type: 'boolean', Default: 'true' | |
13807 | === | |
13808 | ||
13809 | cindex:[message log, disabling] | |
13810 | cindex:[log,message log; disabling] | |
13811 | If this option is turned off, per-message log files are not created in the | |
13812 | _msglog_ spool sub-directory. This reduces the amount of disk I/O required by | |
13813 | Exim, by reducing the number of files involved in handling a message from a | |
13814 | minimum of four (header spool file, body spool file, delivery journal, and | |
13815 | per-message log) to three. The other major I/O activity is Exim's main log, | |
13816 | which is not affected by this option. | |
13817 | ||
13818 | ||
13819 | oindex:[%message_size_limit%] | |
13820 | `..'= | |
13821 | %message_size_limit%, Use: 'main', Type: 'string'!!, Default: '50M' | |
13822 | === | |
13823 | ||
13824 | cindex:[message,size limit] | |
13825 | cindex:[limit,message size] | |
13826 | cindex:[size of message, limit] | |
13827 | This option limits the maximum size of message that Exim will process. The | |
13828 | value is expanded for each incoming | |
13829 | connection so, for example, it can be made to depend on the IP address of the | |
13830 | remote host for messages arriving via TCP/IP. *Note*: This limit cannot be | |
13831 | made to depend on a message's sender or any other properties of an individual | |
13832 | message, because it has to be advertised in the server's response to EHLO. | |
13833 | String expansion failure causes a temporary error. A value of zero means no | |
13834 | limit, but its use is not recommended. See also %bounce_return_size_limit%. | |
13835 | ||
13836 | Incoming SMTP messages are failed with a 552 error if the limit is | |
13837 | exceeded; locally-generated messages either get a stderr message or a delivery | |
13838 | failure message to the sender, depending on the %-oe% setting. Rejection of an | |
13839 | oversized message is logged in both the main and the reject logs. See also the | |
13840 | generic transport option %message_size_limit%, which limits the size of | |
13841 | message that an individual transport can process. | |
13842 | ||
13843 | ||
13844 | oindex:[%move_frozen_messages%] | |
13845 | `..'= | |
13846 | %move_frozen_messages%, Use: 'main', Type: 'boolean', Default: 'false' | |
13847 | === | |
13848 | ||
13849 | cindex:[frozen messages,moving] | |
13850 | This option, which is available only if Exim has been built with the setting | |
13851 | ||
13852 | SUPPORT_MOVE_FROZEN_MESSAGES=yes | |
13853 | ||
13854 | in _Local/Makefile_, causes frozen messages and their message logs to be | |
13855 | moved from the _input_ and _msglog_ directories on the spool to _Finput_ | |
13856 | and _Fmsglog_, respectively. There is currently no support in Exim or the | |
13857 | standard utilities for handling such moved messages, and they do not show up in | |
13858 | lists generated by %-bp% or by the Exim monitor. | |
13859 | ||
13860 | ||
13861 | oindex:[%mua_wrapper%] | |
13862 | `..'= | |
13863 | %mua_wrapper%, Use: 'main', Type: 'boolean', Default: 'false' | |
13864 | === | |
13865 | ||
13866 | Setting this option true causes Exim to run in a very restrictive mode in which | |
13867 | it passes messages synchronously to a smart host. Chapter <<CHAPnonqueueing>> | |
13868 | contains a full description of this facility. | |
13869 | ||
13870 | ||
13871 | ||
13872 | oindex:[%mysql_servers%] | |
13873 | `..'= | |
13874 | %mysql_servers%, Use: 'main', Type: 'string list', Default: 'unset' | |
13875 | === | |
13876 | ||
13877 | cindex:[MySQL,server list] | |
13878 | This option provides a list of MySQL servers and associated connection data, to | |
13879 | be used in conjunction with ^mysql^ lookups (see section <<SECTsql>>). The | |
13880 | option is available only if Exim has been built with MySQL support. | |
13881 | ||
13882 | ||
13883 | oindex:[%never_users%] | |
13884 | `..'= | |
068aaea8 | 13885 | %never_users%, Use: 'main', Type: 'string list'!!, Default: 'unset' |
168e428f PH |
13886 | === |
13887 | ||
068aaea8 PH |
13888 | [revisionflag="changed"] |
13889 | This option is expanded just once, at the start of Exim's processing. Local | |
13890 | message deliveries are normally run in processes that are setuid to the | |
168e428f PH |
13891 | recipient, and remote deliveries are normally run under Exim's own uid and gid. |
13892 | It is usually desirable to prevent any deliveries from running as root, as a | |
13893 | safety precaution. | |
13894 | ||
13895 | When Exim is built, an option called FIXED_NEVER_USERS can be set to a | |
13896 | list of users that must not be used for local deliveries. This list is fixed in | |
13897 | the binary and cannot be overridden by the configuration file. By default, it | |
13898 | contains just the single user name ``root''. The %never_users% runtime option | |
13899 | can be used to add more users to the fixed list. | |
13900 | ||
13901 | If a message is to be delivered as one of the users on the fixed list or the | |
13902 | %never_users% list, an error occurs, and delivery is deferred. A common | |
13903 | example is | |
13904 | ||
13905 | never_users = root:daemon:bin | |
13906 | ||
13907 | Including root is redundant if it is also on the fixed list, but it does no | |
13908 | harm. This option overrides the %pipe_as_creator% option of the ^pipe^ | |
13909 | transport driver. | |
13910 | ||
13911 | ||
13912 | oindex:[%oracle_servers%] | |
13913 | `..'= | |
13914 | %oracle_servers%, Use: 'main', Type: 'string list', Default: 'unset' | |
13915 | === | |
13916 | ||
13917 | cindex:[Oracle,server list] | |
13918 | This option provides a list of Oracle servers and associated connection data, | |
13919 | to be used in conjunction with ^oracle^ lookups (see section <<SECTsql>>). The | |
13920 | option is available only if Exim has been built with Oracle support. | |
13921 | ||
13922 | ||
13923 | oindex:[%percent_hack_domains%] | |
13924 | `..'= | |
13925 | %percent_hack_domains%, Use: 'main', Type: 'domain list'!!, Default: 'unset' | |
13926 | === | |
13927 | ||
13928 | cindex:[``percent hack''] | |
13929 | cindex:[source routing,in email address] | |
13930 | cindex:[address,source-routed] | |
13931 | The ``percent hack'' is the convention whereby a local part containing a percent | |
13932 | sign is re-interpreted as a new email address, with the percent replaced by @. | |
13933 | This is sometimes called ``source routing'', though that term is also applied to | |
13934 | RFC 2822 addresses that begin with an @ character. If this option is set, Exim | |
13935 | implements the percent facility for those domains listed, but no others. This | |
13936 | happens before an incoming SMTP address is tested against an ACL. | |
13937 | ||
13938 | *Warning*: The ``percent hack'' has often been abused by people who are | |
13939 | trying to get round relaying restrictions. For this reason, it is best avoided | |
13940 | if at all possible. Unfortunately, a number of less security-conscious MTAs | |
13941 | implement it unconditionally. If you are running Exim on a gateway host, and | |
13942 | routing mail through to internal MTAs without processing the local parts, it is | |
13943 | a good idea to reject recipient addresses with percent characters in their | |
13944 | local parts. Exim's default configuration does this. | |
13945 | ||
13946 | ||
13947 | oindex:[%perl_at_start%] | |
13948 | `..'= | |
13949 | %perl_at_start%, Use: 'main', Type: 'boolean', Default: 'false' | |
13950 | === | |
13951 | ||
13952 | This option is available only when Exim is built with an embedded Perl | |
13953 | interpreter. See chapter <<CHAPperl>> for details of its use. | |
13954 | ||
13955 | ||
13956 | oindex:[%perl_startup%] | |
13957 | `..'= | |
13958 | %perl_startup%, Use: 'main', Type: 'string', Default: 'unset' | |
13959 | === | |
13960 | ||
13961 | This option is available only when Exim is built with an embedded Perl | |
13962 | interpreter. See chapter <<CHAPperl>> for details of its use. | |
13963 | ||
13964 | ||
13965 | oindex:[%pgsql_servers%] | |
13966 | `..'= | |
13967 | %pgsql_servers%, Use: 'main', Type: 'string list', Default: 'unset' | |
13968 | === | |
13969 | ||
13970 | cindex:[PostgreSQL lookup type,server list] | |
13971 | This option provides a list of PostgreSQL servers and associated connection | |
13972 | data, to be used in conjunction with ^pgsql^ lookups (see section <<SECTsql>>). | |
13973 | The option is available only if Exim has been built with PostgreSQL support. | |
13974 | ||
13975 | ||
13976 | oindex:[%pid_file_path%] | |
13977 | `..'= | |
13978 | %pid_file_path%, Use: 'main', Type: 'string'!!, Default: 'set at compile time' | |
13979 | === | |
13980 | ||
13981 | cindex:[daemon,pid file path] | |
13982 | cindex:[pid file, path for] | |
13983 | This option sets the name of the file to which the Exim daemon writes its | |
13984 | process id. The string is expanded, so it can contain, for example, references | |
13985 | to the host name: | |
13986 | ||
13987 | pid_file_path = /var/log/$primary_hostname/exim.pid | |
13988 | ||
13989 | If no path is set, the pid is written to the file _exim-daemon.pid_ in Exim's | |
13990 | spool directory. | |
13991 | The value set by the option can be overridden by the %-oP% command line | |
13992 | option. A pid file is not written if a ``non-standard'' daemon is run by means of | |
13993 | the %-oX% option, unless a path is explicitly supplied by %-oP%. | |
13994 | ||
13995 | ||
13996 | oindex:[%pipelining_advertise_hosts%] | |
13997 | `..'= | |
13998 | %pipelining_advertise_hosts%, Use: 'main', Type: 'host list'!!, Default: '\*' | |
13999 | === | |
14000 | ||
14001 | cindex:[PIPELINING advertising, suppressing] | |
14002 | This option can be used to suppress the advertisement of the SMTP | |
14003 | PIPELINING extension to specific hosts. When PIPELINING is not | |
14004 | advertised and %smtp_enforce_sync% is true, an Exim server enforces strict | |
14005 | synchronization for each SMTP command and response. | |
14006 | When PIPELINING is advertised, Exim assumes that clients will use it; ``out | |
14007 | of order'' commands that are ``expected'' do not count as protocol errors (see | |
14008 | %smtp_max_synprot_errors%). | |
14009 | ||
14010 | ||
14011 | oindex:[%preserve_message_logs%] | |
14012 | `..'= | |
14013 | %preserve_message_logs%, Use: 'main', Type: 'boolean', Default: 'false' | |
14014 | === | |
14015 | ||
14016 | cindex:[message logs, preserving] | |
14017 | If this option is set, message log files are not deleted when messages are | |
14018 | completed. Instead, they are moved to a sub-directory of the spool directory | |
14019 | called _msglog.OLD_, where they remain available for statistical or debugging | |
14020 | purposes. This is a dangerous option to set on systems with any appreciable | |
14021 | volume of mail. Use with care! | |
14022 | ||
14023 | ||
14024 | oindex:[%primary_hostname%] | |
14025 | `..'= | |
14026 | %primary_hostname%, Use: 'main', Type: 'string', Default: 'see below' | |
14027 | === | |
14028 | ||
14029 | cindex:[name,of local host] | |
14030 | cindex:[host,name of local] | |
14031 | cindex:[local host,name of] | |
068aaea8 PH |
14032 | cindex:[$primary_hostname$] |
14033 | This specifies the name of the current host. It is used in the default EHLO or | |
14034 | HELO command for outgoing SMTP messages (changeable via the %helo_data% option | |
14035 | in the ^smtp^ transport), and as the default for %qualify_domain%. The value is | |
14036 | also used by default in some SMTP response messages from an Exim server. This | |
14037 | can be changed dynamically by setting %smtp_active_hostname%. | |
168e428f | 14038 | |
068aaea8 PH |
14039 | If %primary_hostname% is not set, Exim calls 'uname()' to find the host name. |
14040 | If this fails, Exim panics and dies. If the name returned by 'uname()' contains | |
14041 | only one component, Exim passes it to 'gethostbyname()' (or 'getipnodebyname()' | |
14042 | when available) in order to obtain the fully qualified version. The variable | |
14043 | $primary_hostname$ contains the host name, whether set explicitly by this | |
14044 | option, or defaulted. | |
168e428f PH |
14045 | |
14046 | ||
14047 | oindex:[%print_topbitchars%] | |
14048 | `..'= | |
14049 | %print_topbitchars%, Use: 'main', Type: 'boolean', Default: 'false' | |
14050 | === | |
14051 | ||
14052 | cindex:[printing characters] | |
14053 | cindex:[8-bit characters] | |
14054 | By default, Exim considers only those characters whose codes lie in the range | |
14055 | 32--126 to be printing characters. In a number of circumstances (for example, | |
14056 | when writing log entries) non-printing characters are converted into escape | |
14057 | sequences, primarily to avoid messing up the layout. If %print_topbitchars% is | |
14058 | set, code values of 128 and above are also considered to be printing | |
14059 | characters. | |
14060 | ||
14061 | ||
14062 | oindex:[%process_log_path%] | |
14063 | `..'= | |
14064 | %process_log_path%, Use: 'main', Type: 'string', Default: 'unset' | |
14065 | === | |
14066 | ||
14067 | cindex:[process log path] | |
14068 | cindex:[log,process log] | |
14069 | cindex:['exiwhat'] | |
14070 | This option sets the name of the file to which an Exim process writes its | |
14071 | ``process log'' when sent a USR1 signal. This is used by the 'exiwhat' utility | |
14072 | script. If this option is unset, the file called _exim-process.info_ in | |
14073 | Exim's spool directory is used. The ability to specify the name explicitly can | |
14074 | be useful in environments where two different Exims are running, using | |
14075 | different spool directories. | |
14076 | ||
14077 | ||
14078 | oindex:[%prod_requires_admin%] | |
14079 | `..'= | |
14080 | %prod_requires_admin%, Use: 'main', Type: 'boolean', Default: 'true' | |
14081 | === | |
14082 | ||
14083 | cindex:[%-M% option] | |
14084 | cindex:[%-R% option] | |
14085 | cindex:[%-q% option] | |
14086 | The %-M%, %-R%, and %-q% command-line options require the caller to be an | |
14087 | admin user unless %prod_requires_admin% is set false. See also | |
14088 | %queue_list_requires_admin%. | |
14089 | ||
14090 | ||
14091 | oindex:[%qualify_domain%] | |
14092 | `..'= | |
14093 | %qualify_domain%, Use: 'main', Type: 'string', Default: 'see below' | |
14094 | === | |
14095 | ||
14096 | cindex:[domain,for qualifying addresses] | |
14097 | cindex:[address,qualification] | |
14098 | This option specifies the domain name that is added to any envelope sender | |
14099 | addresses that do not have a domain qualification. It also applies to | |
14100 | recipient addresses if %qualify_recipient% is not set. | |
14101 | ||
14102 | Unqualified addresses are accepted by default only for locally-generated | |
14103 | messages. | |
14104 | ||
14105 | Qualification is also applied to addresses in header lines such as 'From:' and | |
14106 | 'To:' for locally-generated messages, unless the %-bnq% command line option | |
14107 | is used. | |
14108 | ||
14109 | ||
14110 | Messages from external sources must always contain fully qualified addresses, | |
14111 | unless the sending host matches %sender_unqualified_hosts% or | |
14112 | %recipient_unqualified_hosts% (as appropriate), in which case incoming | |
14113 | addresses are qualified with %qualify_domain% or %qualify_recipient% as | |
14114 | necessary. Internally, Exim always works with fully qualified envelope | |
14115 | addresses. If %qualify_domain% is not set, it defaults to the | |
14116 | %primary_hostname% value. | |
14117 | ||
14118 | ||
14119 | oindex:[%qualify_recipient%] | |
14120 | `..'= | |
14121 | %qualify_recipient%, Use: 'main', Type: 'string', Default: 'see below' | |
14122 | === | |
14123 | ||
14124 | This option allows you to specify a different domain for qualifying recipient | |
14125 | addresses to the one that is used for senders. See %qualify_domain% above. | |
14126 | ||
14127 | ||
14128 | ||
14129 | oindex:[%queue_domains%] | |
14130 | `..'= | |
14131 | %queue_domains%, Use: 'main', Type: 'domain list'!!, Default: 'unset' | |
14132 | === | |
14133 | ||
14134 | cindex:[domain,specifying non-immediate delivery] | |
14135 | cindex:[queueing incoming messages] | |
14136 | cindex:[message,queueing certain domains] | |
14137 | This option lists domains for which immediate delivery is not required. | |
14138 | A delivery process is started whenever a message is received, but only those | |
14139 | domains that do not match are processed. All other deliveries wait until the | |
14140 | next queue run. See also %hold_domains% and %queue_smtp_domains%. | |
14141 | ||
14142 | ||
14143 | oindex:[%queue_list_requires_admin%] | |
14144 | `..'= | |
14145 | %queue_list_requires_admin%, Use: 'main', Type: 'boolean', Default: 'true' | |
14146 | === | |
14147 | ||
14148 | cindex:[%-bp% option] | |
14149 | The %-bp% command-line option, which lists the messages that are on the queue, | |
14150 | requires the caller to be an admin user unless %queue_list_requires_admin% | |
14151 | is set false. See also %prod_requires_admin%. | |
14152 | ||
14153 | ||
14154 | oindex:[%queue_only%] | |
14155 | `..'= | |
14156 | %queue_only%, Use: 'main', Type: 'boolean', Default: 'false' | |
14157 | === | |
14158 | ||
14159 | cindex:[queueing incoming messages] | |
14160 | cindex:[message,queueing unconditionally] | |
14161 | If %queue_only% is set, a delivery process is not automatically started | |
14162 | whenever a message is received. Instead, the message waits on the queue for the | |
14163 | next queue run. Even if %queue_only% is false, incoming messages may not get | |
14164 | delivered immediately when certain conditions (such as heavy load) occur. | |
14165 | ||
14166 | The %-odq% command line has the same effect as %queue_only%. The %-odb% and | |
14167 | %-odi% command line options override %queue_only% unless | |
14168 | %queue_only_override% is set false. See also %queue_only_file%, | |
14169 | %queue_only_load%, and %smtp_accept_queue%. | |
14170 | ||
14171 | ||
14172 | oindex:[%queue_only_file%] | |
14173 | `..'= | |
14174 | %queue_only_file%, Use: 'main', Type: 'string', Default: 'unset' | |
14175 | === | |
14176 | ||
14177 | cindex:[queueing incoming messages] | |
14178 | cindex:[message,queueing by file existence] | |
14179 | This option can be set to a colon-separated list of absolute path names, each | |
14180 | one optionally preceded by ``smtp''. When Exim is receiving a message, | |
14181 | it tests for the existence of each listed path using a call to 'stat()'. For | |
14182 | each path that exists, the corresponding queuing option is set. | |
14183 | For paths with no prefix, %queue_only% is set; for paths prefixed by ``smtp'', | |
14184 | %queue_smtp_domains% is set to match all domains. So, for example, | |
14185 | ||
14186 | queue_only_file = smtp/some/file | |
14187 | ||
14188 | causes Exim to behave as if %queue_smtp_domains% were set to ``\*'' whenever | |
14189 | _/some/file_ exists. | |
14190 | ||
14191 | ||
14192 | oindex:[%queue_only_load%] | |
14193 | `..'= | |
14194 | %queue_only_load%, Use: 'main', Type: 'fixed-point', Default: 'unset' | |
14195 | === | |
14196 | ||
14197 | cindex:[load average] | |
14198 | cindex:[queueing incoming messages] | |
14199 | cindex:[message,queueing by load] | |
14200 | If the system load average is higher than this value, incoming messages from | |
14201 | all sources are queued, and no automatic deliveries are started. If this | |
14202 | happens during local or remote SMTP input, all subsequent messages on the same | |
14203 | connection are queued. Deliveries will subsequently be performed by queue | |
14204 | runner processes. This option has no effect on ancient operating systems on | |
14205 | which Exim cannot determine the load average. See also | |
14206 | %deliver_queue_load_max% and %smtp_load_reserve%. | |
14207 | ||
14208 | ||
14209 | oindex:[%queue_only_override%] | |
14210 | `..'= | |
14211 | %queue_only_override%, Use: 'main', Type: 'boolean', Default: 'true' | |
14212 | === | |
14213 | ||
14214 | cindex:[queueing incoming messages] | |
14215 | When this option is true, the %-od'x'% command line options override the | |
14216 | setting of %queue_only% or %queue_only_file% in the configuration file. If | |
14217 | %queue_only_override% is set false, the %-od'x'% options cannot be used to | |
14218 | override; they are accepted, but ignored. | |
14219 | ||
14220 | ||
14221 | oindex:[%queue_run_in_order%] | |
14222 | `..'= | |
14223 | %queue_run_in_order%, Use: 'main', Type: 'boolean', Default: 'false' | |
14224 | === | |
14225 | ||
14226 | cindex:[queue runner,processing messages in order] | |
14227 | If this option is set, queue runs happen in order of message arrival instead of | |
14228 | in an arbitrary order. For this to happen, a complete list of the entire queue | |
14229 | must be set up before the deliveries start. When the queue is all held in a | |
14230 | single directory (the default), | |
14231 | ||
14232 | a single list is created for both the ordered and the non-ordered cases. | |
14233 | However, if %split_spool_directory% is set, a single list is not created when | |
14234 | %queue_run_in_order% is false. In this case, the sub-directories are | |
14235 | processed one at a time (in a random order), and this avoids setting up one | |
14236 | huge list for the whole queue. Thus, setting %queue_run_in_order% with | |
14237 | %split_spool_directory% may degrade performance when the queue is large, | |
14238 | because of the extra work in setting up the single, large list. In most | |
14239 | situations, %queue_run_in_order% should not be set. | |
14240 | ||
14241 | ||
14242 | ||
14243 | oindex:[%queue_run_max%] | |
14244 | `..'= | |
14245 | %queue_run_max%, Use: 'main', Type: 'integer', Default: '5' | |
14246 | === | |
14247 | ||
14248 | cindex:[queue runner,maximum number of] | |
14249 | This controls the maximum number of queue runner processes that an Exim daemon | |
14250 | can run simultaneously. This does not mean that it starts them all at once, | |
14251 | but rather that if the maximum number are still running when the time comes to | |
14252 | start another one, it refrains from starting another one. This can happen with | |
14253 | very large queues and/or very sluggish deliveries. This option does not, | |
14254 | however, interlock with other processes, so additional queue runners can be | |
14255 | started by other means, or by killing and restarting the daemon. | |
14256 | ||
068aaea8 PH |
14257 | [revisionflag="changed"] |
14258 | Setting this option to zero does not suppress queue runs; rather, it disables | |
14259 | the limit, allowing any number of simultaneous queue runner processes to be | |
14260 | run. If you do not want queue runs to occur, omit the %-q%'xx' setting on the | |
14261 | daemon's command line. | |
14262 | ||
168e428f PH |
14263 | |
14264 | oindex:[%queue_smtp_domains%] | |
14265 | `..'= | |
14266 | %queue_smtp_domains%, Use: 'main', Type: 'domain list'!!, Default: 'unset' | |
14267 | === | |
14268 | ||
14269 | cindex:[queueing incoming messages] | |
14270 | cindex:[message,queueing remote deliveries] | |
14271 | When this option is set, a delivery process is started whenever a message is | |
14272 | received, routing is performed, and local deliveries take place. | |
14273 | However, if any SMTP deliveries are required for domains that match | |
14274 | %queue_smtp_domains%, they are not immediately delivered, but instead the | |
14275 | message waits on the queue for the next queue run. Since routing of the message | |
14276 | has taken place, Exim knows to which remote hosts it must be delivered, and so | |
14277 | when the queue run happens, multiple messages for the same host are delivered | |
14278 | over a single SMTP connection. The %-odqs% command line option causes all SMTP | |
14279 | deliveries to be queued in this way, and is equivalent to setting | |
14280 | %queue_smtp_domains% to ``\*''. See also %hold_domains% and %queue_domains%. | |
14281 | ||
14282 | ||
14283 | oindex:[%receive_timeout%] | |
14284 | `..'= | |
14285 | %receive_timeout%, Use: 'main', Type: 'time', Default: '0s' | |
14286 | === | |
14287 | ||
14288 | cindex:[timeout,for non-SMTP input] | |
14289 | This option sets the timeout for accepting a non-SMTP message, that is, the | |
14290 | maximum time that Exim waits when reading a message on the standard input. If | |
14291 | the value is zero, it will wait for ever. This setting is overridden by the | |
14292 | %-or% command line option. The timeout for incoming SMTP messages is | |
14293 | controlled by %smtp_receive_timeout%. | |
14294 | ||
14295 | oindex:[%received_header_text%] | |
14296 | `..'= | |
14297 | %received_header_text%, Use: 'main', Type: 'string'!!, Default: 'see below' | |
14298 | === | |
14299 | ||
14300 | cindex:[customizing, 'Received:' header] | |
14301 | cindex:['Received:' header line,customizing] | |
14302 | This string defines the contents of the 'Received:' message header that is | |
14303 | added to each message, except for the timestamp, which is automatically added | |
14304 | on at the end (preceded by a semicolon). The string is expanded each time it is | |
14305 | used. If the expansion yields an empty string, no 'Received:' header line is | |
14306 | added to the message. Otherwise, the string should start with the text | |
14307 | ``Received:'' and conform to the RFC 2822 specification for 'Received:' header | |
14308 | lines. The default setting is: | |
14309 | ||
d1e83bff | 14310 | [revisionflag="changed"] |
168e428f PH |
14311 | .... |
14312 | received_header_text = Received: \ | |
d1e83bff PH |
14313 | ${if def:sender_rcvhost {from $sender_rcvhost\n\t}\ |
14314 | {${if def:sender_ident {from ${quote_local_part: $sender_ident} }}\ | |
14315 | ${if def:sender_helo_name {(helo=$sender_helo_name)\n\t}}}}\ | |
14316 | by $primary_hostname \ | |
14317 | ${if def:received_protocol {with $received_protocol}} \ | |
14318 | ${if def:tls_cipher {($tls_cipher)\n\t}}\ | |
14319 | (Exim $version_number)\n\t\ | |
14320 | ${if def:sender_address {(envelope-from <$sender_address>)\n\t}}\ | |
14321 | id $message_exim_id\ | |
14322 | ${if def:received_for {\n\tfor $received_for}} | |
168e428f PH |
14323 | .... |
14324 | ||
d1e83bff PH |
14325 | The reference to the TLS cipher is omitted when Exim is built without TLS |
14326 | support. The use of conditional expansions ensures that this works for both | |
14327 | locally generated messages and messages received from remote hosts, giving | |
14328 | header lines such as the following: | |
168e428f PH |
14329 | |
14330 | Received: from scrooge.carol.example ([192.168.12.25] ident=root) | |
14331 | by marley.carol.example with esmtp (Exim 4.00) | |
d1e83bff | 14332 | (envelope-from <bob@carol.example>) |
168e428f PH |
14333 | id 16IOWa-00019l-00 |
14334 | for chas@dickens.example; Tue, 25 Dec 2001 14:43:44 +0000 | |
14335 | Received: by scrooge.carol.example with local (Exim 4.00) | |
14336 | id 16IOWW-000083-00; Tue, 25 Dec 2001 14:43:41 +0000 | |
14337 | ||
14338 | Until the body of the message has been received, the timestamp is the time when | |
14339 | the message started to be received. Once the body has arrived, and all policy | |
14340 | checks have taken place, the timestamp is updated to the time at which the | |
14341 | message was accepted. | |
14342 | ||
14343 | ||
14344 | oindex:[%received_headers_max%] | |
14345 | `..'= | |
14346 | %received_headers_max%, Use: 'main', Type: 'integer', Default: '30' | |
14347 | === | |
14348 | ||
14349 | cindex:[loop,prevention] | |
14350 | cindex:[mail loop prevention] | |
14351 | cindex:['Received:' header line,counting] | |
14352 | When a message is to be delivered, the number of 'Received:' headers is | |
14353 | counted, and if it is greater than this parameter, a mail loop is assumed to | |
14354 | have occurred, the delivery is abandoned, and an error message is generated. | |
14355 | This applies to both local and remote deliveries. | |
14356 | ||
14357 | ||
14358 | oindex:[%recipient_unqualified_hosts%] | |
14359 | `..'= | |
14360 | %recipient_unqualified_hosts%, Use: 'main', Type: 'host list'!!, Default: 'unset' | |
14361 | === | |
14362 | ||
14363 | cindex:[unqualified addresses] | |
14364 | cindex:[host,unqualified addresses from] | |
14365 | This option lists those hosts from which Exim is prepared to accept unqualified | |
14366 | recipient addresses in message envelopes. The addresses are made fully | |
14367 | qualified by the addition of the %qualify_recipient% value. This option also | |
14368 | affects message header lines. Exim does not reject unqualified recipient | |
14369 | addresses in headers, but it qualifies them only if the message came from a | |
14370 | host that matches %recipient_unqualified_hosts%, | |
14371 | or if the message was submitted locally (not using TCP/IP), and the %-bnq% | |
14372 | option was not set. | |
14373 | ||
14374 | ||
14375 | oindex:[%recipients_max%] | |
14376 | `..'= | |
14377 | %recipients_max%, Use: 'main', Type: 'integer', Default: '0' | |
14378 | === | |
14379 | ||
14380 | cindex:[limit,number of recipients] | |
14381 | cindex:[recipient,maximum number] | |
14382 | If this option is set greater than zero, it specifies the maximum number of | |
14383 | original recipients for any message. Additional recipients that are generated | |
14384 | by aliasing or forwarding do not count. SMTP messages get a 452 response for | |
14385 | all recipients over the limit; earlier recipients are delivered as normal. | |
14386 | Non-SMTP messages with too many recipients are failed, and no deliveries are | |
14387 | done. | |
14388 | ||
14389 | cindex:[RCPT,maximum number of incoming] | |
14390 | Note that the RFCs specify that an SMTP server should accept at least 100 | |
14391 | RCPT commands in a single message. | |
14392 | ||
14393 | ||
14394 | oindex:[%recipients_max_reject%] | |
14395 | `..'= | |
14396 | %recipients_max_reject%, Use: 'main', Type: 'boolean', Default: 'false' | |
14397 | === | |
14398 | ||
14399 | If this option is set true, Exim rejects SMTP messages containing too many | |
14400 | recipients by giving 552 errors to the surplus RCPT commands, and a 554 | |
14401 | error to the eventual DATA command. Otherwise (the default) it gives a 452 | |
14402 | error to the surplus RCPT commands and accepts the message on behalf of the | |
14403 | initial set of recipients. The remote server should then re-send the message | |
14404 | for the remaining recipients at a later time. | |
14405 | ||
14406 | ||
14407 | oindex:[%remote_max_parallel%] | |
14408 | `..'= | |
14409 | %remote_max_parallel%, Use: 'main', Type: 'integer', Default: '2' | |
14410 | === | |
14411 | ||
14412 | cindex:[delivery,parallelism for remote] | |
14413 | This option controls parallel delivery of one message to a number of remote | |
14414 | hosts. If the value is less than 2, parallel delivery is disabled, and Exim | |
14415 | does all the remote deliveries for a message one by one. Otherwise, if a single | |
14416 | message has to be delivered to more than one remote host, or if several copies | |
14417 | have to be sent to the same remote host, up to %remote_max_parallel% | |
14418 | deliveries are done simultaneously. If more than %remote_max_parallel% | |
14419 | deliveries are required, the maximum number of processes are started, and as | |
14420 | each one finishes, another is begun. The order of starting processes is the | |
14421 | same as if sequential delivery were being done, and can be controlled by the | |
14422 | %remote_sort_domains% option. If parallel delivery takes place while running | |
14423 | with debugging turned on, the debugging output from each delivery process is | |
14424 | tagged with its process id. | |
14425 | ||
14426 | This option controls only the maximum number of parallel deliveries for one | |
14427 | message in one Exim delivery process. Because Exim has no central queue | |
14428 | manager, there is no way of controlling the total number of simultaneous | |
14429 | deliveries if the configuration allows a delivery attempt as soon as a message | |
14430 | is received. | |
14431 | ||
14432 | cindex:[number of deliveries] | |
14433 | cindex:[delivery,maximum number of] | |
14434 | If you want to control the total number of deliveries on the system, you | |
14435 | need to set the %queue_only% option. This ensures that all incoming messages | |
14436 | are added to the queue without starting a delivery process. Then set up an Exim | |
14437 | daemon to start queue runner processes at appropriate intervals (probably | |
14438 | fairly often, for example, every minute), and limit the total number of queue | |
14439 | runners by setting the %queue_run_max% parameter. Because each queue runner | |
14440 | delivers only one message at a time, the maximum number of deliveries that can | |
14441 | then take place at once is %queue_run_max% multiplied by | |
14442 | %remote_max_parallel%. | |
14443 | ||
14444 | If it is purely remote deliveries you want to control, use | |
14445 | %queue_smtp_domains% instead of %queue_only%. This has the added benefit of | |
14446 | doing the SMTP routing before queuing, so that several messages for the same | |
14447 | host will eventually get delivered down the same connection. | |
14448 | ||
14449 | ||
14450 | oindex:[%remote_sort_domains%] | |
14451 | `..'= | |
14452 | %remote_sort_domains%, Use: 'main', Type: 'domain list'!!, Default: 'unset' | |
14453 | === | |
14454 | ||
14455 | cindex:[sorting remote deliveries] | |
14456 | cindex:[delivery,sorting remote] | |
14457 | When there are a number of remote deliveries for a message, they are sorted by | |
14458 | domain into the order given by this list. For example, | |
14459 | ||
14460 | remote_sort_domains = *.cam.ac.uk:*.uk | |
14461 | ||
14462 | would attempt to deliver to all addresses in the 'cam.ac.uk' domain first, then | |
14463 | to those in the %uk% domain, then to any others. | |
14464 | ||
14465 | ||
14466 | oindex:[%retry_data_expire%] | |
14467 | `..'= | |
14468 | %retry_data_expire%, Use: 'main', Type: 'time', Default: '7d' | |
14469 | === | |
14470 | ||
14471 | cindex:[hints database,data expiry] | |
14472 | This option sets a ``use before'' time on retry information in Exim's hints | |
14473 | database. Any older retry data is ignored. This means that, for example, once a | |
14474 | host has not been tried for 7 days, Exim behaves as if it has no knowledge of | |
14475 | past failures. | |
14476 | ||
14477 | ||
14478 | oindex:[%retry_interval_max%] | |
14479 | `..'= | |
14480 | %retry_interval_max%, Use: 'main', Type: 'time', Default: '24h' | |
14481 | === | |
14482 | ||
14483 | cindex:[retry,limit on interval] | |
14484 | cindex:[limit,on retry interval] | |
14485 | Chapter <<CHAPretry>> describes Exim's mechanisms for controlling the intervals | |
14486 | between delivery attempts for messages that cannot be delivered straight away. | |
14487 | This option sets an overall limit to the length of time between retries. | |
14488 | ||
14489 | ||
14490 | oindex:[%return_path_remove%] | |
14491 | `..'= | |
14492 | %return_path_remove%, Use: 'main', Type: 'boolean', Default: 'true' | |
14493 | === | |
14494 | ||
14495 | cindex:['Return-path:' header line,removing] | |
14496 | RFC 2821, section 4.4, states that an SMTP server must insert a 'Return-path:' | |
14497 | header line into a message when it makes a ``final delivery''. The 'Return-path:' | |
14498 | header preserves the sender address as received in the MAIL command. This | |
14499 | description implies that this header should not be present in an incoming | |
14500 | message. If %return_path_remove% is true, any existing 'Return-path:' | |
14501 | headers are removed from messages at the time they are received. Exim's | |
14502 | transports have options for adding 'Return-path:' headers at the time of | |
14503 | delivery. They are normally used only for final local deliveries. | |
14504 | ||
14505 | ||
14506 | oindex:[%return_size_limit%] | |
14507 | `..'= | |
14508 | %return_size_limit%, Use: 'main', Type: 'integer', Default: '100K' | |
14509 | === | |
14510 | ||
14511 | This option is an obsolete synonym for %bounce_return_size_limit%. | |
14512 | ||
14513 | ||
14514 | oindex:[%rfc1413_hosts%] | |
14515 | `..'= | |
14516 | %rfc1413_hosts%, Use: 'main', Type: 'host list'!!, Default: '\*' | |
14517 | === | |
14518 | ||
14519 | cindex:[RFC 1413] | |
14520 | cindex:[host,for RFC 1413 calls] | |
14521 | RFC 1413 identification calls are made to any client host which matches an item | |
14522 | in the list. | |
14523 | ||
14524 | ||
14525 | oindex:[%rfc1413_query_timeout%] | |
14526 | `..'= | |
14527 | %rfc1413_query_timeout%, Use: 'main', Type: 'time', Default: '30s' | |
14528 | === | |
14529 | ||
14530 | cindex:[RFC 1413,query timeout] | |
14531 | cindex:[timeout,for RFC 1413 call] | |
14532 | This sets the timeout on RFC 1413 identification calls. If it is set to zero, | |
14533 | no RFC 1413 calls are ever made. | |
14534 | ||
14535 | ||
14536 | oindex:[%sender_unqualified_hosts%] | |
14537 | `..'= | |
14538 | %sender_unqualified_hosts%, Use: 'main', Type: 'host list'!!, Default: 'unset' | |
14539 | === | |
14540 | ||
14541 | cindex:[unqualified addresses] | |
14542 | cindex:[host,unqualified addresses from] | |
14543 | This option lists those hosts from which Exim is prepared to accept unqualified | |
14544 | sender addresses. The addresses are made fully qualified by the addition of | |
14545 | %qualify_domain%. This option also affects message header lines. Exim does not | |
14546 | reject unqualified addresses in headers that contain sender addresses, but it | |
14547 | qualifies them only if the message came from a host that matches | |
14548 | %sender_unqualified_hosts%, | |
14549 | or if the message was submitted locally (not using TCP/IP), and the %-bnq% | |
14550 | option was not set. | |
14551 | ||
14552 | ||
14553 | oindex:[%smtp_accept_keepalive%] | |
14554 | `..'= | |
14555 | %smtp_accept_keepalive%, Use: 'main', Type: 'boolean', Default: 'true' | |
14556 | === | |
14557 | ||
14558 | cindex:[keepalive,on incoming connection] | |
14559 | This option controls the setting of the SO_KEEPALIVE option on incoming | |
14560 | TCP/IP socket connections. When set, it causes the kernel to probe idle | |
14561 | connections periodically, by sending packets with ``old'' sequence numbers. The | |
14562 | other end of the connection should send an acknowledgement if the connection is | |
14563 | still okay or a reset if the connection has been aborted. The reason for doing | |
14564 | this is that it has the beneficial effect of freeing up certain types of | |
14565 | connection that can get stuck when the remote host is disconnected without | |
14566 | tidying up the TCP/IP call properly. The keepalive mechanism takes several | |
14567 | hours to detect unreachable hosts. | |
14568 | ||
14569 | ||
14570 | ||
14571 | oindex:[%smtp_accept_max%] | |
14572 | `..'= | |
14573 | %smtp_accept_max%, Use: 'main', Type: 'integer', Default: '20' | |
14574 | === | |
14575 | ||
14576 | cindex:[limit,incoming SMTP connections] | |
14577 | cindex:[SMTP,incoming connection count] | |
14578 | cindex:[inetd] | |
14579 | This option specifies the maximum number of simultaneous incoming SMTP calls | |
14580 | that Exim will accept. It applies only to the listening daemon; there is no | |
14581 | control (in Exim) when incoming SMTP is being handled by 'inetd'. If the value | |
14582 | is set to zero, no limit is applied. However, it is required to be non-zero if | |
14583 | either %smtp_accept_max_per_host% or %smtp_accept_queue% is set. See also | |
14584 | %smtp_accept_reserve%. | |
14585 | ||
14586 | ||
14587 | ||
14588 | oindex:[%smtp_accept_max_nonmail%] | |
14589 | `..'= | |
14590 | %smtp_accept_max_nonmail%, Use: 'main', Type: 'integer', Default: '10' | |
14591 | === | |
14592 | ||
14593 | cindex:[limit,non-mail SMTP commands] | |
14594 | cindex:[SMTP,limiting non-mail commands] | |
14595 | Exim counts the number of ``non-mail'' commands in an SMTP session, and drops the | |
14596 | connection if there are too many. This option defines ``too many''. The check | |
14597 | catches some denial-of-service attacks, repeated failing AUTHs, or a mad | |
14598 | client looping sending EHLO, for example. The check is applied only if the | |
14599 | client host matches %smtp_accept_max_nonmail_hosts%. | |
14600 | ||
14601 | When a new message is expected, one occurrence of RSET is not counted. This | |
14602 | allows a client to send one RSET between messages (this is not necessary, | |
14603 | but some clients do it). Exim also allows one uncounted occurence of HELO | |
14604 | or EHLO, and one occurrence of STARTTLS between messages. After | |
14605 | starting up a TLS session, another EHLO is expected, and so it too is not | |
14606 | counted. The first occurrence of AUTH in a connection, or immediately | |
14607 | following STARTTLS is not counted. Otherwise, all commands other than | |
14608 | MAIL, RCPT, DATA, and QUIT are counted. | |
14609 | ||
14610 | ||
14611 | oindex:[%smtp_accept_max_nonmail_hosts%] | |
14612 | `..'= | |
14613 | %smtp_accept_max_nonmail_hosts%, Use: 'main', Type: 'host list'!!, Default: '\*' | |
14614 | === | |
14615 | ||
14616 | You can control which hosts are subject to the %smtp_accept_max_nonmail% | |
14617 | check by setting this option. The default value makes it apply to all hosts. By | |
14618 | changing the value, you can exclude any badly-behaved hosts that you have to | |
14619 | live with. | |
14620 | ||
14621 | ||
14622 | ||
14623 | oindex:[%smtp_accept_max_per_connection%] | |
14624 | `..'= | |
14625 | %smtp_accept_max_per_connection%, Use: 'main', Type: 'integer', Default: '1000' | |
14626 | === | |
14627 | ||
14628 | cindex:[SMTP incoming message count, limiting] | |
14629 | cindex:[limit,messages per SMTP connection] | |
14630 | The value of this option limits the number of MAIL commands that Exim is | |
14631 | prepared to accept over a single SMTP connection, whether or not each command | |
14632 | results in the transfer of a message. After the limit is reached, a 421 | |
14633 | response is given to subsequent MAIL commands. This limit is a safety | |
14634 | precaution against a client that goes mad (incidents of this type have been | |
14635 | seen). | |
14636 | ||
14637 | ||
14638 | oindex:[%smtp_accept_max_per_host%] | |
14639 | `..'= | |
14640 | %smtp_accept_max_per_host%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
14641 | === | |
14642 | ||
14643 | cindex:[limit,SMTP connections from one host] | |
14644 | cindex:[host,limiting SMTP connections from] | |
14645 | This option restricts the number of simultaneous IP connections from a single | |
14646 | host (strictly, from a single IP address) to the Exim daemon. The option is | |
14647 | expanded, to enable different limits to be applied to different hosts by | |
14648 | reference to $sender_host_address$. Once the limit is reached, additional | |
14649 | connection attempts from the same host are rejected with error code 421. The | |
14650 | default value of zero imposes no limit. If this option is set, it is required | |
14651 | that %smtp_accept_max% be non-zero. | |
14652 | ||
14653 | *Warning*: When setting this option you should not use any expansion | |
14654 | constructions that take an appreciable amount of time. The expansion and test | |
14655 | happen in the main daemon loop, in order to reject additional connections | |
14656 | without forking additional processes (otherwise a denial-of-service attack | |
14657 | could cause a vast number or processes to be created). While the daemon is | |
14658 | doing this processing, it cannot accept any other incoming connections. | |
14659 | ||
14660 | ||
14661 | ||
14662 | oindex:[%smtp_accept_queue%] | |
14663 | `..'= | |
14664 | %smtp_accept_queue%, Use: 'main', Type: 'integer', Default: '0' | |
14665 | === | |
14666 | ||
14667 | cindex:[SMTP,incoming connection count] | |
14668 | cindex:[queueing incoming messages] | |
14669 | cindex:[message,queueing by SMTP connection count] | |
14670 | If the number of simultaneous incoming SMTP calls handled via the listening | |
14671 | daemon exceeds this value, messages received by SMTP are just placed on the | |
14672 | queue; no delivery processes are started automatically. A value of zero implies | |
14673 | no limit, and clearly any non-zero value is useful only if it is less than the | |
14674 | %smtp_accept_max% value (unless that is zero). See also %queue_only%, | |
14675 | %queue_only_load%, %queue_smtp_domains%, and the various %-od% command | |
14676 | line options. | |
14677 | ||
14678 | ||
14679 | oindex:[%smtp_accept_queue_per_connection%] | |
14680 | `..'= | |
14681 | %smtp_accept_queue_per_connection%, Use: 'main', Type: 'integer', Default: '10' | |
14682 | === | |
14683 | ||
14684 | cindex:[queueing incoming messages] | |
14685 | cindex:[message,queueing by message count] | |
14686 | This option limits the number of delivery processes that Exim starts | |
14687 | automatically when receiving messages via SMTP, whether via the daemon or by | |
14688 | the use of %-bs% or %-bS%. If the value of the option is greater than zero, | |
14689 | and the number of messages received in a single SMTP session exceeds this | |
14690 | number, subsequent messages are placed on the queue, but no delivery processes | |
14691 | are started. This helps to limit the number of Exim processes when a server | |
14692 | restarts after downtime and there is a lot of mail waiting for it on other | |
14693 | systems. On large systems, the default should probably be increased, and on | |
14694 | dial-in client systems it should probably be set to zero (that is, disabled). | |
14695 | ||
14696 | ||
14697 | oindex:[%smtp_accept_reserve%] | |
14698 | `..'= | |
14699 | %smtp_accept_reserve%, Use: 'main', Type: 'integer', Default: '0' | |
14700 | === | |
14701 | ||
14702 | cindex:[SMTP,incoming call count] | |
14703 | cindex:[host,reserved] | |
14704 | When %smtp_accept_max% is set greater than zero, this option specifies a | |
14705 | number of SMTP connections that are reserved for connections from the hosts | |
14706 | that are specified in %smtp_reserve_hosts%. The value set in | |
14707 | %smtp_accept_max% includes this reserve pool. The specified hosts are not | |
14708 | restricted to this number of connections; the option specifies a minimum number | |
14709 | of connection slots for them, not a maximum. It is a guarantee that that group | |
14710 | of hosts can always get at least %smtp_accept_reserve% connections. | |
14711 | ||
14712 | For example, if %smtp_accept_max% is set to 50 and %smtp_accept_reserve% is | |
14713 | set to 5, once there are 45 active connections (from any hosts), new | |
14714 | connections are accepted only from hosts listed in %smtp_reserve_hosts%. | |
14715 | See also %smtp_accept_max_per_host%. | |
14716 | ||
14717 | ||
14718 | oindex:[%smtp_active_hostname%] | |
14719 | `..'= | |
14720 | %smtp_active_hostname%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
14721 | === | |
14722 | ||
14723 | cindex:[host,name in SMTP responses] | |
14724 | cindex:[SMTP,host name in responses] | |
068aaea8 | 14725 | cindex:[$primary_hostname$] |
168e428f PH |
14726 | This option is provided for multi-homed servers that want to masquerade as |
14727 | several different hosts. At the start of an SMTP connection, its value is | |
14728 | expanded and used instead of the value of $primary_hostname$ in SMTP | |
14729 | responses. For example, it is used as domain name in the response to an | |
14730 | incoming HELO or EHLO command. | |
14731 | ||
068aaea8 PH |
14732 | cindex:[$smtp_active_hostname$] |
14733 | It is also used in HELO commands for callout verification. The active hostname | |
14734 | is placed in the $smtp_active_hostname$ variable, which is saved with any | |
14735 | messages that are received. It is therefore available for use in routers and | |
14736 | transports when the message is later delivered. | |
168e428f PH |
14737 | |
14738 | If this option is unset, or if its expansion is forced to fail, or if the | |
14739 | expansion results in an empty string, the value of $primary_hostname$ is | |
14740 | used. Other expansion failures cause a message to be written to the main and | |
14741 | panic logs, and the SMTP command receives a temporary error. Typically, the | |
14742 | value of %smtp_active_hostname% depends on the incoming interface address. | |
14743 | For example: | |
14744 | ||
14745 | .... | |
14746 | smtp_active_hostname = ${if eq{$interface_address}{10.0.0.1}\ | |
14747 | {cox.mydomain}{box.mydomain}} | |
14748 | .... | |
14749 | ||
14750 | ||
14751 | oindex:[%smtp_banner%] | |
14752 | `..'= | |
14753 | %smtp_banner%, Use: 'main', Type: 'string'!!, Default: 'see below' | |
14754 | === | |
14755 | ||
14756 | cindex:[SMTP,welcome banner] | |
14757 | cindex:[banner for SMTP] | |
14758 | cindex:[welcome banner for SMTP] | |
14759 | cindex:[customizing,SMTP banner] | |
14760 | This string, which is expanded every time it is used, is output as the initial | |
14761 | positive response to an SMTP connection. The default setting is: | |
14762 | ||
14763 | .... | |
14764 | smtp_banner = $smtp_active_hostname ESMTP Exim \ | |
14765 | $version_number $tod_full | |
14766 | .... | |
14767 | ||
14768 | Failure to expand the string causes a panic error. If you want to create a | |
14769 | multiline response to the initial SMTP connection, use ``\n'' in the string at | |
14770 | appropriate points, but not at the end. Note that the 220 code is not included | |
14771 | in this string. Exim adds it automatically (several times in the case of a | |
14772 | multiline response). | |
14773 | ||
14774 | ||
14775 | oindex:[%smtp_check_spool_space%] | |
14776 | `..'= | |
14777 | %smtp_check_spool_space%, Use: 'main', Type: 'boolean', Default: 'true' | |
14778 | === | |
14779 | ||
14780 | cindex:[checking disk space] | |
14781 | cindex:[disk space, checking] | |
14782 | cindex:[spool directory,checking space] | |
14783 | When this option is set, if an incoming SMTP session encounters the SIZE | |
14784 | option on a MAIL command, it checks that there is enough space in the | |
14785 | spool directory's partition to accept a message of that size, while still | |
14786 | leaving free the amount specified by %check_spool_space% (even if that value | |
14787 | is zero). If there isn't enough space, a temporary error code is returned. | |
14788 | ||
14789 | ||
14790 | oindex:[%smtp_connect_backlog%] | |
14791 | `..'= | |
14792 | %smtp_connect_backlog%, Use: 'main', Type: 'integer', Default: '20' | |
14793 | === | |
14794 | ||
14795 | cindex:[connection backlog] | |
14796 | cindex:[SMTP,connection backlog] | |
14797 | cindex:[backlog of connections] | |
14798 | This option specifies a maximum number of waiting SMTP connections. Exim passes | |
14799 | this value to the TCP/IP system when it sets up its listener. Once this number | |
14800 | of connections are waiting for the daemon's attention, subsequent connection | |
14801 | attempts are refused at the TCP/IP level. At least, that is what the manuals | |
14802 | say; in some circumstances such connection attempts have been observed to time | |
14803 | out instead. For large systems it is probably a good idea to increase the | |
14804 | value (to 50, say). It also gives some protection against denial-of-service | |
14805 | attacks by SYN flooding. | |
14806 | ||
14807 | ||
14808 | oindex:[%smtp_enforce_sync%] | |
14809 | `..'= | |
14810 | %smtp_enforce_sync%, Use: 'main', Type: 'boolean', Default: 'true' | |
14811 | === | |
14812 | ||
14813 | cindex:[SMTP,synchronization checking] | |
14814 | cindex:[synchronization checking in SMTP] | |
14815 | The SMTP protocol specification requires the client to wait for a response from | |
14816 | the server at certain points in the dialogue. Without PIPELINING these | |
14817 | synchronization points are after every command; with PIPELINING they are | |
14818 | fewer, but they still exist. | |
14819 | ||
14820 | Some spamming sites send out a complete set of SMTP commands without waiting | |
14821 | for any response. Exim protects against this by rejecting a message if the | |
14822 | client has sent further input when it should not have. The error response ``554 | |
14823 | SMTP synchronization error'' is sent, and the connection is dropped. Testing for | |
14824 | this error cannot be perfect because of transmission delays (unexpected input | |
14825 | may be on its way but not yet received when Exim checks). However, it does | |
14826 | detect many instances. | |
14827 | ||
14828 | The check can be globally disabled by setting %smtp_enforce_sync% false. | |
14829 | If you want to disable the check selectively (for example, only for certain | |
14830 | hosts), you can do so by an appropriate use of a %control% modifier in an ACL | |
14831 | (see section <<SECTcontrols>>). See also %pipelining_advertise_hosts%. | |
14832 | ||
14833 | ||
14834 | ||
14835 | oindex:[%smtp_etrn_command%] | |
14836 | `..'= | |
14837 | %smtp_etrn_command%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
14838 | === | |
14839 | ||
14840 | cindex:[ETRN,command to be run] | |
068aaea8 | 14841 | cindex:[$domain$] |
168e428f PH |
14842 | If this option is set, the given command is run whenever an SMTP ETRN |
14843 | command is received from a host that is permitted to issue such commands (see | |
14844 | chapter <<CHAPACL>>). The string is split up into separate arguments which are | |
14845 | independently expanded. The expansion variable $domain$ is set to the | |
14846 | argument of the ETRN command, and no syntax checking is done on it. For | |
14847 | example: | |
14848 | ||
14849 | smtp_etrn_command = /etc/etrn_command $domain $sender_host_address | |
14850 | ||
14851 | A new process is created to run the command, but Exim does not wait for it to | |
14852 | complete. Consequently, its status cannot be checked. If the command cannot be | |
14853 | run, a line is written to the panic log, but the ETRN caller still receives | |
14854 | a 250 success response. Exim is normally running under its own uid when | |
14855 | receiving SMTP, so it is not possible for it to change the uid before running | |
14856 | the command. | |
14857 | ||
14858 | ||
14859 | oindex:[%smtp_etrn_serialize%] | |
14860 | `..'= | |
14861 | %smtp_etrn_serialize%, Use: 'main', Type: 'boolean', Default: 'true' | |
14862 | === | |
14863 | ||
14864 | cindex:[ETRN,serializing] | |
14865 | When this option is set, it prevents the simultaneous execution of more than | |
14866 | one identical command as a result of ETRN in an SMTP connection. See | |
14867 | section <<SECTETRN>> for details. | |
14868 | ||
14869 | ||
14870 | oindex:[%smtp_load_reserve%] | |
14871 | `..'= | |
14872 | %smtp_load_reserve%, Use: 'main', Type: 'fixed-point', Default: 'unset' | |
14873 | === | |
14874 | ||
14875 | cindex:[load average] | |
14876 | If the system load average ever gets higher than this, incoming SMTP calls are | |
14877 | accepted only from those hosts that match an entry in %smtp_reserve_hosts%. | |
14878 | If %smtp_reserve_hosts% is not set, no incoming SMTP calls are accepted when | |
14879 | the load is over the limit. The option has no effect on ancient operating | |
14880 | systems on which Exim cannot determine the load average. See also | |
14881 | %deliver_queue_load_max% and %queue_only_load%. | |
14882 | ||
14883 | ||
14884 | ||
14885 | oindex:[%smtp_max_synprot_errors%] | |
14886 | `..'= | |
14887 | %smtp_max_synprot_errors%, Use: 'main', Type: 'integer', Default: '3' | |
14888 | === | |
14889 | ||
14890 | cindex:[SMTP,limiting syntax and protocol errors] | |
14891 | cindex:[limit,SMTP syntax and protocol errors] | |
14892 | Exim rejects SMTP commands that contain syntax or protocol errors. In | |
14893 | particular, a syntactically invalid email address, as in this command: | |
14894 | ||
14895 | RCPT TO:<abc xyz@a.b.c> | |
14896 | ||
14897 | causes immediate rejection of the command, before any other tests are done. | |
14898 | (The ACL cannot be run if there is no valid address to set up for it.) An | |
14899 | example of a protocol error is receiving RCPT before MAIL. If there are | |
14900 | too many syntax or protocol errors in one SMTP session, the connection is | |
14901 | dropped. The limit is set by this option. | |
14902 | ||
14903 | cindex:[PIPELINING,expected errors] | |
14904 | When the PIPELINING extension to SMTP is in use, some protocol errors are | |
14905 | ``expected'', for instance, a RCPT command after a rejected MAIL command. | |
14906 | Exim assumes that PIPELINING will be used if it advertises it (see | |
14907 | %pipelining_advertise_hosts%), and in this situation, ``expected'' errors do | |
14908 | not count towards the limit. | |
14909 | ||
14910 | ||
14911 | ||
14912 | oindex:[%smtp_max_unknown_commands%] | |
14913 | `..'= | |
14914 | %smtp_max_unknown_commands%, Use: 'main', Type: 'integer', Default: '3' | |
14915 | === | |
14916 | ||
14917 | cindex:[SMTP,limiting unknown commands] | |
14918 | cindex:[limit,unknown SMTP commands] | |
14919 | If there are too many unrecognized commands in an incoming SMTP session, an | |
14920 | Exim server drops the connection. This is a defence against some kinds of abuse | |
14921 | that subvert web | |
14922 | clients | |
14923 | into making connections to SMTP ports; in these circumstances, a number of | |
14924 | non-SMTP command lines are sent first. | |
14925 | ||
14926 | ||
14927 | ||
14928 | oindex:[%smtp_ratelimit_hosts%] | |
14929 | `..'= | |
14930 | %smtp_ratelimit_hosts%, Use: 'main', Type: 'host list'!!, Default: 'unset' | |
14931 | === | |
14932 | ||
14933 | cindex:[SMTP,rate limiting] | |
14934 | cindex:[limit,rate of message arrival] | |
14935 | cindex:[RCPT,rate limiting] | |
14936 | Some sites find it helpful to be able to limit the rate at which certain hosts | |
14937 | can send them messages, and the rate at which an individual message can specify | |
14938 | recipients. When a host matches %smtp_ratelimit_hosts%, the values of | |
14939 | %smtp_ratelimit_mail% and %smtp_ratelimit_rcpt% are used to control the | |
14940 | rate of acceptance of MAIL and RCPT commands in a single SMTP session, | |
14941 | respectively. Each option, if set, must contain a set of four comma-separated | |
14942 | values: | |
14943 | ||
14944 | - A threshold, before which there is no rate limiting. | |
14945 | ||
14946 | - An initial time delay. Unlike other times in Exim, numbers with decimal | |
14947 | fractional parts are allowed here. | |
14948 | ||
14949 | - A factor by which to increase the delay each time. | |
14950 | ||
14951 | - A maximum value for the delay. This should normally be less than 5 minutes, | |
14952 | because after that time, the client is liable to timeout the SMTP command. | |
14953 | ||
14954 | For example, these settings have been used successfully at the site which | |
14955 | first suggested this feature, for controlling mail from their customers: | |
14956 | ||
14957 | smtp_ratelimit_mail = 2,0.5s,1.05,4m | |
14958 | smtp_ratelimit_rcpt = 4,0.25s,1.015,4m | |
14959 | ||
14960 | The first setting specifies delays that are applied to MAIL commands after | |
14961 | two have been received over a single connection. The initial delay is 0.5 | |
14962 | seconds, increasing by a factor of 1.05 each time. The second setting applies | |
14963 | delays to RCPT commands when more than four occur in a single message. | |
14964 | ||
14965 | It is also possible to configure delays explicitly in ACLs. See section | |
14966 | <<SECTACLmodi>> for details. | |
14967 | ||
14968 | ||
14969 | ||
14970 | oindex:[%smtp_ratelimit_mail%] | |
14971 | `..'= | |
14972 | %smtp_ratelimit_mail%, Use: 'main', Type: 'string', Default: 'unset' | |
14973 | === | |
14974 | ||
14975 | See %smtp_ratelimit_hosts% above. | |
14976 | ||
14977 | ||
14978 | oindex:[%smtp_ratelimit_rcpt%] | |
14979 | `..'= | |
14980 | %smtp_ratelimit_rcpt%, Use: 'main', Type: 'string', Default: 'unset' | |
14981 | === | |
14982 | ||
14983 | See %smtp_ratelimit_hosts% above. | |
14984 | ||
14985 | ||
14986 | oindex:[%smtp_receive_timeout%] | |
14987 | `..'= | |
14988 | %smtp_receive_timeout%, Use: 'main', Type: 'time', Default: '5m' | |
14989 | === | |
14990 | ||
14991 | cindex:[timeout,for SMTP input] | |
14992 | cindex:[SMTP timeout, input] | |
14993 | This sets a timeout value for SMTP reception. It applies to all forms of SMTP | |
14994 | input, including batch SMTP. If a line of input (either an SMTP command or a | |
14995 | data line) is not received within this time, the SMTP connection is dropped and | |
14996 | the message is abandoned. | |
14997 | A line is written to the log containing one of the following messages: | |
14998 | ||
14999 | SMTP command timeout on connection from... | |
15000 | SMTP data timeout on connection from... | |
15001 | ||
15002 | The former means that Exim was expecting to read an SMTP command; the latter | |
15003 | means that it was in the DATA phase, reading the contents of a message. | |
15004 | ||
15005 | ||
15006 | cindex:[%-os% option] | |
15007 | The value set by this option can be overridden by the | |
15008 | %-os% command-line option. A setting of zero time disables the timeout, but | |
15009 | this should never be used for SMTP over TCP/IP. (It can be useful in some cases | |
15010 | of local input using %-bs% or %-bS%.) For non-SMTP input, the reception | |
15011 | timeout is controlled by %receive_timeout% and %-or%. | |
15012 | ||
15013 | ||
15014 | oindex:[%smtp_reserve_hosts%] | |
15015 | `..'= | |
15016 | %smtp_reserve_hosts%, Use: 'main', Type: 'host list'!!, Default: 'unset' | |
15017 | === | |
15018 | ||
15019 | This option defines hosts for which SMTP connections are reserved; see | |
15020 | %smtp_accept_reserve% and %smtp_load_reserve% above. | |
15021 | ||
15022 | ||
15023 | oindex:[%smtp_return_error_details%] | |
15024 | `..'= | |
15025 | %smtp_return_error_details%, Use: 'main', Type: 'boolean', Default: 'false' | |
15026 | === | |
15027 | ||
15028 | cindex:[SMTP,details policy failures] | |
15029 | cindex:[policy control rejection, returning details] | |
15030 | In the default state, Exim uses bland messages such as | |
15031 | ``Administrative prohibition'' when it rejects SMTP commands for policy | |
15032 | reasons. Many sysadmins like this because it gives away little information | |
15033 | to spammers. However, some other syadmins who are applying strict checking | |
15034 | policies want to give out much fuller information about failures. Setting | |
15035 | %smtp_return_error_details% true causes Exim to be more forthcoming. For | |
15036 | example, instead of ``Administrative prohibition'', it might give: | |
15037 | ||
15038 | 550-Rejected after DATA: '>' missing at end of address: | |
15039 | 550 failing address in "From" header is: <user@dom.ain | |
15040 | ||
15041 | ||
15042 | ||
15043 | oindex:[%spamd_address%] | |
15044 | `..'= | |
15045 | %spamd_address%, Use: 'main', Type: 'string', Default: `127.0.0.1 783` | |
15046 | === | |
15047 | ||
15048 | This option is available when Exim is compiled with the content-scanning | |
15049 | extension. It specifies how Exim connects to SpamAssassin's %spamd% daemon. See | |
15050 | section <<SECTscanspamass>> for more details. | |
15051 | ||
15052 | ||
15053 | ||
15054 | oindex:[%split_spool_directory%] | |
15055 | `..'= | |
15056 | %split_spool_directory%, Use: 'main', Type: 'boolean', Default: 'false' | |
15057 | === | |
15058 | ||
15059 | cindex:[multiple spool directories] | |
15060 | cindex:[spool directory,split] | |
15061 | cindex:[directories, multiple] | |
15062 | If this option is set, it causes Exim to split its input directory into 62 | |
15063 | subdirectories, each with a single alphanumeric character as its name. The | |
15064 | sixth character of the message id is used to allocate messages to | |
15065 | subdirectories; this is the least significant base-62 digit of the time of | |
15066 | arrival of the message. | |
15067 | ||
15068 | Splitting up the spool in this way may provide better performance on systems | |
15069 | where there are long mail queues, by reducing the number of files in any one | |
15070 | directory. The msglog directory is also split up in a similar way to the input | |
15071 | directory; however, if %preserve_message_logs% is set, all old msglog files | |
15072 | are still placed in the single directory _msglog.OLD_. | |
15073 | ||
15074 | It is not necessary to take any special action for existing messages when | |
15075 | changing %split_spool_directory%. Exim notices messages that are in the | |
15076 | ``wrong'' place, and continues to process them. If the option is turned off after | |
15077 | a period of being on, the subdirectories will eventually empty and be | |
15078 | automatically deleted. | |
15079 | ||
15080 | When %split_spool_directory% is set, the behaviour of queue runner processes | |
15081 | changes. Instead of creating a list of all messages in the queue, and then | |
15082 | trying to deliver each one in turn, it constructs a list of those in one | |
15083 | sub-directory and tries to deliver them, before moving on to the next | |
15084 | sub-directory. The sub-directories are processed in a random order. This | |
15085 | spreads out the scanning of the input directories, and uses less memory. It is | |
15086 | particularly beneficial when there are lots of messages on the queue. However, | |
15087 | if %queue_run_in_order% is set, none of this new processing happens. The | |
15088 | entire queue has to be scanned and sorted before any deliveries can start. | |
15089 | ||
15090 | ||
15091 | oindex:[%spool_directory%] | |
15092 | `..'= | |
15093 | %spool_directory%, Use: 'main', Type: 'string'!!, Default: 'set at compile time' | |
15094 | === | |
15095 | ||
15096 | cindex:[spool directory,path to] | |
15097 | This defines the directory in which Exim keeps its spool, that is, the messages | |
15098 | it is waiting to deliver. The default value is taken from the compile-time | |
15099 | configuration setting, if there is one. If not, this option must be set. The | |
15100 | string is expanded, so it can contain, for example, a reference to | |
15101 | $primary_hostname$. | |
15102 | ||
15103 | If the spool directory name is fixed on your installation, it is recommended | |
15104 | that you set it at build time rather than from this option, particularly if the | |
15105 | log files are being written to the spool directory (see %log_file_path%). | |
15106 | Otherwise log files cannot be used for errors that are detected early on, such | |
15107 | as failures in the configuration file. | |
15108 | ||
15109 | By using this option to override the compiled-in path, it is possible to run | |
15110 | tests of Exim without using the standard spool. | |
15111 | ||
068aaea8 PH |
15112 | oindex:[%sqlite_lock_timeout%] |
15113 | `..'= | |
15114 | %sqlite_lock_timeout%, Use: 'main', Type: 'time', Default: '5s' | |
15115 | === | |
15116 | ||
15117 | [revisionflag="changed"] | |
15118 | cindex:[sqlite,lock timeout] | |
15119 | This option controls the timeout that the ^sqlite^ lookup uses when trying to | |
15120 | access an SQLite database. See section <<SECTsqlite>> for more details. | |
15121 | ||
168e428f PH |
15122 | |
15123 | oindex:[%strip_excess_angle_brackets%] | |
15124 | `..'= | |
15125 | %strip_excess_angle_brackets%, Use: 'main', Type: 'boolean', Default: 'false' | |
15126 | === | |
15127 | ||
15128 | cindex:[angle brackets, excess] | |
15129 | If this option is set, redundant pairs of angle brackets round ``route-addr'' | |
15130 | items in addresses are stripped. For example, `\<\<xxx@a.b.c.d\>\>` is treated | |
15131 | as `<xxx@a.b.c.d>`. If this is in the envelope and the message is passed on | |
15132 | to another MTA, the excess angle brackets are not passed on. If this option is | |
15133 | not set, multiple pairs of angle brackets cause a syntax error. | |
15134 | ||
15135 | ||
15136 | oindex:[%strip_trailing_dot%] | |
15137 | `..'= | |
15138 | %strip_trailing_dot%, Use: 'main', Type: 'boolean', Default: 'false' | |
15139 | === | |
15140 | ||
15141 | cindex:[trailing dot on domain] | |
15142 | cindex:[dot,trailing on domain] | |
15143 | If this option is set, a trailing dot at the end of a domain in an address is | |
15144 | ignored. If this is in the envelope and the message is passed on to another | |
15145 | MTA, the dot is not passed on. If this option is not set, a dot at the end of a | |
15146 | domain causes a syntax error. | |
15147 | However, addresses in header lines are checked only when an ACL requests header | |
15148 | syntax checking. | |
15149 | ||
15150 | ||
15151 | oindex:[%syslog_duplication%] | |
15152 | `..'= | |
15153 | %syslog_duplication%, Use: 'main', Type: 'boolean', Default: 'true' | |
15154 | === | |
15155 | ||
15156 | cindex:[syslog,duplicate log lines; suppressing] | |
15157 | When Exim is logging to syslog, it writes the log lines for its three | |
15158 | separate logs at different syslog priorities so that they can in principle | |
15159 | be separated on the logging hosts. Some installations do not require this | |
15160 | separation, and in those cases, the duplication of certain log lines is a | |
15161 | nuisance. If %syslog_duplication% is set false, only one copy of any | |
15162 | particular log line is written to syslog. For lines that normally go to | |
15163 | both the main log and the reject log, the reject log version (possibly | |
15164 | containing message header lines) is written, at LOG_NOTICE priority. | |
15165 | Lines that normally go to both the main and the panic log are written at | |
15166 | the LOG_ALERT priority. | |
15167 | ||
15168 | ||
15169 | oindex:[%syslog_facility%] | |
15170 | `..'= | |
15171 | %syslog_facility%, Use: 'main', Type: 'string', Default: 'unset' | |
15172 | === | |
15173 | ||
15174 | cindex:[syslog,facility; setting] | |
15175 | This option sets the syslog ``facility'' name, used when Exim is logging to | |
15176 | syslog. The value must be one of the strings ``mail'', ``user'', ``news'', ``uucp'', | |
15177 | ``daemon'', or ``local'x'##'' where 'x' is a digit between 0 and 7. If this | |
15178 | option is unset, ``mail'' is used. See chapter <<CHAPlog>> for details of Exim's | |
15179 | logging. | |
15180 | ||
15181 | ||
15182 | ||
15183 | oindex:[%syslog_processname%] | |
15184 | `..'= | |
15185 | %syslog_processname%, Use: 'main', Type: 'string', Default: `exim` | |
15186 | === | |
15187 | ||
15188 | cindex:[syslog,process name; setting] | |
15189 | This option sets the syslog ``ident'' name, used when Exim is logging to syslog. | |
15190 | The value must be no longer than 32 characters. See chapter <<CHAPlog>> for | |
15191 | details of Exim's logging. | |
15192 | ||
15193 | ||
15194 | ||
15195 | oindex:[%syslog_timestamp%] | |
15196 | `..'= | |
15197 | %syslog_timestamp%, Use: 'main', Type: 'boolean', Default: 'true' | |
15198 | === | |
15199 | ||
15200 | cindex:[syslog,timestamps] | |
15201 | If %syslog_timestamp% is set false, the timestamps on Exim's log lines are | |
15202 | omitted when these lines are sent to syslog. See chapter <<CHAPlog>> for | |
15203 | details of Exim's logging. | |
15204 | ||
15205 | ||
15206 | oindex:[%system_filter%] | |
15207 | `..'= | |
15208 | %system_filter%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
15209 | === | |
15210 | ||
15211 | cindex:[filter,system filter] | |
15212 | cindex:[system filter,specifying] | |
15213 | cindex:[Sieve filter,not available for system filter] | |
15214 | This option specifies an Exim filter file that is applied to all messages at | |
15215 | the start of each delivery attempt, before any routing is done. System filters | |
15216 | must be Exim filters; they cannot be Sieve filters. If the system filter | |
15217 | generates any deliveries to files or pipes, or any new mail messages, the | |
15218 | appropriate %system_filter_..._transport% option(s) must be set, to define | |
15219 | which transports are to be used. Details of this facility are given in chapter | |
15220 | <<CHAPsystemfilter>>. | |
15221 | ||
15222 | ||
15223 | oindex:[%system_filter_directory_transport%] | |
15224 | `..'= | |
15225 | %system_filter_directory_transport%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
15226 | === | |
15227 | ||
068aaea8 | 15228 | cindex:[$address_file$] |
168e428f PH |
15229 | This sets the name of the transport driver that is to be used when the |
15230 | %save% command in a system message filter specifies a path ending in ``/'', | |
15231 | implying delivery of each message into a separate file in some directory. | |
15232 | During the delivery, the variable $address_file$ contains the path name. | |
15233 | ||
15234 | ||
15235 | oindex:[%system_filter_file_transport%] | |
15236 | `..'= | |
15237 | %system_filter_file_transport%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
15238 | === | |
15239 | ||
15240 | cindex:[file,transport for system filter] | |
15241 | This sets the name of the transport driver that is to be used when the %save% | |
15242 | command in a system message filter specifies a path not ending in ``/''. During | |
15243 | the delivery, the variable $address_file$ contains the path name. | |
15244 | ||
15245 | oindex:[%system_filter_group%] | |
15246 | `..'= | |
15247 | %system_filter_group%, Use: 'main', Type: 'string', Default: 'unset' | |
15248 | === | |
15249 | ||
15250 | cindex:[gid (group id),system filter] | |
15251 | This option is used only when %system_filter_user% is also set. It sets the | |
15252 | gid under which the system filter is run, overriding any gid that is associated | |
15253 | with the user. The value may be numerical or symbolic. | |
15254 | ||
15255 | oindex:[%system_filter_pipe_transport%] | |
15256 | `..'= | |
15257 | %system_filter_pipe_transport%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
15258 | === | |
15259 | ||
15260 | cindex:[^pipe^ transport,for system filter] | |
068aaea8 | 15261 | cindex:[$address_pipe$] |
168e428f PH |
15262 | This specifies the transport driver that is to be used when a %pipe% command is |
15263 | used in a system filter. During the delivery, the variable $address_pipe$ | |
15264 | contains the pipe command. | |
15265 | ||
15266 | ||
15267 | oindex:[%system_filter_reply_transport%] | |
15268 | `..'= | |
15269 | %system_filter_reply_transport%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
15270 | === | |
15271 | ||
15272 | cindex:[^autoreply^ transport,for system filter] | |
15273 | This specifies the transport driver that is to be used when a %mail% command is | |
15274 | used in a system filter. | |
15275 | ||
15276 | oindex:[%system_filter_user%] | |
15277 | `..'= | |
15278 | %system_filter_user%, Use: 'main', Type: 'string', Default: 'unset' | |
15279 | === | |
15280 | ||
15281 | cindex:[uid (user id),system filter] | |
15282 | If this option is not set, the system filter is run in the main Exim delivery | |
15283 | process, as root. When the option is set, the system filter runs in a separate | |
15284 | process, as the given user. Unless the string consists entirely of digits, it | |
15285 | is looked up in the password data. Failure to find the named user causes a | |
15286 | configuration error. The gid is either taken from the password data, or | |
15287 | specified by %system_filter_group%. When the uid is specified numerically, | |
15288 | %system_filter_group% is required to be set. | |
15289 | ||
15290 | If the system filter generates any pipe, file, or reply deliveries, the uid | |
15291 | under which the filter is run is used when transporting them, unless a | |
15292 | transport option overrides. Normally you should set %system_filter_user% if | |
15293 | your system filter generates these kinds of delivery. | |
15294 | ||
15295 | ||
15296 | oindex:[%tcp_nodelay%] | |
15297 | `..'= | |
15298 | %tcp_nodelay%, Use: 'main', Type: 'boolean', Default: 'true' | |
15299 | === | |
15300 | ||
15301 | cindex:[daemon,TCP_NODELAY on sockets] | |
15302 | cindex:[Nagle algorithm] | |
15303 | cindex:[TCP_NODELAY on listening sockets] | |
15304 | If this option is set false, it stops the Exim daemon setting the | |
15305 | TCP_NODELAY option on its listening sockets. Setting TCP_NODELAY | |
15306 | turns off the ``Nagle algorithm'', which is a way of improving network | |
15307 | performance in interactive (character-by-character) situations. Turning it off | |
15308 | should improve Exim's performance a bit, so that is what happens by default. | |
15309 | However, it appears that some broken clients cannot cope, and time out. Hence | |
15310 | this option. It affects only those sockets that are set up for listening by the | |
15311 | daemon. Sockets created by the smtp transport for delivering mail always set | |
15312 | TCP_NODELAY. | |
15313 | ||
15314 | ||
15315 | oindex:[%timeout_frozen_after%] | |
15316 | `..'= | |
15317 | %timeout_frozen_after%, Use: 'main', Type: 'time', Default: '0s' | |
15318 | === | |
15319 | ||
15320 | cindex:[frozen messages,timing out] | |
15321 | cindex:[timeout,frozen messages] | |
15322 | If %timeout_frozen_after% is set to a time greater than zero, a frozen | |
15323 | message of any kind that has been on the queue for longer than the given | |
15324 | time is automatically cancelled at the next queue run. If it is a bounce | |
15325 | message, it is just discarded; otherwise, a bounce is sent to the sender, in a | |
15326 | similar manner to cancellation by the %-Mg% command line option. If you want | |
15327 | to timeout frozen bounce messages earlier than other kinds of frozen message, | |
15328 | see %ignore_bounce_errors_after%. | |
15329 | ||
15330 | ||
15331 | oindex:[%timezone%] | |
15332 | `..'= | |
15333 | %timezone%, Use: 'main', Type: 'string', Default: 'unset' | |
15334 | === | |
15335 | ||
15336 | cindex:[timezone, setting] | |
15337 | The value of %timezone% is used to set the environment variable TZ while | |
15338 | running Exim (if it is different on entry). This ensures that all timestamps | |
15339 | created by Exim are in the required timezone. If you want all your timestamps | |
15340 | to be in UTC (aka GMT) you should set | |
15341 | ||
15342 | timezone = UTC | |
15343 | ||
15344 | The default value is taken from TIMEZONE_DEFAULT in _Local/Makefile_, | |
15345 | or, if that is not set, from the value of the TZ environment variable when Exim | |
15346 | is built. If %timezone% is set to the empty string, either at build or run | |
15347 | time, any existing TZ variable is removed from the environment when Exim | |
15348 | runs. This is appropriate behaviour for obtaining wall-clock time on some, but | |
15349 | unfortunately not all, operating systems. | |
15350 | ||
15351 | ||
15352 | oindex:[%tls_advertise_hosts%] | |
15353 | `..'= | |
15354 | %tls_advertise_hosts%, Use: 'main', Type: 'host list'!!, Default: 'unset' | |
15355 | === | |
15356 | ||
15357 | cindex:[TLS,advertising] | |
15358 | cindex:[encryption,on SMTP connection] | |
15359 | cindex:[SMTP,encrypted connection] | |
15360 | When Exim is built with support for TLS encrypted connections, the availability | |
15361 | of the STARTTLS command to set up an encrypted session is advertised in | |
15362 | response to EHLO only to those client hosts that match this option. See | |
15363 | chapter <<CHAPTLS>> for details of Exim's support for TLS. | |
15364 | ||
15365 | ||
15366 | oindex:[%tls_certificate%] | |
15367 | `..'= | |
15368 | %tls_certificate%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
15369 | === | |
15370 | ||
15371 | cindex:[TLS,server certificate; location of] | |
15372 | cindex:[certificate for server, location of] | |
15373 | The value of this option is expanded, and must then be the absolute path to a | |
15374 | file which contains the server's certificates. The server's private key is also | |
15375 | assumed to be in this file if %tls_privatekey% is unset. See chapter <<CHAPTLS>> | |
15376 | for further details. | |
15377 | ||
15378 | *Note*: The certificates defined by this option are used only when Exim is | |
15379 | receiving incoming messages as a server. If you want to supply certificates for | |
15380 | use when sending messages as a client, you must set the %tls_certificate% | |
15381 | option in the relevant ^smtp^ transport. | |
15382 | ||
15383 | ||
15384 | oindex:[%tls_crl%] | |
15385 | `..'= | |
15386 | %tls_crl%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
15387 | === | |
15388 | ||
15389 | cindex:[TLS,server certificate revocation list] | |
15390 | cindex:[certificate,revocation list for server] | |
15391 | This option specifies a certificate revocation list. The expanded value must | |
15392 | be the name of a file that contains a CRL in PEM format. | |
15393 | ||
15394 | ||
15395 | oindex:[%tls_dhparam%] | |
15396 | `..'= | |
15397 | %tls_dhparam%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
15398 | === | |
15399 | ||
15400 | cindex:[TLS,D-H parameters for server] | |
15401 | The value of this option is expanded, and must then be the absolute path to | |
15402 | a file which contains the server's DH parameter values. | |
15403 | This is used only for OpenSSL. When Exim is linked with GnuTLS, this option is | |
15404 | ignored. See section <<SECTopenvsgnu>> for further details. | |
15405 | ||
15406 | ||
15407 | oindex:[%tls_on_connect_ports%] | |
15408 | `..'= | |
15409 | %tls_on_connect_ports%, Use: 'main', Type: 'string list', Default: 'unset' | |
15410 | === | |
15411 | ||
15412 | This option specifies a list of incoming SSMTP (aka SMTPS) ports that should | |
15413 | operate the obsolete SSMTP (SMTPS) protocol, where a TLS session is immediately | |
15414 | set up without waiting for the client to issue a STARTTLS command. For | |
15415 | further details, see section <<SECTsupobssmt>>. | |
15416 | ||
15417 | ||
15418 | ||
15419 | oindex:[%tls_privatekey%] | |
15420 | `..'= | |
15421 | %tls_privatekey%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
15422 | === | |
15423 | ||
15424 | cindex:[TLS,server private key; location of] | |
15425 | The value of this option is expanded, and must then be the absolute path to a | |
15426 | file which contains the server's private key. If this option is unset, the | |
15427 | private key is assumed to be in the same file as the server's certificates. See | |
15428 | chapter <<CHAPTLS>> for further details. | |
15429 | ||
15430 | ||
15431 | oindex:[%tls_remember_esmtp%] | |
15432 | `..'= | |
15433 | %tls_remember_esmtp%, Use: 'main', Type: 'boolean', Default: 'false' | |
15434 | === | |
15435 | ||
15436 | cindex:[TLS,esmtp state; remembering] | |
15437 | cindex:[TLS,broken clients] | |
15438 | If this option is set true, Exim violates the RFCs by remembering that it is in | |
15439 | ``esmtp'' state after successfully negotiating a TLS session. This provides | |
15440 | support for broken clients that fail to send a new EHLO after starting a | |
15441 | TLS session. | |
15442 | ||
15443 | ||
15444 | oindex:[%tls_require_ciphers%] | |
15445 | `..'= | |
15446 | %tls_require_ciphers%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
15447 | === | |
15448 | ||
15449 | cindex:[TLS,requiring specific ciphers] | |
15450 | cindex:[cipher,requiring specific] | |
15451 | This option controls which ciphers can be used for incoming TLS connections. | |
15452 | The ^smtp^ transport has an option of the same name for controlling outgoing | |
15453 | connections. This option is expanded for each connection, so can be varied for | |
15454 | different clients if required. The value of this option must be a list of | |
15455 | permitted cipher suites. The OpenSSL and GnuTLS libraries handle cipher control | |
15456 | in somewhat different ways. | |
15457 | ||
15458 | If GnuTLS is being used, the client controls the preference order of the | |
15459 | available ciphers. | |
15460 | ||
15461 | Details are given in sections <<SECTreqciphssl>> and <<SECTreqciphgnu>>. | |
15462 | ||
15463 | ||
15464 | oindex:[%tls_try_verify_hosts%] | |
15465 | `..'= | |
15466 | %tls_try_verify_hosts%, Use: 'main', Type: 'host list'!!, Default: 'unset' | |
15467 | === | |
15468 | ||
15469 | cindex:[TLS,client certificate verification] | |
15470 | cindex:[certificate,verification of client] | |
15471 | See %tls_verify_hosts% below. | |
15472 | ||
15473 | ||
15474 | oindex:[%tls_verify_certificates%] | |
15475 | `..'= | |
15476 | %tls_verify_certificates%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
15477 | === | |
15478 | ||
15479 | cindex:[TLS,client certificate verification] | |
15480 | cindex:[certificate,verification of client] | |
15481 | The value of this option is expanded, and must then be the absolute path to | |
15482 | a file containing permitted certificates for clients that | |
15483 | match %tls_verify_hosts% or %tls_try_verify_hosts%. Alternatively, if you | |
15484 | are using OpenSSL, you can set %tls_verify_certificates% to the name of a | |
15485 | directory containing certificate files. This does not work with GnuTLS; the | |
15486 | option must be set to the name of a single file if you are using GnuTLS. | |
15487 | ||
15488 | ||
15489 | oindex:[%tls_verify_hosts%] | |
15490 | `..'= | |
15491 | %tls_verify_hosts%, Use: 'main', Type: 'host list'!!, Default: 'unset' | |
15492 | === | |
15493 | ||
15494 | cindex:[TLS,client certificate verification] | |
15495 | cindex:[certificate,verification of client] | |
15496 | This option, along with %tls_try_verify_hosts%, controls the checking of | |
15497 | certificates from clients. | |
15498 | The expected certificates are defined by %tls_verify_certificates%, which | |
15499 | must be set. A configuration error occurs if either %tls_verify_hosts% or | |
15500 | %tls_try_verify_hosts% is set and %tls_verify_certificates% is not set. | |
15501 | ||
15502 | Any client that matches %tls_verify_hosts% is constrained by | |
15503 | %tls_verify_certificates%. The client must present one of the listed | |
15504 | certificates. If it does not, the connection is aborted. | |
15505 | ||
15506 | A weaker form of checking is provided by %tls_try_verify_hosts%. If a client | |
15507 | matches this option (but not %tls_verify_hosts%), Exim requests a | |
15508 | certificate and checks it against %tls_verify_certificates%, but does not | |
15509 | abort the connection if there is no certificate or if it does not match. This | |
15510 | state can be detected in an ACL, which makes it possible to implement policies | |
15511 | such as ``accept for relay only if a verified certificate has been received, but | |
15512 | accept for local delivery if encrypted, even without a verified certificate''. | |
15513 | ||
15514 | Client hosts that match neither of these lists are not asked to present | |
15515 | certificates. | |
15516 | ||
15517 | ||
15518 | oindex:[%trusted_groups%] | |
15519 | `..'= | |
068aaea8 | 15520 | %trusted_groups%, Use: 'main', Type: 'string list'!!, Default: 'unset' |
168e428f PH |
15521 | === |
15522 | ||
068aaea8 | 15523 | [revisionflag="changed"] |
168e428f PH |
15524 | cindex:[trusted group] |
15525 | cindex:[group,trusted] | |
068aaea8 PH |
15526 | This option is expanded just once, at the start of Exim's processing. If this |
15527 | option is set, any process that is running in one of the listed groups, or | |
15528 | which has one of them as a supplementary group, is trusted. The groups can be | |
15529 | specified numerically or by name. See section <<SECTtrustedadmin>> for details | |
15530 | of what trusted callers are permitted to do. If neither %trusted_groups% nor | |
15531 | %trusted_users% is set, only root and the Exim user are trusted. | |
168e428f PH |
15532 | |
15533 | ||
15534 | oindex:[%trusted_users%] | |
15535 | `..'= | |
068aaea8 | 15536 | %trusted_users%, Use: 'main', Type: 'string list'!!, Default: 'unset' |
168e428f PH |
15537 | === |
15538 | ||
068aaea8 | 15539 | [revisionflag="changed"] |
168e428f PH |
15540 | cindex:[trusted user] |
15541 | cindex:[user,trusted] | |
068aaea8 PH |
15542 | This option is expanded just once, at the start of Exim's processing. If this |
15543 | option is set, any process that is running as one of the listed users is | |
15544 | trusted. The users can be specified numerically or by name. See section | |
15545 | <<SECTtrustedadmin>> for details of what trusted callers are permitted to do. | |
15546 | If neither %trusted_groups% nor %trusted_users% is set, only root and the Exim | |
15547 | user are trusted. | |
168e428f PH |
15548 | |
15549 | oindex:[%unknown_login%] | |
15550 | `..'= | |
15551 | %unknown_login%, Use: 'main', Type: 'string'!!, Default: 'unset' | |
15552 | === | |
15553 | ||
15554 | cindex:[uid (user id),unknown caller] | |
068aaea8 | 15555 | cindex:[$caller_uid$] |
168e428f PH |
15556 | This is a specialized feature for use in unusual configurations. By default, if |
15557 | the uid of the caller of Exim cannot be looked up using 'getpwuid()', Exim | |
15558 | gives up. The %unknown_login% option can be used to set a login name to be | |
15559 | used in this circumstance. It is expanded, so values like %user\$caller_uid% | |
15560 | can be set. When %unknown_login% is used, the value of %unknown_username% is | |
15561 | used for the user's real name (gecos field), unless this has been set by the | |
15562 | %-F% option. | |
15563 | ||
15564 | ||
15565 | oindex:[%unknown_username%] | |
15566 | `..'= | |
15567 | %unknown_username%, Use: 'main', Type: 'string', Default: 'unset' | |
15568 | === | |
15569 | ||
15570 | See %unknown_login%. | |
15571 | ||
15572 | ||
15573 | oindex:[%untrusted_set_sender%] | |
15574 | `..'= | |
15575 | %untrusted_set_sender%, Use: 'main', Type: 'address list'!!, Default: 'unset' | |
15576 | === | |
15577 | ||
15578 | cindex:[trusted user] | |
15579 | cindex:[sender,setting by untrusted user] | |
15580 | cindex:[untrusted user, setting sender] | |
15581 | cindex:[user,untrusted setting sender] | |
15582 | cindex:[envelope sender] | |
15583 | When an untrusted user submits a message to Exim using the standard input, Exim | |
15584 | normally creates an envelope sender address from the user's login and the | |
15585 | default qualification domain. Data from the %-f% option (for setting envelope | |
15586 | senders on non-SMTP messages) or the SMTP MAIL command (if %-bs% or %-bS% | |
15587 | is used) is ignored. | |
15588 | ||
15589 | However, untrusted users are permitted to set an empty envelope sender address, | |
15590 | to declare that a message should never generate any bounces. For example: | |
15591 | ||
15592 | exim -f '<>' user@domain.example | |
15593 | ||
068aaea8 | 15594 | cindex:[$sender_ident$] |
168e428f PH |
15595 | The %untrusted_set_sender% option allows you to permit untrusted users to set |
15596 | other envelope sender addresses in a controlled way. When it is set, untrusted | |
15597 | users are allowed to set envelope sender addresses that match any of the | |
15598 | patterns in the list. Like all address lists, the string is expanded. The | |
15599 | identity of the user is in $sender_ident$, so you can, for example, restrict | |
15600 | users to setting senders that start with their login ids | |
15601 | followed by a hyphen | |
15602 | by a setting like this: | |
15603 | ||
15604 | untrusted_set_sender = ^$sender_ident- | |
15605 | ||
15606 | If you want to allow untrusted users to set envelope sender addresses without | |
15607 | restriction, you can use | |
15608 | ||
15609 | untrusted_set_sender = * | |
15610 | ||
15611 | The %untrusted_set_sender% option applies to all forms of local input, but | |
15612 | only to the setting of the envelope sender. It does not permit untrusted users | |
15613 | to use the other options which trusted user can use to override message | |
15614 | parameters. Furthermore, it does not stop Exim from removing an existing | |
15615 | 'Sender:' header in the message, or from adding a 'Sender:' header if | |
15616 | necessary. See %local_sender_retain% and %local_from_check% for ways of | |
15617 | overriding these actions. The handling of the 'Sender:' header is also | |
15618 | described in section <<SECTthesenhea>>. | |
15619 | ||
15620 | The log line for a message's arrival shows the envelope sender following ``<=''. | |
15621 | For local messages, the user's login always follows, after ``U=''. In %-bp% | |
15622 | displays, and in the Exim monitor, if an untrusted user sets an envelope sender | |
15623 | address, the user's login is shown in parentheses after the sender address. | |
15624 | ||
15625 | ||
15626 | oindex:[%uucp_from_pattern%] | |
15627 | `..'= | |
15628 | %uucp_from_pattern%, Use: 'main', Type: 'string', Default: 'see below' | |
15629 | === | |
15630 | ||
15631 | cindex:[``From'' line] | |
15632 | cindex:[UUCP,``From'' line] | |
15633 | Some applications that pass messages to an MTA via a command line interface use | |
15634 | an initial line starting with ``From'' to pass the envelope sender. In | |
15635 | particular, this is used by UUCP software. Exim recognizes such a line by means | |
15636 | of a regular expression that is set in %uucp_from_pattern%. When the pattern | |
15637 | matches, the sender address is constructed by expanding the contents of | |
15638 | %uucp_from_sender%, provided that the caller of Exim is a trusted user. The | |
15639 | default pattern recognizes lines in the following two forms: | |
15640 | ||
15641 | From ph10 Fri Jan 5 12:35 GMT 1996 | |
15642 | From ph10 Fri, 7 Jan 97 14:00:00 GMT | |
15643 | ||
15644 | The pattern can be seen by running | |
15645 | ||
15646 | exim -bP uucp_from_pattern | |
15647 | ||
15648 | It checks only up to the hours and minutes, and allows for a 2-digit or 4-digit | |
15649 | year in the second case. The first word after ``From'' is matched in the regular | |
15650 | expression by a parenthesized subpattern. The default value for | |
068aaea8 PH |
15651 | %uucp_from_sender% is ``$1'', which therefore just uses this first word |
15652 | (``ph10'' in the example above) as the message's sender. See also | |
168e428f PH |
15653 | %ignore_fromline_hosts%. |
15654 | ||
15655 | ||
15656 | oindex:[%uucp_from_sender%] | |
15657 | `..'= | |
15658 | %uucp_from_sender%, Use: 'main', Type: 'string'!!, Default: `\$1` | |
15659 | === | |
15660 | ||
15661 | See %uucp_from_pattern% above. | |
15662 | ||
15663 | ||
15664 | oindex:[%warn_message_file%] | |
15665 | `..'= | |
15666 | %warn_message_file%, Use: 'main', Type: 'string', Default: 'unset' | |
15667 | === | |
15668 | ||
15669 | cindex:[warning of delay,customizing the message] | |
15670 | cindex:[customizing,warning message] | |
15671 | This option defines a template file containing paragraphs of text to be used | |
15672 | for constructing the warning message which is sent by Exim when a message has | |
15673 | been on the queue for a specified amount of time, as specified by | |
15674 | %delay_warning%. Details of the file's contents are given in chapter | |
15675 | <<CHAPemsgcust>>. See also %bounce_message_file%. | |
15676 | ||
15677 | ||
15678 | oindex:[%write_rejectlog%] | |
15679 | `..'= | |
15680 | %write_rejectlog%, Use: 'main', Type: 'boolean', Default: 'true' | |
15681 | === | |
15682 | ||
15683 | cindex:[reject log,disabling] | |
15684 | If this option is set false, Exim no longer writes anything to the reject log. | |
15685 | See chapter <<CHAPlog>> for details of what Exim writes to its logs. | |
15686 | ||
15687 | ||
15688 | ||
15689 | ||
15690 | //////////////////////////////////////////////////////////////////////////// | |
15691 | //////////////////////////////////////////////////////////////////////////// | |
15692 | ||
15693 | [[CHAProutergeneric]] | |
15694 | Generic options for routers | |
15695 | --------------------------- | |
15696 | cindex:[options,generic; for routers] | |
15697 | cindex:[generic options,router] | |
15698 | This chapter describes the generic options that apply to all routers. | |
15699 | Those that are preconditions are marked with !? in the ``use'' field. | |
15700 | ||
15701 | For a general description of how a router operates, see sections | |
15702 | <<SECTrunindrou>> and <<SECTrouprecon>>. The latter specifies the order in | |
15703 | which the preconditions are tested. The order of expansion of the options that | |
15704 | provide data for a transport is: %errors_to%, %headers_add%, %headers_remove%, | |
15705 | %transport%. | |
15706 | ||
15707 | ||
15708 | ||
15709 | oindex:[%address_data%] | |
15710 | `..'= | |
15711 | %address_data%, Use: 'routers', Type: 'string'!!, Default: 'unset' | |
15712 | === | |
15713 | ||
068aaea8 | 15714 | [revisionflag="changed"] |
168e428f PH |
15715 | cindex:[router,data attached to address] |
15716 | The string is expanded just before the router is run, that is, after all the | |
15717 | precondition tests have succeeded. If the expansion is forced to fail, the | |
068aaea8 PH |
15718 | router declines, the value of %address_data% remains unchanged, and the %more% |
15719 | option controls what happens next. Other expansion failures cause delivery of | |
15720 | the address to be deferred. | |
168e428f | 15721 | |
068aaea8 | 15722 | cindex:[$address_data$] |
168e428f PH |
15723 | When the expansion succeeds, the value is retained with the address, and can be |
15724 | accessed using the variable $address_data$ in the current router, subsequent | |
15725 | routers, and the eventual transport. | |
15726 | ||
15727 | *Warning*: if the current or any subsequent router is a ^redirect^ router | |
068aaea8 PH |
15728 | that runs a user's filter file, the contents of $address_data$ are accessible |
15729 | in the filter. This is not normally a problem, because such data is usually | |
15730 | either not confidential or it ``belongs'' to the current user, but if you do | |
15731 | put confidential data into $address_data$ you need to remember this point. | |
168e428f PH |
15732 | |
15733 | Even if the router declines or passes, the value of $address_data$ remains | |
15734 | with the address, though it can be changed by another %address_data% setting | |
15735 | on a subsequent router. If a router generates child addresses, the value of | |
15736 | $address_data$ propagates to them. This also applies to the special kind of | |
15737 | ``child'' that is generated by a router with the %unseen% option. | |
15738 | ||
15739 | The idea of %address_data% is that you can use it to look up a lot of data for | |
15740 | the address once, and then pick out parts of the data later. For example, you | |
15741 | could use a single LDAP lookup to return a string of the form | |
15742 | ||
15743 | uid=1234 gid=5678 mailbox=/mail/xyz forward=/home/xyz/.forward | |
15744 | ||
15745 | In the transport you could pick out the mailbox by a setting such as | |
15746 | ||
15747 | file = ${extract{mailbox}{$address_data}} | |
15748 | ||
15749 | This makes the configuration file less messy, and also reduces the number of | |
15750 | lookups (though Exim does cache lookups). | |
15751 | ||
15752 | The %address_data% facility is also useful as a means of passing information | |
15753 | from one router to another, and from a router to a transport. In addition, if | |
15754 | ||
068aaea8 PH |
15755 | cindex:[$sender_address_data$] |
15756 | cindex:[$address_data$] | |
15757 | When $address_data$ is set by a router when verifying a recipient address from | |
15758 | an ACL, it remains available for use in the rest of the ACL statement. After | |
168e428f PH |
15759 | verifying a sender, the value is transferred to $sender_address_data$. |
15760 | ||
15761 | ||
15762 | ||
15763 | ||
15764 | oindex:[%address_test%] | |
15765 | `..'= | |
15766 | %address_test%, Use: 'routers'!?, Type: 'boolean', Default: 'true' | |
15767 | === | |
15768 | ||
15769 | cindex:[%-bt% option] | |
15770 | cindex:[router,skipping when address testing] | |
15771 | If this option is set false, the router is skipped when routing is being tested | |
15772 | by means of the %-bt% command line option. This can be a convenience when your | |
15773 | first router sends messages to an external scanner, because it saves you | |
15774 | having to set the ``already scanned'' indicator when testing real address | |
15775 | routing. | |
15776 | ||
15777 | ||
15778 | ||
15779 | oindex:[%cannot_route_message%] | |
15780 | `..'= | |
15781 | %cannot_route_message%, Use: 'routers', Type: 'string'!!, Default: 'unset' | |
15782 | === | |
15783 | ||
15784 | cindex:[router,customizing ``cannot route'' message] | |
15785 | cindex:[customizing,``cannot route'' message] | |
15786 | This option specifies a text message that is used when an address cannot be | |
15787 | routed because Exim has run out of routers. The default message is ``Unrouteable | |
15788 | address''. This option is useful only on routers that have %more% set false, or | |
15789 | on the very last router in a configuration, because the value that is used is | |
15790 | taken from the last router that inspects an address. For example, using the | |
15791 | default configuration, you could put: | |
15792 | ||
15793 | cannot_route_message = Remote domain not found in DNS | |
15794 | ||
15795 | on the first (^dnslookup^) router, and | |
15796 | ||
15797 | cannot_route_message = Unknown local user | |
15798 | ||
15799 | on the final router that checks for local users. If string expansion fails, the | |
15800 | default message is used. | |
15801 | Unless the expansion failure was explicitly forced, a message about the failure | |
15802 | is written to the main and panic logs, in addition to the normal message about | |
15803 | the routing failure. | |
15804 | ||
15805 | ||
15806 | oindex:[%caseful_local_part%] | |
15807 | `..'= | |
15808 | %caseful_local_part%, Use: 'routers', Type: 'boolean', Default: 'false' | |
15809 | === | |
15810 | ||
15811 | cindex:[case of local parts] | |
15812 | cindex:[router,case of local parts] | |
15813 | By default, routers handle the local parts of addresses in a case-insensitive | |
15814 | manner, though the actual case is preserved for transmission with the message. | |
15815 | If you want the case of letters to be significant in a router, you must set | |
15816 | this option true. For individual router options that contain address or local | |
15817 | part lists (for example, %local_parts%), case-sensitive matching can be turned | |
15818 | on by ``+caseful'' as a list item. See section <<SECTcasletadd>> for more details. | |
15819 | ||
068aaea8 PH |
15820 | cindex:[$local_part$] |
15821 | cindex:[$original_local_part$] | |
15822 | cindex:[$parent_local_part$] | |
168e428f PH |
15823 | The value of the $local_part$ variable is forced to lower case while a |
15824 | router is running unless %caseful_local_part% is set. When a router assigns | |
15825 | an address to a transport, the value of $local_part$ when the transport runs | |
15826 | is the same as it was in the router. Similarly, when a router generates child | |
15827 | addresses by aliasing or forwarding, the values of $original_local_part$ | |
15828 | and $parent_local_part$ are those that were used by the redirecting router. | |
15829 | ||
15830 | This option applies to the processing of an address by a router. When a | |
15831 | recipient address is being processed in an ACL, there is a separate %control% | |
15832 | modifier that can be used to specify case-sensitive processing within the ACL | |
15833 | (see section <<SECTcontrols>>). | |
15834 | ||
15835 | ||
15836 | ||
15837 | oindex:[%check_local_user%] | |
15838 | `..'= | |
15839 | %check_local_user%, Use: 'routers'!?, Type: 'boolean', Default: 'false' | |
15840 | === | |
15841 | ||
15842 | cindex:[local user, checking in router] | |
15843 | cindex:[router,checking for local user] | |
15844 | cindex:[_/etc/passwd_] | |
068aaea8 | 15845 | cindex:[$home$] |
168e428f PH |
15846 | When this option is true, Exim checks that the local part of the recipient |
15847 | address (with affixes removed if relevant) is the name of an account on the | |
15848 | local system. The check is done by calling the 'getpwnam()' function rather | |
15849 | than trying to read _/etc/passwd_ directly. This means that other methods of | |
15850 | holding password data (such as NIS) are supported. If the local part is a local | |
15851 | user, $home$ is set from the password data, and can be tested in other | |
15852 | preconditions that are evaluated after this one (the order of evaluation is | |
15853 | given in section <<SECTrouprecon>>). However, the value of $home$ can be | |
15854 | overridden by %router_home_directory%. If the local part is not a local user, | |
15855 | the router is skipped. | |
15856 | ||
15857 | If you want to check that the local part is either the name of a local user | |
15858 | or matches something else, you cannot combine %check_local_user% with a | |
15859 | setting of %local_parts%, because that specifies the logical 'and' of the | |
15860 | two conditions. However, you can use a ^passwd^ lookup in a %local_parts% | |
15861 | setting to achieve this. For example: | |
15862 | ||
15863 | local_parts = passwd;$local_part : lsearch;/etc/other/users | |
15864 | ||
15865 | Note, however, that the side effects of %check_local_user% (such as setting | |
15866 | up a home directory) do not occur when a ^passwd^ lookup is used in a | |
15867 | %local_parts% (or any other) precondition. | |
15868 | ||
15869 | ||
15870 | ||
15871 | oindex:[%condition%] | |
15872 | `..'= | |
15873 | %condition%, Use: 'routers'!?, Type: 'string'!!, Default: 'unset' | |
15874 | === | |
15875 | ||
15876 | cindex:[router,customized precondition] | |
15877 | This option specifies a general precondition test that has to succeed for the | |
15878 | router to be called. The %condition% option is the last precondition to be | |
15879 | evaluated (see section <<SECTrouprecon>>). The string is expanded, and if the | |
15880 | result is a forced failure, or an empty string, or one of the strings ``0'' or | |
15881 | ``no'' or ``false'' (checked without regard to the case of the letters), the router | |
15882 | is skipped, and the address is offered to the next one. | |
15883 | ||
15884 | If the result is any other value, the router is run (as this is the last | |
15885 | precondition to be evaluated, all the other preconditions must be true). | |
15886 | ||
15887 | The %condition% option provides a means of applying custom conditions to the | |
15888 | running of routers. Note that in the case of a simple conditional expansion, | |
15889 | the default expansion values are exactly what is wanted. For example: | |
15890 | ||
15891 | condition = ${if >{$message_age}{600}} | |
15892 | ||
15893 | Because of the default behaviour of the string expansion, this is equivalent to | |
15894 | ||
15895 | condition = ${if >{$message_age}{600}{true}{}} | |
15896 | ||
15897 | ||
15898 | If the expansion fails (other than forced failure) delivery is deferred. Some | |
15899 | of the other precondition options are common special cases that could in fact | |
15900 | be specified using %condition%. | |
15901 | ||
15902 | ||
15903 | ||
15904 | oindex:[%debug_print%] | |
15905 | `..'= | |
15906 | %debug_print%, Use: 'routers', Type: 'string'!!, Default: 'unset' | |
15907 | === | |
15908 | ||
15909 | cindex:[testing,variables in drivers] | |
15910 | If this option is set and debugging is enabled (see the %-d% command line | |
15911 | option), the string is expanded and included in the debugging output. | |
15912 | If expansion of the string fails, the error message is written to the debugging | |
15913 | output, and Exim carries on processing. | |
15914 | This option is provided to help with checking out the values of variables and | |
15915 | so on when debugging router configurations. For example, if a %condition% | |
15916 | option appears not to be working, %debug_print% can be used to output the | |
15917 | variables it references. The output happens after checks for %domains%, | |
15918 | %local_parts%, and %check_local_user% but before any other preconditions are | |
15919 | tested. A newline is added to the text if it does not end with one. | |
15920 | ||
15921 | ||
15922 | ||
15923 | oindex:[%disable_logging%] | |
15924 | `..'= | |
15925 | %disable_logging%, Use: 'routers', Type: 'boolean', Default: 'false' | |
15926 | === | |
15927 | ||
15928 | If this option is set true, nothing is logged for any routing errors | |
15929 | or for any deliveries caused by this router. You should not set this option | |
15930 | unless you really, really know what you are doing. See also the generic | |
15931 | transport option of the same name. | |
15932 | ||
15933 | ||
15934 | oindex:[%domains%] | |
15935 | `..'= | |
15936 | %domains%, Use: 'routers'!?, Type: 'domain list'!!, Default: 'unset' | |
15937 | === | |
15938 | ||
15939 | cindex:[router,restricting to specific domains] | |
068aaea8 | 15940 | cindex:[$domain_data$] |
168e428f PH |
15941 | If this option is set, the router is skipped unless the current domain matches |
15942 | the list. If the match is achieved by means of a file lookup, the data that the | |
15943 | lookup returned for the domain is placed in $domain_data$ for use in string | |
068aaea8 PH |
15944 | expansions of the driver's private options. See section <<SECTrouprecon>> for a |
15945 | list of the order in which preconditions are evaluated. | |
168e428f PH |
15946 | |
15947 | ||
15948 | ||
15949 | oindex:[%driver%] | |
15950 | `..'= | |
15951 | %driver%, Use: 'routers', Type: 'string', Default: 'unset' | |
15952 | === | |
15953 | ||
15954 | This option must always be set. It specifies which of the available routers is | |
15955 | to be used. | |
15956 | ||
15957 | ||
15958 | ||
15959 | oindex:[%errors_to%] | |
15960 | `..'= | |
15961 | %errors_to%, Use: 'routers', Type: 'string'!!, Default: 'unset' | |
15962 | === | |
15963 | ||
15964 | cindex:[envelope sender] | |
15965 | cindex:[router,changing address for errors] | |
15966 | If a router successfully handles an address, it may queue the address for | |
15967 | delivery or it may generate child addresses. In both cases, if there is a | |
15968 | delivery problem during later processing, the resulting bounce message is sent | |
15969 | to the address that results from expanding this string, provided that the | |
d1e83bff PH |
15970 | address verifies successfully. %errors_to% is expanded before %headers_add%, |
15971 | %headers_remove%, and %transport%. | |
168e428f PH |
15972 | |
15973 | If the option is unset, or the expansion is forced to fail, or the result of | |
15974 | the expansion fails to verify, the errors address associated with the incoming | |
15975 | address is used. At top level, this is the envelope sender. A non-forced | |
15976 | expansion failure causes delivery to be deferred. | |
15977 | ||
15978 | If an address for which %errors_to% has been set ends up being delivered over | |
15979 | SMTP, the envelope sender for that delivery is the %errors_to% value, so that | |
15980 | any bounces that are generated by other MTAs on the delivery route are also | |
15981 | sent there. The most common use of %errors_to% is probably to direct mailing | |
15982 | list bounces to the manager of the list, as described in section | |
15983 | <<SECTmailinglists>>. | |
15984 | ||
15985 | The %errors_to% setting associated with an address can be overridden if it | |
15986 | subsequently passes through other routers that have their own %errors_to% | |
15987 | settings, | |
15988 | or if it is delivered by a transport with a %return_path% setting. | |
15989 | ||
15990 | You can set %errors_to% to the empty string by either of these settings: | |
15991 | ||
15992 | errors_to = | |
15993 | errors_to = "" | |
15994 | ||
15995 | An expansion item that yields an empty string has the same effect. If you do | |
15996 | this, a locally detected delivery error for addresses processed by this router | |
15997 | no longer gives rise to a bounce message; the error is discarded. If the | |
15998 | address is delivered to a remote host, the return path is set to `<>`, unless | |
15999 | overridden by the %return_path% option on the transport. | |
16000 | ||
068aaea8 | 16001 | cindex:[$address_data$] |
168e428f PH |
16002 | If for some reason you want to discard local errors, but use a non-empty |
16003 | MAIL command for remote delivery, you can preserve the original return | |
16004 | path in $address_data$ in the router, and reinstate it in the transport by | |
16005 | setting %return_path%. | |
16006 | ||
16007 | ||
16008 | ||
16009 | oindex:[%expn%] | |
16010 | `..'= | |
16011 | %expn%, Use: 'routers'!?, Type: 'boolean', Default: 'true' | |
16012 | === | |
16013 | ||
16014 | cindex:[address,testing] | |
16015 | cindex:[testing,addresses] | |
16016 | cindex:[EXPN,router skipping] | |
16017 | cindex:[router,skipping for EXPN] | |
16018 | If this option is turned off, the router is skipped when testing an address | |
16019 | as a result of processing an SMTP EXPN command. You might, for example, | |
16020 | want to turn it off on a router for users' _.forward_ files, while leaving it | |
16021 | on for the system alias file. | |
16022 | See section <<SECTrouprecon>> for a list of the order in which preconditions | |
16023 | are evaluated. | |
16024 | ||
16025 | The use of the SMTP EXPN command is controlled by an ACL (see chapter | |
16026 | <<CHAPACL>>). When Exim is running an EXPN command, it is similar to testing | |
16027 | an address with %-bt%. Compare VRFY, whose counterpart is %-bv%. | |
16028 | ||
16029 | ||
16030 | ||
16031 | oindex:[%fail_verify%] | |
16032 | `..'= | |
16033 | %fail_verify%, Use: 'routers', Type: 'boolean', Default: 'false' | |
16034 | === | |
16035 | ||
16036 | cindex:[router,forcing verification failure] | |
16037 | Setting this option has the effect of setting both %fail_verify_sender% and | |
16038 | %fail_verify_recipient% to the same value. | |
16039 | ||
16040 | ||
16041 | ||
16042 | oindex:[%fail_verify_recipient%] | |
16043 | `..'= | |
16044 | %fail_verify_recipient%, Use: 'routers', Type: 'boolean', Default: 'false' | |
16045 | === | |
16046 | ||
16047 | If this option is true and an address is accepted by this router when | |
16048 | verifying a recipient, verification fails. | |
16049 | ||
16050 | ||
16051 | ||
16052 | oindex:[%fail_verify_sender%] | |
16053 | `..'= | |
16054 | %fail_verify_sender%, Use: 'routers', Type: 'boolean', Default: 'false' | |
16055 | === | |
16056 | ||
16057 | If this option is true and an address is accepted by this router when | |
16058 | verifying a sender, verification fails. | |
16059 | ||
16060 | ||
16061 | ||
16062 | oindex:[%fallback_hosts%] | |
16063 | `..'= | |
16064 | %fallback_hosts%, Use: 'routers', Type: 'string list', Default: 'unset' | |
16065 | === | |
16066 | ||
068aaea8 | 16067 | [revisionflag="changed"] |
168e428f PH |
16068 | cindex:[router,fallback hosts] |
16069 | cindex:[fallback,hosts specified on router] | |
16070 | String expansion is not applied to this option. The argument must be a | |
068aaea8 PH |
16071 | colon-separated list of host names or IP addresses. The list separator can be |
16072 | changed (see section <<SECTlistconstruct>>), and a port can be specified with | |
16073 | each name or address. In fact, the format of each item is exactly the same as | |
16074 | defined for the list of hosts in a ^manualroute^ router (see section | |
16075 | <<SECTformatonehostitem>>). | |
16076 | ||
16077 | If a router queues an address for a remote transport, this host list is | |
16078 | associated with the address, and used instead of the transport's fallback host | |
16079 | list. If %hosts_randomize% is set on the transport, the order of the list is | |
16080 | randomized for each use. See the %fallback_hosts% option of the ^smtp^ | |
16081 | transport for further details. | |
168e428f PH |
16082 | |
16083 | ||
16084 | oindex:[%group%] | |
16085 | `..'= | |
16086 | %group%, Use: 'routers', Type: 'string'!!, Default: 'see below' | |
16087 | === | |
16088 | ||
16089 | cindex:[gid (group id),local delivery] | |
16090 | cindex:[local transports,uid and gid] | |
16091 | cindex:[transport,local] | |
16092 | cindex:[router,setting group] | |
16093 | When a router queues an address for a transport, and the transport does not | |
16094 | specify a group, the group given here is used when running the delivery | |
16095 | process. | |
16096 | The group may be specified numerically or by name. If expansion fails, the | |
16097 | error is logged and delivery is deferred. | |
16098 | The default is unset, unless %check_local_user% is set, when the default | |
16099 | is taken from the password information. See also %initgroups% and %user% and | |
16100 | the discussion in chapter <<CHAPenvironment>>. | |
16101 | ||
16102 | ||
16103 | ||
16104 | oindex:[%headers_add%] | |
16105 | `..'= | |
16106 | %headers_add%, Use: 'routers', Type: 'string'!!, Default: 'unset' | |
16107 | === | |
16108 | ||
d1e83bff | 16109 | [revisionflag="changed"] |
168e428f PH |
16110 | cindex:[header lines,adding] |
16111 | cindex:[router,adding header lines] | |
16112 | This option specifies a string of text that is expanded at routing time, and | |
16113 | associated with any addresses that are accepted by the router. However, this | |
16114 | option has no effect when an address is just being verified. The way in which | |
16115 | the text is used to add header lines at transport time is described in section | |
d1e83bff PH |
16116 | <<SECTheadersaddrem>>. New header lines are not actually added until the |
16117 | message is in the process of being transported. This means that references to | |
16118 | header lines in string expansions in the transport's configuration do not | |
16119 | ``see'' the added header lines. | |
168e428f PH |
16120 | |
16121 | The %headers_add% option is expanded after %errors_to%, but before | |
16122 | %headers_remove% and %transport%. If the expanded string is empty, or if the | |
16123 | expansion is forced to fail, the option has no effect. Other expansion failures | |
16124 | are treated as configuration errors. | |
16125 | ||
068aaea8 | 16126 | *Warning 1*: The %headers_add% option cannot be used for a ^redirect^ |
168e428f PH |
16127 | router that has the %one_time% option set. |
16128 | ||
068aaea8 PH |
16129 | [revisionflag="changed"] |
16130 | *Warning 2*: If the %unseen% option is set on the router, all header additions | |
16131 | are deleted when the address is passed on to subsequent routers. | |
16132 | ||
168e428f PH |
16133 | |
16134 | ||
16135 | ||
16136 | oindex:[%headers_remove%] | |
16137 | `..'= | |
16138 | %headers_remove%, Use: 'routers', Type: 'string'!!, Default: 'unset' | |
16139 | === | |
16140 | ||
d1e83bff | 16141 | [revisionflag="changed"] |
168e428f PH |
16142 | cindex:[header lines,removing] |
16143 | cindex:[router,removing header lines] | |
16144 | This option specifies a string of text that is expanded at routing time, and | |
16145 | associated with any addresses that are accepted by the router. However, this | |
16146 | option has no effect when an address is just being verified. The way in which | |
16147 | the text is used to remove header lines at transport time is described in | |
d1e83bff PH |
16148 | section <<SECTheadersaddrem>>. Header lines are not actually removed until the |
16149 | message is in the process of being transported. This means that references to | |
16150 | header lines in string expansions in the transport's configuration still | |
16151 | ``see'' the original header lines. | |
168e428f PH |
16152 | |
16153 | The %headers_remove% option is expanded after %errors_to% and %headers_add%, | |
16154 | but before %transport%. If the expansion is forced to fail, the option has no | |
16155 | effect. Other expansion failures are treated as configuration errors. | |
16156 | ||
068aaea8 | 16157 | *Warning 1*: The %headers_remove% option cannot be used for a ^redirect^ |
168e428f PH |
16158 | router that has the %one_time% option set. |
16159 | ||
068aaea8 PH |
16160 | [revisionflag="changed"] |
16161 | *Warning 2*: If the %unseen% option is set on the router, all header removal | |
16162 | requests are deleted when the address is passed on to subsequent routers. | |
168e428f PH |
16163 | |
16164 | ||
16165 | ||
16166 | oindex:[%ignore_target_hosts%] | |
16167 | `..'= | |
16168 | %ignore_target_hosts%, Use: 'routers', Type: 'host list'!!, Default: 'unset' | |
16169 | === | |
16170 | ||
16171 | cindex:[IP address,discarding] | |
16172 | cindex:[router,discarding IP addresses] | |
16173 | Although this option is a host list, it should normally contain IP address | |
16174 | entries rather than names. If any host that is looked up by the router has an | |
16175 | IP address that matches an item in this list, Exim behaves as if that IP | |
16176 | address did not exist. This option allows you to cope with rogue DNS entries | |
16177 | like | |
16178 | ||
16179 | remote.domain.example. A 127.0.0.1 | |
16180 | ||
16181 | by setting | |
16182 | ||
16183 | ignore_target_hosts = 127.0.0.1 | |
16184 | ||
16185 | on the relevant router. If all the hosts found by a ^dnslookup^ router are | |
16186 | discarded in this way, the router declines. In a conventional configuration, an | |
16187 | attempt to mail to such a domain would normally provoke the ``unrouteable | |
16188 | domain'' error, and an attempt to verify an address in the domain would fail. | |
16189 | ||
16190 | Similarly, if %ignore_target_hosts% is set on an ^ipliteral^ router, the | |
16191 | router declines if presented with one of the listed addresses. | |
16192 | ||
16193 | This option may also be useful for ignoring link-local and site-local IPv6 | |
16194 | addresses. Because, like all host lists, the value of %ignore_target_hosts% | |
16195 | is expanded before use as a list, it is possible to make it dependent on the | |
16196 | domain that is being routed. | |
16197 | ||
068aaea8 | 16198 | cindex:[$host_address$] |
168e428f PH |
16199 | During its expansion, $host_address$ is set to the IP address that is being |
16200 | checked. | |
16201 | ||
16202 | oindex:[%initgroups%] | |
16203 | `..'= | |
16204 | %initgroups%, Use: 'routers', Type: 'boolean', Default: 'false' | |
16205 | === | |
16206 | ||
16207 | cindex:[additional groups] | |
16208 | cindex:[groups, additional] | |
16209 | cindex:[local transports,uid and gid] | |
16210 | cindex:[transport,local] | |
16211 | If the router queues an address for a transport, and this option is true, and | |
16212 | the uid supplied by the router is not overridden by the transport, the | |
16213 | 'initgroups()' function is called when running the transport to ensure that | |
16214 | any additional groups associated with the uid are set up. See also %group% and | |
16215 | %user% and the discussion in chapter <<CHAPenvironment>>. | |
16216 | ||
16217 | ||
16218 | ||
16219 | oindex:[%local_part_prefix%] | |
16220 | `..'= | |
16221 | %local_part_prefix%, Use: 'routers'!?, Type: 'string list', Default: 'unset' | |
16222 | === | |
16223 | ||
16224 | cindex:[router,prefix for local part] | |
16225 | cindex:[prefix,for local part; used in router] | |
068aaea8 PH |
16226 | If this option is set, the router is skipped unless the local part starts with |
16227 | one of the given strings, or %local_part_prefix_optional% is true. See section | |
16228 | <<SECTrouprecon>> for a list of the order in which preconditions are evaluated. | |
168e428f PH |
16229 | |
16230 | The list is scanned from left to right, and the first prefix that matches is | |
16231 | used. A limited form of wildcard is available; if the prefix begins with an | |
16232 | asterisk, it matches the longest possible sequence of arbitrary characters at | |
16233 | the start of the local part. An asterisk should therefore always be followed by | |
16234 | some character that does not occur in normal local parts. | |
168e428f PH |
16235 | cindex:[multiple mailboxes] |
16236 | cindex:[mailbox,multiple] | |
16237 | Wildcarding can be used to set up multiple user mailboxes, as described in | |
16238 | section <<SECTmulbox>>. | |
16239 | ||
068aaea8 PH |
16240 | [revisionflag="changed"] |
16241 | cindex:[$local_part$] | |
16242 | cindex:[$local_part_prefix$] | |
168e428f PH |
16243 | During the testing of the %local_parts% option, and while the router is |
16244 | running, the prefix is removed from the local part, and is available in the | |
068aaea8 PH |
16245 | expansion variable $local_part_prefix$. When a message is being delivered, if |
16246 | the router accepts the address, this remains true during subsequent delivery by | |
16247 | a transport. In particular, the local part that is transmitted in the RCPT | |
16248 | command for LMTP, SMTP, and BSMTP deliveries has the prefix removed by default. | |
16249 | This behaviour can be overridden by setting %rcpt_include_affixes% true on the | |
168e428f PH |
16250 | relevant transport. |
16251 | ||
068aaea8 PH |
16252 | [revisionflag="changed"] |
16253 | When an address is being verified, %local_part_prefix% affects only the | |
16254 | behaviour of the router. If the callout feature of verification is in use, this | |
16255 | means that the full address, including the prefix, will be used during the | |
16256 | callout. | |
16257 | ||
168e428f PH |
16258 | The prefix facility is commonly used to handle local parts of the form |
16259 | %owner-something%. Another common use is to support local parts of the form | |
16260 | %real-username% to bypass a user's _.forward_ file -- helpful when trying to | |
16261 | tell a user their forwarding is broken -- by placing a router like this one | |
16262 | immediately before the router that handles _.forward_ files: | |
16263 | ||
16264 | real_localuser: | |
16265 | driver = accept | |
16266 | local_part_prefix = real- | |
16267 | check_local_user | |
16268 | transport = local_delivery | |
16269 | ||
16270 | If both %local_part_prefix% and %local_part_suffix% are set for a router, | |
16271 | both conditions must be met if not optional. Care must be taken if wildcards | |
16272 | are used in both a prefix and a suffix on the same router. Different | |
16273 | separator characters must be used to avoid ambiguity. | |
16274 | ||
16275 | ||
16276 | oindex:[%local_part_prefix_optional%] | |
16277 | `..'= | |
16278 | %local_part_prefix_optional%, Use: 'routers', Type: 'boolean', Default: 'false' | |
16279 | === | |
16280 | ||
16281 | See %local_part_prefix% above. | |
16282 | ||
16283 | ||
16284 | ||
16285 | oindex:[%local_part_suffix%] | |
16286 | `..'= | |
16287 | %local_part_suffix%, Use: 'routers'!?, Type: 'string list', Default: 'unset' | |
16288 | === | |
16289 | ||
16290 | cindex:[router,suffix for local part] | |
16291 | cindex:[suffix for local part, used in router] | |
16292 | This option operates in the same way as %local_part_prefix%, except that the | |
16293 | local part must end (rather than start) with the given string, the | |
16294 | %local_part_suffix_optional% option determines whether the suffix is | |
16295 | mandatory, and the wildcard \* character, if present, must be the last | |
16296 | character of the suffix. This option facility is commonly used to handle local | |
16297 | parts of the form %something-request% and multiple user mailboxes of the form | |
16298 | %username-foo%. | |
16299 | ||
16300 | ||
16301 | oindex:[%local_part_suffix_optional%] | |
16302 | `..'= | |
16303 | %local_part_suffix_optional%, Use: 'routers', Type: 'boolean', Default: 'false' | |
16304 | === | |
16305 | ||
16306 | See %local_part_suffix% above. | |
16307 | ||
16308 | ||
16309 | ||
16310 | oindex:[%local_parts%] | |
16311 | `..'= | |
16312 | %local_parts%, Use: 'routers'!?, Type: 'local part list'!!, Default: 'unset' | |
16313 | === | |
16314 | ||
16315 | cindex:[router,restricting to specific local parts] | |
16316 | cindex:[local part,checking in router] | |
16317 | The router is run only if the local part of the address matches the list. | |
16318 | See section <<SECTrouprecon>> for a list of the order in which preconditions | |
16319 | are evaluated, and | |
16320 | section <<SECTlocparlis>> for a discussion of local part lists. Because the | |
16321 | string is expanded, it is possible to make it depend on the domain, for | |
16322 | example: | |
16323 | ||
16324 | local_parts = dbm;/usr/local/specials/$domain | |
16325 | ||
068aaea8 | 16326 | cindex:[$local_part_data$] |
168e428f PH |
16327 | If the match is achieved by a lookup, the data that the lookup returned |
16328 | for the local part is placed in the variable $local_part_data$ for use in | |
16329 | expansions of the router's private options. You might use this option, for | |
16330 | example, if you have a large number of local virtual domains, and you want to | |
16331 | send all postmaster mail to the same place without having to set up an alias in | |
16332 | each virtual domain: | |
16333 | ||
16334 | postmaster: | |
16335 | driver = redirect | |
16336 | local_parts = postmaster | |
16337 | data = postmaster@real.domain.example | |
16338 | ||
16339 | ||
16340 | ||
16341 | ||
16342 | oindex:[%log_as_local%] | |
16343 | `..'= | |
16344 | %log_as_local%, Use: 'routers', Type: 'boolean', Default: 'see below' | |
16345 | === | |
16346 | ||
16347 | cindex:[log,delivery line] | |
16348 | cindex:[delivery,log line format] | |
16349 | Exim has two logging styles for delivery, the idea being to make local | |
16350 | deliveries stand out more visibly from remote ones. In the ``local'' style, the | |
16351 | recipient address is given just as the local part, without a domain. The use of | |
16352 | this style is controlled by this option. It defaults to true for the ^accept^ | |
16353 | router, and false for all the others. | |
16354 | ||
16355 | ||
16356 | ||
16357 | oindex:[%more%] | |
16358 | `..'= | |
16359 | %more%, Use: 'routers', Type: 'boolean'!!, Default: 'true' | |
16360 | === | |
16361 | ||
16362 | The result of string expansion for this option must be a valid boolean value, | |
16363 | that is, one of the strings ``yes'', ``no'', ``true'', or ``false''. Any other | |
16364 | result causes an error, and delivery is deferred. If the expansion is forced to | |
16365 | fail, the default value for the option (true) is used. Other failures cause | |
16366 | delivery to be deferred. | |
16367 | ||
068aaea8 PH |
16368 | If this option is set false, and the router declines to handle the address, no |
16369 | further routers are tried, routing fails, and the address is bounced. | |
16370 | cindex:[%self% option] However, if the router explicitly passes an address to | |
16371 | the following router by means of the setting | |
168e428f PH |
16372 | |
16373 | self = pass | |
16374 | ||
16375 | or otherwise, the setting of %more% is ignored. Also, the setting of %more% | |
16376 | does not affect the behaviour if one of the precondition tests fails. In that | |
16377 | case, the address is always passed to the next router. | |
16378 | ||
068aaea8 PH |
16379 | [revisionflag="changed"] |
16380 | Note that %address_data% is not considered to be a precondition. If its | |
16381 | expansion is forced to fail, the router declines, and the value of %more% | |
16382 | controls what happens next. | |
16383 | ||
168e428f PH |
16384 | |
16385 | ||
16386 | oindex:[%pass_on_timeout%] | |
16387 | `..'= | |
16388 | %pass_on_timeout%, Use: 'routers', Type: 'boolean', Default: 'false' | |
16389 | === | |
16390 | ||
16391 | cindex:[timeout,of router] | |
16392 | cindex:[router,timeout] | |
16393 | If a router times out during a host lookup, it normally causes deferral of the | |
16394 | address. If %pass_on_timeout% is set, the address is passed on to the next | |
16395 | router, overriding %no_more%. This may be helpful for systems that are | |
16396 | intermittently connected to the Internet, or those that want to pass to a smart | |
16397 | host any messages that cannot immediately be delivered. | |
16398 | ||
16399 | There are occasional other temporary errors that can occur while doing DNS | |
16400 | lookups. They are treated in the same way as a timeout, and this option | |
16401 | applies to all of them. | |
16402 | ||
16403 | ||
16404 | ||
16405 | oindex:[%pass_router%] | |
16406 | `..'= | |
16407 | %pass_router%, Use: 'routers', Type: 'string', Default: 'unset' | |
16408 | === | |
16409 | ||
16410 | cindex:[router,go to after ``pass''] | |
16411 | When a router returns ``pass'', the address is normally handed on to the next | |
16412 | router in sequence. This can be changed by setting %pass_router% to the name | |
16413 | of another router. However (unlike %redirect_router%) the named router must be | |
16414 | below the current router, to avoid loops. Note that this option applies only to | |
16415 | the special case of ``pass''. It does not apply when a router returns ``decline''. | |
16416 | ||
16417 | ||
16418 | ||
16419 | oindex:[%redirect_router%] | |
16420 | `..'= | |
16421 | %redirect_router%, Use: 'routers', Type: 'string', Default: 'unset' | |
16422 | === | |
16423 | ||
16424 | cindex:[router,start at after redirection] | |
16425 | Sometimes an administrator knows that it is pointless to reprocess addresses | |
16426 | generated from alias or forward files with the same router again. For | |
16427 | example, if an alias file translates real names into login ids there is no | |
16428 | point searching the alias file a second time, especially if it is a large file. | |
16429 | ||
16430 | The %redirect_router% option can be set to the name of any router instance. It | |
16431 | causes the routing of any generated addresses to start at the named router | |
16432 | instead of at the first router. This option has no effect if the router in | |
16433 | which it is set does not generate new addresses. | |
16434 | ||
16435 | ||
16436 | ||
16437 | oindex:[%require_files%] | |
16438 | `..'= | |
16439 | %require_files%, Use: 'routers'!?, Type: 'string list'!!, Default: 'unset' | |
16440 | === | |
16441 | ||
16442 | cindex:[file,requiring for router] | |
16443 | cindex:[router,requiring file existence] | |
16444 | This option provides a general mechanism for predicating the running of a | |
16445 | router on the existence or non-existence of certain files or directories. | |
16446 | Before running a router, as one of its precondition tests, Exim works its way | |
16447 | through the %require_files% list, expanding each item separately. | |
16448 | ||
16449 | Because the list is split before expansion, any colons in expansion items must | |
16450 | be doubled, or the facility for using a different list separator must be used. | |
16451 | If any expansion is forced to fail, the item is ignored. Other expansion | |
16452 | failures cause routing of the address to be deferred. | |
16453 | ||
16454 | If any expanded string is empty, it is ignored. Otherwise, except as described | |
16455 | below, each string must be a fully qualified file path, optionally preceded by | |
16456 | ``!''. The paths are passed to the 'stat()' function to test for the existence | |
16457 | of the files or directories. The router is skipped if any paths not preceded by | |
16458 | ``!'' do not exist, or if any paths preceded by ``!'' do exist. | |
16459 | ||
16460 | cindex:[NFS] | |
16461 | If 'stat()' cannot determine whether a file exists or not, delivery of | |
16462 | the message is deferred. This can happen when NFS-mounted filesystems are | |
16463 | unavailable. | |
16464 | ||
16465 | This option is checked after the %domains%, %local_parts%, and %senders% | |
16466 | options, so you cannot use it to check for the existence of a file in which to | |
16467 | look up a domain, local part, or sender. (See section <<SECTrouprecon>> for a | |
16468 | full list of the order in which preconditions are evaluated.) However, as | |
16469 | these options are all expanded, you can use the %exists% expansion condition to | |
16470 | make such tests. The %require_files% option is intended for checking files | |
16471 | that the router may be going to use internally, or which are needed by a | |
16472 | transport (for example _.procmailrc_). | |
16473 | ||
16474 | During delivery, the 'stat()' function is run as root, but there is a | |
16475 | facility for some checking of the accessibility of a file by another user. | |
16476 | This is not a proper permissions check, but just a ``rough'' check that | |
16477 | operates as follows: | |
16478 | ||
16479 | If an item in a %require_files% list does not contain any forward slash | |
16480 | characters, it is taken to be the user (and optional group, separated by a | |
16481 | comma) to be checked for subsequent files in the list. If no group is specified | |
16482 | but the user is specified symbolically, the gid associated with the uid is | |
16483 | used. For example: | |
16484 | ||
16485 | require_files = mail:/some/file | |
16486 | require_files = $local_part:$home/.procmailrc | |
16487 | ||
16488 | If a user or group name in a %require_files% list does not exist, the | |
16489 | %require_files% condition fails. | |
16490 | ||
16491 | Exim performs the check by scanning along the components of the file path, and | |
16492 | checking the access for the given uid and gid. It checks for ``x'' access on | |
16493 | directories, and ``r'' access on the final file. Note that this means that file | |
16494 | access control lists, if the operating system has them, are ignored. | |
16495 | ||
16496 | *Warning 1*: When the router is being run to verify addresses for an | |
16497 | incoming SMTP message, Exim is not running as root, but under its own uid. This | |
16498 | may affect the result of a %require_files% check. In particular, 'stat()' | |
16499 | may yield the error EACCES (``Permission denied''). This means that the Exim | |
16500 | user is not permitted to read one of the directories on the file's path. | |
16501 | ||
16502 | *Warning 2*: Even when Exim is running as root while delivering a message, | |
16503 | 'stat()' can yield EACCES for a file in an NFS directory that is mounted | |
16504 | without root access. | |
16505 | ||
16506 | In this case, if a check for access by a particular user is requested, Exim | |
16507 | creates a subprocess that runs as that user, and tries the check again in that | |
16508 | process. | |
16509 | ||
16510 | The default action for handling an unresolved EACCES is to consider it to | |
16511 | be caused by a configuration error, | |
16512 | ||
16513 | and routing is deferred because the existence or non-existence of the file | |
16514 | cannot be determined. However, in some circumstances it may be desirable to | |
16515 | treat this condition as if the file did not exist. If the file name (or the | |
16516 | exclamation mark that precedes the file name for non-existence) is preceded by | |
16517 | a plus sign, the EACCES error is treated as if the file did not exist. For | |
16518 | example: | |
16519 | ||
16520 | require_files = +/some/file | |
16521 | ||
16522 | If the router is not an essential part of verification (for example, it | |
16523 | handles users' _.forward_ files), another solution is to set the %verify% | |
16524 | option false so that the router is skipped when verifying. | |
16525 | ||
16526 | ||
16527 | ||
16528 | oindex:[%retry_use_local_part%] | |
16529 | `..'= | |
16530 | %retry_use_local_part%, Use: 'routers', Type: 'boolean', Default: 'see below' | |
16531 | === | |
16532 | ||
16533 | cindex:[hints database,retry keys] | |
16534 | cindex:[local part,in retry keys] | |
16535 | When a delivery suffers a temporary routing failure, a retry record is created | |
16536 | in Exim's hints database. For addresses whose routing depends only on the | |
16537 | domain, the key for the retry record should not involve the local part, but for | |
16538 | other addresses, both the domain and the local part should be included. | |
16539 | Usually, remote routing is of the former kind, and local routing is of the | |
16540 | latter kind. | |
16541 | ||
16542 | This option controls whether the local part is used to form the key for retry | |
16543 | hints for addresses that suffer temporary errors while being handled by this | |
16544 | router. The default value is true for any router that has %check_local_user% | |
16545 | set, and false otherwise. Note that this option does not apply to hints keys | |
16546 | for transport delays; they are controlled by a generic transport option of the | |
16547 | same name. | |
16548 | ||
16549 | The setting of %retry_use_local_part% applies only to the router on which it | |
16550 | appears. If the router generates child addresses, they are routed | |
16551 | independently; this setting does not become attached to them. | |
16552 | ||
16553 | ||
16554 | ||
16555 | oindex:[%router_home_directory%] | |
16556 | `..'= | |
16557 | %router_home_directory%, Use: 'routers', Type: 'string'!!, Default: 'unset' | |
16558 | === | |
16559 | ||
16560 | cindex:[router,home directory for] | |
16561 | cindex:[home directory,for router] | |
068aaea8 | 16562 | cindex:[$home$] |
168e428f PH |
16563 | This option sets a home directory for use while the router is running. (Compare |
16564 | %transport_home_directory%, which sets a home directory for later | |
16565 | transporting.) In particular, if used on a ^redirect^ router, this option | |
16566 | sets a value for $home$ while a filter is running. The value is expanded; | |
16567 | forced expansion failure causes the option to be ignored -- other failures | |
16568 | cause the router to defer. | |
16569 | ||
16570 | Expansion of %router_home_directory% happens immediately after the | |
16571 | %check_local_user% test (if configured), before any further expansions take | |
16572 | place. | |
16573 | (See section <<SECTrouprecon>> for a list of the order in which preconditions | |
16574 | are evaluated.) | |
16575 | While the router is running, %router_home_directory% overrides the value of | |
16576 | $home$ that came from %check_local_user%. | |
16577 | ||
16578 | When a router accepts an address and routes it to a transport (including the | |
16579 | cases when a redirect router generates a pipe, file, or autoreply delivery), | |
16580 | the home directory setting for the transport is taken from the first of these | |
16581 | values that is set: | |
16582 | ||
16583 | - The %home_directory% option on the transport; | |
16584 | ||
16585 | - The %transport_home_directory% option on the router; | |
16586 | ||
16587 | - The password data if %check_local_user% is set on the router; | |
16588 | ||
16589 | - The %router_home_directory% option on the router. | |
16590 | ||
16591 | In other words, %router_home_directory% overrides the password data for the | |
16592 | router, but not for the transport. | |
16593 | ||
16594 | ||
16595 | ||
16596 | oindex:[%self%] | |
16597 | `..'= | |
16598 | %self%, Use: 'routers', Type: 'string', Default: 'freeze' | |
16599 | === | |
16600 | ||
16601 | cindex:[MX record,pointing to local host] | |
16602 | cindex:[local host,MX pointing to] | |
16603 | This option applies to those routers that use a recipient address to find a | |
16604 | list of remote hosts. Currently, these are the ^dnslookup^, ^ipliteral^, | |
16605 | and ^manualroute^ routers. | |
16606 | Certain configurations of the ^queryprogram^ router can also specify a list | |
16607 | of remote hosts. | |
16608 | Usually such routers are configured to send the message to a remote host via an | |
16609 | ^smtp^ transport. The %self% option specifies what happens when the first | |
16610 | host on the list turns out to be the local host. | |
16611 | The way in which Exim checks for the local host is described in section | |
16612 | <<SECTreclocipadd>>. | |
16613 | ||
16614 | Normally this situation indicates either an error in Exim's configuration (for | |
16615 | example, the router should be configured not to process this domain), or an | |
16616 | error in the DNS (for example, the MX should not point to this host). For this | |
16617 | reason, the default action is to log the incident, defer the address, and | |
16618 | freeze the message. The following alternatives are provided for use in special | |
16619 | cases: | |
16620 | ||
16621 | %defer%:: | |
16622 | Delivery of the message is tried again later, but the message is not frozen. | |
16623 | ||
16624 | %reroute%: <'domain'>:: | |
16625 | The domain is changed to the given domain, and the address is passed back to | |
16626 | be reprocessed by the routers. No rewriting of headers takes place. This | |
16627 | behaviour is essentially a redirection. | |
16628 | ||
16629 | %reroute: rewrite:% <'domain'>:: | |
16630 | The domain is changed to the given domain, and the address is passed back to be | |
16631 | reprocessed by the routers. Any headers that contain the original domain are | |
16632 | rewritten. | |
16633 | ||
16634 | %pass%:: | |
16635 | The router passes the address to the next router, or to the router named in the | |
16636 | %pass_router% option if it is set. | |
16637 | cindex:[%more% option] | |
16638 | This overrides %no_more%. | |
16639 | + | |
068aaea8 | 16640 | cindex:[$self_hostname$] |
168e428f PH |
16641 | During subsequent routing and delivery, the variable $self_hostname$ contains |
16642 | the name of the local host that the router encountered. This can be used to | |
16643 | distinguish between different cases for hosts with multiple names. The | |
16644 | combination | |
16645 | ||
16646 | self = pass | |
16647 | no_more | |
16648 | + | |
16649 | ensures that only those addresses that routed to the local host are passed on. | |
16650 | Without %no_more%, addresses that were declined for other reasons would also | |
16651 | be passed to the next router. | |
16652 | ||
16653 | %fail%:: | |
16654 | Delivery fails and an error report is generated. | |
16655 | ||
16656 | %send%:: | |
16657 | cindex:[local host,sending to] | |
16658 | The anomaly is ignored and the address is queued for the transport. This | |
16659 | setting should be used with extreme caution. For an ^smtp^ transport, it makes | |
16660 | sense only in cases where the program that is listening on the SMTP port is not | |
16661 | this version of Exim. That is, it must be some other MTA, or Exim with a | |
16662 | different configuration file that handles the domain in another way. | |
16663 | ||
16664 | ||
16665 | ||
16666 | oindex:[%senders%] | |
16667 | `..'= | |
16668 | %senders%, Use: 'routers'!?, Type: 'address list'!!, Default: 'unset' | |
16669 | === | |
16670 | ||
16671 | cindex:[router,checking senders] | |
16672 | If this option is set, the router is skipped unless the message's sender | |
16673 | address matches something on the list. | |
16674 | See section <<SECTrouprecon>> for a list of the order in which preconditions | |
16675 | are evaluated. | |
16676 | ||
16677 | There are issues concerning verification when the running of routers is | |
16678 | dependent on the sender. When Exim is verifying the address in an %errors_to% | |
16679 | setting, it sets the sender to the null string. When using the %-bt% option to | |
16680 | check a configuration file, it is necessary also to use the %-f% option to set | |
16681 | an appropriate sender. For incoming mail, the sender is unset when verifying | |
16682 | the sender, but is available when verifying any recipients. If the SMTP | |
16683 | VRFY command is enabled, it must be used after MAIL if the sender | |
16684 | address matters. | |
16685 | ||
16686 | ||
16687 | oindex:[%translate_ip_address%] | |
16688 | `..'= | |
16689 | %translate_ip_address%, Use: 'routers', Type: 'string'!!, Default: 'unset' | |
16690 | === | |
16691 | ||
16692 | cindex:[IP address,translating] | |
16693 | cindex:[packet radio] | |
16694 | cindex:[router,IP address translation] | |
16695 | There exist some rare networking situations (for example, packet radio) where | |
16696 | it is helpful to be able to translate IP addresses generated by normal routing | |
16697 | mechanisms into other IP addresses, thus performing a kind of manual IP | |
16698 | routing. This should be done only if the normal IP routing of the TCP/IP stack | |
16699 | is inadequate or broken. Because this is an extremely uncommon requirement, the | |
16700 | code to support this option is not included in the Exim binary unless | |
16701 | SUPPORT_TRANSLATE_IP_ADDRESS=yes is set in _Local/Makefile_. | |
16702 | ||
068aaea8 | 16703 | cindex:[$host_address$] |
168e428f PH |
16704 | The %translate_ip_address% string is expanded for every IP address generated |
16705 | by the router, with the generated address set in $host_address$. If the | |
16706 | expansion is forced to fail, no action is taken. | |
16707 | For any other expansion error, delivery of the message is deferred. | |
16708 | If the result of the expansion is an IP address, that replaces the original | |
16709 | address; otherwise the result is assumed to be a host name -- this is looked up | |
16710 | using 'gethostbyname()' (or 'getipnodebyname()' when available) to produce | |
16711 | one or more replacement IP addresses. For example, to subvert all IP addresses | |
16712 | in some specific networks, this could be added to a router: | |
16713 | ||
16714 | .... | |
16715 | translate_ip_address = \ | |
16716 | ${lookup{${mask:$host_address/26}}lsearch{/some/file}{$value}fail}} | |
16717 | .... | |
16718 | ||
16719 | The file would contain lines like | |
16720 | ||
16721 | 10.2.3.128/26 some.host | |
16722 | 10.8.4.34/26 10.44.8.15 | |
16723 | ||
16724 | You should not make use of this facility unless you really understand what you | |
16725 | are doing. | |
16726 | ||
16727 | ||
16728 | ||
16729 | oindex:[%transport%] | |
16730 | `..'= | |
16731 | %transport%, Use: 'routers', Type: 'string'!!, Default: 'unset' | |
16732 | === | |
16733 | ||
16734 | This option specifies the transport to be used when a router accepts an address | |
16735 | and sets it up for delivery. A transport is never needed if a router is used | |
16736 | only for verification. The value of the option is expanded at routing time, | |
16737 | after the expansion of %errors_to%, %headers_add%, and %headers_remove%, and | |
16738 | result must be the name of one of the configured transports. If it is not, | |
16739 | delivery is deferred. | |
16740 | ||
16741 | The %transport% option is not used by the ^redirect^ router, but it does have | |
16742 | some private options that set up transports for pipe and file deliveries (see | |
16743 | chapter <<CHAPredirect>>). | |
16744 | ||
16745 | ||
16746 | ||
16747 | oindex:[%transport_current_directory%] | |
16748 | `..'= | |
16749 | %transport_current_directory%, Use: 'routers', Type: 'string'!!, Default: 'unset' | |
16750 | === | |
16751 | ||
16752 | cindex:[current directory for local transport] | |
16753 | This option associates a current directory with any address that is routed | |
16754 | to a local transport. This can happen either because a transport is | |
16755 | explicitly configured for the router, or because it generates a delivery to a | |
16756 | file or a pipe. During the delivery process (that is, at transport time), this | |
16757 | option string is expanded and is set as the current directory, unless | |
16758 | overridden by a setting on the transport. | |
16759 | If the expansion fails for any reason, including forced failure, an error is | |
16760 | logged, and delivery is deferred. | |
16761 | See chapter <<CHAPenvironment>> for details of the local delivery environment. | |
16762 | ||
16763 | ||
16764 | ||
16765 | ||
16766 | oindex:[%transport_home_directory%] | |
16767 | `..'= | |
16768 | %transport_home_directory%, Use: 'routers', Type: 'string'!!, Default: 'see below' | |
16769 | === | |
16770 | ||
16771 | cindex:[home directory,for local transport] | |
16772 | This option associates a home directory with any address that is routed to a | |
16773 | local transport. This can happen either because a transport is explicitly | |
16774 | configured for the router, or because it generates a delivery to a file or a | |
16775 | pipe. During the delivery process (that is, at transport time), the option | |
16776 | string is expanded and is set as the home directory, unless overridden by a | |
16777 | setting of %home_directory% on the transport. | |
16778 | If the expansion fails for any reason, including forced failure, an error is | |
16779 | logged, and delivery is deferred. | |
16780 | ||
16781 | If the transport does not specify a home directory, and | |
16782 | %transport_home_directory% is not set for the router, the home directory for | |
16783 | the tranport is taken from the password data if %check_local_user% is set for | |
16784 | the router. Otherwise it is taken from %router_home_directory% if that option | |
16785 | is set; if not, no home directory is set for the transport. | |
16786 | ||
16787 | See chapter <<CHAPenvironment>> for further details of the local delivery | |
16788 | environment. | |
16789 | ||
16790 | ||
16791 | ||
16792 | ||
16793 | oindex:[%unseen%] | |
16794 | `..'= | |
16795 | %unseen%, Use: 'routers', Type: 'boolean'!!, Default: 'false' | |
16796 | === | |
16797 | ||
16798 | cindex:[router,carrying on after success] | |
16799 | The result of string expansion for this option must be a valid boolean value, | |
068aaea8 PH |
16800 | that is, one of the strings ``yes'', ``no'', ``true'', or ``false''. Any other |
16801 | result causes an error, and delivery is deferred. If the expansion is forced to | |
16802 | fail, the default value for the option (false) is used. Other failures cause | |
16803 | delivery to be deferred. | |
16804 | ||
168e428f PH |
16805 | When this option is set true, routing does not cease if the router accepts the |
16806 | address. Instead, a copy of the incoming address is passed to the next router, | |
16807 | overriding a false setting of %more%. There is little point in setting %more% | |
16808 | false if %unseen% is always true, but it may be useful in cases when the value | |
16809 | of %unseen% contains expansion items (and therefore, presumably, is sometimes | |
16810 | true and sometimes false). | |
16811 | ||
068aaea8 | 16812 | [revisionflag="changed"] |
168e428f PH |
16813 | cindex:[copy of message (%unseen% option)] |
16814 | The %unseen% option can be used to cause copies of messages to be delivered to | |
16815 | some other destination, while also carrying out a normal delivery. In effect, | |
16816 | the current address is made into a ``parent'' that has two children -- one that | |
16817 | is delivered as specified by this router, and a clone that goes on to be routed | |
068aaea8 PH |
16818 | further. For this reason, %unseen% may not be combined with the %one_time% |
16819 | option in a ^redirect^ router. | |
168e428f | 16820 | |
068aaea8 PH |
16821 | *Warning*: Header lines added to the address (or specified for removal) by this |
16822 | router or by previous routers affect the ``unseen'' copy of the message only. | |
16823 | The clone that continues to be processed by further routers starts with no | |
16824 | added headers and none specified for removal. However, any data that was set by | |
16825 | the %address_data% option in the current or previous routers is passed on. | |
16826 | Setting the %unseen% option has a similar effect to the %unseen% command | |
16827 | qualifier in filter files. | |
168e428f PH |
16828 | |
16829 | ||
16830 | ||
16831 | oindex:[%user%] | |
16832 | `..'= | |
16833 | %user%, Use: 'routers', Type: 'string'!!, Default: 'see below' | |
16834 | === | |
16835 | ||
16836 | cindex:[uid (user id),local delivery] | |
16837 | cindex:[local transports,uid and gid] | |
16838 | cindex:[transport,local] | |
16839 | cindex:[router,user for filter processing] | |
16840 | cindex:[filter,user for processing] | |
16841 | When a router queues an address for a transport, and the transport does not | |
16842 | specify a user, the user given here is used when running the delivery process. | |
16843 | The user may be specified numerically or by name. If expansion fails, the | |
16844 | error is logged and delivery is deferred. | |
16845 | This user is also used by the ^redirect^ router when running a filter file. | |
16846 | The default is unset, except when %check_local_user% is set. In this case, | |
16847 | the default is taken from the password information. If the user is specified as | |
16848 | a name, and %group% is not set, the group associated with the user is used. See | |
16849 | also %initgroups% and %group% and the discussion in chapter <<CHAPenvironment>>. | |
16850 | ||
16851 | ||
16852 | ||
16853 | oindex:[%verify%] | |
16854 | `..'= | |
16855 | %verify%, Use: 'routers'!?, Type: 'boolean', Default: 'true' | |
16856 | === | |
16857 | ||
16858 | Setting this option has the effect of setting %verify_sender% and | |
16859 | %verify_recipient% to the same value. | |
16860 | ||
16861 | ||
16862 | oindex:[%verify_only%] | |
16863 | `..'= | |
16864 | %verify_only%, Use: 'routers'!?, Type: 'boolean', Default: 'false' | |
16865 | === | |
16866 | ||
16867 | cindex:[EXPN,with %verify_only%] | |
16868 | cindex:[%-bv% option] | |
16869 | cindex:[router,used only when verifying] | |
16870 | If this option is set, the router is used only when verifying an address or | |
16871 | testing with the %-bv% option, not when actually doing a delivery, testing | |
16872 | with the %-bt% option, or running the SMTP EXPN command. It can be further | |
16873 | restricted to verifying only senders or recipients by means of %verify_sender% | |
16874 | and %verify_recipient%. | |
16875 | ||
16876 | *Warning*: When the router is being run to verify addresses for an incoming | |
16877 | SMTP message, Exim is not running as root, but under its own uid. If the router | |
16878 | accesses any files, you need to make sure that they are accessible to the Exim | |
16879 | user or group. | |
16880 | ||
16881 | ||
16882 | oindex:[%verify_recipient%] | |
16883 | `..'= | |
16884 | %verify_recipient%, Use: 'routers'!?, Type: 'boolean', Default: 'true' | |
16885 | === | |
16886 | ||
16887 | If this option is false, the router is skipped when verifying recipient | |
16888 | addresses | |
16889 | or testing recipient verification using %-bv%. | |
16890 | See section <<SECTrouprecon>> for a list of the order in which preconditions | |
16891 | are evaluated. | |
16892 | ||
16893 | ||
16894 | oindex:[%verify_sender%] | |
16895 | `..'= | |
16896 | %verify_sender%, Use: 'routers'!?, Type: 'boolean', Default: 'true' | |
16897 | === | |
16898 | ||
16899 | If this option is false, the router is skipped when verifying sender addresses | |
16900 | or testing sender verification using %-bvs%. | |
16901 | See section <<SECTrouprecon>> for a list of the order in which preconditions | |
16902 | are evaluated. | |
16903 | ||
16904 | ||
16905 | ||
16906 | ||
16907 | ||
16908 | ||
16909 | //////////////////////////////////////////////////////////////////////////// | |
16910 | //////////////////////////////////////////////////////////////////////////// | |
16911 | ||
16912 | The accept router | |
16913 | ----------------- | |
16914 | cindex:[^accept^ router] | |
16915 | cindex:[routers,^accept^] | |
16916 | The ^accept^ router has no private options of its own. Unless it is being used | |
16917 | purely for verification (see %verify_only%) a transport is required to be | |
16918 | defined by the generic %transport% option. If the preconditions that are | |
16919 | specified by generic options are met, the router accepts the address and queues | |
16920 | it for the given transport. The most common use of this router is for setting | |
16921 | up deliveries to local mailboxes. For example: | |
16922 | ||
16923 | localusers: | |
16924 | driver = accept | |
16925 | domains = mydomain.example | |
16926 | check_local_user | |
16927 | transport = local_delivery | |
16928 | ||
16929 | The %domains% condition in this example checks the domain of the address, and | |
16930 | %check_local_user% checks that the local part is the login of a local user. | |
16931 | When both preconditions are met, the ^accept^ router runs, and queues the | |
16932 | address for the ^local_delivery^ transport. | |
16933 | ||
16934 | ||
16935 | ||
16936 | ||
16937 | ||
16938 | ||
16939 | //////////////////////////////////////////////////////////////////////////// | |
16940 | //////////////////////////////////////////////////////////////////////////// | |
16941 | ||
16942 | [[CHAPdnslookup]] | |
16943 | The dnslookup router | |
16944 | -------------------- | |
16945 | cindex:[^dnslookup^ router] | |
16946 | cindex:[routers,^dnslookup^] | |
16947 | The ^dnslookup^ router looks up the hosts that handle mail for the | |
16948 | recipient's domain in the DNS. A transport must always be set for this router, | |
16949 | unless %verify_only% is set. | |
16950 | ||
16951 | If SRV support is configured (see %check_srv% below), Exim first searches for | |
16952 | SRV records. If none are found, or if SRV support is not configured, | |
16953 | MX records are looked up. If no MX records exist, address records are sought. | |
16954 | However, %mx_domains% can be set to disable the direct use of address records. | |
16955 | ||
16956 | MX records of equal priority are sorted by Exim into a random order. Exim then | |
16957 | looks for address records for the host names obtained from MX or SRV records. | |
16958 | When a host has more than one IP address, they are sorted into a random order, | |
16959 | except that IPv6 addresses are always sorted before IPv4 addresses. If all the | |
16960 | IP addresses found are discarded by a setting of the %ignore_target_hosts% | |
16961 | generic option, the router declines. | |
16962 | ||
16963 | Unless they have the highest priority (lowest MX value), MX records that point | |
16964 | to the local host, or to any host name that matches %hosts_treat_as_local%, | |
16965 | are discarded, together with any other MX records of equal or lower priority. | |
16966 | ||
16967 | cindex:[MX record,pointing to local host] | |
16968 | cindex:[local host,MX pointing to] | |
16969 | cindex:[%self% option,in ^dnslookup^ router] | |
16970 | If the host pointed to by the highest priority MX record, or looked up as an | |
16971 | address record, is the local host, or matches %hosts_treat_as_local%, what | |
16972 | happens is controlled by the generic %self% option. | |
16973 | ||
16974 | ||
16975 | [[SECTprowitdnsloo]] | |
16976 | Problems with DNS lookups | |
16977 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
16978 | There have been problems with DNS servers when SRV records are looked up. | |
16979 | Some mis-behaving servers return a DNS error or timeout when a non-existent | |
16980 | SRV record is sought. Similar problems have in the past been reported for | |
16981 | MX records. The global %dns_again_means_nonexist% option can help with this | |
16982 | problem, but it is heavy-handed because it is a global option. | |
16983 | ||
16984 | For this reason, there are two options, %srv_fail_domains% and | |
16985 | %mx_fail_domains%, that control what happens when a DNS lookup in a | |
16986 | ^dnslookup^ router results in a DNS failure or a ``try again'' response. If an | |
16987 | attempt to look up an SRV or MX record causes one of these results, and the | |
16988 | domain matches the relevant list, Exim behaves as if the DNS had responded ``no | |
16989 | such record''. In the case of an SRV lookup, this means that the router proceeds | |
16990 | to look for MX records; in the case of an MX lookup, it proceeds to look for A | |
16991 | or AAAA records, unless the domain matches %mx_domains%, in which case routing | |
16992 | fails. | |
16993 | ||
16994 | ||
16995 | ||
16996 | ||
16997 | Private options for dnslookup | |
16998 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
16999 | cindex:[options,^dnslookup^ router] | |
17000 | The private options for the ^dnslookup^ router are as follows: | |
17001 | ||
17002 | oindex:[%check_secondary_mx%] | |
17003 | `..'= | |
17004 | %check_secondary_mx%, Use: 'dnslookup', Type: 'boolean', Default: 'false' | |
17005 | === | |
17006 | ||
17007 | cindex:[MX record,checking for secondary] | |
17008 | If this option is set, the router declines unless the local host is found in | |
17009 | (and removed from) the list of hosts obtained by MX lookup. This can be used to | |
17010 | process domains for which the local host is a secondary mail exchanger | |
17011 | differently to other domains. The way in which Exim decides whether a host is | |
17012 | the local host is described in section <<SECTreclocipadd>>. | |
17013 | ||
17014 | ||
17015 | oindex:[%check_srv%] | |
17016 | `..'= | |
17017 | %check_srv%, Use: 'dnslookup', Type: 'string'!!, Default: 'unset' | |
17018 | === | |
17019 | ||
17020 | cindex:[SRV record,enabling use of] | |
17021 | The ^dnslookup^ router supports the use of SRV records (see RFC 2782) in | |
17022 | addition to MX and address records. The support is disabled by default. To | |
17023 | enable SRV support, set the %check_srv% option to the name of the service | |
17024 | required. For example, | |
17025 | ||
17026 | check_srv = smtp | |
17027 | ||
17028 | looks for SRV records that refer to the normal smtp service. The option is | |
17029 | expanded, so the service name can vary from message to message or address | |
17030 | to address. This might be helpful if SRV records are being used for a | |
17031 | submission service. If the expansion is forced to fail, the %check_srv% | |
17032 | option is ignored, and the router proceeds to look for MX records in the | |
17033 | normal way. | |
17034 | ||
17035 | When the expansion succeeds, the router searches first for SRV records for | |
17036 | the given service (it assumes TCP protocol). A single SRV record with a | |
17037 | host name that consists of just a single dot indicates ``no such service for | |
17038 | this domain''; if this is encountered, the router declines. If other kinds of | |
17039 | SRV record are found, they are used to construct a host list for delivery | |
17040 | according to the rules of RFC 2782. MX records are not sought in this case. | |
17041 | ||
17042 | When no SRV records are found, MX records (and address records) are sought in | |
17043 | the traditional way. In other words, SRV records take precedence over MX | |
17044 | records, just as MX records take precedence over address records. Note that | |
17045 | this behaviour is not sanctioned by RFC 2782, though a previous draft RFC | |
17046 | defined it. It is apparently believed that MX records are sufficient for email | |
17047 | and that SRV records should not be used for this purpose. However, SRV records | |
17048 | have an additional ``weight'' feature which some people might find useful when | |
17049 | trying to split an SMTP load between hosts of different power. | |
17050 | ||
17051 | See section <<SECTprowitdnsloo>> above for a discussion of Exim's behaviour when | |
17052 | there is a DNS lookup error. | |
17053 | ||
17054 | ||
17055 | ||
17056 | oindex:[%mx_domains%] | |
17057 | `..'= | |
17058 | %mx_domains%, Use: 'dnslookup', Type: 'domain list'!!, Default: 'unset' | |
17059 | === | |
17060 | ||
17061 | cindex:[MX record,required to exist] | |
17062 | cindex:[SRV record,required to exist] | |
17063 | A domain that matches %mx_domains% is required to have either an MX or an SRV | |
17064 | record in order to be recognised. (The name of this option could be improved.) | |
17065 | For example, if all the mail hosts in 'fict.example' are known to have MX | |
17066 | records, except for those in 'discworld.fict.example', you could use this | |
17067 | setting: | |
17068 | ||
17069 | mx_domains = ! *.discworld.fict.example : *.fict.example | |
17070 | ||
17071 | This specifies that messages addressed to a domain that matches the list but | |
17072 | has no MX record should be bounced immediately instead of being routed using | |
17073 | the address record. | |
17074 | ||
17075 | ||
17076 | oindex:[%mx_fail_domains%] | |
17077 | `..'= | |
17078 | %mx_fail_domains%, Use: 'dnslookup', Type: 'domain list'!!, Default: 'unset' | |
17079 | === | |
17080 | ||
17081 | If the DNS lookup for MX records for one of the domains in this list causes a | |
17082 | DNS lookup error, Exim behaves as if no MX records were found. See section | |
17083 | <<SECTprowitdnsloo>> for more discussion. | |
17084 | ||
17085 | ||
17086 | ||
17087 | ||
17088 | oindex:[%qualify_single%] | |
17089 | `..'= | |
17090 | %qualify_single%, Use: 'dnslookup', Type: 'boolean', Default: 'true' | |
17091 | === | |
17092 | ||
17093 | cindex:[DNS,resolver options] | |
17094 | cindex:[DNS,qualifying single-component names] | |
17095 | When this option is true, the resolver option RES_DEFNAMES is set for DNS | |
17096 | lookups. Typically, but not standardly, this causes the resolver to qualify | |
17097 | single-component names with the default domain. For example, on a machine | |
17098 | called 'dictionary.ref.example', the domain 'thesaurus' would be changed to | |
17099 | 'thesaurus.ref.example' inside the resolver. For details of what your resolver | |
17100 | actually does, consult your man pages for 'resolver' and 'resolv.conf'. | |
17101 | ||
17102 | ||
17103 | ||
17104 | oindex:[%rewrite_headers%] | |
17105 | `..'= | |
17106 | %rewrite_headers%, Use: 'dnslookup', Type: 'boolean', Default: 'true' | |
17107 | === | |
17108 | ||
17109 | cindex:[rewriting,header lines] | |
17110 | cindex:[header lines,rewriting] | |
17111 | If the domain name in the address that is being processed is not fully | |
17112 | qualified, it may be expanded to its full form by a DNS lookup. For example, if | |
17113 | an address is specified as 'dormouse@teaparty', the domain might be | |
17114 | expanded to 'teaparty.wonderland.fict.example'. Domain expansion can also | |
17115 | occur as a result of setting the %widen_domains% option. If %rewrite_headers% | |
17116 | is true, all occurrences of the abbreviated domain name in any 'Bcc:', 'Cc:', | |
17117 | 'From:', 'Reply-to:', 'Sender:', and 'To:' header lines of the message are | |
17118 | rewritten with the full domain name. | |
17119 | ||
17120 | This option should be turned off only when it is known that no message is | |
17121 | ever going to be sent outside an environment where the abbreviation makes | |
17122 | sense. | |
17123 | ||
17124 | When an MX record is looked up in the DNS and matches a wildcard record, name | |
17125 | servers normally return a record containing the name that has been looked up, | |
17126 | making it impossible to detect whether a wildcard was present or not. However, | |
17127 | some name servers have recently been seen to return the wildcard entry. If the | |
17128 | name returned by a DNS lookup begins with an asterisk, it is not used for | |
17129 | header rewriting. | |
17130 | ||
17131 | ||
17132 | oindex:[%same_domain_copy_routing%] | |
17133 | `..'= | |
17134 | %same_domain_copy_routing%, Use: 'dnslookup', Type: 'boolean', Default: 'false' | |
17135 | === | |
17136 | ||
17137 | cindex:[address,copying routing] | |
17138 | Addresses with the same domain are normally routed by the ^dnslookup^ router | |
17139 | to the same list of hosts. However, this cannot be presumed, because the router | |
17140 | options and preconditions may refer to the local part of the address. By | |
17141 | default, therefore, Exim routes each address in a message independently. DNS | |
17142 | servers run caches, so repeated DNS lookups are not normally expensive, and in | |
17143 | any case, personal messages rarely have more than a few recipients. | |
17144 | ||
17145 | If you are running mailing lists with large numbers of subscribers at the same | |
17146 | domain, and you are using a ^dnslookup^ router which is independent of the | |
17147 | local part, you can set %same_domain_copy_routing% to bypass repeated DNS | |
17148 | lookups for identical domains in one message. In this case, when ^dnslookup^ | |
17149 | routes an address to a remote transport, any other unrouted addresses in the | |
17150 | message that have the same domain are automatically given the same routing | |
17151 | without processing them independently, | |
17152 | provided the following conditions are met: | |
17153 | ||
17154 | - No router that processed the address specified %headers_add% or | |
17155 | %headers_remove%. | |
17156 | ||
17157 | - The router did not change the address in any way, for example, by ``widening'' | |
17158 | the domain. | |
17159 | ||
17160 | ||
17161 | ||
17162 | ||
17163 | oindex:[%search_parents%] | |
17164 | `..'= | |
17165 | %search_parents%, Use: 'dnslookup', Type: 'boolean', Default: 'false' | |
17166 | === | |
17167 | ||
17168 | cindex:[DNS,resolver options] | |
17169 | When this option is true, the resolver option RES_DNSRCH is set for DNS | |
17170 | lookups. This is different from the %qualify_single% option in that it applies | |
17171 | to domains containing dots. Typically, but not standardly, it causes the | |
17172 | resolver to search for the name in the current domain and in parent domains. | |
17173 | For example, on a machine in the 'fict.example' domain, if looking up | |
17174 | 'teaparty.wonderland' failed, the resolver would try | |
17175 | 'teaparty.wonderland.fict.example'. For details of what your resolver | |
17176 | actually does, consult your man pages for 'resolver' and 'resolv.conf'. | |
17177 | ||
17178 | Setting this option true can cause problems in domains that have a wildcard MX | |
17179 | record, because any domain that does not have its own MX record matches the | |
17180 | local wildcard. | |
17181 | ||
17182 | ||
17183 | ||
17184 | oindex:[%srv_fail_domains%] | |
17185 | `..'= | |
17186 | %srv_fail_domains%, Use: 'dnslookup', Type: 'domain list'!!, Default: 'unset' | |
17187 | === | |
17188 | ||
17189 | If the DNS lookup for SRV records for one of the domains in this list causes a | |
17190 | DNS lookup error, Exim behaves as if no SRV records were found. See section | |
17191 | <<SECTprowitdnsloo>> for more discussion. | |
17192 | ||
17193 | ||
17194 | ||
17195 | ||
17196 | oindex:[%widen_domains%] | |
17197 | `..'= | |
17198 | %widen_domains%, Use: 'dnslookup', Type: 'string list', Default: 'unset' | |
17199 | === | |
17200 | ||
17201 | cindex:[domain,partial; widening] | |
17202 | If a DNS lookup fails and this option is set, each of its strings in turn is | |
17203 | added onto the end of the domain, and the lookup is tried again. For example, | |
17204 | if | |
17205 | ||
17206 | widen_domains = fict.example:ref.example | |
17207 | ||
17208 | is set and a lookup of 'klingon.dictionary' fails, | |
17209 | 'klingon.dictionary.fict.example' is looked up, and if this fails, | |
17210 | 'klingon.dictionary.ref.example' is tried. Note that the %qualify_single% | |
17211 | and %search_parents% options can cause some widening to be undertaken inside | |
17212 | the DNS resolver. | |
17213 | ||
068aaea8 PH |
17214 | [revisionflag="changed"] |
17215 | %widen_domains% is not applied to sender addresses when verifying, unless | |
17216 | %rewrite_headers% is false (not the default). | |
17217 | ||
168e428f PH |
17218 | |
17219 | ||
17220 | Effect of qualify_single and search_parents | |
17221 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
17222 | When a domain from an envelope recipient is changed by the resolver as a result | |
17223 | of the %qualify_single% or %search_parents% options, Exim rewrites the | |
17224 | corresponding address in the message's header lines unless %rewrite_headers% | |
17225 | is set false. Exim then re-routes the address, using the full domain. | |
17226 | ||
17227 | These two options affect only the DNS lookup that takes place inside the router | |
17228 | for the domain of the address that is being routed. They do not affect lookups | |
17229 | such as that implied by | |
17230 | ||
17231 | domains = @mx_any | |
17232 | ||
17233 | that may happen while processing a router precondition before the router is | |
17234 | entered. No widening ever takes place for these lookups. | |
17235 | ||
17236 | ||
17237 | ||
17238 | ||
17239 | ||
17240 | ||
17241 | ||
17242 | ||
17243 | ||
17244 | //////////////////////////////////////////////////////////////////////////// | |
17245 | //////////////////////////////////////////////////////////////////////////// | |
17246 | ||
17247 | The ipliteral router | |
17248 | -------------------- | |
17249 | cindex:[^ipliteral^ router] | |
17250 | cindex:[domain literal,routing] | |
17251 | cindex:[routers,^ipliteral^] | |
17252 | This router has no private options. Unless it is being used purely for | |
17253 | verification (see %verify_only%) a transport is required to be defined by the | |
17254 | generic %transport% option. The router accepts the address if its domain part | |
17255 | takes the form of an RFC 2822 domain literal, that is, an IP address enclosed | |
17256 | in square brackets. For example, this router handles the address | |
17257 | ||
17258 | root@[192.168.1.1] | |
17259 | ||
17260 | by setting up delivery to the host with that IP address. | |
17261 | ||
17262 | cindex:[%self% option,in ^ipliteral^ router] | |
17263 | If the IP address matches something in %ignore_target_hosts%, the router | |
17264 | declines. If an IP literal turns out to refer to the local host, the generic | |
17265 | %self% option determines what happens. | |
17266 | ||
17267 | The RFCs require support for domain literals; however, their use is | |
17268 | controversial in today's Internet. If you want to use this router, you must | |
17269 | also set the main configuration option %allow_domain_literals%. Otherwise, | |
17270 | Exim will not recognize the domain literal syntax in addresses. | |
17271 | ||
17272 | ||
17273 | ||
17274 | //////////////////////////////////////////////////////////////////////////// | |
17275 | //////////////////////////////////////////////////////////////////////////// | |
17276 | ||
17277 | The iplookup router | |
17278 | ------------------- | |
17279 | cindex:[^iplookup^ router] | |
17280 | cindex:[routers,^iplookup^] | |
17281 | The ^iplookup^ router was written to fulfil a specific requirement in | |
17282 | Cambridge University (which in fact no longer exists). For this reason, it is | |
17283 | not included in the binary of Exim by default. If you want to include it, you | |
17284 | must set | |
17285 | ||
17286 | ROUTER_IPLOOKUP=yes | |
17287 | ||
17288 | in your _Local/Makefile_ configuration file. | |
17289 | ||
17290 | The ^iplookup^ router routes an address by sending it over a TCP or UDP | |
17291 | connection to one or more specific hosts. The host can then return the same or | |
17292 | a different address -- in effect rewriting the recipient address in the | |
17293 | message's envelope. The new address is then passed on to subsequent routers. If | |
17294 | this process fails, the address can be passed on to other routers, or delivery | |
17295 | can be deferred. | |
17296 | ||
17297 | Background, for those that are interested: We have an Oracle database of all | |
17298 | Cambridge users, and one of the items of data it maintains for each user is | |
17299 | where to send mail addressed to 'user@cam.ac.uk'. The MX records for | |
17300 | 'cam.ac.uk' point to a central machine that has a large alias list that is | |
17301 | abstracted from the database. Mail from outside is switched by this system, and | |
17302 | originally internal mail was also done this way. However, this resulted in a | |
17303 | fair number of messages travelling from some of our larger systems to the | |
17304 | switch and back again. The Oracle machine now runs a UDP service that can be | |
17305 | called by the ^iplookup^ router in Exim to find out where 'user@cam.ac.uk' | |
17306 | addresses really have to go; this saves passing through the central switch, and | |
17307 | in many cases saves doing any remote delivery at all. | |
17308 | ||
17309 | Since ^iplookup^ is just a rewriting router, a transport must not be | |
17310 | specified for it. | |
17311 | cindex:[options,^iplookup^ router] | |
17312 | ||
17313 | ||
17314 | oindex:[%hosts%] | |
17315 | `..'= | |
17316 | %hosts%, Use: 'iplookup', Type: 'string', Default: 'unset' | |
17317 | === | |
17318 | ||
17319 | This option must be supplied. Its value is a colon-separated list of host | |
17320 | names. The hosts are looked up using 'gethostbyname()' | |
17321 | (or 'getipnodebyname()' when available) | |
17322 | and are tried in order until one responds to the query. If none respond, what | |
17323 | happens is controlled by %optional%. | |
17324 | ||
17325 | ||
17326 | oindex:[%optional%] | |
17327 | `..'= | |
17328 | %optional%, Use: 'iplookup', Type: 'boolean', Default: 'false' | |
17329 | === | |
17330 | ||
17331 | If %optional% is true, if no response is obtained from any host, the address is | |
17332 | passed to the next router, overriding %no_more%. If %optional% is false, | |
17333 | delivery to the address is deferred. | |
17334 | ||
17335 | ||
17336 | oindex:[%port%] | |
17337 | `..'= | |
17338 | %port%, Use: 'iplookup', Type: 'integer', Default: '0' | |
17339 | === | |
17340 | ||
17341 | cindex:[port,^iplookup^ router] | |
17342 | This option must be supplied. It specifies the port number for the TCP or UDP | |
17343 | call. | |
17344 | ||
17345 | ||
17346 | oindex:[%protocol%] | |
17347 | `..'= | |
17348 | %protocol%, Use: 'iplookup', Type: 'string', Default: 'udp' | |
17349 | === | |
17350 | ||
17351 | This option can be set to ``udp'' or ``tcp'' to specify which of the two protocols | |
17352 | is to be used. | |
17353 | ||
17354 | ||
17355 | oindex:[%query%] | |
17356 | `..'= | |
17357 | %query%, Use: 'iplookup', Type: 'string'!!, Default: `\$local_part@\$domain \$local_part@\$domain` | |
17358 | === | |
17359 | ||
17360 | This defines the content of the query that is sent to the remote hosts. The | |
17361 | repetition serves as a way of checking that a response is to the correct query | |
17362 | in the default case (see %response_pattern% below). | |
17363 | ||
17364 | ||
17365 | oindex:[%reroute%] | |
17366 | `..'= | |
17367 | %reroute%, Use: 'iplookup', Type: 'string'!!, Default: 'unset' | |
17368 | === | |
17369 | ||
17370 | If this option is not set, the rerouted address is precisely the byte string | |
17371 | returned by the remote host, up to the first white space, if any. If set, the | |
17372 | string is expanded to form the rerouted address. It can include parts matched | |
17373 | in the response by %response_pattern% by means of numeric variables such as | |
17374 | $1$, $2$, etc. The variable $0$ refers to the entire input string, | |
17375 | whether or not a pattern is in use. In all cases, the rerouted address must end | |
17376 | up in the form 'local_part@domain'. | |
17377 | ||
17378 | ||
17379 | oindex:[%response_pattern%] | |
17380 | `..'= | |
17381 | %response_pattern%, Use: 'iplookup', Type: 'string', Default: 'unset' | |
17382 | === | |
17383 | ||
17384 | This option can be set to a regular expression that is applied to the string | |
17385 | returned from the remote host. If the pattern does not match the response, the | |
17386 | router declines. If %response_pattern% is not set, no checking of the response | |
17387 | is done, unless the query was defaulted, in which case there is a check that | |
17388 | the text returned after the first white space is the original address. This | |
17389 | checks that the answer that has been received is in response to the correct | |
17390 | question. For example, if the response is just a new domain, the following | |
17391 | could be used: | |
17392 | ||
17393 | response_pattern = ^([^@]+)$ | |
17394 | reroute = $local_part@$1 | |
17395 | ||
17396 | ||
17397 | ||
17398 | oindex:[%timeout%] | |
17399 | `..'= | |
17400 | %timeout%, Use: 'iplookup', Type: 'time', Default: '5s' | |
17401 | === | |
17402 | ||
17403 | This specifies the amount of time to wait for a response from the remote | |
17404 | machine. The same timeout is used for the 'connect()' function for a TCP | |
17405 | call. It does not apply to UDP. | |
17406 | ||
17407 | ||
17408 | ||
17409 | ||
17410 | //////////////////////////////////////////////////////////////////////////// | |
17411 | //////////////////////////////////////////////////////////////////////////// | |
17412 | ||
17413 | The manualroute router | |
17414 | ---------------------- | |
17415 | cindex:[^manualroute^ router] | |
17416 | cindex:[routers,^manualroute^] | |
17417 | cindex:[domain,manually routing] | |
17418 | The ^manualroute^ router is so-called because it provides a way of manually | |
17419 | routing an address according to its domain. It is mainly used when you want to | |
17420 | route addresses to remote hosts according to your own rules, bypassing the | |
17421 | normal DNS routing that looks up MX records. However, ^manualroute^ can also | |
17422 | route to local transports, a facility that may be useful if you want to save | |
17423 | messages for dial-in hosts in local files. | |
17424 | ||
17425 | The ^manualroute^ router compares a list of domain patterns with the domain it | |
17426 | is trying to route. If there is no match, the router declines. Each pattern has | |
17427 | associated with it a list of hosts and some other optional data, which may | |
17428 | include a transport. The combination of a pattern and its data is called a | |
17429 | ``routing rule''. For patterns that do not have an associated transport, the | |
17430 | generic %transport% option must specify a transport, unless the router is being | |
17431 | used purely for verification (see %verify_only%). | |
17432 | ||
068aaea8 | 17433 | cindex:[$host$] |
168e428f PH |
17434 | In the case of verification, matching the domain pattern is sufficient for the |
17435 | router to accept the address. When actually routing an address for delivery, | |
17436 | an address that matches a domain pattern is queued for the associated | |
17437 | transport. If the transport is not a local one, a host list must be associated | |
17438 | with the pattern; IP addresses are looked up for the hosts, and these are | |
17439 | passed to the transport along with the mail address. For local transports, a | |
17440 | host list is optional. If it is present, it is passed in $host$ as a single | |
17441 | text string. | |
17442 | ||
17443 | The list of routing rules can be provided as an inline string in %route_list%, | |
17444 | or the data can be obtained by looking up the domain in a file or database by | |
17445 | setting %route_data%. Only one of these settings may appear in any one | |
17446 | instance of ^manualroute^. The format of routing rules is described below, | |
17447 | following the list of private options. | |
17448 | ||
17449 | ||
17450 | [[SECTprioptman]] | |
17451 | Private options for manualroute | |
17452 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
17453 | ||
17454 | cindex:[options,^manualroute^ router] | |
17455 | The private options for the ^manualroute^ router are as follows: | |
17456 | ||
17457 | ||
17458 | oindex:[%host_find_failed%] | |
17459 | `..'= | |
17460 | %host_find_failed%, Use: 'manualroute', Type: 'string', Default: 'freeze' | |
17461 | === | |
17462 | ||
17463 | This option controls what happens when ^manualroute^ tries to find an IP | |
17464 | address for a host, and the host does not exist. The option can be set to one | |
17465 | of | |
17466 | ||
17467 | decline | |
17468 | defer | |
17469 | fail | |
17470 | freeze | |
17471 | pass | |
17472 | ||
17473 | The default assumes that this state is a serious configuration error. The | |
17474 | difference between ``pass'' and ``decline'' is that the former forces the address | |
17475 | to be passed to the next router (or the router defined by %pass_router%), | |
17476 | cindex:[%more% option] | |
17477 | overriding %no_more%, whereas the latter passes the address to the next router | |
17478 | only if %more% is true. | |
17479 | ||
17480 | This option applies only to a definite ``does not exist'' state; if a host lookup | |
17481 | gets a temporary error, delivery is deferred unless the generic | |
17482 | %pass_on_timeout% option is set. | |
17483 | ||
17484 | ||
17485 | oindex:[%hosts_randomize%] | |
17486 | `..'= | |
17487 | %hosts_randomize%, Use: 'manualroute', Type: 'boolean', Default: 'false' | |
17488 | === | |
17489 | ||
17490 | cindex:[randomized host list] | |
17491 | cindex:[host,list of; randomized] | |
17492 | If this option is set, the order of the items in a host list in a routing rule | |
17493 | is randomized each time the list is used, unless an option in the routing rule | |
17494 | overrides (see below). Randomizing the order of a host list can be used to do | |
17495 | crude load sharing. However, if more than one mail address is routed by the | |
17496 | same router to the same host list, the host lists are considered to be the same | |
17497 | (even though they may be randomized into different orders) for the purpose of | |
17498 | deciding whether to batch the deliveries into a single SMTP transaction. | |
17499 | ||
17500 | When %hosts_randomize% is true, a host list may be split | |
17501 | into groups whose order is separately randomized. This makes it possible to | |
17502 | set up MX-like behaviour. The boundaries between groups are indicated by an | |
17503 | item that is just `+` in the host list. For example: | |
17504 | ||
17505 | route_list = * host1:host2:host3:+:host4:host5 | |
17506 | ||
17507 | The order of the first three hosts and the order of the last two hosts is | |
17508 | randomized for each use, but the first three always end up before the last two. | |
17509 | If %hosts_randomize% is not set, a `+` item in the list is ignored. If a | |
17510 | randomized host list is passed to an ^smtp^ transport that also has | |
17511 | %hosts_randomize set%, the list is not re-randomized. | |
17512 | ||
17513 | ||
17514 | oindex:[%route_data%] | |
17515 | `..'= | |
17516 | %route_data%, Use: 'manualroute', Type: 'string'!!, Default: 'unset' | |
17517 | === | |
17518 | ||
17519 | If this option is set, it must expand to yield the data part of a routing rule. | |
17520 | Typically, the expansion string includes a lookup based on the domain. For | |
17521 | example: | |
17522 | ||
17523 | route_data = ${lookup{$domain}dbm{/etc/routes}} | |
17524 | ||
17525 | If the expansion is forced to fail, or the result is an empty string, the | |
17526 | router declines. Other kinds of expansion failure cause delivery to be | |
17527 | deferred. | |
17528 | ||
17529 | ||
17530 | oindex:[%route_list%] | |
17531 | `..'= | |
17532 | %route_list%, Use: 'manualroute', "Type: 'string list, semicolon-separated'", Default: 'unset' | |
17533 | === | |
17534 | ||
17535 | This string is a list of routing rules, in the form defined below. Note that, | |
17536 | unlike most string lists, the items are separated by semicolons. This is so | |
17537 | that they may contain colon-separated host lists. | |
17538 | ||
17539 | ||
17540 | oindex:[%same_domain_copy_routing%] | |
17541 | `..'= | |
17542 | %same_domain_copy_routing%, Use: 'manualroute', Type: 'boolean', Default: 'false' | |
17543 | === | |
17544 | ||
17545 | cindex:[address,copying routing] | |
17546 | Addresses with the same domain are normally routed by the ^manualroute^ router | |
17547 | to the same list of hosts. However, this cannot be presumed, because the router | |
17548 | options and preconditions may refer to the local part of the address. By | |
17549 | default, therefore, Exim routes each address in a message independently. DNS | |
17550 | servers run caches, so repeated DNS lookups are not normally expensive, and in | |
17551 | any case, personal messages rarely have more than a few recipients. | |
17552 | ||
17553 | If you are running mailing lists with large numbers of subscribers at the same | |
17554 | domain, and you are using a ^manualroute^ router which is independent of the | |
17555 | local part, you can set %same_domain_copy_routing% to bypass repeated DNS | |
17556 | lookups for identical domains in one message. In this case, when ^manualroute^ | |
17557 | routes an address to a remote transport, any other unrouted addresses in the | |
17558 | message that have the same domain are automatically given the same routing | |
17559 | without processing them independently. However, this is only done if | |
17560 | %headers_add% and %headers_remove% are unset. | |
17561 | ||
17562 | ||
17563 | ||
17564 | ||
17565 | Routing rules in route_list | |
17566 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
17567 | The value of %route_list% is a string consisting of a sequence of routing | |
17568 | rules, separated by semicolons. If a semicolon is needed in a rule, it can be | |
068aaea8 PH |
17569 | entered as two semicolons. Alternatively, the list separator can be changed as |
17570 | described (for colon-separated lists) in section <<SECTlistconstruct>>. | |
17571 | Empty rules are ignored. The format of each rule is | |
168e428f PH |
17572 | |
17573 | <domain pattern> <list of hosts> <options> | |
17574 | ||
17575 | The following example contains two rules, each with a simple domain pattern and | |
17576 | no options: | |
17577 | ||
17578 | .... | |
17579 | route_list = \ | |
17580 | dict.ref.example mail-1.ref.example:mail-2.ref.example ; \ | |
17581 | thes.ref.example mail-3.ref.example:mail-4.ref.example | |
17582 | .... | |
17583 | ||
17584 | The three parts of a rule are separated by white space. The pattern and the | |
17585 | list of hosts can be enclosed in quotes if necessary, and if they are, the | |
17586 | usual quoting rules apply. Each rule in a %route_list% must start with a | |
17587 | single domain pattern, which is the only mandatory item in the rule. The | |
17588 | pattern is in the same format as one item in a domain list (see section | |
17589 | <<SECTdomainlist>>), | |
17590 | except that it may not be the name of an interpolated file. | |
17591 | That is, it may be wildcarded, or a regular expression, or a file or database | |
17592 | lookup (with semicolons doubled, because of the use of semicolon as a separator | |
17593 | in a %route_list%). | |
17594 | ||
17595 | The rules in %route_list% are searched in order until one of the patterns | |
17596 | matches the domain that is being routed. The list of hosts and then options are | |
17597 | then used as described below. If there is no match, the router declines. When | |
17598 | %route_list% is set, %route_data% must not be set. | |
17599 | ||
17600 | ||
17601 | ||
17602 | Routing rules in route_data | |
17603 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
17604 | The use of %route_list% is convenient when there are only a small number of | |
17605 | routing rules. For larger numbers, it is easier to use a file or database to | |
17606 | hold the routing information, and use the %route_data% option instead. | |
17607 | The value of %route_data% is a list of hosts, followed by (optional) options. | |
17608 | Most commonly, %route_data% is set as a string that contains an | |
17609 | expansion lookup. For example, suppose we place two routing rules in a file | |
17610 | like this: | |
17611 | ||
17612 | dict.ref.example: mail-1.ref.example:mail-2.ref.example | |
17613 | thes.ref.example: mail-3.ref.example:mail-4.ref.example | |
17614 | ||
17615 | This data can be accessed by setting | |
17616 | ||
17617 | route_data = ${lookup{$domain}lsearch{/the/file/name}} | |
17618 | ||
17619 | Failure of the lookup results in an empty string, causing the router to | |
17620 | decline. However, you do not have to use a lookup in %route_data%. The only | |
17621 | requirement is that the result of expanding the string is a list of hosts, | |
17622 | possibly followed by options, separated by white space. The list of hosts must | |
17623 | be enclosed in quotes if it contains white space. | |
17624 | ||
17625 | ||
17626 | ||
17627 | ||
17628 | Format of the list of hosts | |
17629 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
068aaea8 | 17630 | [revisionflag="changed"] |
168e428f PH |
17631 | A list of hosts, whether obtained via %route_data% or %route_list%, is always |
17632 | separately expanded before use. If the expansion fails, the router declines. | |
17633 | The result of the expansion must be a colon-separated list of names and/or | |
068aaea8 PH |
17634 | IP addresses, optionally also including ports. The format of each item in the |
17635 | list is described in the next section. The list separator can be changed as | |
17636 | described in section <<SECTlistconstruct>>. | |
168e428f PH |
17637 | |
17638 | If the list of hosts was obtained from a %route_list% item, the following | |
17639 | variables are set during its expansion: | |
17640 | ||
17641 | - cindex:[numerical variables ($1$ $2$ etc),in ^manualroute^ router] | |
17642 | If the domain was matched against a regular expression, the numeric variables | |
068aaea8 PH |
17643 | $1$, $2$, etc. may be set. For example: |
17644 | ||
17645 | .... | |
17646 | route_list = ^domain(\d+) host-$1.text.example | |
17647 | .... | |
168e428f PH |
17648 | |
17649 | - $0$ is always set to the entire domain. | |
17650 | ||
17651 | - $1$ is also set when partial matching is done in a file lookup. | |
17652 | ||
17653 | - cindex:[$value$] | |
17654 | If the pattern that matched the domain was a lookup item, the data that was | |
068aaea8 PH |
17655 | looked up is available in the expansion variable $value$. For example: |
17656 | ||
17657 | .... | |
17658 | route_list = lsearch;;/some/file.routes $value | |
17659 | .... | |
17660 | ||
17661 | Note the doubling of the semicolon in the pattern that is necessary because | |
17662 | semicolon is the default route list separator. | |
17663 | ||
17664 | ||
17665 | ||
17666 | [[SECTformatonehostitem]] | |
17667 | Format of one host item | |
17668 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
17669 | [revisionflag="changed"] | |
17670 | Each item in the list of hosts is either a host name or an IP address, | |
17671 | optionally with an attached port number. When no port is given, an IP address | |
17672 | is not enclosed in brackets. When a port is specified, it overrides the port | |
17673 | specification on the transport. The port is separated from the name or address | |
17674 | by a colon. This leads to some complications: | |
168e428f | 17675 | |
068aaea8 PH |
17676 | [revisionflag="changed"] |
17677 | - Because colon is the default separator for the list of hosts, either | |
17678 | the colon that specifies a port must be doubled, or the list separator must | |
17679 | be changed. The following two examples have the same effect: | |
17680 | + | |
17681 | route_list = * "host1.tld::1225 : host2.tld::1226" | |
17682 | route_list = * "<+ host1.tld:1225 + host2.tld:1226" | |
17683 | ||
17684 | [revisionflag="changed"] | |
17685 | - When IPv6 addresses are involved, it gets worse, because they contain | |
17686 | colons of their own. To make this case easier, it is permitted to | |
17687 | enclose an IP address (either v4 or v6) in square brackets if a port | |
17688 | number follows. For example: | |
17689 | + | |
17690 | route_list = * "</ [10.1.1.1]:1225 / [::1]:1226" | |
168e428f PH |
17691 | |
17692 | ||
17693 | ||
068aaea8 | 17694 | [[SECThostshowused]] |
168e428f PH |
17695 | How the list of hosts is used |
17696 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
17697 | When an address is routed to an ^smtp^ transport by ^manualroute^, each of | |
17698 | the hosts is tried, in the order specified, when carrying out the SMTP | |
17699 | delivery. However, the order can be changed by setting the %hosts_randomize% | |
17700 | option, either on the router (see section <<SECTprioptman>> above), or on the | |
17701 | transport. | |
17702 | ||
17703 | Hosts may be listed by name or by IP address. An unadorned name in the list of | |
17704 | hosts is interpreted as a host name. A name that is followed by `/MX` is | |
17705 | interpreted as an indirection to a sublist of hosts obtained by looking up MX | |
17706 | records in the DNS. For example: | |
17707 | ||
17708 | route_list = * x.y.z:p.q.r/MX:e.f.g | |
17709 | ||
068aaea8 PH |
17710 | [revisionflag="changed"] |
17711 | If this feature is used with a port specifier, the port must come last. For | |
17712 | example: | |
17713 | ||
17714 | route_list = * dom1.tld/mx::1225 | |
17715 | ||
168e428f PH |
17716 | If the %hosts_randomize% option is set, the order of the items in the list is |
17717 | randomized before any lookups are done. Exim then scans the list; for any name | |
17718 | that is not followed by `/MX` it looks up an IP address. If this turns out to | |
17719 | be an interface on the local host and the item is not the first in the list, | |
17720 | Exim discards it and any subsequent items. If it is the first item, what | |
17721 | happens is controlled by the | |
17722 | cindex:[%self% option,in ^manualroute^ router] | |
17723 | %self% option of the router. | |
17724 | ||
17725 | A name on the list that is followed by `/MX` is replaced with the list of | |
17726 | hosts obtained by looking up MX records for the name. This is always a DNS | |
17727 | lookup; the %bydns% and %byname% options (see section <<SECThowoptused>> below) | |
17728 | are not relevant here. The order of these hosts is determined by the preference | |
17729 | values in the MX records, according to the usual rules. Because randomizing | |
17730 | happens before the MX lookup, it does not affect the order that is defined by | |
17731 | MX preferences. | |
17732 | ||
17733 | If the local host is present in the sublist obtained from MX records, but is | |
17734 | not the most preferred host in that list, it and any equally or less | |
17735 | preferred hosts are removed before the sublist is inserted into the main list. | |
17736 | ||
17737 | If the local host is the most preferred host in the MX list, what happens | |
17738 | depends on where in the original list of hosts the `/MX` item appears. If it | |
17739 | is not the first item (that is, there are previous hosts in the main list), | |
17740 | Exim discards this name and any subsequent items in the main list. | |
17741 | ||
17742 | If the MX item is first in the list of hosts, and the local host is the | |
17743 | most preferred host, what happens is controlled by the %self% option of the | |
17744 | router. | |
17745 | ||
17746 | DNS failures when lookup up the MX records are treated in the same way as DNS | |
17747 | failures when looking up IP addresses: %pass_on_timeout% and | |
17748 | %host_find_failed% are used when relevant. | |
17749 | ||
17750 | The generic %ignore_target_hosts% option applies to all hosts in the list, | |
17751 | whether obtained from an MX lookup or not. | |
17752 | ||
17753 | ||
17754 | ||
17755 | [[SECThowoptused]] | |
17756 | How the options are used | |
17757 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
17758 | The options are a sequence of words; in practice no more than three are ever | |
17759 | present. One of the words can be the name of a transport; this overrides the | |
17760 | %transport% option on the router for this particular routing rule only. The | |
17761 | other words (if present) control randomization of the list of hosts on a | |
17762 | per-rule basis, and how the IP addresses of the hosts are to be found when | |
17763 | routing to a remote transport. These options are as follows: | |
17764 | ||
17765 | - %randomize%: randomize the order of the hosts in this list, overriding the | |
17766 | setting of %hosts_randomize% for this routing rule only. | |
17767 | ||
17768 | - %no_randomize%: do not randomize the order of the hosts in this list, | |
17769 | overriding the setting of %hosts_randomize% for this routing rule only. | |
17770 | ||
17771 | - %byname%: use 'getipnodebyname()' ('gethostbyname()' on older systems) to | |
17772 | find IP addresses. This function may ultimately cause a DNS lookup, but it may | |
17773 | also look in _/etc/hosts_ or other sources of information. | |
17774 | ||
17775 | - %bydns%: look up address records for the hosts directly in the DNS; fail if | |
17776 | no address records are found. If there is a temporary DNS error (such as a | |
17777 | timeout), delivery is deferred. | |
17778 | ||
17779 | For example: | |
17780 | ||
17781 | .... | |
17782 | route_list = domain1 host1:host2:host3 randomize bydns;\ | |
17783 | domain2 host4:host5 | |
17784 | .... | |
17785 | ||
17786 | If neither %byname% nor %bydns% is given, Exim behaves as follows: First, a DNS | |
17787 | lookup is done. If this yields anything other than HOST_NOT_FOUND, that | |
17788 | result is used. Otherwise, Exim goes on to try a call to 'getipnodebyname()' | |
17789 | or 'gethostbyname()', and the result of the lookup is the result of that | |
17790 | call. | |
17791 | ||
17792 | *Warning*: It has been discovered that on some systems, if a DNS lookup | |
17793 | called via 'getipnodebyname()' times out, HOST_NOT_FOUND is returned | |
17794 | instead of TRY_AGAIN. That is why the default action is to try a DNS | |
17795 | lookup first. Only if that gives a definite ``no such host'' is the local | |
17796 | function called. | |
17797 | ||
17798 | ||
17799 | ||
17800 | If no IP address for a host can be found, what happens is controlled by the | |
17801 | %host_find_failed% option. | |
17802 | ||
068aaea8 | 17803 | cindex:[$host$] |
168e428f PH |
17804 | When an address is routed to a local transport, IP addresses are not looked up. |
17805 | The host list is passed to the transport in the $host$ variable. | |
17806 | ||
17807 | ||
17808 | ||
17809 | Manualroute examples | |
17810 | ~~~~~~~~~~~~~~~~~~~~ | |
17811 | In some of the examples that follow, the presence of the %remote_smtp% | |
17812 | transport, as defined in the default configuration file, is assumed: | |
17813 | ||
17814 | - cindex:[smart host,example router] | |
17815 | The ^manualroute^ router can be used to forward all external mail to a | |
17816 | 'smart host'. If you have set up, in the main part of the configuration, a | |
17817 | named domain list that contains your local domains, for example, | |
17818 | ||
17819 | domainlist local_domains = my.domain.example | |
17820 | + | |
17821 | you can arrange for all other domains to be routed to a smart host by making | |
17822 | your first router something like this: | |
17823 | + | |
17824 | smart_route: | |
17825 | driver = manualroute | |
17826 | domains = !+local_domains | |
17827 | transport = remote_smtp | |
17828 | route_list = * smarthost.ref.example | |
17829 | + | |
17830 | This causes all non-local addresses to be sent to the single host | |
17831 | 'smarthost.ref.example'. If a colon-separated list of smart hosts is given, | |
17832 | they are tried in order | |
17833 | (but you can use %hosts_randomize% to vary the order each time). | |
17834 | Another way of configuring the same thing is this: | |
17835 | + | |
17836 | smart_route: | |
17837 | driver = manualroute | |
17838 | transport = remote_smtp | |
17839 | route_list = !+local_domains smarthost.ref.example | |
17840 | + | |
17841 | There is no difference in behaviour between these two routers as they stand. | |
17842 | However, they behave differently if %no_more% is added to them. In the first | |
17843 | example, the router is skipped if the domain does not match the %domains% | |
17844 | precondition; the following router is always tried. If the router runs, it | |
17845 | always matches the domain and so can never decline. Therefore, %no_more% would | |
17846 | have no effect. In the second case, the router is never skipped; it always | |
17847 | runs. However, if it doesn't match the domain, it declines. In this case | |
17848 | %no_more% would prevent subsequent routers from running. | |
17849 | ||
17850 | - cindex:[mail hub example] | |
17851 | A 'mail hub' is a host which receives mail for a number of domains via MX | |
17852 | records in the DNS and delivers it via its own private routing mechanism. Often | |
17853 | the final destinations are behind a firewall, with the mail hub being the one | |
17854 | machine that can connect to machines both inside and outside the firewall. The | |
17855 | ^manualroute^ router is usually used on a mail hub to route incoming messages | |
17856 | to the correct hosts. For a small number of domains, the routing can be inline, | |
17857 | using the %route_list% option, but for a larger number a file or database | |
17858 | lookup is easier to manage. | |
17859 | + | |
17860 | If the domain names are in fact the names of the machines to which the mail is | |
17861 | to be sent by the mail hub, the configuration can be quite simple. For | |
17862 | example, | |
17863 | ||
17864 | hub_route: | |
17865 | driver = manualroute | |
17866 | transport = remote_smtp | |
17867 | route_list = *.rhodes.tvs.example $domain | |
17868 | + | |
17869 | This configuration routes domains that match `*.rhodes.tvs.example` to hosts | |
17870 | whose names are the same as the mail domains. A similar approach can be taken | |
17871 | if the host name can be obtained from the domain name by a string manipulation | |
17872 | that the expansion facilities can handle. Otherwise, a lookup based on the | |
17873 | domain can be used to find the host: | |
17874 | ||
17875 | through_firewall: | |
17876 | driver = manualroute | |
17877 | transport = remote_smtp | |
17878 | route_data = ${lookup {$domain} cdb {/internal/host/routes}} | |
17879 | + | |
17880 | The result of the lookup must be the name or IP address of the host (or | |
17881 | hosts) to which the address is to be routed. If the lookup fails, the route | |
17882 | data is empty, causing the router to decline. The address then passes to the | |
17883 | next router. | |
17884 | ||
17885 | - cindex:[batched SMTP output example] | |
17886 | cindex:[SMTP,batched outgoing; example] | |
17887 | You can use ^manualroute^ to deliver messages to pipes or files in batched | |
17888 | SMTP format for onward transportation by some other means. This is one way of | |
17889 | storing mail for a dial-up host when it is not connected. The route list entry | |
17890 | can be as simple as a single domain name in a configuration like this: | |
17891 | ||
17892 | save_in_file: | |
17893 | driver = manualroute | |
17894 | transport = batchsmtp_appendfile | |
17895 | route_list = saved.domain.example | |
17896 | + | |
17897 | though often a pattern is used to pick up more than one domain. If there are | |
17898 | several domains or groups of domains with different transport requirements, | |
17899 | different transports can be listed in the routing information: | |
17900 | + | |
17901 | .... | |
17902 | save_in_file: | |
17903 | driver = manualroute | |
17904 | route_list = \ | |
17905 | *.saved.domain1.example $domain batch_appendfile; \ | |
17906 | *.saved.domain2.example \ | |
17907 | ${lookup{$domain}dbm{/domain2/hosts}{$value}fail} \ | |
17908 | batch_pipe | |
17909 | .... | |
17910 | + | |
068aaea8 PH |
17911 | cindex:[$domain$] |
17912 | cindex:[$host$] | |
168e428f PH |
17913 | The first of these just passes the domain in the $host$ variable, which |
17914 | doesn't achieve much (since it is also in $domain$), but the second does a | |
17915 | file lookup to find a value to pass, causing the router to decline to handle | |
17916 | the address if the lookup fails. | |
17917 | ||
17918 | - cindex:[UUCP,example of router for] | |
17919 | Routing mail directly to UUCP software is a specific case of the use of | |
17920 | ^manualroute^ in a gateway to another mail environment. This is an example of | |
17921 | one way it can be done: | |
17922 | + | |
17923 | .... | |
17924 | # Transport | |
17925 | uucp: | |
17926 | driver = pipe | |
17927 | user = nobody | |
17928 | command = /usr/local/bin/uux -r - \ | |
17929 | ${substr_-5:$host}!rmail ${local_part} | |
17930 | return_fail_output = true | |
17931 | ||
17932 | # Router | |
17933 | uucphost: | |
17934 | transport = uucp | |
17935 | driver = manualroute | |
17936 | route_data = \ | |
17937 | ${lookup{$domain}lsearch{/usr/local/exim/uucphosts}} | |
17938 | .... | |
17939 | + | |
17940 | The file _/usr/local/exim/uucphosts_ contains entries like | |
17941 | ||
17942 | darksite.ethereal.example: darksite.UUCP | |
17943 | + | |
17944 | It can be set up more simply without adding and removing ``.UUCP'' but this way | |
17945 | makes clear the distinction between the domain name | |
17946 | 'darksite.ethereal.example' and the UUCP host name 'darksite'. | |
17947 | ||
17948 | ||
17949 | ||
17950 | ||
17951 | ||
17952 | ||
17953 | ||
17954 | ||
17955 | //////////////////////////////////////////////////////////////////////////// | |
17956 | //////////////////////////////////////////////////////////////////////////// | |
17957 | ||
17958 | [[CHAPdriverlast]] | |
17959 | The queryprogram router | |
17960 | ----------------------- | |
17961 | cindex:[^queryprogram^ router] | |
17962 | cindex:[routers,^queryprogram^] | |
17963 | cindex:[routing,by external program] | |
17964 | The ^queryprogram^ router routes an address by running an external command and | |
17965 | acting on its output. This is an expensive way to route, and is intended mainly | |
17966 | for use in lightly-loaded systems, or for performing experiments. However, if | |
17967 | it is possible to use the precondition options (%domains%, %local_parts%, | |
17968 | etc) to skip this router for most addresses, it could sensibly be used in | |
17969 | special cases, even on a busy host. There are the following private options: | |
17970 | cindex:[options,^queryprogram^ router] | |
17971 | ||
17972 | oindex:[%command%] | |
17973 | `..'= | |
17974 | %command%, Use: 'queryprogram', Type: 'string'!!, Default: 'unset' | |
17975 | === | |
17976 | ||
17977 | This option must be set. It specifies the command that is to be run. The | |
17978 | command is split up into a command name and arguments, and then each is | |
17979 | expanded separately (exactly as for a ^pipe^ transport, described in chapter | |
17980 | <<CHAPpipetransport>>). | |
17981 | ||
17982 | ||
17983 | oindex:[%command_group%] | |
17984 | `..'= | |
17985 | %command_group%, Use: 'queryprogram', Type: 'string', Default: 'unset' | |
17986 | === | |
17987 | ||
17988 | cindex:[gid (group id),in ^queryprogram^ router] | |
17989 | This option specifies a gid to be set when running the command. It must be set | |
17990 | if %command_user% specifies a numerical uid. If it begins with a digit, it is | |
17991 | interpreted as the numerical value of the gid. Otherwise it is looked up using | |
17992 | 'getgrnam()'. | |
17993 | ||
17994 | ||
17995 | oindex:[%command_user%] | |
17996 | `..'= | |
17997 | %command_user%, Use: 'queryprogram', Type: 'string', Default: 'unset' | |
17998 | === | |
17999 | ||
18000 | cindex:[uid (user id),for ^queryprogram^] | |
18001 | This option must be set. It specifies the uid which is set when running the | |
18002 | command. If it begins with a digit it is interpreted as the numerical value of | |
18003 | the uid. Otherwise, it is looked up using 'getpwnam()' to obtain a value for | |
18004 | the uid and, if %command_group% is not set, a value for the gid also. | |
18005 | ||
18006 | ||
18007 | oindex:[%current_directory%] | |
18008 | `..'= | |
18009 | %current_directory%, Use: 'queryprogram', Type: 'string', Default: '/' | |
18010 | === | |
18011 | ||
18012 | This option specifies an absolute path which is made the current directory | |
18013 | before running the command. | |
18014 | ||
18015 | ||
18016 | oindex:[%timeout%] | |
18017 | `..'= | |
18018 | %timeout%, Use: 'queryprogram', Type: 'time', Default: '1h' | |
18019 | === | |
18020 | ||
18021 | If the command does not complete within the timeout period, its process group | |
18022 | is killed and the message is frozen. A value of zero time specifies no | |
18023 | timeout. | |
18024 | ||
18025 | ||
18026 | The standard output of the command is connected to a pipe, which is read when | |
18027 | the command terminates. It should consist of a single line of output, | |
18028 | containing up to five fields, separated by white space. The maximum length of | |
18029 | the line is 1023 characters. Longer lines are silently truncated. The first | |
18030 | field is one of the following words (case-insensitive): | |
18031 | ||
18032 | - 'Accept': routing succeeded; the remaining fields specify what to do (see | |
18033 | below). | |
18034 | ||
18035 | - 'Decline': the router declines; pass the address to the next router, unless | |
18036 | %no_more% is set. | |
18037 | ||
18038 | - 'Fail': routing failed; do not pass the address to any more routers. Any | |
18039 | subsequent text on the line is an error message. If the router is run as part | |
18040 | of address verification during an incoming SMTP message, the message is | |
18041 | included in the SMTP response. | |
18042 | ||
18043 | - 'Defer': routing could not be completed at this time; try again later. Any | |
18044 | subsequent text on the line is an error message which is logged. It is not | |
18045 | included in any SMTP response. | |
18046 | ||
18047 | - 'Freeze': the same as 'defer', except that the message is frozen. | |
18048 | ||
18049 | - 'Pass': pass the address to the next router (or the router specified by | |
18050 | %pass_router%), overriding %no_more%. | |
18051 | ||
18052 | - 'Redirect': the message is redirected. The remainder of the line is a list of | |
18053 | new addresses, which are routed independently, starting with the first router, | |
18054 | or the router specified by %redirect_router%, if set. | |
18055 | ||
18056 | When the first word is 'accept', the remainder of the line consists of a | |
18057 | number of keyed data values, as follows (split into two lines here, to fit on | |
18058 | the page): | |
18059 | ||
18060 | ACCEPT TRANSPORT=<transport> HOSTS=<list of hosts> | |
18061 | LOOKUP=byname|bydns DATA=<text> | |
18062 | ||
18063 | The data items can be given in any order, and all are optional. If no transport | |
18064 | is included, the transport specified by the generic %transport% option is used. | |
18065 | The list of hosts and the lookup type are needed only if the transport is an | |
18066 | ^smtp^ transport that does not itself supply a list of hosts. | |
18067 | ||
18068 | The format of the list of hosts is the same as for the ^manualroute^ router. | |
068aaea8 PH |
18069 | As well as host names and IP addresses with optional port numbers, as described |
18070 | in section <<SECTformatonehostitem>>, it may contain names followed by `/MX` to | |
18071 | specify sublists of hosts that are obtained by looking up MX records (see | |
18072 | section <<SECThostshowused>>). | |
168e428f PH |
18073 | |
18074 | If the lookup type is not specified, Exim behaves as follows when trying to | |
18075 | find an IP address for each host: First, a DNS lookup is done. If this yields | |
18076 | anything other than HOST_NOT_FOUND, that result is used. Otherwise, Exim | |
18077 | goes on to try a call to 'getipnodebyname()' or 'gethostbyname()', and the | |
18078 | result of the lookup is the result of that call. | |
18079 | ||
068aaea8 | 18080 | cindex:[$address_data$] |
168e428f PH |
18081 | If the DATA field is set, its value is placed in the $address_data$ |
18082 | variable. For example, this return line | |
18083 | ||
18084 | accept hosts=x1.y.example:x2.y.example data="rule1" | |
18085 | ||
18086 | routes the address to the default transport, passing a list of two hosts. When | |
18087 | the transport runs, the string ``rule1'' is in $address_data$. | |
18088 | ||
18089 | ||
18090 | ||
18091 | ||
18092 | //////////////////////////////////////////////////////////////////////////// | |
18093 | //////////////////////////////////////////////////////////////////////////// | |
18094 | ||
18095 | [[CHAPredirect]] | |
18096 | The redirect router | |
18097 | ------------------- | |
18098 | cindex:[^redirect^ router] | |
18099 | cindex:[routers,^redirect^] | |
18100 | cindex:[alias file,in a ^redirect^ router] | |
18101 | cindex:[address redirection,^redirect^ router] | |
18102 | The ^redirect^ router handles several kinds of address redirection. Its most | |
18103 | common uses are for resolving local part aliases from a central alias file | |
18104 | (usually called _/etc/aliases_) and for handling users' personal _.forward_ | |
18105 | files, but it has many other potential uses. The incoming address can be | |
18106 | redirected in several different ways: | |
18107 | ||
18108 | - It can be replaced by one or more new addresses which are themselves routed | |
18109 | independently. | |
18110 | ||
18111 | - It can be routed to be delivered to a given file or directory. | |
18112 | ||
18113 | - It can be routed to be delivered to a specified pipe command. | |
18114 | ||
18115 | - It can cause an automatic reply to be generated. | |
18116 | ||
18117 | - It can be forced to fail, with a custom error message. | |
18118 | ||
18119 | - It can be temporarily deferred. | |
18120 | ||
18121 | - It can be discarded. | |
18122 | ||
18123 | The generic %transport% option must not be set for ^redirect^ routers. | |
18124 | However, there are some private options which define transports for delivery to | |
18125 | files and pipes, and for generating autoreplies. See the %file_transport%, | |
18126 | %pipe_transport% and %reply_transport% descriptions below. | |
18127 | ||
18128 | ||
18129 | ||
18130 | Redirection data | |
18131 | ~~~~~~~~~~~~~~~~ | |
18132 | The router operates by interpreting a text string which it obtains either by | |
18133 | expanding the contents of the %data% option, or by reading the entire contents | |
18134 | of a file whose name is given in the %file% option. These two options are | |
18135 | mutually exclusive. The first is commonly used for handling system aliases, in | |
18136 | a configuration like this: | |
18137 | ||
18138 | system_aliases: | |
18139 | driver = redirect | |
18140 | data = ${lookup{$local_part}lsearch{/etc/aliases}} | |
18141 | ||
18142 | If the lookup fails, the expanded string in this example is empty. When the | |
18143 | expansion of %data% results in an empty string, the router declines. A forced | |
18144 | expansion failure also causes the router to decline; other expansion failures | |
18145 | cause delivery to be deferred. | |
18146 | ||
18147 | A configuration using %file% is commonly used for handling users' _.forward_ | |
18148 | files, like this: | |
18149 | ||
18150 | userforward: | |
18151 | driver = redirect | |
18152 | check_local_user | |
18153 | file = $home/.forward | |
18154 | no_verify | |
18155 | ||
18156 | If the file does not exist, or causes no action to be taken (for example, it is | |
18157 | empty or consists only of comments), the router declines. *Warning*: This | |
18158 | is not the case when the file contains syntactically valid items that happen to | |
18159 | yield empty addresses, for example, items containing only RFC 2822 address | |
18160 | comments. | |
18161 | ||
18162 | ||
18163 | ||
18164 | Forward files and address verification | |
18165 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
18166 | cindex:[address redirection,while verifying] | |
18167 | It is usual to set %no_verify% on ^redirect^ routers which handle users' | |
18168 | _.forward_ files, as in the example above. There are two reasons for this: | |
18169 | ||
18170 | - When Exim is receiving an incoming SMTP message from a remote host, it is | |
18171 | running under the Exim uid, not as root. | |
18172 | No additional groups are set up, even if the Exim uid is a member of other | |
18173 | groups (that is, the 'initgroups()' function is not run). | |
18174 | Exim is unable to change uid to read the file as the user, and it may not be | |
18175 | able to read it as the Exim user. So in practice the router may not be able to | |
18176 | operate. | |
18177 | ||
18178 | - However, even when the router can operate, the existence of a _.forward_ file | |
18179 | is unimportant when verifying an address. What should be checked is whether the | |
18180 | local part is a valid user name or not. Cutting out the redirection processing | |
18181 | saves some resources. | |
18182 | ||
18183 | ||
18184 | ||
18185 | ||
18186 | ||
18187 | ||
18188 | Interpreting redirection data | |
18189 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
18190 | cindex:[Sieve filter,specifying in redirection data] | |
18191 | cindex:[filter,specifying in redirection data] | |
18192 | The contents of the data string, whether obtained from %data% or %file%, can be | |
18193 | interpreted in two different ways: | |
18194 | ||
18195 | - If the %allow_filter% option is set true, and the data begins with the text | |
18196 | ``#Exim filter'' or ``#Sieve filter'', it is interpreted as a list of | |
18197 | 'filtering' instructions in the form of an Exim or Sieve filter file, | |
18198 | respectively. Details of the syntax and semantics of filter files are described | |
18199 | in a separate document entitled 'Exim's interfaces to mail filtering'; this | |
18200 | document is intended for use by end users. | |
18201 | ||
18202 | - Otherwise, the data must be a comma-separated list of redirection items, as | |
18203 | described in the next section. | |
18204 | ||
18205 | When a message is redirected to a file (a ``mail folder''), the file name given | |
18206 | in a non-filter redirection list must always be an absolute path. A filter may | |
18207 | generate a relative path -- how this is handled depends on the transport's | |
18208 | configuration. See section <<SECTfildiropt>> for a discussion of this issue for | |
18209 | the ^appendfile^ transport. | |
18210 | ||
18211 | ||
18212 | ||
18213 | [[SECTitenonfilred]] | |
18214 | Items in a non-filter redirection list | |
18215 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
18216 | cindex:[address redirection,non-filter list items] | |
18217 | When the redirection data is not an Exim or Sieve filter, for example, if it | |
18218 | comes from a conventional alias or forward file, it consists of a list of | |
18219 | addresses, file names, pipe commands, or certain special items (see section | |
18220 | <<SECTspecitredli>> below). The special items can be individually enabled or | |
18221 | disabled by means of options whose names begin with %allow_% or %forbid_%, | |
18222 | depending on their default values. The items in the list are separated by | |
18223 | commas or newlines. | |
18224 | If a comma is required in an item, the entire item must be enclosed in double | |
18225 | quotes. | |
18226 | ||
18227 | Lines starting with a # character are comments, and are ignored, and # may | |
18228 | also appear following a comma, in which case everything between the # and the | |
18229 | next newline character is ignored. | |
18230 | ||
18231 | If an item is entirely enclosed in double quotes, these are removed. Otherwise | |
18232 | double quotes are retained because some forms of mail address require their use | |
068aaea8 PH |
18233 | (but never to enclose the entire address). In the following description, |
18234 | ``item'' refers to what remains after any surrounding double quotes have been | |
18235 | removed. | |
168e428f | 18236 | |
068aaea8 | 18237 | cindex:[$local_part$] |
168e428f PH |
18238 | *Warning*: If you use an Exim expansion to construct a redirection address, |
18239 | and the expansion contains a reference to $local_part$, you should make use | |
068aaea8 PH |
18240 | of the %quote_local_part% expansion operator, in case the local part contains |
18241 | special characters. For example, to redirect all mail for the domain | |
168e428f PH |
18242 | 'obsolete.example', retaining the existing local part, you could use this |
18243 | setting: | |
18244 | ||
068aaea8 | 18245 | data = ${quote_local_part:$local_part}@newdomain.example |
168e428f PH |
18246 | |
18247 | ||
18248 | ||
18249 | ||
18250 | [[SECTredlocmai]] | |
18251 | Redirecting to a local mailbox | |
18252 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
18253 | cindex:[routing,loops in] | |
18254 | cindex:[loop while routing, avoidance of] | |
18255 | cindex:[address redirection,to local mailbox] | |
18256 | A redirection item may safely be the same as the address currently under | |
18257 | consideration. This does not cause a routing loop, because a router is | |
18258 | automatically skipped if any ancestor of the address that is being processed | |
18259 | is the same as the current address and was processed by the current router. | |
18260 | Such an address is therefore passed to the following routers, so it is handled | |
18261 | as if there were no redirection. When making this loop-avoidance test, the | |
18262 | complete local part, including any prefix or suffix, is used. | |
18263 | ||
18264 | cindex:[address redirection,local part without domain] | |
18265 | Specifying the same local part without a domain is a common usage in personal | |
18266 | filter files when the user wants to have messages delivered to the local | |
18267 | mailbox and also forwarded elsewhere. For example, the user whose login is | |
18268 | 'cleo' might have a _.forward_ file containing this: | |
18269 | ||
18270 | cleo, cleopatra@egypt.example | |
18271 | ||
18272 | cindex:[backslash in alias file] | |
18273 | cindex:[alias file,backslash in] | |
18274 | For compatibility with other MTAs, such unqualified local parts may be | |
18275 | preceeded by ``\'', but this is not a requirement for loop prevention. However, | |
18276 | it does make a difference if more than one domain is being handled | |
18277 | synonymously. | |
18278 | ||
18279 | If an item begins with ``\'' and the rest of the item parses as a valid RFC 2822 | |
18280 | address that does not include a domain, the item is qualified using the domain | |
18281 | of the incoming address. In the absence of a leading ``\'', unqualified | |
18282 | addresses are qualified using the value in %qualify_recipient%, but you can | |
18283 | force the incoming domain to be used by setting %qualify_preserve_domain%. | |
18284 | ||
18285 | Care must be taken if there are alias names for local users. | |
18286 | Consider an MTA handling a single local domain where the system alias file | |
18287 | contains: | |
18288 | ||
18289 | Sam.Reman: spqr | |
18290 | ||
18291 | Now suppose that Sam (whose login id is 'spqr') wants to save copies of | |
18292 | messages in the local mailbox, and also forward copies elsewhere. He creates | |
18293 | this forward file: | |
18294 | ||
18295 | Sam.Reman, spqr@reme.elsewhere.example | |
18296 | ||
18297 | With these settings, an incoming message addressed to 'Sam.Reman' fails. The | |
18298 | ^redirect^ router for system aliases does not process 'Sam.Reman' the | |
18299 | second time round, because it has previously routed it, | |
18300 | and the following routers presumably cannot handle the alias. The forward file | |
18301 | should really contain | |
18302 | ||
18303 | spqr, spqr@reme.elsewhere.example | |
18304 | ||
18305 | but because this is such a common error, the %check_ancestor% option (see | |
18306 | below) exists to provide a way to get round it. This is normally set on a | |
18307 | ^redirect^ router that is handling users' _.forward_ files. | |
18308 | ||
18309 | ||
18310 | ||
18311 | [[SECTspecitredli]] | |
18312 | Special items in redirection lists | |
18313 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
18314 | In addition to addresses, the following types of item may appear in redirection | |
18315 | lists (that is, in non-filter redirection data): | |
18316 | ||
18317 | - cindex:[pipe,in redirection list] | |
18318 | cindex:[address redirection,to pipe] | |
18319 | An item is treated as a pipe command if it begins with ``|'' and does not parse | |
18320 | as a valid RFC 2822 address that includes a domain. A transport for running the | |
18321 | command must be specified by the %pipe_transport% option. | |
18322 | Normally, either the router or the transport specifies a user and a group under | |
18323 | which to run the delivery. The default is to use the Exim user and group. | |
18324 | + | |
18325 | Single or double quotes can be used for enclosing the individual arguments of | |
18326 | the pipe command; no interpretation of escapes is done for single quotes. If | |
18327 | the command contains a comma character, it is necessary to put the whole item | |
18328 | in double quotes, for example: | |
18329 | ||
18330 | "|/some/command ready,steady,go" | |
18331 | + | |
18332 | since items in redirection lists are terminated by commas. Do not, however, | |
18333 | quote just the command. An item such as | |
18334 | ||
18335 | |"/some/command ready,steady,go" | |
18336 | + | |
18337 | is interpreted as a pipe with a rather strange command name, and no arguments. | |
18338 | ||
18339 | - cindex:[file,in redirection list] | |
18340 | cindex:[address redirection,to file] | |
18341 | An item is interpreted as a path name if it begins with ``/'' and does not parse | |
18342 | as a valid RFC 2822 address that includes a domain. For example, | |
18343 | ||
18344 | /home/world/minbari | |
18345 | + | |
18346 | is treated as a file name, but | |
18347 | ||
18348 | /s=molari/o=babylon/@x400gate.way | |
18349 | + | |
18350 | is treated as an address. For a file name, a transport must be specified using | |
18351 | the %file_transport% option. However, if the generated path name ends with a | |
18352 | forward slash character, it is interpreted as a directory name rather than a | |
18353 | file name, and %directory_transport% is used instead. | |
18354 | + | |
18355 | Normally, either the router or the transport specifies a user and a group under | |
18356 | which to run the delivery. The default is to use the Exim user and group. | |
18357 | + | |
18358 | cindex:[_/dev/null_] | |
18359 | However, if a redirection item is the path _/dev/null_, delivery to it is | |
18360 | bypassed at a high level, and the log entry shows ``\*\*bypassed\*\*'' | |
18361 | instead of a transport name. In this case the user and group are not used. | |
18362 | ||
18363 | - cindex:[included address list] | |
18364 | cindex:[address redirection,included external list] | |
18365 | If an item is of the form | |
18366 | ||
18367 | :include:<path name> | |
18368 | + | |
18369 | a list of further items is taken from the given file and included at that | |
18370 | point. *Note*: such a file can not be a filter file; it is just an out-of-line | |
18371 | addition to the list. The items in the included list are separated by commas or | |
18372 | newlines and are not subject to expansion. If this is the first item in an | |
18373 | alias list in an ^lsearch^ file, a colon must be used to terminate the alias | |
18374 | name. This example is incorrect: | |
18375 | ||
18376 | list1 :include:/opt/lists/list1 | |
18377 | + | |
18378 | It must be given as | |
18379 | ||
18380 | list1: :include:/opt/lists/list1 | |
18381 | + | |
18382 | - cindex:[address redirection,to black hole] | |
18383 | Sometimes you want to throw away mail to a particular local part. Making the | |
18384 | %data% option expand to an empty string does not work, because that causes the | |
18385 | router to decline. Instead, the alias item | |
18386 | cindex:[black hole] | |
18387 | cindex:[abandoning mail] | |
18388 | ||
18389 | :blackhole: | |
18390 | + | |
18391 | can be used. It does what its name implies. No delivery is done, and no error | |
18392 | message is generated. This has the same effect as specifing _/dev/null_, but | |
18393 | can be independently disabled. | |
18394 | + | |
18395 | *Warning*: If `:blackhole:` appears anywhere in a redirection list, no | |
18396 | delivery is done for the original local part, even if other redirection items | |
18397 | are present. If you are generating a multi-item list (for example, by reading a | |
18398 | database) and need the ability to provide a no-op item, you must use | |
18399 | _/dev/null_. | |
18400 | ||
18401 | - cindex:[delivery,forcing failure] | |
18402 | cindex:[delivery,forcing deferral] | |
18403 | cindex:[failing delivery,forcing] | |
18404 | cindex:[deferred delivery, forcing] | |
18405 | cindex:[customizing,failure message] | |
18406 | An attempt to deliver a particular address can be deferred or forced to fail by | |
18407 | redirection items of the form | |
18408 | ||
18409 | :defer: | |
18410 | :fail: | |
18411 | + | |
18412 | respectively. When a redirection list contains such an item, it applies to the | |
18413 | entire redirection; any other items in the list are ignored (':blackhole:' is | |
18414 | different). Any text following ':fail:' or ':defer:' is placed in the error | |
18415 | text associated with the failure. For example, an alias file might contain: | |
18416 | ||
18417 | X.Employee: :fail: Gone away, no forwarding address | |
18418 | + | |
18419 | In the case of an address that is being verified from an ACL or as the subject | |
18420 | of a | |
18421 | cindex:[VRFY error text, display of] | |
18422 | VRFY command, the text is included in the SMTP error response by | |
18423 | default. | |
18424 | cindex:[EXPN error text, display of] | |
18425 | The text is not included in the response to an EXPN command. | |
18426 | + | |
068aaea8 | 18427 | cindex:[$acl_verify_message$] |
168e428f PH |
18428 | In an ACL, an explicitly provided message overrides the default, but the |
18429 | default message is available in the variable $acl_verify_message$ and can | |
18430 | therefore be included in a custom message if this is desired. Exim sends a 451 | |
18431 | SMTP code for a ':defer:', and 550 for ':fail:'. In non-SMTP cases the text | |
18432 | is included in the error message that Exim generates. | |
18433 | + | |
18434 | Normally the error text is the rest of the redirection list -- a comma does not | |
18435 | terminate it -- but a newline does act as a terminator. Newlines are not | |
18436 | normally present in alias expansions. In ^lsearch^ lookups they are removed as | |
18437 | part of the continuation process, but they may exist in other kinds of lookup | |
18438 | and in ':include:' files. | |
18439 | + | |
18440 | During routing for message delivery (as opposed to verification), a redirection | |
18441 | containing ':fail:' causes an immediate failure of the incoming address, | |
18442 | whereas ':defer:' causes the message to remain on the queue so that a | |
18443 | subsequent delivery attempt can happen at a later time. If an address is | |
18444 | deferred for too long, it will ultimately fail, because the normal retry | |
18445 | rules still apply. | |
18446 | ||
18447 | - cindex:[alias file,exception to default] | |
18448 | Sometimes it is useful to use a single-key search type with a default (see | |
18449 | chapter <<CHAPfdlookup>>) to look up aliases. However, there may be a need for | |
18450 | exceptions to the default. These can be handled by aliasing them to | |
18451 | ||
18452 | :unknown: | |
18453 | + | |
18454 | This differs from ':fail:' in that it causes the ^redirect^ router to decline, | |
18455 | whereas ':fail:' forces routing to fail. A lookup which results in an empty | |
18456 | redirection list has the same effect. | |
18457 | ||
18458 | ||
18459 | ||
18460 | Duplicate addresses | |
18461 | ~~~~~~~~~~~~~~~~~~~ | |
18462 | cindex:[duplicate addresses] | |
18463 | cindex:[address duplicate, discarding] | |
18464 | cindex:[pipe,duplicated] | |
18465 | Exim removes duplicate addresses from the list to which it is delivering, so as | |
18466 | to deliver just one copy to each address. This does not apply to deliveries | |
18467 | routed to pipes by different immediate parent addresses, but an indirect | |
18468 | aliasing scheme of the type | |
18469 | ||
18470 | pipe: |/some/command $local_part | |
18471 | localpart1: pipe | |
18472 | localpart2: pipe | |
18473 | ||
18474 | does not work with a message that is addressed to both local parts, because | |
18475 | when the second is aliased to the intermediate local part ``pipe'' it gets | |
18476 | discarded as being the same as a previously handled address. However, a scheme | |
18477 | such as | |
18478 | ||
18479 | localpart1: |/some/command $local_part | |
18480 | localpart2: |/some/command $local_part | |
18481 | ||
18482 | does result in two different pipe deliveries, because the immediate parents of | |
18483 | the pipes are distinct. | |
18484 | ||
18485 | ||
18486 | ||
18487 | Repeated redirection expansion | |
18488 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
18489 | cindex:[repeated redirection expansion] | |
18490 | cindex:[address redirection,repeated for each delivery attempt] | |
18491 | When a message cannot be delivered to all of its recipients immediately, | |
18492 | leading to two or more delivery attempts, redirection expansion is carried out | |
18493 | afresh each time for those addresses whose children were not all previously | |
18494 | delivered. If redirection is being used as a mailing list, this can lead to new | |
18495 | members of the list receiving copies of old messages. The %one_time% option | |
18496 | can be used to avoid this. | |
18497 | ||
18498 | ||
18499 | Errors in redirection lists | |
18500 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
18501 | cindex:[address redirection,errors] | |
18502 | If %skip_syntax_errors% is set, a malformed address that causes a parsing | |
18503 | error is skipped, and an entry is written to the main log. This may be useful | |
18504 | for mailing lists that are automatically managed. Otherwise, if an error is | |
18505 | detected while generating the list of new addresses, the original address is | |
18506 | deferred. See also %syntax_errors_to%. | |
18507 | ||
18508 | ||
18509 | ||
18510 | Private options for the redirect router | |
18511 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
18512 | ||
18513 | cindex:[options,^redirect^ router] | |
18514 | The private options for the ^redirect^ router are as follows: | |
18515 | ||
18516 | ||
18517 | oindex:[%allow_defer%] | |
18518 | `..'= | |
18519 | %allow_defer%, Use: 'redirect', Type: 'boolean', Default: 'false' | |
18520 | === | |
18521 | ||
18522 | Setting this option allows the use of ':defer:' in non-filter redirection | |
18523 | data, | |
18524 | or the %defer% command in an Exim filter file. | |
18525 | ||
18526 | ||
18527 | oindex:[%allow_fail%] | |
18528 | `..'= | |
18529 | %allow_fail%, Use: 'redirect', Type: 'boolean', Default: 'false' | |
18530 | === | |
18531 | ||
18532 | cindex:[failing delivery,from filter] | |
18533 | If this option is true, the ':fail:' item can be used in a redirection list, | |
18534 | and the %fail% command may be used in a filter file. | |
18535 | ||
18536 | ||
18537 | oindex:[%allow_filter%] | |
18538 | `..'= | |
18539 | %allow_filter%, Use: 'redirect', Type: 'boolean', Default: 'false' | |
18540 | === | |
18541 | ||
18542 | cindex:[filter,enabling use of] | |
18543 | cindex:[Sieve filter,enabling use of] | |
18544 | Setting this option allows Exim to interpret redirection data that starts with | |
18545 | ``#Exim filter'' or ``#Sieve filter'' as a set of filtering instructions. There | |
18546 | are some features of Exim filter files that some administrators may wish to | |
18547 | lock out; see the %forbid_filter_xxx% options below. | |
18548 | ||
18549 | It is also possible to lock out Exim filters or Sieve filters while allowing | |
18550 | the other type; see %forbid_exim_filter% and %forbid_sieve_filter%. | |
18551 | ||
18552 | ||
18553 | The filter is run using the uid and gid set by the generic %user% and %group% | |
18554 | options. These take their defaults from the password data if | |
18555 | %check_local_user% is set, so in the normal case of users' personal filter | |
18556 | files, the filter is run as the relevant user. When %allow_filter% is set | |
18557 | true, Exim insists that either %check_local_user% or %user% is set. | |
18558 | ||
18559 | ||
18560 | ||
18561 | oindex:[%allow_freeze%] | |
18562 | `..'= | |
18563 | %allow_freeze%, Use: 'redirect', Type: 'boolean', Default: 'false' | |
18564 | === | |
18565 | ||
18566 | cindex:[freezing messages,allowing in filter] | |
18567 | Setting this option allows the use of the %freeze% command in an Exim filter. | |
18568 | This command is more normally encountered in system filters, and is disabled by | |
18569 | default for redirection filters because it isn't something you usually want to | |
18570 | let ordinary users do. | |
18571 | ||
18572 | ||
18573 | ||
18574 | oindex:[%check_ancestor%] | |
18575 | `..'= | |
18576 | %check_ancestor%, Use: 'redirect', Type: 'boolean', Default: 'false' | |
18577 | === | |
18578 | ||
18579 | This option is concerned with handling generated addresses that are the same | |
18580 | as some address in the list of redirection ancestors of the current address. | |
18581 | Although it is turned off by default in the code, it is set in the default | |
18582 | configuration file for handling users' _.forward_ files. It is recommended | |
18583 | for this use of the ^redirect^ router. | |
18584 | ||
18585 | When %check_ancestor% is set, if a generated address (including the domain) is | |
18586 | the same as any ancestor of the current address, it is replaced by a copy of | |
18587 | the current address. This helps in the case where local part A is aliased to B, | |
18588 | and B has a _.forward_ file pointing back to A. For example, within a single | |
18589 | domain, the local part ``Joe.Bloggs'' is aliased to ``jb'' and _~jb/.forward_ | |
18590 | contains: | |
18591 | ||
18592 | \Joe.Bloggs, <other item(s)> | |
18593 | ||
18594 | Without the %check_ancestor% setting, either local part (``jb'' or ``joe.bloggs'') | |
18595 | gets processed once by each router and so ends up as it was originally. If ``jb'' | |
18596 | is the real mailbox name, mail to ``jb'' gets delivered (having been turned into | |
18597 | ``joe.bloggs'' by the _.forward_ file and back to ``jb'' by the alias), but mail | |
18598 | to ``joe.bloggs'' fails. Setting %check_ancestor% on the ^redirect^ router that | |
18599 | handles the _.forward_ file prevents it from turning ``jb'' back into | |
18600 | ``joe.bloggs'' when that was the original address. See also the %repeat_use% | |
18601 | option below. | |
18602 | ||
18603 | ||
18604 | oindex:[%check_group%] | |
18605 | `..'= | |
18606 | %check_group%, Use: 'redirect', Type: 'boolean', Default: 'see below' | |
18607 | === | |
18608 | ||
18609 | When the %file% option is used, the group owner of the file is checked only | |
18610 | when this option is set. The permitted groups are those listed in the | |
18611 | %owngroups% option, together with the user's default group if | |
18612 | %check_local_user% is set. If the file has the wrong group, routing is | |
18613 | deferred. The default setting for this option is true if %check_local_user% | |
18614 | is set and the %modemask% option permits the group write bit, or if the | |
18615 | %owngroups% option is set. Otherwise it is false, and no group check occurs. | |
18616 | ||
18617 | ||
18618 | ||
18619 | oindex:[%check_owner%] | |
18620 | `..'= | |
18621 | %check_owner%, Use: 'redirect', Type: 'boolean', Default: 'see below' | |
18622 | === | |
18623 | ||
18624 | When the %file% option is used, the owner of the file is checked only when this | |
18625 | option is set. If %check_local_user% is set, the local user is permitted; | |
18626 | otherwise the owner must be one of those listed in the %owners% option. The | |
18627 | default value for this option is true if %check_local_user% or %owners% is | |
18628 | set. Otherwise the default is false, and no owner check occurs. | |
18629 | ||
18630 | ||
18631 | oindex:[%data%] | |
18632 | `..'= | |
18633 | %data%, Use: 'redirect', Type: 'string'!!, Default: 'unset' | |
18634 | === | |
18635 | ||
18636 | This option is mutually exclusive with %file%. One or other of them must be | |
18637 | set, but not both. The contents of %data% are expanded, and then used as the | |
18638 | list of forwarding items, or as a set of filtering instructions. If the | |
18639 | expansion is forced to fail, or the result is an empty string or a string that | |
18640 | has no effect (consists entirely of comments), the router declines. | |
18641 | ||
18642 | When filtering instructions are used, the string must begin with ``#Exim | |
18643 | filter'', and all comments in the string, including this initial one, must be | |
18644 | terminated with newline characters. For example: | |
18645 | ||
18646 | .... | |
18647 | data = #Exim filter\n\ | |
18648 | if $h_to: contains Exim then save $home/mail/exim endif | |
18649 | .... | |
18650 | ||
18651 | If you are reading the data from a database where newlines cannot be included, | |
18652 | you can use the $\{sg\}$ expansion item to turn the escape string of your | |
18653 | choice into a newline. | |
18654 | ||
18655 | ||
18656 | oindex:[%directory_transport%] | |
18657 | `..'= | |
18658 | %directory_transport%, Use: 'redirect', Type: 'string'!!, Default: 'unset' | |
18659 | === | |
18660 | ||
18661 | A ^redirect^ router sets up a direct delivery to a directory when a path name | |
18662 | ending with a slash is specified as a new ``address''. The transport used is | |
18663 | specified by this option, which, after expansion, must be the name of a | |
18664 | configured transport. This should normally be an ^appendfile^ transport. | |
18665 | ||
18666 | ||
18667 | oindex:[%file%] | |
18668 | `..'= | |
18669 | %file%, Use: 'redirect', Type: 'string'!!, Default: 'unset' | |
18670 | === | |
18671 | ||
18672 | This option specifies the name of a file that contains the redirection data. It | |
18673 | is mutually exclusive with the %data% option. The string is expanded before | |
18674 | use; if the expansion is forced to fail, the router declines. Other expansion | |
18675 | failures cause delivery to be deferred. The result of a successful expansion | |
18676 | must be an absolute path. The entire file is read and used as the redirection | |
18677 | data. If the data is an empty string or a string that has no effect (consists | |
18678 | entirely of comments), the router declines. | |
18679 | ||
18680 | cindex:[NFS,checking for file existence] | |
18681 | If the attempt to open the file fails with a ``does not exist'' error, Exim | |
18682 | runs a check on the containing directory, | |
18683 | unless %ignore_enotdir% is true (see below). | |
18684 | If the directory does not appear to exist, delivery is deferred. This can | |
18685 | happen when users' _.forward_ files are in NFS-mounted directories, and there | |
18686 | is a mount problem. If the containing directory does exist, but the file does | |
18687 | not, the router declines. | |
18688 | ||
18689 | ||
18690 | oindex:[%file_transport%] | |
18691 | `..'= | |
18692 | %file_transport%, Use: 'redirect', Type: 'string'!!, Default: 'unset' | |
18693 | === | |
18694 | ||
068aaea8 | 18695 | cindex:[$address_file$] |
168e428f PH |
18696 | A ^redirect^ router sets up a direct delivery to a file when a path name not |
18697 | ending in a slash is specified as a new ``address''. The transport used is | |
18698 | specified by this option, which, after expansion, must be the name of a | |
068aaea8 PH |
18699 | configured transport. This should normally be an ^appendfile^ transport. When |
18700 | it is running, the file name is in $address_file$. | |
168e428f PH |
18701 | |
18702 | ||
18703 | oindex:[%forbid_blackhole%] | |
18704 | `..'= | |
18705 | %forbid_blackhole%, Use: 'redirect', Type: 'boolean', Default: 'false' | |
18706 | === | |
18707 | ||
18708 | If this option is true, the ':blackhole:' item may not appear in a redirection | |
18709 | list. | |
18710 | ||
18711 | ||
18712 | oindex:[%forbid_exim_filter%] | |
18713 | `..'= | |
18714 | %forbid_exim_filter%, Use: 'redirect', Type: 'boolean', Default: 'false' | |
18715 | === | |
18716 | ||
18717 | If this option is set true, only Sieve filters are permitted when | |
18718 | %allow_filter% is true. | |
18719 | ||
18720 | ||
18721 | ||
18722 | ||
18723 | oindex:[%forbid_file%] | |
18724 | `..'= | |
18725 | %forbid_file%, Use: 'redirect', Type: 'boolean', Default: 'false' | |
18726 | === | |
18727 | ||
18728 | cindex:[delivery,to file; forbidding] | |
18729 | cindex:[Sieve filter,forbidding delivery to a file] | |
18730 | cindex:[Sieve filter,``keep'' facility; disabling] | |
18731 | If this option is true, this router may not generate a new address that | |
18732 | specifies delivery to a local file or directory, either from a filter or from a | |
18733 | conventional forward file. This option is forced to be true if %one_time% is | |
18734 | set. It applies to Sieve filters as well as to Exim filters, but if true, it | |
18735 | locks out the Sieve's ``keep'' facility. | |
18736 | ||
18737 | ||
068aaea8 PH |
18738 | oindex:[%forbid_filter_dlfunc%] |
18739 | `..'= | |
18740 | %forbid_filter_dlfunc%, Use: 'redirect', Type: 'boolean', Default: 'false' | |
18741 | === | |
18742 | ||
18743 | [revisionflag="changed"] | |
18744 | cindex:[filter,locking out certain features] | |
18745 | If this option is true, string expansions in Exim filters are not allowed to | |
18746 | make use of the %dlfunc% expansion facility to run dynamically loaded | |
18747 | functions. | |
18748 | ||
18749 | ||
168e428f PH |
18750 | oindex:[%forbid_filter_existstest%] |
18751 | `..'= | |
18752 | %forbid_filter_existstest%, Use: 'redirect', Type: 'boolean', Default: 'false' | |
18753 | === | |
18754 | ||
068aaea8 PH |
18755 | [revisionflag="changed"] |
18756 | cindex:[expansion,statting a file] | |
168e428f | 18757 | If this option is true, string expansions in Exim filters are not allowed to |
068aaea8 | 18758 | make use of the %exists% condition or the %stat% expansion item. |
168e428f PH |
18759 | |
18760 | ||
18761 | oindex:[%forbid_filter_logwrite%] | |
18762 | `..'= | |
18763 | %forbid_filter_logwrite%, Use: 'redirect', Type: 'boolean', Default: 'false' | |
18764 | === | |
18765 | ||
18766 | If this option is true, use of the logging facility in Exim filters is not | |
18767 | permitted. Logging is in any case available only if the filter is being run | |
18768 | under some unprivileged uid (which is normally the case for ordinary users' | |
18769 | _.forward_ files). | |
18770 | ||
18771 | ||
18772 | oindex:[%forbid_filter_lookup%] | |
18773 | `..'= | |
18774 | %forbid_filter_lookup%, Use: 'redirect', Type: 'boolean', Default: 'false' | |
18775 | === | |
18776 | ||
18777 | If this option is true, string expansions in Exim filter files are not allowed | |
18778 | to make use of %lookup% items. | |
18779 | ||
18780 | ||
18781 | oindex:[%forbid_filter_perl%] | |
18782 | `..'= | |
18783 | %forbid_filter_perl%, Use: 'redirect', Type: 'boolean', Default: 'false' | |
18784 | === | |
18785 | ||
068aaea8 | 18786 | This option has an effect only if Exim is built with embedded Perl support. If |
168e428f PH |
18787 | it is true, string expansions in Exim filter files are not allowed to make use |
18788 | of the embedded Perl support. | |
18789 | ||
18790 | ||
18791 | oindex:[%forbid_filter_readfile%] | |
18792 | `..'= | |
18793 | %forbid_filter_readfile%, Use: 'redirect', Type: 'boolean', Default: 'false' | |
18794 | === | |
18795 | ||
18796 | If this option is true, string expansions in Exim filter files are not allowed | |
18797 | to make use of %readfile% items. | |
18798 | ||
18799 | ||
18800 | oindex:[%forbid_filter_readsocket%] | |
18801 | `..'= | |
18802 | %forbid_filter_readsocket%, Use: 'redirect', Type: 'boolean', Default: 'false' | |
18803 | === | |
18804 | ||
18805 | If this option is true, string expansions in Exim filter files are not allowed | |
18806 | to make use of %readsocket% items. | |
18807 | ||
18808 | ||
18809 | oindex:[%forbid_filter_reply%] | |
18810 | `..'= | |
18811 | %forbid_filter_reply%, Use: 'redirect', Type: 'boolean', Default: 'false' | |
18812 | === | |
18813 | ||
18814 | If this option is true, this router may not generate an automatic reply | |
18815 | message. Automatic replies can be generated only from Exim | |
18816 | ||
18817 | or Sieve filter files, not from traditional forward files. | |
18818 | ||
18819 | This option is forced to be true if %one_time% is set. | |
18820 | ||
18821 | ||
18822 | oindex:[%forbid_filter_run%] | |
18823 | `..'= | |
18824 | %forbid_filter_run%, Use: 'redirect', Type: 'boolean', Default: 'false' | |
18825 | === | |
18826 | ||
18827 | If this option is true, string expansions in Exim filter files are not allowed | |
18828 | to make use of %run% items. | |
18829 | ||
18830 | ||
18831 | oindex:[%forbid_include%] | |
18832 | `..'= | |
18833 | %forbid_include%, Use: 'redirect', Type: 'boolean', Default: 'false' | |
18834 | === | |
18835 | ||
18836 | If this option is true, items of the form | |
18837 | ||
18838 | :include:<path name> | |
18839 | ||
18840 | are not permitted in non-filter redirection lists. | |
18841 | ||
18842 | ||
18843 | oindex:[%forbid_pipe%] | |
18844 | `..'= | |
18845 | %forbid_pipe%, Use: 'redirect', Type: 'boolean', Default: 'false' | |
18846 | === | |
18847 | ||
18848 | cindex:[delivery,to pipe; forbidding] | |
18849 | If this option is true, this router may not generate a new address which | |
18850 | specifies delivery to a pipe, either from an Exim filter or from a conventional | |
18851 | forward file. This option is forced to be true if %one_time% is set. | |
18852 | ||
18853 | ||
18854 | oindex:[%forbid_sieve_filter%] | |
18855 | `..'= | |
18856 | %forbid_sieve_filter%, Use: 'redirect', Type: 'boolean', Default: 'false' | |
18857 | === | |
18858 | ||
18859 | If this option is set true, only Exim filters are permitted when | |
18860 | %allow_filter% is true. | |
18861 | ||
18862 | ||
18863 | ||
18864 | ||
18865 | oindex:[%hide_child_in_errmsg%] | |
18866 | `..'= | |
18867 | %hide_child_in_errmsg%, Use: 'redirect', Type: 'boolean', Default: 'false' | |
18868 | === | |
18869 | ||
18870 | cindex:[bounce message,redirection details; suppressing] | |
18871 | If this option is true, it prevents Exim from quoting a child address if it | |
18872 | generates a bounce or delay message for it. Instead it says ``an address | |
18873 | generated from <''the top level address'>'. Of course, this applies only to | |
18874 | bounces generated locally. If a message is forwarded to another host, 'its' | |
18875 | bounce may well quote the generated address. | |
18876 | ||
18877 | ||
18878 | oindex:[%ignore_eacces%] | |
18879 | `..'= | |
18880 | %ignore_eacces%, Use: 'redirect', Type: 'boolean', Default: 'false' | |
18881 | === | |
18882 | ||
18883 | cindex:[EACCES] | |
18884 | If this option is set and an attempt to open a redirection file yields the | |
18885 | EACCES error (permission denied), the ^redirect^ router behaves as if the | |
18886 | file did not exist. | |
18887 | ||
18888 | ||
18889 | oindex:[%ignore_enotdir%] | |
18890 | `..'= | |
18891 | %ignore_enotdir%, Use: 'redirect', Type: 'boolean', Default: 'false' | |
18892 | === | |
18893 | ||
18894 | cindex:[ENOTDIR] | |
18895 | If this option is set and an attempt to open a redirection file yields the | |
18896 | ENOTDIR error (something on the path is not a directory), the ^redirect^ | |
18897 | router behaves as if the file did not exist. | |
18898 | ||
18899 | Setting %ignore_enotdir% has another effect as well: When a ^redirect^ | |
18900 | router that has the %file% option set discovers that the file does not exist | |
18901 | (the ENOENT error), it tries to 'stat()' the parent directory, as a check | |
18902 | against unmounted NFS directories. If the parent can not be statted, delivery | |
18903 | is deferred. However, it seems wrong to do this check when %ignore_enotdir% is | |
18904 | set, because that option tells Exim to ignore ``something on the path is not a | |
18905 | directory'' (the ENOTDIR error). This is a confusing area, because it seems | |
18906 | that some operating systems give ENOENT where others give ENOTDIR. | |
18907 | ||
18908 | ||
18909 | ||
18910 | oindex:[%include_directory%] | |
18911 | `..'= | |
18912 | %include_directory%, Use: 'redirect', Type: 'string', Default: 'unset' | |
18913 | === | |
18914 | ||
18915 | If this option is set, the path names of any ':include:' items in a redirection | |
18916 | list must start with this directory. | |
18917 | ||
18918 | ||
18919 | oindex:[%modemask%] | |
18920 | `..'= | |
18921 | %modemask%, Use: 'redirect', Type: 'octal integer', Default: '022' | |
18922 | === | |
18923 | ||
18924 | This specifies mode bits which must not be set for a file specified by the | |
18925 | %file% option. If any of the forbidden bits are set, delivery is deferred. | |
18926 | ||
18927 | ||
18928 | oindex:[%one_time%] | |
18929 | `..'= | |
18930 | %one_time%, Use: 'redirect', Type: 'boolean', Default: 'false' | |
18931 | === | |
18932 | ||
18933 | cindex:[one-time aliasing/forwarding expansion] | |
18934 | cindex:[alias file,one-time expansion] | |
18935 | cindex:[forward file,one-time expansion] | |
18936 | cindex:[mailing lists,one-time expansion] | |
18937 | cindex:[address redirection,one-time expansion] | |
18938 | Sometimes the fact that Exim re-evaluates aliases and reprocesses redirection | |
068aaea8 PH |
18939 | files each time it tries to deliver a message causes a problem when one or more |
18940 | of the generated addresses fails be delivered at the first attempt. The problem | |
18941 | is not one of duplicate delivery -- Exim is clever enough to handle that -- but | |
18942 | of what happens when the redirection list changes during the time that the | |
18943 | message is on Exim's queue. This is particularly true in the case of mailing | |
18944 | lists, where new subscribers might receive copies of messages that were posted | |
18945 | before they subscribed. | |
18946 | ||
18947 | If %one_time% is set and any addresses generated by the router fail to deliver | |
18948 | at the first attempt, the failing addresses are added to the message as ``top | |
18949 | level'' addresses, and the parent address that generated them is marked | |
18950 | ``delivered''. Thus, redirection does not happen again at the next delivery | |
18951 | attempt. | |
168e428f | 18952 | |
068aaea8 PH |
18953 | *Warning 1*: Any header line addition or removal that is specified by this |
18954 | router would be lost if delivery did not succeed at the first attempt. For this | |
18955 | reason, the %headers_add% and %headers_remove% generic options are not | |
18956 | permitted when %one_time% is set. | |
168e428f PH |
18957 | |
18958 | *Warning 2*: To ensure that the router generates only addresses (as opposed | |
18959 | to pipe or file deliveries or auto-replies) %forbid_file%, %forbid_pipe%, | |
18960 | and %forbid_filter_reply% are forced to be true when %one_time% is set. | |
18961 | ||
068aaea8 PH |
18962 | [revisionflag="changed"] |
18963 | *Warning 3*: The %unseen% generic router option may not be set with %one_time%. | |
18964 | ||
168e428f PH |
18965 | The original top-level address is remembered with each of the generated |
18966 | addresses, and is output in any log messages. However, any intermediate parent | |
18967 | addresses are not recorded. This makes a difference to the log only if | |
18968 | %all_parents% log selector is set. It is expected that %one_time% will | |
18969 | typically be used for mailing lists, where there is normally just one level of | |
18970 | expansion. | |
18971 | ||
18972 | ||
18973 | oindex:[%owners%] | |
18974 | `..'= | |
18975 | %owners%, Use: 'redirect', Type: 'string list', Default: 'unset' | |
18976 | === | |
18977 | ||
18978 | cindex:[ownership,alias file] | |
18979 | cindex:[ownership,forward file] | |
18980 | cindex:[alias file,ownership] | |
18981 | cindex:[forward file,ownership] | |
18982 | This specifies a list of permitted owners for the file specified by %file%. | |
18983 | This list is in addition to the local user when %check_local_user% is set. | |
18984 | See %check_owner% above. | |
18985 | ||
18986 | ||
18987 | oindex:[%owngroups%] | |
18988 | `..'= | |
18989 | %owngroups%, Use: 'redirect', Type: 'string list', Default: 'unset' | |
18990 | === | |
18991 | ||
18992 | This specifies a list of permitted groups for the file specified by %file%. The | |
18993 | list is in addition to the local user's primary group when %check_local_user% | |
18994 | is set. See %check_group% above. | |
18995 | ||
18996 | ||
18997 | oindex:[%pipe_transport%] | |
18998 | `..'= | |
18999 | %pipe_transport%, Use: 'redirect', Type: 'string'!!, Default: 'unset' | |
19000 | === | |
19001 | ||
068aaea8 | 19002 | cindex:[$address_pipe$] |
168e428f PH |
19003 | A ^redirect^ router sets up a direct delivery to a pipe when a string starting |
19004 | with a vertical bar character is specified as a new ``address''. The transport | |
19005 | used is specified by this option, which, after expansion, must be the name of a | |
068aaea8 PH |
19006 | configured transport. This should normally be a ^pipe^ transport. When the |
19007 | transport is run, the pipe command is in $address_pipe$. | |
168e428f PH |
19008 | |
19009 | ||
19010 | oindex:[%qualify_domain%] | |
19011 | `..'= | |
19012 | %qualify_domain%, Use: 'redirect', Type: 'string'!!, Default: 'unset' | |
19013 | === | |
19014 | ||
068aaea8 | 19015 | cindex:[$qualify_recipient$] |
168e428f PH |
19016 | If this option is set and an unqualified address (one without a domain) is |
19017 | generated, it is qualified with the domain specified by expanding this string, | |
19018 | instead of the global setting in %qualify_recipient%. If the expansion fails, | |
19019 | the router declines. If you want to revert to the default, you can have the | |
19020 | expansion generate $qualify_recipient$. | |
19021 | ||
19022 | ||
19023 | oindex:[%qualify_preserve_domain%] | |
19024 | `..'= | |
19025 | %qualify_preserve_domain%, Use: 'redirect', Type: 'boolean', Default: 'false' | |
19026 | === | |
19027 | ||
19028 | cindex:[domain,in redirection; preserving] | |
19029 | cindex:[preserving domain in redirection] | |
19030 | cindex:[address redirection,domain; preserving] | |
19031 | If this is set and an unqualified address (one without a domain) is generated, | |
19032 | it is qualified with the domain of the | |
19033 | parent address (the immediately preceding ancestor) instead of the local | |
19034 | %qualify_domain% or global %qualify_recipient% value. | |
19035 | ||
19036 | ||
19037 | oindex:[%repeat_use%] | |
19038 | `..'= | |
19039 | %repeat_use%, Use: 'redirect', Type: 'boolean', Default: 'true' | |
19040 | === | |
19041 | ||
19042 | If this option is set false, the router is skipped for a child address that has | |
19043 | any ancestor that was routed by this router. This test happens before any of | |
19044 | the other preconditions are tested. Exim's default anti-looping rules skip | |
19045 | only when the ancestor is the same as the current address. See also | |
19046 | %check_ancestor% above and the generic %redirect_router% option. | |
19047 | ||
19048 | ||
19049 | oindex:[%reply_transport%] | |
19050 | `..'= | |
19051 | %reply_transport%, Use: 'redirect', Type: 'string'!!, Default: 'unset' | |
19052 | === | |
19053 | ||
19054 | A ^redirect^ router sets up an automatic reply when a %mail% or %vacation% | |
19055 | command is used in a filter file. The transport used is specified by this | |
19056 | option, which, after expansion, must be the name of a configured transport. | |
19057 | This should normally be an ^autoreply^ transport. Other transports are | |
19058 | unlikely to do anything sensible or useful. | |
19059 | ||
19060 | ||
19061 | oindex:[%rewrite%] | |
19062 | `..'= | |
19063 | %rewrite%, Use: 'redirect', Type: 'boolean', Default: 'true' | |
19064 | === | |
19065 | ||
19066 | cindex:[address redirection,disabling rewriting] | |
19067 | If this option is set false, addresses generated by the router are not | |
19068 | subject to address rewriting. Otherwise, they are treated like new addresses | |
19069 | and are rewritten according to the global rewriting rules. | |
19070 | ||
19071 | ||
068aaea8 PH |
19072 | oindex:[%sieve_subaddress%] |
19073 | `..'= | |
19074 | %sieve_subaddress%, Use: 'redirect', Type: 'string'!!, Default: 'unset' | |
19075 | === | |
19076 | ||
19077 | [revisionflag="changed"] | |
19078 | The value of this option is passed to a Sieve filter to specify the | |
19079 | :subaddress part of an address. | |
19080 | ||
19081 | ||
19082 | oindex:[%sieve_useraddress%] | |
19083 | `..'= | |
19084 | %sieve_useraddress%, Use: 'redirect', Type: 'string'!!, Default: 'unset' | |
19085 | === | |
19086 | ||
19087 | [revisionflag="changed"] | |
19088 | The value of this option is passed to a Sieve filter to specify the :user part | |
19089 | of an address. However, if it is unset, the entire original local part | |
19090 | (including any prefix or suffix) is used for :user. | |
19091 | ||
19092 | ||
168e428f PH |
19093 | |
19094 | oindex:[%sieve_vacation_directory%] | |
19095 | `..'= | |
19096 | %sieve_vacation_directory%, Use: 'redirect', Type: 'string'!!, Default: 'unset' | |
19097 | === | |
19098 | ||
068aaea8 | 19099 | [revisionflag="changed"] |
168e428f PH |
19100 | cindex:[Sieve filter,vacation directory] |
19101 | To enable the ``vacation'' extension for Sieve filters, you must set | |
19102 | %sieve_vacation_directory% to the directory where vacation databases are held | |
19103 | (do not put anything else in that directory), and ensure that the | |
068aaea8 PH |
19104 | %reply_transport% option refers to an ^autoreply^ transport. Each user needs |
19105 | their own directory; Exim will create it if necessary. | |
168e428f PH |
19106 | |
19107 | ||
19108 | ||
19109 | ||
19110 | oindex:[%skip_syntax_errors%] | |
19111 | `..'= | |
19112 | %skip_syntax_errors%, Use: 'redirect', Type: 'boolean', Default: 'false' | |
19113 | === | |
19114 | ||
19115 | cindex:[forward file,broken] | |
19116 | cindex:[address redirection,broken files] | |
19117 | cindex:[alias file,broken] | |
19118 | cindex:[broken alias or forward files] | |
19119 | cindex:[ignoring faulty addresses] | |
19120 | cindex:[skipping faulty addresses] | |
19121 | cindex:[error,skipping bad syntax] | |
19122 | If %skip_syntax_errors% is set, syntactically malformed addresses in | |
19123 | non-filter redirection data are skipped, and each failing address is logged. If | |
19124 | %syntax_errors_to% is set, a message is sent to the address it defines, | |
19125 | giving details of the failures. If %syntax_errors_text% is set, its contents | |
19126 | are expanded and placed at the head of the error message generated by | |
19127 | %syntax_errors_to%. Usually it is appropriate to set %syntax_errors_to% to | |
19128 | be the same address as the generic %errors_to% option. The | |
19129 | %skip_syntax_errors% option is often used when handling mailing lists. | |
19130 | ||
19131 | If all the addresses in a redirection list are skipped because of syntax | |
19132 | errors, the router declines to handle the original address, and it is passed to | |
19133 | the following routers. | |
19134 | ||
19135 | If %skip_syntax_errors% is set when an Exim filter is interpreted, any syntax | |
19136 | error in the filter causes filtering to be abandoned without any action being | |
19137 | taken. The incident is logged, and the router declines to handle the address, | |
19138 | so it is passed to the following routers. | |
19139 | ||
19140 | cindex:[Sieve filter,syntax errors in] | |
19141 | Syntax errors in a Sieve filter file cause the ``keep'' action to occur. This | |
19142 | action is specified by RFC 3028. The values of %skip_syntax_errors%, | |
19143 | %syntax_errors_to%, and %syntax_errors_text% are not used. | |
19144 | ||
19145 | %skip_syntax_errors% can be used to specify that errors in users' forward | |
19146 | lists or filter files should not prevent delivery. The %syntax_errors_to% | |
19147 | option, used with an address that does not get redirected, can be used to | |
19148 | notify users of these errors, by means of a router like this: | |
19149 | ||
19150 | .... | |
19151 | userforward: | |
19152 | driver = redirect | |
19153 | allow_filter | |
19154 | check_local_user | |
19155 | file = $home/.forward | |
19156 | file_transport = address_file | |
19157 | pipe_transport = address_pipe | |
19158 | reply_transport = address_reply | |
19159 | no_verify | |
19160 | skip_syntax_errors | |
19161 | syntax_errors_to = real-$local_part\$domain | |
19162 | syntax_errors_text = \ | |
19163 | This is an automatically generated message. An error has\n\ | |
19164 | been found in your .forward file. Details of the error are\n\ | |
19165 | reported below. While this error persists, you will receive\n\ | |
19166 | a copy of this message for every message that is addressed\n\ | |
19167 | to you. If your .forward file is a filter file, or if it is\n\ | |
19168 | a non-filter file containing no valid forwarding addresses,\n\ | |
19169 | a copy of each incoming message will be put in your normal\n\ | |
19170 | mailbox. If a non-filter file contains at least one valid\n\ | |
19171 | forwarding address, forwarding to the valid addresses will\n\ | |
19172 | happen, and those will be the only deliveries that occur. | |
19173 | .... | |
19174 | ||
19175 | You also need a router to ensure that local addresses that are prefixed by | |
19176 | `real-` are recognized, but not forwarded or filtered. For example, you could | |
19177 | put this immediately before the ^userforward^ router: | |
19178 | ||
19179 | real_localuser: | |
19180 | driver = accept | |
19181 | check_local_user | |
19182 | local_part_prefix = real- | |
19183 | transport = local_delivery | |
19184 | ||
19185 | ||
19186 | ||
19187 | oindex:[%syntax_errors_text%] | |
19188 | `..'= | |
19189 | %syntax_errors_text%, Use: 'redirect', Type: 'string'!!, Default: 'unset' | |
19190 | === | |
19191 | ||
19192 | See %skip_syntax_errors% above. | |
19193 | ||
19194 | ||
19195 | oindex:[%syntax_errors_to%] | |
19196 | `..'= | |
19197 | %syntax_errors_to%, Use: 'redirect', Type: 'string', Default: 'unset' | |
19198 | === | |
19199 | ||
19200 | See %skip_syntax_errors% above. | |
19201 | ||
19202 | ||
19203 | ||
19204 | ||
19205 | ||
19206 | ||
19207 | //////////////////////////////////////////////////////////////////////////// | |
19208 | //////////////////////////////////////////////////////////////////////////// | |
19209 | ||
19210 | [[CHAPenvironment]] | |
19211 | [titleabbrev="Environment for local transports"] | |
19212 | Environment for running local transports | |
19213 | ---------------------------------------- | |
19214 | cindex:[local transports,environment for] | |
19215 | cindex:[environment for local transports] | |
19216 | cindex:[transport,local; environment for] | |
19217 | Local transports handle deliveries to files and pipes. (The ^autoreply^ | |
19218 | transport can be thought of as similar to a pipe.) Exim always runs transports | |
19219 | in subprocesses, under specified uids and gids. Typical deliveries to local | |
19220 | mailboxes run under the uid and gid of the local user. | |
19221 | ||
19222 | Exim also sets a specific current directory while running the transport; for | |
19223 | some transports a home directory setting is also relevant. The ^pipe^ | |
19224 | transport is the only one that sets up environment variables; see section | |
19225 | <<SECTpipeenv>> for details. | |
19226 | ||
19227 | The values used for the uid, gid, and the directories may come from several | |
19228 | different places. In many cases, the router that handles the address associates | |
19229 | settings with that address as a result of its %check_local_user%, %group%, or | |
19230 | %user% options. However, values may also be given in the transport's own | |
19231 | configuration, and these override anything that comes from the router. | |
19232 | ||
19233 | ||
19234 | ||
19235 | Concurrent deliveries | |
19236 | ~~~~~~~~~~~~~~~~~~~~~ | |
19237 | cindex:[concurrent deliveries] | |
19238 | cindex:[simultaneous deliveries] | |
19239 | If two different messages for the same local recpient arrive more or less | |
19240 | simultaneously, the two delivery processes are likely to run concurrently. When | |
19241 | the ^appendfile^ transport is used to write to a file, Exim applies locking | |
19242 | rules to stop concurrent processes from writing to the same file at the same | |
19243 | time. | |
19244 | ||
19245 | However, when you use a ^pipe^ transport, it is up to you to arrange any | |
19246 | locking that is needed. Here is a silly example: | |
19247 | ||
19248 | my_transport: | |
19249 | driver = pipe | |
19250 | command = /bin/sh -c 'cat >>/some/file' | |
19251 | ||
19252 | This is supposed to write the message at the end of the file. However, if two | |
19253 | messages arrive at the same time, the file will be scrambled. You can use the | |
19254 | %exim_lock% utility program (see section <<SECTmailboxmaint>>) to lock a file | |
19255 | using the same algorithm that Exim itself uses. | |
19256 | ||
19257 | ||
19258 | ||
19259 | ||
19260 | [[SECTenvuidgid]] | |
19261 | Uids and gids | |
19262 | ~~~~~~~~~~~~~ | |
19263 | cindex:[local transports,uid and gid] | |
19264 | cindex:[transport,local; uid and gid] | |
19265 | All transports have the options %group% and %user%. If %group% is set, it | |
19266 | overrides any group that the router set in the address, even if %user% is not | |
19267 | set for the transport. This makes it possible, for example, to run local mail | |
19268 | delivery under the uid of the recipient (set by the router), but in a special | |
19269 | group (set by the transport). For example: | |
19270 | ||
19271 | # Routers ... | |
19272 | # User/group are set by check_local_user in this router | |
19273 | local_users: | |
19274 | driver = accept | |
19275 | check_local_user | |
19276 | transport = group_delivery | |
19277 | ||
19278 | # Transports ... | |
19279 | # This transport overrides the group | |
19280 | group_delivery: | |
19281 | driver = appendfile | |
19282 | file = /var/spool/mail/$local_part | |
19283 | group = mail | |
19284 | ||
19285 | If %user% is set for a transport, its value overrides what is set in the | |
19286 | address. If %user% is non-numeric and %group% is not set, the gid associated | |
19287 | with the user is used. If %user% is numeric, %group% must be set. | |
19288 | ||
19289 | cindex:[%initgroups% option] | |
19290 | When the uid is taken from the transport's configuration, the 'initgroups()' | |
19291 | function is called for the groups associated with that uid if the %initgroups% | |
19292 | option is set for the transport. When the uid is not specified by the | |
19293 | transport, but is associated with the address by a router, the option for | |
19294 | calling 'initgroups()' is taken from the router configuration. | |
19295 | ||
19296 | cindex:[^pipe^ transport,uid for] | |
19297 | The ^pipe^ transport contains the special option %pipe_as_creator%. If this | |
19298 | is set and %user% is not set, the uid of the process that called Exim to | |
19299 | receive the message is used, and if %group% is not set, the corresponding | |
19300 | original gid is also used. | |
19301 | ||
19302 | ||
19303 | ||
19304 | Current and home directories | |
19305 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
19306 | cindex:[current directory for local transport] | |
19307 | cindex:[home directory,for local transport] | |
19308 | cindex:[transport,local; home directory for] | |
19309 | cindex:[transport,local; current directory for] | |
19310 | Routers may set current and home directories for local transports by means of | |
19311 | the %transport_current_directory% and %transport_home_directory% options. | |
19312 | However, if the transport's %current_directory% or %home_directory% options | |
19313 | are set, they override the router's values. In detail, the home directory | |
19314 | for a local transport is taken from the first of these values that is set: | |
19315 | ||
19316 | - The %home_directory% option on the transport; | |
19317 | ||
19318 | - The %transport_home_directory% option on the router; | |
19319 | ||
19320 | - The password data if %check_local_user% is set on the router; | |
19321 | ||
19322 | - The %router_home_directory% option on the router. | |
19323 | ||
19324 | The current directory is taken from the first of these values that is set: | |
19325 | ||
19326 | - The %current_directory% option on the transport; | |
19327 | ||
19328 | - The %transport_current_directory% option on the router. | |
19329 | ||
19330 | ||
19331 | If neither the router nor the transport sets a current directory, Exim uses the | |
19332 | value of the home directory, if it is set. Otherwise it sets the current | |
19333 | directory to _/_ before running a local transport. | |
19334 | ||
19335 | ||
19336 | ||
19337 | Expansion variables derived from the address | |
19338 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
068aaea8 PH |
19339 | cindex:[$domain$] |
19340 | cindex:[$local_part$] | |
19341 | cindex:[$original_domain$] | |
168e428f | 19342 | Normally a local delivery is handling a single address, and in that case the |
068aaea8 PH |
19343 | variables such as $domain$ and $local_part$ are set during local deliveries. |
19344 | However, in some circumstances more than one address may be handled at once | |
19345 | (for example, while writing batch SMTP for onward transmission by some other | |
19346 | means). In this case, the variables associated with the local part are never | |
19347 | set, $domain$ is set only if all the addresses have the same domain, and | |
19348 | $original_domain$ is never set. | |
168e428f PH |
19349 | |
19350 | ||
19351 | ||
19352 | ||
19353 | ||
19354 | ||
19355 | ||
19356 | //////////////////////////////////////////////////////////////////////////// | |
19357 | //////////////////////////////////////////////////////////////////////////// | |
19358 | ||
19359 | [[CHAPtransportgeneric]] | |
19360 | Generic options for transports | |
19361 | ------------------------------ | |
19362 | ||
19363 | cindex:[generic options,transport] | |
19364 | cindex:[options,generic; for transports] | |
19365 | cindex:[transport,generic options for] | |
19366 | The following generic options apply to all transports: | |
19367 | ||
19368 | ||
19369 | oindex:[%body_only%] | |
19370 | `..'= | |
19371 | %body_only%, Use: 'transports', Type: 'boolean', Default: 'false' | |
19372 | === | |
19373 | ||
19374 | cindex:[transport,body only] | |
19375 | cindex:[message,transporting body only] | |
19376 | cindex:[body of message,transporting] | |
19377 | If this option is set, the message's headers are not transported. It is | |
19378 | mutually exclusive with %headers_only%. If it is used with the ^appendfile^ or | |
19379 | ^pipe^ transports, the settings of %message_prefix% and %message_suffix% | |
19380 | should be checked, because this option does not automatically suppress them. | |
19381 | ||
19382 | ||
19383 | oindex:[%current_directory%] | |
19384 | `..'= | |
19385 | %current_directory%, Use: 'transports', Type: 'string'!!, Default: 'unset' | |
19386 | === | |
19387 | ||
19388 | cindex:[transport,current directory for] | |
19389 | This specifies the current directory that is to be set while running the | |
19390 | transport, overriding any value that may have been set by the router. | |
19391 | If the expansion fails for any reason, including forced failure, an error is | |
19392 | logged, and delivery is deferred. | |
19393 | ||
19394 | ||
19395 | oindex:[%disable_logging%] | |
19396 | `..'= | |
19397 | %disable_logging%, Use: 'transports', Type: 'boolean', Default: 'false' | |
19398 | === | |
19399 | ||
19400 | If this option is set true, nothing is logged for any | |
19401 | deliveries by the transport or for any | |
19402 | transport errors. You should not set this option unless you really, really know | |
19403 | what you are doing. | |
19404 | ||
19405 | ||
19406 | oindex:[%debug_print%] | |
19407 | `..'= | |
19408 | %debug_print%, Use: 'transports', Type: 'string'!!, Default: 'unset' | |
19409 | === | |
19410 | ||
19411 | cindex:[testing,variables in drivers] | |
19412 | If this option is set and debugging is enabled (see the %-d% command line | |
19413 | option), the string is expanded and included in the debugging output when the | |
19414 | transport is run. | |
19415 | If expansion of the string fails, the error message is written to the debugging | |
19416 | output, and Exim carries on processing. | |
19417 | This facility is provided to help with checking out the values of variables and | |
19418 | so on when debugging driver configurations. For example, if a %headers_add% | |
19419 | option is not working properly, %debug_print% could be used to output the | |
19420 | variables it references. A newline is added to the text if it does not end with | |
19421 | one. | |
19422 | ||
19423 | ||
19424 | oindex:[%delivery_date_add%] | |
19425 | `..'= | |
19426 | %delivery_date_add%, Use: 'transports', Type: 'boolean', Default: 'false' | |
19427 | === | |
19428 | ||
19429 | cindex:['Delivery-date:' header line] | |
19430 | If this option is true, a 'Delivery-date:' header is added to the message. This | |
19431 | gives the actual time the delivery was made. As this is not a standard header, | |
19432 | Exim has a configuration option (%delivery_date_remove%) which requests its | |
19433 | removal from incoming messages, so that delivered messages can safely be resent | |
19434 | to other recipients. | |
19435 | ||
19436 | ||
19437 | oindex:[%driver%] | |
19438 | `..'= | |
19439 | %driver%, Use: 'transports', Type: 'string', Default: 'unset' | |
19440 | === | |
19441 | ||
19442 | This specifies which of the available transport drivers is to be used. | |
19443 | There is no default, and this option must be set for every transport. | |
19444 | ||
19445 | ||
19446 | oindex:[%envelope_to_add%] | |
19447 | `..'= | |
19448 | %envelope_to_add%, Use: 'transports', Type: 'boolean', Default: 'false' | |
19449 | === | |
19450 | ||
19451 | cindex:['Envelope-to:' header line] | |
19452 | If this option is true, an 'Envelope-to:' header is added to the message. This | |
19453 | gives the original address(es) in the incoming envelope that caused this | |
19454 | delivery to happen. More than one address may be present if the transport is | |
19455 | configured to handle several addresses at once, or if more than one original | |
19456 | address was redirected to the same final address. As this is not a standard | |
19457 | header, Exim has a configuration option (%envelope_to_remove%) which requests | |
19458 | its removal from incoming messages, so that delivered messages can safely be | |
19459 | resent to other recipients. | |
19460 | ||
19461 | ||
19462 | oindex:[%group%] | |
19463 | `..'= | |
19464 | %group%, Use: 'transports', Type: 'string'!!, Default: 'Exim group' | |
19465 | === | |
19466 | ||
19467 | cindex:[transport,group; specifying] | |
19468 | This option specifies a gid for running the transport process, overriding any | |
19469 | value that the router supplies, and also overriding any value associated with | |
19470 | %user% (see below). | |
19471 | ||
19472 | ||
19473 | oindex:[%headers_add%] | |
19474 | `..'= | |
19475 | %headers_add%, Use: 'transports', Type: 'string'!!, Default: 'unset' | |
19476 | === | |
19477 | ||
19478 | cindex:[header lines,adding in transport] | |
19479 | cindex:[transport,header lines; adding] | |
19480 | This option specifies a string of text that is expanded and added to the header | |
19481 | portion of a message as it is transported, as described in section | |
19482 | <<SECTheadersaddrem>>. Additional header lines can also be specified by routers. | |
19483 | If the result of the expansion is an empty string, or if the expansion is | |
19484 | forced to fail, no action is taken. Other expansion failures are treated as | |
19485 | errors and cause the delivery to be deferred. | |
19486 | ||
19487 | ||
19488 | ||
19489 | oindex:[%headers_only%] | |
19490 | `..'= | |
19491 | %headers_only%, Use: 'transports', Type: 'boolean', Default: 'false' | |
19492 | === | |
19493 | ||
19494 | cindex:[transport,header lines only] | |
19495 | cindex:[message,transporting headers only] | |
19496 | cindex:[header lines,transporting] | |
19497 | If this option is set, the message's body is not transported. It is mutually | |
19498 | exclusive with %body_only%. If it is used with the ^appendfile^ or ^pipe^ | |
19499 | transports, the settings of %message_prefix% and %message_suffix% should be | |
19500 | checked, since this option does not automatically suppress them. | |
19501 | ||
19502 | ||
19503 | oindex:[%headers_remove%] | |
19504 | `..'= | |
19505 | %headers_remove%, Use: 'transports', Type: 'string'!!, Default: 'unset' | |
19506 | === | |
19507 | ||
19508 | cindex:[header lines,removing] | |
19509 | cindex:[transport,header lines; removing] | |
19510 | This option specifies a string that is expanded into a list of header names; | |
19511 | these headers are omitted from the message as it is transported, as described | |
19512 | in section <<SECTheadersaddrem>>. Header removal can also be specified by | |
19513 | routers. If the result of the expansion is an empty string, or if the expansion | |
19514 | is forced to fail, no action is taken. Other expansion failures are treated as | |
19515 | errors and cause the delivery to be deferred. | |
19516 | ||
19517 | ||
19518 | ||
19519 | oindex:[%headers_rewrite%] | |
19520 | `..'= | |
19521 | %headers_rewrite%, Use: 'transports', Type: 'string', Default: 'unset' | |
19522 | === | |
19523 | ||
19524 | cindex:[transport,header lines; rewriting] | |
19525 | cindex:[rewriting,at transport time] | |
19526 | This option allows addresses in header lines to be rewritten at transport time, | |
19527 | that is, as the message is being copied to its destination. The contents of the | |
19528 | option are a colon-separated list of rewriting rules. Each rule is in exactly | |
19529 | the same form as one of the general rewriting rules that are applied when a | |
19530 | message is received. These are described in chapter <<CHAPrewrite>>. For example, | |
19531 | ||
19532 | .... | |
19533 | headers_rewrite = a@b c@d f : \ | |
19534 | x@y w@z | |
19535 | .... | |
19536 | ||
19537 | changes %a@b% into %c@d% in 'From:' header lines, and %x@y% into %w@z% in | |
19538 | all address-bearing header lines. The rules are applied to the header lines | |
19539 | just before they are written out at transport time, so they affect only those | |
19540 | copies of the message that pass through the transport. However, only the | |
19541 | message's original header lines, and any that were added by a system filter, | |
19542 | are rewritten. If a router or transport adds header lines, they are | |
19543 | not affected by this option. These rewriting rules are 'not' applied to the | |
19544 | envelope. You can change the return path using %return_path%, but you cannot | |
19545 | change envelope recipients at this time. | |
19546 | ||
19547 | ||
19548 | oindex:[%home_directory%] | |
19549 | `..'= | |
19550 | %home_directory%, Use: 'transports', Type: 'string'!!, Default: 'unset' | |
19551 | === | |
19552 | ||
19553 | cindex:[transport,home directory for] | |
068aaea8 | 19554 | cindex:[$home$] |
168e428f PH |
19555 | This option specifies a home directory setting for the transport, overriding |
19556 | any value that may be set by the router. The home directory is placed in | |
19557 | $home$ while expanding the transport's private options. It is also used as | |
19558 | the current directory if no current directory is set by the | |
19559 | %current_directory% option on the transport or the | |
19560 | %transport_current_directory% option on the router. | |
19561 | If the expansion fails for any reason, including forced failure, an error is | |
19562 | logged, and delivery is deferred. | |
19563 | ||
19564 | ||
19565 | oindex:[%initgroups%] | |
19566 | `..'= | |
19567 | %initgroups%, Use: 'transports', Type: 'boolean', Default: 'false' | |
19568 | === | |
19569 | ||
19570 | cindex:[additional groups] | |
19571 | cindex:[groups, additional] | |
19572 | cindex:[transport,group; additional] | |
19573 | If this option is true and the uid for the delivery process is provided by the | |
19574 | transport, the 'initgroups()' function is called when running the transport | |
19575 | to ensure that any additional groups associated with the uid are set up. | |
19576 | ||
19577 | ||
19578 | oindex:[%message_size_limit%] | |
19579 | `..'= | |
19580 | %message_size_limit%, Use: 'transports', Type: 'string'!!, Default: '0' | |
19581 | === | |
19582 | ||
19583 | cindex:[limit,message size per transport] | |
19584 | cindex:[size of message, limit] | |
19585 | cindex:[transport,message size; limiting] | |
19586 | This option controls the size of messages passed through the transport. It is | |
19587 | expanded before use; the result of the expansion must be a sequence of digits, | |
19588 | optionally followed by K or M. | |
19589 | If the expansion fails for any reason, including forced failure, or if the | |
19590 | result is not of the required form, delivery is deferred. | |
19591 | If the value is greater than zero and the size of a message exceeds this | |
19592 | limit, the address is failed. If there is any chance that the resulting bounce | |
19593 | message could be routed to the same transport, you should ensure that | |
19594 | %return_size_limit% is less than the transport's %message_size_limit%, as | |
19595 | otherwise the bounce message will fail to get delivered. | |
19596 | ||
19597 | ||
19598 | ||
19599 | oindex:[%rcpt_include_affixes%] | |
19600 | `..'= | |
19601 | %rcpt_include_affixes%, Use: 'transports', Type: 'boolean', Default: 'false' | |
19602 | === | |
19603 | ||
19604 | cindex:[prefix,for local part; including in envelope] | |
19605 | cindex:[suffix,for local part; including in envelope] | |
19606 | cindex:[local part,prefix] | |
19607 | cindex:[local part,suffix] | |
19608 | When this option is false (the default), and an address that has had any | |
19609 | affixes (prefixes or suffixes) removed from the local part is delivered by any | |
19610 | form of SMTP or LMTP, the affixes are not included. For example, if a router | |
19611 | that contains | |
19612 | ||
19613 | local_part_prefix = *- | |
19614 | ||
19615 | routes the address 'abc-xyz@some.domain' to an SMTP transport, the envelope | |
19616 | is delivered with | |
19617 | ||
19618 | RCPT TO:<xyz@some.domain> | |
19619 | ||
068aaea8 PH |
19620 | [revisionflag="changed"] |
19621 | This is also the case when an ACL-time callout is being used to verify a | |
19622 | recipient address. | |
19623 | ||
168e428f PH |
19624 | If %rcpt_include_affixes% is set true, the whole local part is included in |
19625 | the RCPT command. This option applies to BSMTP deliveries by the | |
19626 | ^appendfile^ and ^pipe^ transports as well as to the ^lmtp^ and ^smtp^ | |
19627 | transports. | |
19628 | ||
19629 | ||
19630 | oindex:[%retry_use_local_part%] | |
19631 | `..'= | |
19632 | %retry_use_local_part%, Use: 'transports', Type: 'boolean', Default: 'see below' | |
19633 | === | |
19634 | ||
19635 | cindex:[hints database,retry keys] | |
19636 | When a delivery suffers a temporary failure, a retry record is created | |
19637 | in Exim's hints database. For remote deliveries, the key for the retry record | |
19638 | is based on the name and/or IP address of the failing remote host. For local | |
19639 | deliveries, the key is normally the entire address, including both the local | |
19640 | part and the domain. This is suitable for most common cases of local delivery | |
19641 | temporary failure -- for example, exceeding a mailbox quota should delay only | |
19642 | deliveries to that mailbox, not to the whole domain. | |
19643 | ||
19644 | However, in some special cases you may want to treat a temporary local delivery | |
19645 | as a failure associated with the domain, and not with a particular local part. | |
19646 | (For example, if you are storing all mail for some domain in files.) You can do | |
19647 | this by setting %retry_use_local_part% false. | |
19648 | ||
19649 | For all the local transports, its default value is true. For remote transports, | |
19650 | the default value is false for tidiness, but changing the value has no effect | |
19651 | on a remote transport in the current implementation. | |
19652 | ||
19653 | ||
19654 | oindex:[%return_path%] | |
19655 | `..'= | |
19656 | %return_path%, Use: 'transports', Type: 'string'!!, Default: 'unset' | |
19657 | === | |
19658 | ||
19659 | cindex:[envelope sender] | |
19660 | cindex:[transport,return path; changing] | |
19661 | cindex:[return path,changing in transport] | |
19662 | If this option is set, the string is expanded at transport time and replaces | |
19663 | the existing return path (envelope sender) value in the copy of the message | |
19664 | that is being delivered. An empty return path is permitted. This feature is | |
19665 | designed for remote deliveries, where the value of this option is used in the | |
19666 | SMTP MAIL command. If you set %return_path% for a local transport, the | |
19667 | only effect is to change the address that is placed in the 'Return-path:' | |
19668 | header line, if one is added to the message (see the next option). | |
19669 | ||
068aaea8 | 19670 | cindex:[$return_path$] |
168e428f PH |
19671 | The expansion can refer to the existing value via $return_path$. This is |
19672 | either the message's envelope sender, or an address set by the | |
19673 | %errors_to% option on a router. If the expansion is forced to fail, no | |
19674 | replacement occurs; if it fails for another reason, delivery is deferred. This | |
19675 | option can be used to support VERP (Variable Envelope Return Paths) -- see | |
19676 | chapter <<CHAPSMTP>>. | |
19677 | ||
19678 | *Note*: If a delivery error is detected locally, | |
19679 | including the case when a remote server rejects a message at SMTP time, | |
19680 | the bounce message is not sent to the value of this option, but to the | |
19681 | previously set errors address (which defaults to the incoming sender address). | |
19682 | ||
19683 | ||
19684 | ||
19685 | oindex:[%return_path_add%] | |
19686 | `..'= | |
19687 | %return_path_add%, Use: 'transports', Type: 'boolean', Default: 'false' | |
19688 | === | |
19689 | ||
19690 | cindex:['Return-path:' header line] | |
19691 | If this option is true, a 'Return-path:' header is added to the message. | |
19692 | Although the return path is normally available in the prefix line of BSD | |
19693 | mailboxes, this is commonly not displayed by MUAs, and so the user does not | |
19694 | have easy access to it. | |
19695 | ||
19696 | RFC 2821 states that the 'Return-path:' header is added to a message ``when the | |
19697 | delivery SMTP server makes the final delivery''. This implies that this header | |
19698 | should not be present in incoming messages. Exim has a configuration option, | |
19699 | %return_path_remove%, which requests removal of this header from incoming | |
19700 | messages, so that delivered messages can safely be resent to other recipients. | |
19701 | ||
19702 | ||
19703 | oindex:[%shadow_condition%] | |
19704 | `..'= | |
19705 | %shadow_condition%, Use: 'transports', Type: 'string'!!, Default: 'unset' | |
19706 | === | |
19707 | ||
19708 | See %shadow_transport% below. | |
19709 | ||
19710 | ||
19711 | oindex:[%shadow_transport%] | |
19712 | `..'= | |
19713 | %shadow_transport%, Use: 'transports', Type: 'string', Default: 'unset' | |
19714 | === | |
19715 | ||
19716 | cindex:[shadow transport] | |
19717 | cindex:[transport,shadow] | |
19718 | A local transport may set the %shadow_transport% option to the name of another | |
19719 | local transport. Shadow remote transports are not supported. | |
19720 | ||
19721 | Whenever a delivery to the main transport succeeds, and either | |
19722 | %shadow_condition% is unset, or its expansion does not result in the empty | |
19723 | string or one of the strings ``0'' or ``no'' or ``false'', the message is also passed | |
19724 | to the shadow transport, with the same delivery address or addresses. | |
19725 | If expansion fails, no action is taken except that non-forced expansion | |
19726 | failures cause a log line to be written. | |
19727 | ||
19728 | The result of the shadow transport is discarded and does not affect the | |
19729 | subsequent processing of the message. Only a single level of shadowing is | |
19730 | provided; the %shadow_transport% option is ignored on any transport when it is | |
19731 | running as a shadow. Options concerned with output from pipes are also ignored. | |
19732 | ||
19733 | The log line for the successful delivery has an item added on the end, of the | |
19734 | form | |
19735 | ||
19736 | ST=<shadow transport name> | |
19737 | ||
19738 | If the shadow transport did not succeed, the error message is put in | |
19739 | parentheses afterwards. | |
19740 | ||
19741 | Shadow transports can be used for a number of different purposes, including | |
19742 | keeping more detailed log information than Exim normally provides, and | |
19743 | implementing automatic acknowledgement policies based on message headers that | |
19744 | some sites insist on. | |
19745 | ||
19746 | ||
19747 | oindex:[%transport_filter%] | |
19748 | `..'= | |
19749 | %transport_filter%, Use: 'transports', Type: 'string'!!, Default: 'unset' | |
19750 | === | |
19751 | ||
19752 | cindex:[transport,filter] | |
19753 | cindex:[filter,transport filter] | |
19754 | This option sets up a filtering (in the Unix shell sense) process for messages | |
19755 | at transport time. It should not be confused with mail filtering as set up by | |
19756 | individual users or via a system filter. | |
19757 | ||
19758 | When the message is about to be written out, the command specified by | |
068aaea8 PH |
19759 | %transport_filter% is started up in a separate process, and the entire message, |
19760 | including the header lines, is passed to it on its standard input (this in fact | |
19761 | is done from a third process, to avoid deadlock). The command must be specified | |
19762 | as an absolute path. | |
168e428f PH |
19763 | |
19764 | The lines of the message that are written to the transport filter are | |
068aaea8 PH |
19765 | terminated by newline (``\n''). The message is passed to the filter before any |
19766 | SMTP-specific processing, such as turning ``\n'' into ``\r\n'' and escaping | |
19767 | lines beginning with a dot, and also before any processing implied by the | |
19768 | settings of %check_string% and %escape_string% in the ^appendfile^ or ^pipe^ | |
19769 | transports. | |
168e428f PH |
19770 | |
19771 | The standard error for the filter process is set to the same destination as its | |
19772 | standard output; this is read and written to the message's ultimate | |
068aaea8 PH |
19773 | destination. The filter can perform any transformations it likes, but of course |
19774 | should take care not to break RFC 2822 syntax. A demonstration Perl script is | |
19775 | provided in _util/transport-filter.pl_; this makes a few arbitrary | |
19776 | modifications just to show the possibilities. Exim does not check the result, | |
19777 | except to test for a final newline when SMTP is in use. All messages | |
19778 | transmitted over SMTP must end with a newline, so Exim supplies one if it is | |
19779 | missing. | |
168e428f | 19780 | |
068aaea8 PH |
19781 | [revisionflag="changed"] |
19782 | cindex:[content scanning,per user] | |
19783 | A transport filter can be used to provide content-scanning on a per-user basis | |
19784 | at delivery time if the only required effect of the scan is to modify the | |
19785 | message. For example, a content scan could insert a new header line containing | |
19786 | a spam score. This could be interpreted by a filter in the user's MUA. It is | |
19787 | not possible to discard a message at this stage. | |
168e428f PH |
19788 | |
19789 | cindex:[SMTP,SIZE] | |
19790 | A problem might arise if the filter increases the size of a message that is | |
19791 | being sent down an SMTP connection. If the receiving SMTP server has indicated | |
19792 | support for the SIZE parameter, Exim will have sent the size of the message | |
19793 | at the start of the SMTP session. If what is actually sent is substantially | |
19794 | more, the server might reject the message. This can be worked round by setting | |
19795 | the %size_addition% option on the ^smtp^ transport, either to allow for | |
19796 | additions to the message, or to disable the use of SIZE altogether. | |
19797 | ||
068aaea8 | 19798 | cindex:[$pipe_addresses$] |
168e428f PH |
19799 | The value of the %transport_filter% option is the command string for starting |
19800 | the filter, which is run directly from Exim, not under a shell. The string is | |
19801 | parsed by Exim in the same way as a command string for the ^pipe^ transport: | |
19802 | Exim breaks it up into arguments and then expands each argument separately. The | |
19803 | special argument $pipe_addresses$ is replaced by a number of arguments, one | |
19804 | for each address that applies to this delivery. (This isn't an ideal name for | |
19805 | this feature here, but as it was already implemented for the ^pipe^ | |
19806 | transport, it seemed sensible not to change it.) | |
19807 | ||
19808 | cindex:[$host$] | |
19809 | cindex:[$host_address$] | |
19810 | The expansion variables $host$ and $host_address$ are available when the | |
19811 | transport is a remote one. They contain the name and IP address of the host to | |
19812 | which the message is being sent. For example: | |
19813 | ||
19814 | .... | |
19815 | transport_filter = /some/directory/transport-filter.pl \ | |
19816 | $host $host_address $sender_address $pipe_addresses | |
19817 | .... | |
19818 | ||
19819 | The filter process is run under the same uid and gid as the normal delivery. | |
19820 | For remote deliveries this is the Exim uid/gid by default. | |
19821 | ||
19822 | The command should normally yield a zero return code. A non-zero code is taken | |
19823 | to mean that the transport filter failed in some way. Delivery of the message | |
19824 | is deferred. It is not possible to cause a message to be bounced from a | |
19825 | transport filter. | |
19826 | ||
19827 | ||
19828 | If a transport filter is set on an autoreply transport, the original message is | |
19829 | passed through the filter as it is being copied into the newly generated | |
19830 | message, which happens if the %return_message% option is set. | |
19831 | ||
19832 | ||
19833 | oindex:[%transport_filter_timeout%] | |
19834 | `..'= | |
19835 | %transport_filter_timeout%, Use: 'transports', Type: 'time', Default: '5m' | |
19836 | === | |
19837 | ||
068aaea8 | 19838 | [revisionflag="changed"] |
168e428f PH |
19839 | cindex:[transport filter, timeout] |
19840 | When Exim is reading the output of a transport filter, it a applies a timeout | |
068aaea8 PH |
19841 | that can be set by this option. Exceeding the timeout is normally treated as a |
19842 | temporary delivery failure. However, if a transport filter is used with a | |
19843 | ^pipe^ transport, a timeout in the transport filter is treated in the same way | |
19844 | as a timeout in the pipe command itself. By default, a timeout is a hard error, | |
19845 | but if the ^pipe^ transport's %timeout_defer% option is set true, it becomes a | |
19846 | temporary error. | |
168e428f PH |
19847 | |
19848 | ||
19849 | ||
19850 | oindex:[%user%] | |
19851 | `..'= | |
19852 | %user%, Use: 'transports', Type: 'string'!!, Default: 'Exim user' | |
19853 | === | |
19854 | ||
19855 | cindex:[uid (user id),local delivery] | |
19856 | cindex:[transport user, specifying] | |
19857 | This option specifies the user under whose uid the delivery process is to be | |
19858 | run, overriding any uid that may have been set by the router. If the user is | |
19859 | given as a name, the uid is looked up from the password data, and the | |
19860 | associated group is taken as the value of the gid to be used if the %group% | |
19861 | option is not set. | |
19862 | ||
19863 | For deliveries that use local transports, a user and group are normally | |
19864 | specified explicitly or implicitly (for example, as a result of | |
19865 | %check_local_user%) by the router or transport. | |
19866 | ||
19867 | cindex:[hints database,access by remote transport] | |
19868 | For remote transports, you should leave this option unset unless you really are | |
19869 | sure you know what you are doing. When a remote transport is running, it needs | |
19870 | to be able to access Exim's hints databases, because each host may have its own | |
19871 | retry data. | |
19872 | ||
19873 | ||
19874 | ||
19875 | ||
19876 | ||
19877 | ||
19878 | //////////////////////////////////////////////////////////////////////////// | |
19879 | //////////////////////////////////////////////////////////////////////////// | |
19880 | ||
19881 | [[CHAPbatching]] | |
19882 | [titleabbrev="Address batching"] | |
19883 | Address batching in local transports | |
19884 | ------------------------------------ | |
19885 | cindex:[transport,local; address batching in] | |
19886 | The only remote transport (^smtp^) is normally configured to handle more than | |
19887 | one address at a time, so that when several addresses are routed to the same | |
19888 | remote host, just one copy of the message is sent. Local transports, however, | |
19889 | normally handle one address at a time. That is, a separate instance of the | |
19890 | transport is run for each address that is routed to the transport. A separate | |
19891 | copy of the message is delivered each time. | |
19892 | ||
19893 | cindex:[batched local delivery] | |
19894 | cindex:[%batch_max%] | |
19895 | cindex:[%batch_id%] | |
19896 | In special cases, it may be desirable to handle several addresses at once in a | |
19897 | local transport, for example: | |
19898 | ||
19899 | - In an ^appendfile^ transport, when storing messages in files for later | |
19900 | delivery by some other means, a single copy of the message with multiple | |
19901 | recipients saves space. | |
19902 | ||
19903 | - In an ^lmtp^ transport, when delivering over ``local SMTP'' to some process, | |
19904 | a single copy saves time, and is the normal way LMTP is expected to work. | |
19905 | ||
19906 | - In a ^pipe^ transport, when passing the message | |
19907 | to a scanner program or | |
19908 | to some other delivery mechanism such as UUCP, multiple recipients may be | |
19909 | acceptable. | |
19910 | ||
19911 | The three local transports (^appendfile^, ^lmtp^, and ^pipe^) all have | |
19912 | the same options for controlling multiple (``batched'') deliveries, namely | |
19913 | %batch_max% and %batch_id%. To save repeating the information for each | |
19914 | transport, these options are described here. | |
19915 | ||
19916 | The %batch_max% option specifies the maximum number of addresses that can be | |
19917 | delivered together in a single run of the transport. Its default value is one. | |
19918 | When more than one address is routed to a transport that has a %batch_max% | |
19919 | value greater than one, the addresses are delivered in a batch (that is, in a | |
19920 | single run of the transport), subject to certain conditions: | |
19921 | ||
068aaea8 PH |
19922 | - cindex:[$local_part$] |
19923 | If any of the transport's options contain a reference to $local_part$, no | |
168e428f PH |
19924 | batching is possible. |
19925 | ||
068aaea8 PH |
19926 | - cindex:[$domain$] |
19927 | If any of the transport's options contain a reference to $domain$, only | |
168e428f PH |
19928 | addresses with the same domain are batched. |
19929 | ||
19930 | - cindex:[customizing,batching condition] | |
19931 | If %batch_id% is set, it is expanded for each address, and only those | |
19932 | addresses with the same expanded value are batched. This allows you to specify | |
19933 | customized batching conditions. | |
19934 | Failure of the expansion for any reason, including forced failure, disables | |
19935 | batching, but it does not stop the delivery from taking place. | |
19936 | ||
19937 | - Batched addresses must also have the same errors address (where to send | |
19938 | delivery errors), the same header additions and removals, the same user and | |
19939 | group for the transport, and if a host list is present, the first host must | |
19940 | be the same. | |
19941 | ||
19942 | cindex:['Envelope-to:' header line] | |
19943 | If the generic %envelope_to_add% option is set for the transport, the | |
19944 | 'Envelope-to:' header that is added to the message contains all the addresses | |
19945 | that are batched together. | |
19946 | ||
19947 | The ^appendfile^ and ^pipe^ transports have an option called %use_bsmtp%, | |
19948 | which causes them to deliver the message in ``batched SMTP'' format, with the | |
19949 | envelope represented as SMTP commands. The %check_string% and %escape_string% | |
19950 | options are forced to the values | |
19951 | ||
19952 | check_string = "." | |
19953 | escape_string = ".." | |
19954 | ||
19955 | when batched SMTP is in use. A full description of the batch SMTP mechanism is | |
19956 | given in section <<SECTbatchSMTP>>. The ^lmtp^ transport does not have a | |
19957 | %use_bsmtp% option, because it always delivers using the SMTP protocol. | |
19958 | ||
19959 | cindex:[^pipe^ transport,with multiple addresses] | |
068aaea8 | 19960 | cindex:[$pipe_addresses$] |
168e428f PH |
19961 | If you are not using BSMTP, but are using a ^pipe^ transport, you can include |
19962 | $pipe_addresses$ as part of the command. This is not a true variable; it is | |
19963 | a bit of magic that causes each of the recipient addresses to be inserted into | |
19964 | the command as a separate argument. This provides a way of accessing all the | |
19965 | addresses that are being delivered in the batch. | |
19966 | ||
19967 | If you are using a batching ^appendfile^ transport without %use_bsmtp%, the | |
19968 | only way to preserve the recipient addresses is to set the %envelope_to_add% | |
19969 | option. This causes an 'Envelope-to:' header line to be added to the message, | |
19970 | containing all the recipients. | |
19971 | ||
19972 | ||
19973 | ||
19974 | //////////////////////////////////////////////////////////////////////////// | |
19975 | //////////////////////////////////////////////////////////////////////////// | |
19976 | ||
19977 | [[CHAPappendfile]] | |
19978 | The appendfile transport | |
19979 | ------------------------ | |
19980 | cindex:[^appendfile^ transport] | |
19981 | cindex:[transports,^appendfile^] | |
19982 | cindex:[directory creation] | |
19983 | cindex:[creating directories] | |
19984 | The ^appendfile^ transport delivers a message by appending it to an existing | |
19985 | file, or by creating an entirely new file in a specified directory. Single | |
19986 | files to which messages are appended can be in the traditional Unix mailbox | |
19987 | format, or optionally in the MBX format supported by the Pine MUA and | |
19988 | University of Washington IMAP daemon, 'inter alia'. When each message is | |
19989 | being delivered as a separate file, ``maildir'' format can optionally be used to | |
19990 | give added protection against failures that happen part-way through the | |
19991 | delivery. A third form of separate-file delivery known as ``mailstore'' is also | |
19992 | supported. For all file formats, Exim attempts to create as many levels of | |
19993 | directory as necessary, provided that %create_directory% is set. | |
19994 | ||
19995 | The code for the optional formats is not included in the Exim binary by | |
19996 | default. It is necessary to set SUPPORT_MBX, SUPPORT_MAILDIR and/or | |
19997 | SUPPORT_MAILSTORE in _Local/Makefile_ to have the appropriate code | |
19998 | included. | |
19999 | ||
20000 | cindex:[quota,system] | |
20001 | Exim recognises system quota errors, and generates an appropriate message. Exim | |
20002 | also supports its own quota control within the transport, for use when the | |
20003 | system facility is unavailable or cannot be used for some reason. | |
20004 | ||
20005 | If there is an error while appending to a file (for example, quota exceeded or | |
20006 | partition filled), Exim attempts to reset the file's length and last | |
20007 | modification time back to what they were before. If there is an error while | |
20008 | creating an entirely new file, the new file is removed. | |
20009 | ||
20010 | Before appending to a file, a number of security checks are made, and the | |
20011 | file is locked. A detailed description is given below, after the list of | |
20012 | private options. | |
20013 | ||
20014 | ^appendfile^ is most commonly used for local deliveries to users' mailboxes. | |
20015 | However, it can also be used as a pseudo-remote transport for putting messages | |
20016 | into files for remote delivery by some means other than Exim. ``Batch SMTP'' | |
20017 | format is often used in this case (see the %use_bsmtp% option). | |
20018 | ||
20019 | ||
20020 | ||
20021 | [[SECTfildiropt]] | |
20022 | The file and directory options | |
20023 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
20024 | The %file% option specifies a single file, to which the message is appended; | |
20025 | the %directory% option specifies a directory, in which a new file containing | |
20026 | the message is created. Only one of these two options can be set, and for | |
20027 | normal deliveries to mailboxes, one of them 'must' be set. | |
20028 | ||
068aaea8 PH |
20029 | cindex:[$address_file$] |
20030 | cindex:[$local_part$] | |
168e428f PH |
20031 | However, ^appendfile^ is also used for delivering messages to files or |
20032 | directories whose names (or parts of names) are obtained from alias, | |
20033 | forwarding, or filtering operations (for example, a %save% command in a user's | |
20034 | Exim filter). When such a transport is running, $local_part$ contains the | |
20035 | local part that was aliased or forwarded, and $address_file$ contains the | |
20036 | name (or partial name) of the file or directory generated by the redirection | |
20037 | operation. There are two cases: | |
20038 | ||
20039 | - If neither %file% nor %directory% is set, the redirection operation | |
20040 | must specify an absolute path (one that begins with `/`). This is the most | |
20041 | common case when users with local accounts use filtering to sort mail into | |
20042 | different folders. See for example, the ^address_file^ transport in the | |
20043 | default configuration. If the path ends with a slash, it is assumed to be the | |
20044 | name of a directory. A delivery to a directory can also be forced by setting | |
20045 | %maildir_format% or %mailstore_format%. | |
20046 | ||
20047 | - If %file% or %directory% is set for a delivery from a redirection, it is used | |
20048 | to determine the file or directory name for the delivery. Normally, the | |
20049 | contents of $address_file$ are used in some way in the string expansion. | |
20050 | ||
20051 | ||
20052 | cindex:[Sieve filter,configuring ^appendfile^] | |
20053 | cindex:[Sieve filter,relative mailbox path handling] | |
20054 | As an example of the second case, consider an environment where users do not | |
20055 | have home directories. They may be permitted to use Exim filter commands of the | |
20056 | form: | |
20057 | ||
20058 | save folder23 | |
20059 | ||
20060 | or Sieve filter commands of the form: | |
20061 | ||
20062 | require "fileinto"; | |
20063 | fileinto "folder23"; | |
20064 | ||
20065 | In this situation, the expansion of %file% or %directory% in the transport must | |
20066 | transform the relative path into an appropriate absolute file name. In the case | |
20067 | of Sieve filters, the name 'inbox' must be handled. It is the name that is | |
20068 | used as a result of a ``keep'' action in the filter. This example shows one way | |
20069 | of handling this requirement: | |
20070 | ||
20071 | .... | |
20072 | file = ${if eq{$address_file}{inbox} \ | |
20073 | {/var/mail/$local_part} \ | |
20074 | {${if eq{${substr_0_1:$address_file}}{/} \ | |
20075 | {$address_file} \ | |
20076 | {$home/mail/$address_file} \ | |
20077 | }} \ | |
20078 | } | |
20079 | .... | |
20080 | ||
20081 | With this setting of %file%, 'inbox' refers to the standard mailbox location, | |
20082 | absolute paths are used without change, and other folders are in the _mail_ | |
20083 | directory within the home directory. | |
20084 | ||
20085 | *Note 1*: While processing an Exim filter, a relative path such as | |
20086 | _folder23_ is turned into an absolute path if a home directory is known to | |
20087 | the router. In particular, this is the case if %check_local_user% is set. If | |
20088 | you want to prevent this happening at routing time, you can set | |
20089 | %router_home_directory% empty. This forces the router to pass the relative | |
20090 | path to the transport. | |
20091 | ||
20092 | *Note 2*: An absolute path in $address_file$ is not treated specially; | |
20093 | the %file% or %directory% option is still used if it is set. | |
20094 | ||
20095 | ||
20096 | ||
20097 | ||
20098 | Private options for appendfile | |
20099 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
20100 | cindex:[options,^appendfile^ transport] | |
20101 | ||
20102 | ||
20103 | ||
20104 | oindex:[%allow_fifo%] | |
20105 | `..'= | |
20106 | %allow_fifo%, Use: 'appendfile', Type: 'boolean', Default: 'false' | |
20107 | === | |
20108 | ||
20109 | cindex:[fifo (named pipe)] | |
20110 | cindex:[named pipe (fifo)] | |
20111 | cindex:[pipe,named (fifo)] | |
20112 | Setting this option permits delivery to named pipes (FIFOs) as well as to | |
20113 | regular files. If no process is reading the named pipe at delivery time, the | |
20114 | delivery is deferred. | |
20115 | ||
20116 | ||
20117 | oindex:[%allow_symlink%] | |
20118 | `..'= | |
20119 | %allow_symlink%, Use: 'appendfile', Type: 'boolean', Default: 'false' | |
20120 | === | |
20121 | ||
20122 | cindex:[symbolic link,to mailbox] | |
20123 | cindex:[mailbox,symbolic link] | |
20124 | By default, ^appendfile^ will not deliver if the path name for the file is | |
20125 | that of a symbolic link. Setting this option relaxes that constraint, but there | |
20126 | are security issues involved in the use of symbolic links. Be sure you know | |
20127 | what you are doing if you set this. Details of exactly what this option affects | |
20128 | are included in the discussion which follows this list of options. | |
20129 | ||
20130 | ||
20131 | oindex:[%batch_id%] | |
20132 | `..'= | |
20133 | %batch_id%, Use: 'appendfile', Type: 'string'!!, Default: 'unset' | |
20134 | === | |
20135 | ||
20136 | See the description of local delivery batching in chapter <<CHAPbatching>>. | |
20137 | However, batching is automatically disabled for ^appendfile^ deliveries that | |
20138 | happen as a result of forwarding or aliasing or other redirection directly to a | |
20139 | file. | |
20140 | ||
20141 | ||
20142 | oindex:[%batch_max%] | |
20143 | `..'= | |
20144 | %batch_max%, Use: 'appendfile', Type: 'integer', Default: '1' | |
20145 | === | |
20146 | ||
20147 | See the description of local delivery batching in chapter <<CHAPbatching>>. | |
20148 | ||
20149 | ||
20150 | oindex:[%check_group%] | |
20151 | `..'= | |
20152 | %check_group%, Use: 'appendfile', Type: 'boolean', Default: 'false' | |
20153 | === | |
20154 | ||
20155 | When this option is set, the group owner of the file defined by the %file% | |
20156 | option is checked to see that it is the same as the group under which the | |
20157 | delivery process is running. The default setting is false because the default | |
20158 | file mode is 0600, which means that the group is irrelevant. | |
20159 | ||
20160 | ||
20161 | oindex:[%check_owner%] | |
20162 | `..'= | |
20163 | %check_owner%, Use: 'appendfile', Type: 'boolean', Default: 'true' | |
20164 | === | |
20165 | ||
20166 | When this option is set, the owner of the file defined by the %file% option is | |
20167 | checked to ensure that it is the same as the user under which the delivery | |
20168 | process is running. | |
20169 | ||
20170 | ||
20171 | oindex:[%check_string%] | |
20172 | `..'= | |
20173 | %check_string%, Use: 'appendfile', Type: 'string', Default: 'see below' | |
20174 | === | |
20175 | ||
20176 | cindex:[``From'' line] | |
20177 | As ^appendfile^ writes the message, the start of each line is tested for | |
20178 | matching %check_string%, and if it does, the initial matching characters are | |
20179 | replaced by the contents of %escape_string%. The value of %check_string% is a | |
20180 | literal string, not a regular expression, and the case of any letters it | |
20181 | contains is significant. | |
20182 | ||
20183 | If %use_bsmtp% is set the values of %check_string% and %escape_string% are | |
20184 | forced to ``.'' and ``..'' respectively, and any settings in the configuration are | |
20185 | ignored. Otherwise, they default to ``From '' and ``>From '' when the %file% option | |
20186 | is set, and unset when | |
20187 | any of the %directory%, %maildir%, or %mailstore% options are set. | |
20188 | ||
20189 | The default settings, along with %message_prefix% and %message_suffix%, are | |
20190 | suitable for traditional ``BSD'' mailboxes, where a line beginning with ``From | |
20191 | '' indicates the start of a new message. All four options need changing if | |
20192 | another format is used. For example, to deliver to mailboxes in MMDF format: | |
20193 | cindex:[MMDF format mailbox] | |
20194 | cindex:[mailbox,MMDF format] | |
20195 | ||
20196 | check_string = "\1\1\1\1\n" | |
20197 | escape_string = "\1\1\1\1 \n" | |
20198 | message_prefix = "\1\1\1\1\n" | |
20199 | message_suffix = "\1\1\1\1\n" | |
20200 | ||
20201 | oindex:[%create_directory%] | |
20202 | `..'= | |
20203 | %create_directory%, Use: 'appendfile', Type: 'boolean', Default: 'true' | |
20204 | === | |
20205 | ||
20206 | cindex:[directory creation] | |
20207 | When this option is true, Exim attempts to create any missing superior | |
20208 | directories for the file that it is about to write. A created directory's mode | |
20209 | is given by the %directory_mode% option. | |
20210 | ||
20211 | The group ownership of a newly created directory is highly dependent on the | |
20212 | operating system (and possibly the file system) that is being used. For | |
20213 | example, in Solaris, if the parent directory has the setgid bit set, its group | |
20214 | is propagated to the child; if not, the currently set group is used. However, | |
20215 | in FreeBSD, the parent's group is always used. | |
20216 | ||
20217 | ||
20218 | ||
20219 | oindex:[%create_file%] | |
20220 | `..'= | |
20221 | %create_file%, Use: 'appendfile', Type: 'string', Default: 'anywhere' | |
20222 | === | |
20223 | ||
20224 | This option constrains the location of files and directories that are created | |
20225 | by this transport. It applies to files defined by the %file% option and | |
20226 | directories defined by the %directory% option. In the case of maildir delivery, | |
20227 | it applies to the top level directory, not the maildir directories beneath. | |
20228 | ||
20229 | The option must be set to one of the words ``anywhere'', ``inhome'', or | |
20230 | ``belowhome''. In the second and third cases, a home directory must have been set | |
20231 | for the transport. This option is not useful when an explicit file name is | |
20232 | given for normal mailbox deliveries. It is intended for the case when file | |
20233 | names are generated from users' _.forward_ files. These are usually handled | |
20234 | by an ^appendfile^ transport called %address_file%. See also | |
20235 | %file_must_exist%. | |
20236 | ||
20237 | ||
20238 | oindex:[%directory%] | |
20239 | `..'= | |
20240 | %directory%, Use: 'appendfile', Type: 'string'!!, Default: 'unset' | |
20241 | === | |
20242 | ||
20243 | This option is mutually exclusive with the %file% option, but one of %file% or | |
20244 | %directory% must be set, unless the delivery is the direct result of a | |
20245 | redirection (see section <<SECTfildiropt>>). | |
20246 | ||
20247 | When %directory% is set, the string is expanded, and the message is delivered | |
20248 | into a new file or files in or below the given directory, instead of being | |
20249 | appended to a single mailbox file. A number of different formats are provided | |
20250 | (see %maildir_format% and %mailstore_format%), and see section <<SECTopdir>> | |
20251 | for further details of this form of delivery. | |
20252 | ||
20253 | ||
20254 | oindex:[%directory_file%] | |
20255 | `..'= | |
20256 | %directory_file%, Use: 'appendfile', Type: 'string'!!, Default: `q\$\{base62{co}\$tod_epoch\}-\$inode` | |
20257 | === | |
20258 | ||
20259 | cindex:[base62] | |
068aaea8 | 20260 | cindex:[$inode$] |
168e428f PH |
20261 | When %directory% is set, but neither %maildir_format% nor %mailstore_format% |
20262 | is set, ^appendfile^ delivers each message into a file whose name is obtained | |
20263 | by expanding this string. The default value generates a unique name from the | |
20264 | current time, in base 62 form, and the inode of the file. The variable | |
20265 | $inode$ is available only when expanding this option. | |
20266 | ||
20267 | ||
20268 | oindex:[%directory_mode%] | |
20269 | `..'= | |
20270 | %directory_mode%, Use: 'appendfile', Type: 'octal integer', Default: '0700' | |
20271 | === | |
20272 | ||
20273 | If ^appendfile^ creates any directories as a result of the %create_directory% | |
20274 | option, their mode is specified by this option. | |
20275 | ||
20276 | ||
20277 | oindex:[%escape_string%] | |
20278 | `..'= | |
20279 | %escape_string%, Use: 'appendfile', Type: 'string', Default: 'see description' | |
20280 | === | |
20281 | ||
20282 | See %check_string% above. | |
20283 | ||
20284 | ||
20285 | oindex:[%file%] | |
20286 | `..'= | |
20287 | %file%, Use: 'appendfile', Type: 'string'!!, Default: 'unset' | |
20288 | === | |
20289 | ||
20290 | This option is mutually exclusive with the %directory% option, but one of | |
20291 | %file% or %directory% must be set, unless the delivery is the direct result of | |
20292 | a redirection (see section <<SECTfildiropt>>). The %file% option specifies a | |
20293 | single file, to which the message is appended. One or more of | |
20294 | %use_fcntl_lock%, %use_flock_lock%, or %use_lockfile% must be set with | |
20295 | %file%. | |
20296 | ||
20297 | cindex:[NFS,lock file] | |
20298 | cindex:[locking files] | |
20299 | cindex:[lock files] | |
20300 | If you are using more than one host to deliver over NFS into the same | |
20301 | mailboxes, you should always use lock files. | |
20302 | ||
20303 | The string value is expanded for each delivery, and must yield an absolute | |
20304 | path. The most common settings of this option are variations on one of these | |
20305 | examples: | |
20306 | ||
20307 | file = /var/spool/mail/$local_part | |
20308 | file = /home/$local_part/inbox | |
20309 | file = $home/inbox | |
20310 | ||
20311 | cindex:[``sticky'' bit] | |
20312 | In the first example, all deliveries are done into the same directory. If Exim | |
20313 | is configured to use lock files (see %use_lockfile% below) it must be able to | |
20314 | create a file in the directory, so the ``sticky'' bit must be turned on for | |
20315 | deliveries to be possible, or alternatively the %group% option can be used to | |
20316 | run the delivery under a group id which has write access to the directory. | |
20317 | ||
20318 | ||
20319 | ||
20320 | oindex:[%file_format%] | |
20321 | `..'= | |
20322 | %file_format%, Use: 'appendfile', Type: 'string', Default: 'unset' | |
20323 | === | |
20324 | ||
20325 | cindex:[file,mailbox; checking existing format] | |
20326 | This option requests the transport to check the format of an existing file | |
20327 | before adding to it. The check consists of matching a specific string at the | |
20328 | start of the file. The value of the option consists of an even number of | |
20329 | colon-separated strings. The first of each pair is the test string, and the | |
20330 | second is the name of a transport. If the transport associated with a matched | |
20331 | string is not the current transport, control is passed over to the other | |
20332 | transport. For example, suppose the standard ^local_delivery^ transport has | |
20333 | this added to it: | |
20334 | ||
20335 | .... | |
20336 | file_format = "From : local_delivery :\ | |
20337 | \1\1\1\1\n : local_mmdf_delivery" | |
20338 | .... | |
20339 | ||
20340 | Mailboxes that begin with ``From'' are still handled by this transport, but if a | |
20341 | mailbox begins with four binary ones followed by a newline, control is passed | |
20342 | to a transport called %local_mmdf_delivery%, which presumably is configured | |
20343 | to do the delivery in MMDF format. If a mailbox does not exist or is empty, it | |
20344 | is assumed to match the current transport. If the start of a mailbox doesn't | |
20345 | match any string, or if the transport named for a given string is not defined, | |
20346 | delivery is deferred. | |
20347 | ||
20348 | ||
20349 | oindex:[%file_must_exist%] | |
20350 | `..'= | |
20351 | %file_must_exist%, Use: 'appendfile', Type: 'boolean', Default: 'false' | |
20352 | === | |
20353 | ||
20354 | If this option is true, the file specified by the %file% option must exist, and | |
20355 | an error occurs if it does not. Otherwise, it is created if it does not exist. | |
20356 | ||
20357 | ||
20358 | oindex:[%lock_fcntl_timeout%] | |
20359 | `..'= | |
20360 | %lock_fcntl_timeout%, Use: 'appendfile', Type: 'time', Default: '0s' | |
20361 | === | |
20362 | ||
20363 | cindex:[timeout,mailbox locking] | |
20364 | cindex:[mailbox locking,blocking and non-blocking] | |
20365 | cindex:[locking files] | |
20366 | By default, the ^appendfile^ transport uses non-blocking calls to 'fcntl()' | |
20367 | when locking an open mailbox file. If the call fails, the delivery process | |
20368 | sleeps for %lock_interval% and tries again, up to %lock_retries% times. | |
20369 | Non-blocking calls are used so that the file is not kept open during the wait | |
20370 | for the lock; the reason for this is to make it as safe as possible for | |
20371 | deliveries over NFS in the case when processes might be accessing an NFS | |
20372 | mailbox without using a lock file. This should not be done, but | |
20373 | misunderstandings and hence misconfigurations are not unknown. | |
20374 | ||
20375 | On a busy system, however, the performance of a non-blocking lock approach is | |
20376 | not as good as using a blocking lock with a timeout. In this case, the waiting | |
20377 | is done inside the system call, and Exim's delivery process acquires the lock | |
20378 | and can proceed as soon as the previous lock holder releases it. | |
20379 | ||
20380 | If %lock_fcntl_timeout% is set to a non-zero time, blocking locks, with that | |
20381 | timeout, are used. There may still be some retrying: the maximum number of | |
20382 | retries is | |
20383 | ||
20384 | (lock_retries * lock_interval) / lock_fcntl_timeout | |
20385 | ||
20386 | rounded up to the next whole number. In other words, the total time during | |
20387 | which ^appendfile^ is trying to get a lock is roughly the same, unless | |
20388 | %lock_fcntl_timeout% is set very large. | |
20389 | ||
20390 | You should consider setting this option if you are getting a lot of delayed | |
20391 | local deliveries because of errors of the form | |
20392 | ||
20393 | failed to lock mailbox /some/file (fcntl) | |
20394 | ||
20395 | ||
20396 | ||
20397 | oindex:[%lock_flock_timeout%] | |
20398 | `..'= | |
20399 | %lock_flock_timeout%, Use: 'appendfile', Type: 'time', Default: '0s' | |
20400 | === | |
20401 | ||
20402 | This timeout applies to file locking when using 'flock()' (see %use_flock%); | |
20403 | the timeout operates in a similar manner to %lock_fcntl_timeout%. | |
20404 | ||
20405 | ||
20406 | oindex:[%lock_interval%] | |
20407 | `..'= | |
20408 | %lock_interval%, Use: 'appendfile', Type: 'time', Default: '3s' | |
20409 | === | |
20410 | ||
20411 | This specifies the time to wait between attempts to lock the file. See below | |
20412 | for details of locking. | |
20413 | ||
20414 | ||
20415 | oindex:[%lock_retries%] | |
20416 | `..'= | |
20417 | %lock_retries%, Use: 'appendfile', Type: 'integer', Default: '10' | |
20418 | === | |
20419 | ||
20420 | This specifies the maximum number of attempts to lock the file. A value of zero | |
20421 | is treated as 1. See below for details of locking. | |
20422 | ||
20423 | ||
20424 | oindex:[%lockfile_mode%] | |
20425 | `..'= | |
20426 | %lockfile_mode%, Use: 'appendfile', Type: 'octal integer', Default: '0600' | |
20427 | === | |
20428 | ||
20429 | This specifies the mode of the created lock file, when a lock file is being | |
20430 | used (see %use_lockfile%). | |
20431 | ||
20432 | ||
20433 | oindex:[%lockfile_timeout%] | |
20434 | `..'= | |
20435 | %lockfile_timeout%, Use: 'appendfile', Type: 'time', Default: '30m' | |
20436 | === | |
20437 | ||
20438 | cindex:[timeout,mailbox locking] | |
20439 | When a lock file is being used (see %use_lockfile%), if a lock file already | |
20440 | exists and is older than this value, it is assumed to have been left behind by | |
20441 | accident, and Exim attempts to remove it. | |
20442 | ||
20443 | ||
20444 | oindex:[%mailbox_filecount%] | |
20445 | `..'= | |
20446 | %mailbox_filecount%, Use: 'appendfile', Type: 'string'!!, Default: 'unset' | |
20447 | === | |
20448 | ||
20449 | cindex:[mailbox,specifying size of] | |
20450 | cindex:[size,of mailbox] | |
20451 | If this option is set, it is expanded, and the result is taken as the current | |
20452 | number of files in the mailbox. It must be a decimal number, optionally | |
20453 | followed by K or M. This provides a way of obtaining this information from an | |
20454 | external source that maintains the data. | |
20455 | ||
20456 | ||
20457 | oindex:[%mailbox_size%] | |
20458 | `..'= | |
20459 | %mailbox_size%, Use: 'appendfile', Type: 'string'!!, Default: 'unset' | |
20460 | === | |
20461 | ||
20462 | cindex:[mailbox,specifying size of] | |
20463 | cindex:[size,of mailbox] | |
20464 | If this option is set, it is expanded, and the result is taken as the current | |
20465 | size the mailbox. It must be a decimal number, optionally followed by K or M. | |
20466 | This provides a way of obtaining this information from an external source that | |
20467 | maintains the data. This is likely to be helpful for maildir deliveries where | |
20468 | it is computationally expensive to compute the size of a mailbox. | |
20469 | ||
20470 | ||
20471 | ||
20472 | oindex:[%maildir_format%] | |
20473 | `..'= | |
20474 | %maildir_format%, Use: 'appendfile', Type: 'boolean', Default: 'false' | |
20475 | === | |
20476 | ||
20477 | cindex:[maildir format,specifying] | |
20478 | If this option is set with the %directory% option, the delivery is into a new | |
20479 | file, in the ``maildir'' format that is used by other mail software. When the | |
20480 | transport is activated directly from a ^redirect^ router (for example, the | |
20481 | ^address_file^ transport in the default configuration), setting | |
20482 | %maildir_format% causes the path received from the router to be treated as a | |
20483 | directory, whether or not it ends with `/`. This option is available only if | |
20484 | SUPPORT_MAILDIR is present in _Local/Makefile_. See section | |
20485 | <<SECTmaildirdelivery>> below for further details. | |
20486 | ||
20487 | ||
20488 | oindex:[%maildir_quota_directory_regex%] | |
20489 | `..'= | |
20490 | %maildir_quota_directory_regex%, Use: 'appendfile', Type: 'string', Default: 'See below' | |
20491 | === | |
20492 | ||
20493 | cindex:[maildir format,quota; directories included in] | |
20494 | cindex:[quota,maildir; directories included in] | |
20495 | This option is relevant only when %maildir_use_size_file% is set. It defines | |
20496 | a regular expression for specifying directories that should be included in the | |
20497 | quota calculation. The default value is | |
20498 | ||
20499 | maildir_quota_directory_regex = ^(?:cur|new|\..*)$ | |
20500 | ||
20501 | which includes the _cur_ and _new_ directories, and any maildir++ folders | |
20502 | (directories whose names begin with a dot). If you want to exclude the | |
20503 | _Trash_ | |
20504 | folder from the count (as some sites do), you need to change this setting to | |
20505 | ||
20506 | maildir_quota_directory_regex = ^(?:cur|new|\.(?!Trash).*)$ | |
20507 | ||
20508 | This uses a negative lookahead in the regular expression to exclude the | |
20509 | directory whose name is _.Trash_. | |
20510 | ||
20511 | ||
20512 | oindex:[%maildir_retries%] | |
20513 | `..'= | |
20514 | %maildir_retries%, Use: 'appendfile', Type: 'integer', Default: '10' | |
20515 | === | |
20516 | ||
20517 | This option specifies the number of times to retry when writing a file in | |
20518 | ``maildir'' format. See section <<SECTmaildirdelivery>> below. | |
20519 | ||
20520 | ||
20521 | oindex:[%maildir_tag%] | |
20522 | `..'= | |
20523 | %maildir_tag%, Use: 'appendfile', Type: 'string'!!, Default: 'unset' | |
20524 | === | |
20525 | ||
20526 | This option applies only to deliveries in maildir format, and is described in | |
20527 | section <<SECTmaildirdelivery>> below. | |
20528 | ||
20529 | ||
20530 | oindex:[%maildir_use_size_file%] | |
20531 | `..'= | |
20532 | %maildir_use_size_file%, Use: 'appendfile', Type: 'boolean', Default: 'false' | |
20533 | === | |
20534 | ||
20535 | cindex:[maildir format,_maildirsize_ file] | |
20536 | Setting this option true enables support for _maildirsize_ files. Exim | |
20537 | creates a _maildirsize_ file in a maildir if one does not exist, taking the | |
20538 | quota from the %quota% option of the transport. If %quota% is unset, the value | |
20539 | is zero. See section <<SECTmaildirdelivery>> below for further details. | |
20540 | ||
20541 | ||
20542 | oindex:[%mailstore_format%] | |
20543 | `..'= | |
20544 | %mailstore_format%, Use: 'appendfile', Type: 'boolean', Default: 'false' | |
20545 | === | |
20546 | ||
20547 | cindex:[mailstore format,specifying] | |
20548 | If this option is set with the %directory% option, the delivery is into two new | |
20549 | files in ``mailstore'' format. The option is available only if | |
20550 | SUPPORT_MAILSTORE is present in _Local/Makefile_. See section | |
20551 | <<SECTopdir>> below for further details. | |
20552 | ||
20553 | ||
20554 | oindex:[%mailstore_prefix%] | |
20555 | `..'= | |
20556 | %mailstore_prefix%, Use: 'appendfile', Type: 'string'!!, Default: 'unset' | |
20557 | === | |
20558 | ||
20559 | This option applies only to deliveries in mailstore format, and is described in | |
20560 | section <<SECTopdir>> below. | |
20561 | ||
20562 | ||
20563 | oindex:[%mailstore_suffix%] | |
20564 | `..'= | |
20565 | %mailstore_suffix%, Use: 'appendfile', Type: 'string'!!, Default: 'unset' | |
20566 | === | |
20567 | ||
20568 | This option applies only to deliveries in mailstore format, and is described in | |
20569 | section <<SECTopdir>> below. | |
20570 | ||
20571 | ||
20572 | oindex:[%mbx_format%] | |
20573 | `..'= | |
20574 | %mbx_format%, Use: 'appendfile', Type: 'boolean', Default: 'false' | |
20575 | === | |
20576 | ||
20577 | cindex:[locking files] | |
20578 | cindex:[file,locking] | |
20579 | cindex:[file,MBX format] | |
20580 | cindex:[MBX format, specifying] | |
20581 | This option is available only if Exim has been compiled with SUPPORT_MBX | |
20582 | set in _Local/Makefile_. If %mbx_format% is set with the %file% option, | |
20583 | the message is appended to the mailbox file in MBX format instead of | |
20584 | traditional Unix format. This format is supported by Pine4 and its associated | |
20585 | IMAP and POP daemons, by means of the 'c-client' library that they all use. | |
20586 | ||
20587 | *Note*: The %message_prefix% and %message_suffix% options are not | |
20588 | automatically changed by the use of %mbx_format%. They should normally be set | |
20589 | empty when using MBX format, so this option almost always appears in this | |
20590 | combination: | |
20591 | ||
20592 | mbx_format = true | |
20593 | message_prefix = | |
20594 | message_suffix = | |
20595 | ||
20596 | ||
20597 | If none of the locking options are mentioned in the configuration, | |
20598 | %use_mbx_lock% is assumed and the other locking options default to false. It | |
20599 | is possible to specify the other kinds of locking with %mbx_format%, but | |
20600 | %use_fcntl_lock% and %use_mbx_lock% are mutually exclusive. MBX locking | |
20601 | interworks with 'c-client', providing for shared access to the mailbox. It | |
20602 | should not be used if any program that does not use this form of locking is | |
20603 | going to access the mailbox, nor should it be used if the mailbox file is NFS | |
20604 | mounted, because it works only when the mailbox is accessed from a single host. | |
20605 | ||
20606 | If you set %use_fcntl_lock% with an MBX-format mailbox, you cannot use | |
20607 | the standard version of 'c-client', because as long as it has a mailbox open | |
20608 | (this means for the whole of a Pine or IMAP session), Exim will not be able to | |
20609 | append messages to it. | |
20610 | ||
20611 | ||
20612 | oindex:[%message_prefix%] | |
20613 | `..'= | |
20614 | %message_prefix%, Use: 'appendfile', Type: 'string'!!, Default: 'see below' | |
20615 | === | |
20616 | ||
20617 | cindex:[``From'' line] | |
20618 | The string specified here is expanded and output at the start of every message. | |
20619 | The default is unset unless %file% is specified and %use_bsmtp% is not set, in | |
20620 | which case it is: | |
20621 | ||
20622 | .... | |
20623 | message_prefix = "From ${if def:return_path{$return_path}\ | |
20624 | {MAILER-DAEMON}} $tod_bsdinbox\n" | |
20625 | .... | |
20626 | ||
20627 | ||
20628 | ||
20629 | oindex:[%message_suffix%] | |
20630 | `..'= | |
20631 | %message_suffix%, Use: 'appendfile', Type: 'string'!!, Default: 'see below' | |
20632 | === | |
20633 | ||
20634 | The string specified here is expanded and output at the end of every message. | |
20635 | The default is unset unless %file% is specified and %use_bsmtp% is not set, in | |
20636 | which case it is a single newline character. The suffix can be suppressed by | |
20637 | setting | |
20638 | ||
20639 | message_suffix = | |
20640 | ||
20641 | ||
20642 | ||
20643 | oindex:[%mode%] | |
20644 | `..'= | |
20645 | %mode%, Use: 'appendfile', Type: 'octal integer', Default: '0600' | |
20646 | === | |
20647 | ||
20648 | If the output file is created, it is given this mode. If it already exists and | |
20649 | has wider permissions, they are reduced to this mode. If it has narrower | |
20650 | permissions, an error occurs unless %mode_fail_narrower% is false. However, | |
20651 | if the delivery is the result of a %save% command in a filter file specifing a | |
20652 | particular mode, the mode of the output file is always forced to take that | |
20653 | value, and this option is ignored. | |
20654 | ||
20655 | ||
20656 | oindex:[%mode_fail_narrower%] | |
20657 | `..'= | |
20658 | %mode_fail_narrower%, Use: 'appendfile', Type: 'boolean', Default: 'true' | |
20659 | === | |
20660 | ||
20661 | This option applies in the case when an existing mailbox file has a narrower | |
20662 | mode than that specified by the %mode% option. If %mode_fail_narrower% is | |
20663 | true, the delivery is deferred (``mailbox has the wrong mode''); otherwise Exim | |
20664 | continues with the delivery attempt, using the existing mode of the file. | |
20665 | ||
20666 | ||
20667 | oindex:[%notify_comsat%] | |
20668 | `..'= | |
20669 | %notify_comsat%, Use: 'appendfile', Type: 'boolean', Default: 'false' | |
20670 | === | |
20671 | ||
20672 | If this option is true, the 'comsat' daemon is notified after every successful | |
20673 | delivery to a user mailbox. This is the daemon that notifies logged on users | |
20674 | about incoming mail. | |
20675 | ||
20676 | ||
20677 | oindex:[%quota%] | |
20678 | `..'= | |
20679 | %quota%, Use: 'appendfile', Type: 'string'!!, Default: 'unset' | |
20680 | === | |
20681 | ||
20682 | cindex:[quota,imposed by Exim] | |
20683 | This option imposes a limit on the size of the file to which Exim is appending, | |
20684 | or to the total space used in the directory tree when the %directory% option is | |
20685 | set. In the latter case, computation of the space used is expensive, because | |
20686 | all the files in the directory (and any sub-directories) have to be | |
20687 | individually inspected and their sizes summed. | |
20688 | (See %quota_size_regex% and %maildir_use_size_file% for ways to avoid this | |
20689 | in environments where users have no shell access to their mailboxes). | |
20690 | ||
20691 | As there is no interlock against two simultaneous deliveries into a | |
20692 | multi-file mailbox, it is possible for the quota to be overrun in this case. | |
20693 | For single-file mailboxes, of course, an interlock is a necessity. | |
20694 | ||
20695 | A file's size is taken as its 'used' value. Because of blocking effects, this | |
20696 | may be a lot less than the actual amount of disk space allocated to the file. | |
20697 | If the sizes of a number of files are being added up, the rounding effect can | |
20698 | become quite noticeable, especially on systems that have large block sizes. | |
20699 | Nevertheless, it seems best to stick to the 'used' figure, because this is | |
20700 | the obvious value which users understand most easily. | |
20701 | ||
068aaea8 | 20702 | [revisionflag="changed"] |
168e428f | 20703 | The value of the option is expanded, and must then be a numerical value |
068aaea8 PH |
20704 | (decimal point allowed), optionally followed by one of the letters K, M, or G, |
20705 | for kilobytes, megabytes, or gigabytes. If Exim is running on a system with | |
20706 | large file support (Linux and FreeBSD have this), mailboxes larger than 2G can | |
20707 | be handled. | |
168e428f PH |
20708 | |
20709 | *Note*: A value of zero is interpreted as ``no quota''. | |
20710 | ||
068aaea8 PH |
20711 | The expansion happens while Exim is running as root, before it changes uid for |
20712 | the delivery. This means that files that are inaccessible to the end user can | |
20713 | be used to hold quota values that are looked up in the expansion. When delivery | |
20714 | fails because this quota is exceeded, the handling of the error is as for | |
20715 | system quota failures. | |
20716 | ||
168e428f PH |
20717 | By default, Exim's quota checking mimics system quotas, and restricts the |
20718 | mailbox to the specified maximum size, though the value is not accurate to the | |
20719 | last byte, owing to separator lines and additional headers that may get added | |
20720 | during message delivery. When a mailbox is nearly full, large messages may get | |
20721 | refused even though small ones are accepted, because the size of the current | |
20722 | message is added to the quota when the check is made. This behaviour can be | |
20723 | changed by setting %quota_is_inclusive% false. When this is done, the check | |
20724 | for exceeding the quota does not include the current message. Thus, deliveries | |
20725 | continue until the quota has been exceeded; thereafter, no further messages are | |
20726 | delivered. See also %quota_warn_threshold%. | |
20727 | ||
20728 | ||
20729 | oindex:[%quota_directory%] | |
20730 | `..'= | |
20731 | %quota_directory%, Use: 'appendfile', Type: 'string'!!, Default: 'unset' | |
20732 | === | |
20733 | ||
20734 | This option defines the directory to check for quota purposes when delivering | |
20735 | into individual files. The default is the delivery directory, or, if a file | |
20736 | called _maildirfolder_ exists in a maildir directory, the parent of the | |
20737 | delivery directory. | |
20738 | ||
20739 | ||
20740 | oindex:[%quota_filecount%] | |
20741 | `..'= | |
20742 | %quota_filecount%, Use: 'appendfile', Type: 'string'!!, Default: '0' | |
20743 | === | |
20744 | ||
20745 | This option applies when the %directory% option is set. It limits the total | |
20746 | number of files in the directory (compare the inode limit in system quotas). It | |
20747 | can only be used if %quota% is also set. The value is expanded; an expansion | |
20748 | failure causes delivery to be deferred. | |
20749 | ||
20750 | ||
20751 | oindex:[%quota_is_inclusive%] | |
20752 | `..'= | |
20753 | %quota_is_inclusive%, Use: 'appendfile', Type: 'boolean', Default: 'true' | |
20754 | === | |
20755 | ||
20756 | See %quota% above. | |
20757 | ||
20758 | ||
20759 | oindex:[%quota_size_regex%] | |
20760 | `..'= | |
20761 | %quota_size_regex%, Use: 'appendfile', Type: 'string', Default: 'unset' | |
20762 | === | |
20763 | ||
20764 | This option applies when one of the delivery modes that writes a separate file | |
20765 | for each message is being used. When Exim wants to find the size of one of | |
20766 | these files in order to test the quota, it first checks %quota_size_regex%. | |
20767 | If this is set to a regular expression that matches the file name, and it | |
20768 | captures one string, that string is interpreted as a representation of the | |
20769 | file's size. The value of %quota_size_regex% is not expanded. | |
20770 | ||
20771 | This feature is useful only when users have no shell access to their mailboxes | |
20772 | -- otherwise they could defeat the quota simply by renaming the files. This | |
20773 | facility can be used with maildir deliveries, by setting %maildir_tag% to add | |
20774 | the file length to the file name. For example: | |
20775 | ||
20776 | maildir_tag = ,S=$message_size | |
20777 | quota_size_regex = ,S=(\d+) | |
20778 | ||
068aaea8 PH |
20779 | [revisionflag="changed"] |
20780 | An alternative to $message_size$ is $message_linecount$, which contains the | |
20781 | number of lines in the message. | |
20782 | ||
168e428f PH |
20783 | The regular expression should not assume that the length is at the end of the |
20784 | file name (even though %maildir_tag% puts it there) because maildir MUAs | |
20785 | sometimes add other information onto the ends of message file names. | |
20786 | ||
20787 | ||
068aaea8 | 20788 | |
168e428f PH |
20789 | oindex:[%quota_warn_message%] |
20790 | `..'= | |
20791 | %quota_warn_message%, Use: 'appendfile', Type: 'string'!!, Default: 'see below' | |
20792 | === | |
20793 | ||
20794 | See below for the use of this option. If it is not set when | |
20795 | %quota_warn_threshold% is set, it defaults to | |
20796 | ||
20797 | .... | |
20798 | quota_warn_message = "\ | |
20799 | To: $local_part@$domain\n\ | |
20800 | Subject: Your mailbox\n\n\ | |
20801 | This message is automatically created \ | |
20802 | by mail delivery software.\n\n\ | |
20803 | The size of your mailbox has exceeded \ | |
20804 | a warning threshold that is\n\ | |
20805 | set by the system administrator.\n" | |
20806 | .... | |
20807 | ||
20808 | ||
20809 | ||
20810 | oindex:[%quota_warn_threshold%] | |
20811 | `..'= | |
20812 | %quota_warn_threshold%, Use: 'appendfile', Type: 'string'!!, Default: '0' | |
20813 | === | |
20814 | ||
20815 | cindex:[quota,warning threshold] | |
20816 | cindex:[mailbox,size warning] | |
20817 | cindex:[size,of mailbox] | |
20818 | This option is expanded in the same way as %quota% (see above). If the | |
20819 | resulting value is greater than zero, and delivery of the message causes the | |
20820 | size of the file or total space in the directory tree to cross the given | |
20821 | threshold, a warning message is sent. If %quota% is also set, the threshold may | |
20822 | be specified as a percentage of it by following the value with a percent sign. | |
20823 | For example: | |
20824 | ||
20825 | quota = 10M | |
20826 | quota_warn_threshold = 75% | |
20827 | ||
20828 | If %quota% is not set, a setting of %quota_warn_threshold% that ends with a | |
20829 | percent sign is ignored. | |
20830 | ||
068aaea8 | 20831 | [revisionflag="changed"] |
168e428f | 20832 | The warning message itself is specified by the %quota_warn_message% option, |
068aaea8 PH |
20833 | and it must start with a 'To:' header line containing the recipient(s) of the |
20834 | warning message. These do not necessarily have to include the recipient(s) of | |
20835 | the original message. A 'Subject:' line should also normally be supplied. You | |
20836 | can include any other header lines that you want. | |
20837 | ||
20838 | The %quota% option does not have to be set in order to use this option; they | |
20839 | are independent of one another except when the threshold is specified as a | |
20840 | percentage. | |
168e428f PH |
20841 | |
20842 | ||
20843 | oindex:[%use_bsmtp%] | |
20844 | `..'= | |
20845 | %use_bsmtp%, Use: 'appendfile', Type: 'boolean', Default: 'false' | |
20846 | === | |
20847 | ||
20848 | cindex:[envelope sender] | |
20849 | If this option is set true, ^appendfile^ writes messages in ``batch SMTP'' | |
20850 | format, with the envelope sender and recipient(s) included as SMTP commands. If | |
20851 | you want to include a leading HELO command with such messages, you can do | |
20852 | so by setting the %message_prefix% option. See section <<SECTbatchSMTP>> for | |
20853 | details of batch SMTP. | |
20854 | ||
20855 | ||
20856 | oindex:[%use_crlf%] | |
20857 | `..'= | |
20858 | %use_crlf%, Use: 'appendfile', Type: 'boolean', Default: 'false' | |
20859 | === | |
20860 | ||
20861 | cindex:[carriage return] | |
20862 | cindex:[linefeed] | |
20863 | This option causes lines to be terminated with the two-character CRLF sequence | |
20864 | (carriage return, linefeed) instead of just a linefeed character. In the case | |
20865 | of batched SMTP, the byte sequence written to the file is then an exact image | |
20866 | of what would be sent down a real SMTP connection. | |
20867 | ||
20868 | The contents of the %message_prefix% and %message_suffix% options are written | |
20869 | verbatim, so must contain their own carriage return characters if these are | |
20870 | needed. In cases where these options have non-empty defaults, the values end | |
20871 | with a single linefeed, so they | |
20872 | must | |
20873 | be changed to end with `\r\n` if %use_crlf% is set. | |
20874 | ||
20875 | ||
20876 | oindex:[%use_fcntl_lock%] | |
20877 | `..'= | |
20878 | %use_fcntl_lock%, Use: 'appendfile', Type: 'boolean', Default: 'see below' | |
20879 | === | |
20880 | ||
20881 | This option controls the use of the 'fcntl()' function to lock a file for | |
20882 | exclusive use when a message is being appended. It is set by default unless | |
20883 | %use_flock_lock% is set. Otherwise, it should be turned off only if you know | |
20884 | that all your MUAs use lock file locking. When both %use_fcntl_lock% and | |
20885 | %use_flock_lock% are unset, %use_lockfile% must be set. | |
20886 | ||
20887 | ||
20888 | oindex:[%use_flock_lock%] | |
20889 | `..'= | |
20890 | %use_flock_lock%, Use: 'appendfile', Type: 'boolean', Default: 'false' | |
20891 | === | |
20892 | ||
20893 | This option is provided to support the use of 'flock()' for file locking, for | |
20894 | the few situations where it is needed. Most modern operating systems support | |
20895 | 'fcntl()' and 'lockf()' locking, and these two functions interwork with | |
20896 | each other. Exim uses 'fcntl()' locking by default. | |
20897 | ||
20898 | This option is required only if you are using an operating system where | |
20899 | 'flock()' is used by programs that access mailboxes (typically MUAs), and | |
20900 | where 'flock()' does not correctly interwork with 'fcntl()'. You can use | |
20901 | both 'fcntl()' and 'flock()' locking simultaneously if you want. | |
20902 | ||
20903 | cindex:[Solaris,'flock()' support] | |
20904 | Not all operating systems provide 'flock()'. Some versions of Solaris do not | |
20905 | have it (and some, I think, provide a not quite right version built on top of | |
20906 | 'lockf()'). If the OS does not have 'flock()', Exim will be built without | |
20907 | the ability to use it, and any attempt to do so will cause a configuration | |
20908 | error. | |
20909 | ||
20910 | *Warning*: 'flock()' locks do not work on NFS files (unless 'flock()' | |
20911 | is just being mapped onto 'fcntl()' by the OS). | |
20912 | ||
20913 | ||
20914 | oindex:[%use_lockfile%] | |
20915 | `..'= | |
20916 | %use_lockfile%, Use: 'appendfile', Type: 'boolean', Default: 'see below' | |
20917 | === | |
20918 | ||
20919 | If this option is turned off, Exim does not attempt to create a lock file when | |
20920 | appending to a mailbox file. In this situation, the only locking is by | |
20921 | 'fcntl()'. You should only turn %use_lockfile% off if you are absolutely | |
20922 | sure that every MUA that is ever going to look at your users' mailboxes uses | |
20923 | 'fcntl()' rather than a lock file, and even then only when you are not | |
20924 | delivering over NFS from more than one host. | |
20925 | ||
20926 | cindex:[NFS,lock file] | |
20927 | In order to append to an NFS file safely from more than one host, it is | |
20928 | necessary to take out a lock 'before' opening the file, and the lock file | |
20929 | achieves this. Otherwise, even with 'fcntl()' locking, there is a risk of | |
20930 | file corruption. | |
20931 | ||
20932 | The %use_lockfile% option is set by default unless %use_mbx_lock% is set. It | |
20933 | is not possible to turn both %use_lockfile% and %use_fcntl_lock% off, except | |
20934 | when %mbx_format% is set. | |
20935 | ||
20936 | ||
20937 | oindex:[%use_mbx_lock%] | |
20938 | `..'= | |
20939 | %use_mbx_lock%, Use: 'appendfile', Type: 'boolean', Default: 'see below' | |
20940 | === | |
20941 | ||
20942 | This option is available only if Exim has been compiled with SUPPORT_MBX | |
20943 | set in _Local/Makefile_. Setting the option specifies that special MBX | |
20944 | locking rules be used. It is set by default if %mbx_format% is set and none of | |
20945 | the locking options are mentioned in the configuration. The locking rules are | |
20946 | the same as are used by the 'c-client' library that underlies Pine and the | |
20947 | IMAP4 and POP daemons that come with it (see the discussion below). The rules | |
20948 | allow for shared access to the mailbox. However, this kind of locking does not | |
20949 | work when the mailbox is NFS mounted. | |
20950 | ||
20951 | You can set %use_mbx_lock% with either (or both) of %use_fcntl_lock% and | |
20952 | %use_flock_lock% to control what kind of locking is used in implementing the | |
20953 | MBX locking rules. The default is to use 'fcntl()' if %use_mbx_lock% is set | |
20954 | without %use_fcntl_lock% or %use_flock_lock%. | |
20955 | ||
20956 | ||
20957 | ||
20958 | ||
20959 | [[SECTopappend]] | |
20960 | Operational details for appending | |
20961 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
20962 | cindex:[appending to a file] | |
20963 | cindex:[file,appending] | |
20964 | Before appending to a file, the following preparations are made: | |
20965 | ||
20966 | - If the name of the file is _/dev/null_, no action is taken, and a success | |
20967 | return is given. | |
20968 | ||
20969 | - cindex:[directory creation] | |
20970 | If any directories on the file's path are missing, Exim creates them if the | |
20971 | %create_directory% option is set. A created directory's mode is given by the | |
20972 | %directory_mode% option. | |
20973 | ||
20974 | - If %file_format% is set, the format of an existing file is checked. If this | |
20975 | indicates that a different transport should be used, control is passed to that | |
20976 | transport. | |
20977 | ||
20978 | - cindex:[file,locking] | |
20979 | cindex:[locking files] | |
20980 | cindex:[NFS,lock file] | |
20981 | If %use_lockfile% is set, a lock file is built in a way that will work | |
20982 | reliably over NFS, as follows: | |
20983 | + | |
20984 | -- | |
20985 | . Create a ``hitching post'' file whose name is that of the lock file with the | |
20986 | current time, primary host name, and process id added, by opening for writing | |
20987 | as a new file. If this fails with an access error, delivery is deferred. | |
20988 | ||
20989 | . Close the hitching post file, and hard link it to the lock file name. | |
20990 | ||
20991 | . If the call to 'link()' succeeds, creation of the lock file has succeeded. | |
20992 | Unlink the hitching post name. | |
20993 | ||
20994 | . Otherwise, use 'stat()' to get information about the hitching post file, and | |
20995 | then unlink hitching post name. If the number of links is exactly two, creation | |
20996 | of the lock file succeeded but something (for example, an NFS server crash and | |
20997 | restart) caused this fact not to be communicated to the 'link()' call. | |
20998 | ||
20999 | . If creation of the lock file failed, wait for %lock_interval% and try again, | |
21000 | up to %lock_retries% times. However, since any program that writes to a | |
21001 | mailbox should complete its task very quickly, it is reasonable to time out old | |
21002 | lock files that are normally the result of user agent and system crashes. If an | |
21003 | existing lock file is older than %lockfile_timeout% Exim attempts to unlink it | |
21004 | before trying again. | |
21005 | -- | |
21006 | + | |
21007 | - A call is made to 'lstat()' to discover whether the main file exists, and if | |
21008 | so, what its characteristics are. If 'lstat()' fails for any reason other | |
21009 | than non-existence, delivery is deferred. | |
21010 | ||
21011 | - cindex:[symbolic link,to mailbox] | |
21012 | cindex:[mailbox,symbolic link] | |
21013 | If the file does exist and is a symbolic link, delivery is deferred, unless the | |
21014 | %allow_symlink% option is set, in which case the ownership of the link is | |
21015 | checked, and then 'stat()' is called to find out about the real file, which | |
21016 | is then subjected to the checks below. The check on the top-level link | |
21017 | ownership prevents one user creating a link for another's mailbox in a sticky | |
21018 | directory, though allowing symbolic links in this case is definitely not a good | |
21019 | idea. If there is a chain of symbolic links, the intermediate ones are not | |
21020 | checked. | |
21021 | ||
21022 | - If the file already exists but is not a regular file, or if the file's owner | |
21023 | and group (if the group is being checked -- see %check_group% above) are | |
21024 | different from the user and group under which the delivery is running, | |
21025 | delivery is deferred. | |
21026 | ||
21027 | - If the file's permissions are more generous than specified, they are reduced. | |
21028 | If they are insufficient, delivery is deferred, unless %mode_fail_narrower% | |
21029 | is set false, in which case the delivery is tried using the existing | |
21030 | permissions. | |
21031 | ||
21032 | - The file's inode number is saved, and the file is then opened for appending. | |
21033 | If this fails because the file has vanished, ^appendfile^ behaves as if it | |
21034 | hadn't existed (see below). For any other failures, delivery is deferred. | |
21035 | ||
21036 | - If the file is opened successfully, check that the inode number hasn't | |
21037 | changed, that it is still a regular file, and that the owner and permissions | |
21038 | have not changed. If anything is wrong, defer delivery and freeze the message. | |
21039 | ||
21040 | - If the file did not exist originally, defer delivery if the %file_must_exist% | |
21041 | option is set. Otherwise, check that the file is being created in a permitted | |
21042 | directory if the %create_file% option is set (deferring on failure), and then | |
21043 | open for writing as a new file, with the O_EXCL and O_CREAT options, | |
21044 | except when dealing with a symbolic link (the %allow_symlink% option must be | |
21045 | set). In this case, which can happen if the link points to a non-existent file, | |
21046 | the file is opened for writing using O_CREAT but not O_EXCL, because | |
21047 | that prevents link following. | |
21048 | ||
21049 | - cindex:[loop,while file testing] | |
21050 | If opening fails because the file exists, obey the tests given above for | |
21051 | existing files. However, to avoid looping in a situation where the file is | |
21052 | being continuously created and destroyed, the exists/not-exists loop is broken | |
21053 | after 10 repetitions, and the message is then frozen. | |
21054 | ||
21055 | - If opening fails with any other error, defer delivery. | |
21056 | ||
21057 | - cindex:[file,locking] | |
21058 | cindex:[locking files] | |
21059 | Once the file is open, unless both %use_fcntl_lock% and %use_flock_lock% | |
21060 | are false, it is locked using 'fcntl()' or 'flock()' or both. If | |
21061 | %use_mbx_lock% is false, an exclusive lock is requested in each case. | |
21062 | However, if %use_mbx_lock% is true, | |
21063 | Exim takes out a shared lock on the open file, | |
21064 | and an exclusive lock on the file whose name is | |
21065 | ||
21066 | /tmp/.<device-number>.<inode-number> | |
21067 | + | |
21068 | using the device and inode numbers of the open mailbox file, in accordance with | |
21069 | the MBX locking rules. | |
21070 | + | |
21071 | If Exim fails to lock the file, there are two possible courses of action, | |
21072 | depending on the value of the locking timeout. This is obtained from | |
21073 | %lock_fcntl_timeout% or %lock_flock_timeout%, as appropriate. | |
21074 | + | |
21075 | If the timeout value is zero, the file is closed, Exim waits for | |
21076 | %lock_interval%, and then goes back and re-opens the file as above and tries | |
21077 | to lock it again. This happens up to %lock_retries% times, after which the | |
21078 | delivery is deferred. | |
21079 | + | |
21080 | If the timeout has a value greater than zero, blocking calls to 'fcntl()' or | |
21081 | 'flock()' are used (with the given timeout), so there has already been some | |
21082 | waiting involved by the time locking fails. Nevertheless, Exim does not give up | |
21083 | immediately. It retries up to | |
21084 | ||
21085 | (lock_retries * lock_interval) / <timeout> | |
21086 | + | |
21087 | times (rounded up). | |
21088 | ||
21089 | ||
21090 | At the end of delivery, Exim closes the file (which releases the 'fcntl()' | |
21091 | and/or 'flock()' locks) and then deletes the lock file if one was created. | |
21092 | ||
21093 | ||
21094 | [[SECTopdir]] | |
21095 | Operational details for delivery to a new file | |
21096 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
21097 | cindex:[delivery,to single file] | |
21098 | cindex:[``From'' line] | |
21099 | When the %directory% option is set instead of %file%, each message is delivered | |
21100 | into a newly-created file or set of files. When ^appendfile^ is activated | |
21101 | directly from a ^redirect^ router, neither %file% nor %directory% is normally | |
21102 | set, because the path for delivery is supplied by the router. (See for example, | |
21103 | the ^address_file^ transport in the default configuration.) In this case, | |
21104 | delivery is to a new file if either the path name ends in `/`, or the | |
21105 | %maildir_format% or %mailstore_format% option is set. | |
21106 | ||
21107 | No locking is required while writing the message to a new file, so the various | |
21108 | locking options of the transport are ignored. The ``From'' line that by default | |
21109 | separates messages in a single file is not normally needed, nor is the escaping | |
21110 | of message lines that start with ``From'', and there is no need to ensure a | |
21111 | newline at the end of each message. Consequently, the default values for | |
21112 | %check_string%, %message_prefix%, and %message_suffix% are all unset when | |
21113 | any of %directory%, %maildir_format%, or %mailstore_format% is set. | |
21114 | ||
21115 | If Exim is required to check a %quota% setting, it adds up the sizes of all the | |
21116 | files in the delivery directory by default. However, you can specify a | |
21117 | different directory by setting %quota_directory%. Also, for maildir deliveries | |
21118 | (see below) the _maildirfolder_ convention is honoured. | |
21119 | ||
21120 | ||
21121 | cindex:[maildir format] | |
21122 | cindex:[mailstore format] | |
21123 | There are three different ways in which delivery to individual files can be | |
21124 | done, controlled by the settings of the %maildir_format% and | |
21125 | %mailstore_format% options. Note that code to support maildir or mailstore | |
21126 | formats is not included in the binary unless SUPPORT_MAILDIR or | |
21127 | SUPPORT_MAILSTORE, respectively, is set in _Local/Makefile_. | |
21128 | ||
21129 | cindex:[directory creation] | |
21130 | In all three cases an attempt is made to create the directory and any necessary | |
21131 | sub-directories if they do not exist, provided that the %create_directory% | |
21132 | option is set (the default). The location of a created directory can be | |
21133 | constrained by setting %create_file%. A created directory's mode is given by | |
21134 | the %directory_mode% option. If creation fails, or if the %create_directory% | |
21135 | option is not set when creation is required, delivery is deferred. | |
21136 | ||
21137 | ||
21138 | ||
21139 | [[SECTmaildirdelivery]] | |
21140 | Maildir delivery | |
21141 | ~~~~~~~~~~~~~~~~ | |
21142 | cindex:[maildir format,description of] | |
21143 | If the %maildir_format% option is true, Exim delivers each message by writing | |
21144 | it to a file whose name is _tmp/<stime>.H<mtime>P<pid>.<host>_ in the | |
21145 | given directory. If the delivery is successful, the file is renamed into the | |
21146 | _new_ subdirectory. | |
21147 | ||
21148 | In the file name, <'stime'> is the current time of day in seconds, and | |
21149 | <'mtime'> is the microsecond fraction of the time. After a maildir delivery, | |
21150 | Exim checks that the time-of-day clock has moved on by at least one microsecond | |
21151 | before terminating the delivery process. This guarantees uniqueness for the | |
21152 | file name. However, as a precaution, Exim calls 'stat()' for the file before | |
21153 | opening it. If any response other than ENOENT (does not exist) is given, | |
21154 | Exim waits 2 seconds and tries again, up to %maildir_retries% times. | |
21155 | ||
21156 | cindex:[quota,in maildir delivery] | |
21157 | cindex:[maildir++] | |
21158 | If Exim is required to check a %quota% setting before a maildir delivery, and | |
21159 | %quota_directory% is not set, it looks for a file called _maildirfolder_ in | |
21160 | the maildir directory (alongside _new_, _cur_, _tmp_). If this exists, | |
21161 | Exim assumes the directory is a maildir++ folder directory, which is one level | |
21162 | down from the user's top level mailbox directory. This causes it to start at | |
21163 | the parent directory instead of the current directory when calculating the | |
21164 | amount of space used. | |
21165 | ||
21166 | One problem with delivering into a multi-file mailbox is that it is | |
21167 | computationally expensive to compute the size of the mailbox for quota | |
21168 | checking. Various approaches have been taken to reduce the amount of work | |
21169 | needed. The next two sections describe two of them. A third alternative is to | |
21170 | use some external process for maintaining the size data, and use the expansion | |
21171 | of the %mailbox_size% option as a way of importing it into Exim. | |
21172 | ||
21173 | ||
21174 | ||
21175 | ||
21176 | Using tags to record message sizes | |
21177 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
21178 | If %maildir_tag% is set, the string is expanded for each delivery. | |
21179 | When the maildir file is renamed into the _new_ sub-directory, the | |
21180 | tag is added to its name. However, if adding the tag takes the length of the | |
21181 | name to the point where the test 'stat()' call fails with ENAMETOOLONG, | |
21182 | the tag is dropped and the maildir file is created with no tag. | |
21183 | ||
068aaea8 | 21184 | cindex:[$message_size$] |
168e428f | 21185 | Tags can be used to encode the size of files in their names; see |
068aaea8 PH |
21186 | %quota_size_regex% above for an example. The expansion of %maildir_tag% happens |
21187 | after the message has been written. The value of the $message_size$ variable is | |
21188 | set to the number of bytes actually written. If the expansion is forced to | |
21189 | fail, the tag is ignored, but a non-forced failure causes delivery to be | |
21190 | deferred. The expanded tag may contain any printing characters except ``/''. | |
168e428f PH |
21191 | Non-printing characters in the string are ignored; if the resulting string is |
21192 | empty, it is ignored. If it starts with an alphanumeric character, a leading | |
21193 | colon is inserted. | |
21194 | ||
21195 | ||
21196 | ||
21197 | Using a maildirsize file | |
21198 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
21199 | cindex:[quota,in maildir delivery] | |
21200 | cindex:[maildir format,_maildirsize_ file] | |
21201 | If %maildir_use_size_file% is true, Exim implements the maildir++ rules for | |
21202 | storing quota and message size information in a file called _maildirsize_ | |
21203 | within the maildir directory. If this file does not exist, Exim creates it, | |
21204 | setting the quota from the %quota% option of the transport. If the maildir | |
21205 | directory itself does not exist, it is created before any attempt to write a | |
21206 | _maildirsize_ file. | |
21207 | ||
21208 | The _maildirsize_ file is used to hold information about the sizes of | |
21209 | messages in the maildir, thus speeding up quota calculations. The quota value | |
21210 | in the file is just a cache; if the quota is changed in the transport, the new | |
21211 | value overrides the cached value when the next message is delivered. The cache | |
21212 | is maintained for the benefit of other programs that access the maildir and | |
21213 | need to know the quota. | |
21214 | ||
21215 | If the %quota% option in the transport is unset or zero, the _maildirsize_ | |
21216 | file is maintained (with a zero quota setting), but no quota is imposed. | |
21217 | ||
21218 | A regular expression is available for controlling which directories in the | |
21219 | maildir participate in quota calculations. See the description of the | |
21220 | %maildir_quota_directory_regex% option above for details. | |
21221 | ||
21222 | ||
21223 | ||
21224 | Mailstore delivery | |
21225 | ~~~~~~~~~~~~~~~~~~ | |
21226 | cindex:[mailstore format,description of] | |
21227 | If the %mailstore_format% option is true, each message is written as two files | |
21228 | in the given directory. A unique base name is constructed from the message id | |
21229 | and the current delivery process, and the files that are written use this base | |
21230 | name plus the suffixes _.env_ and _.msg_. The _.env_ file contains the | |
068aaea8 PH |
21231 | message's envelope, and the _.msg_ file contains the message itself. The base |
21232 | name is placed in the variable $mailstore_basename$. | |
168e428f PH |
21233 | |
21234 | During delivery, the envelope is first written to a file with the suffix | |
21235 | _.tmp_. The _.msg_ file is then written, and when it is complete, the | |
21236 | _.tmp_ file is renamed as the _.env_ file. Programs that access messages in | |
21237 | mailstore format should wait for the presence of both a _.msg_ and a _.env_ | |
21238 | file before accessing either of them. An alternative approach is to wait for | |
21239 | the absence of a _.tmp_ file. | |
21240 | ||
21241 | The envelope file starts with any text defined by the %mailstore_prefix% | |
21242 | option, expanded and terminated by a newline if there isn't one. Then follows | |
21243 | the sender address on one line, then all the recipient addresses, one per line. | |
21244 | There can be more than one recipient only if the %batch_max% option is set | |
21245 | greater than one. Finally, %mailstore_suffix% is expanded and the result | |
21246 | appended to the file, followed by a newline if it does not end with one. | |
21247 | ||
068aaea8 | 21248 | [revisionflag="changed"] |
168e428f PH |
21249 | If expansion of %mailstore_prefix% or %mailstore_suffix% ends with a forced |
21250 | failure, it is ignored. Other expansion errors are treated as serious | |
068aaea8 PH |
21251 | configuration errors, and delivery is deferred. The variable |
21252 | $mailstore_basename$ is available for use during these expansions. | |
168e428f PH |
21253 | |
21254 | ||
21255 | ||
21256 | Non-special new file delivery | |
21257 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
21258 | If neither %maildir_format% nor %mailstore_format% is set, a single new file | |
21259 | is created directly in the named directory. For example, when delivering | |
21260 | messages into files in batched SMTP format for later delivery to some host (see | |
21261 | section <<SECTbatchSMTP>>), a setting such as | |
21262 | ||
21263 | directory = /var/bsmtp/$host | |
21264 | ||
21265 | might be used. A message is written to a file with a temporary name, which is | |
21266 | then renamed when the delivery is complete. The final name is obtained by | |
21267 | expanding the contents of the %directory_file% option. | |
21268 | ||
21269 | ||
21270 | ||
21271 | ||
21272 | ||
21273 | ||
21274 | //////////////////////////////////////////////////////////////////////////// | |
21275 | //////////////////////////////////////////////////////////////////////////// | |
21276 | ||
21277 | The autoreply transport | |
21278 | ----------------------- | |
21279 | cindex:[transports,^autoreply^] | |
21280 | cindex:[^autoreply^ transport] | |
21281 | The ^autoreply^ transport is not a true transport in that it does not cause | |
21282 | the message to be transmitted. Instead, it generates a new mail message. | |
21283 | ||
21284 | If the router that passes the message to this transport does not have the | |
21285 | %unseen% option set, the original message (for the current recipient) is not | |
21286 | delivered anywhere. However, when the %unseen% option is set on the router that | |
21287 | passes the message to this transport, routing of the address continues, so | |
21288 | another router can set up a normal message delivery. | |
21289 | ||
21290 | ||
21291 | The ^autoreply^ transport is usually run as the result of mail filtering, a | |
21292 | ``vacation'' message being the standard example. However, it can also be run | |
21293 | directly from a router like any other transport. To reduce the possibility of | |
21294 | message cascades, messages created by the ^autoreply^ transport always have | |
21295 | empty envelope sender addresses, like bounce messages. | |
21296 | ||
21297 | The parameters of the message to be sent can be specified in the configuration | |
21298 | by options described below. However, these are used only when the address | |
21299 | passed to the transport does not contain its own reply information. When the | |
21300 | transport is run as a consequence of a | |
21301 | %mail% | |
21302 | or %vacation% command in a filter file, the parameters of the message are | |
21303 | supplied by the filter, and passed with the address. The transport's options | |
21304 | that define the message are then ignored (so they are not usually set in this | |
21305 | case). The message is specified entirely by the filter or by the transport; it | |
21306 | is never built from a mixture of options. However, the %file_optional%, | |
21307 | %mode%, and %return_message% options apply in all cases. | |
21308 | ||
21309 | ^Autoreply^ is implemented as a local transport. When used as a result of a | |
21310 | command in a user's filter file, ^autoreply^ normally runs under the uid and | |
21311 | gid of the user, and with appropriate current and home directories (see chapter | |
21312 | <<CHAPenvironment>>). | |
21313 | ||
21314 | There is a subtle difference between routing a message to a ^pipe^ transport | |
21315 | that generates some text to be returned to the sender, and routing it to an | |
21316 | ^autoreply^ transport. This difference is noticeable only if more than one | |
21317 | address from the same message is so handled. In the case of a pipe, the | |
21318 | separate outputs from the different addresses are gathered up and returned to | |
21319 | the sender in a single message, whereas if ^autoreply^ is used, a separate | |
21320 | message is generated for each address that is passed to it. | |
21321 | ||
21322 | Non-printing characters are not permitted in the header lines generated for the | |
21323 | message that ^autoreply^ creates, with the exception of newlines that are | |
068aaea8 | 21324 | immediately followed by white space. If any non-printing characters are found, |
168e428f PH |
21325 | the transport defers. |
21326 | Whether characters with the top bit set count as printing characters or not is | |
21327 | controlled by the %print_topbitchars% global option. | |
21328 | ||
21329 | If any of the generic options for manipulating headers (for example, | |
21330 | %headers_add%) are set on an ^autoreply^ transport, they apply to the copy of | |
21331 | the original message that is included in the generated message when | |
21332 | %return_message% is set. They do not apply to the generated message itself. | |
21333 | ||
068aaea8 | 21334 | cindex:[$sender_address$] |
168e428f PH |
21335 | If the ^autoreply^ transport receives return code 2 from Exim when it submits |
21336 | the message, indicating that there were no recipients, it does not treat this | |
21337 | as an error. This means that autoreplies sent to $sender_address$ when this | |
21338 | is empty (because the incoming message is a bounce message) do not cause | |
21339 | problems. They are just discarded. | |
21340 | ||
21341 | ||
21342 | ||
21343 | Private options for autoreply | |
21344 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
21345 | cindex:[options,^autoreply^ transport] | |
21346 | ||
21347 | oindex:[%bcc%] | |
21348 | `..'= | |
21349 | %bcc%, Use: 'autoreply', Type: 'string'!!, Default: 'unset' | |
21350 | === | |
21351 | ||
21352 | This specifies the addresses that are to receive ``blind carbon copies'' of the | |
21353 | message when the message is specified by the transport. | |
21354 | ||
21355 | ||
21356 | oindex:[%cc%] | |
21357 | `..'= | |
21358 | %cc%, Use: 'autoreply', Type: 'string'!!, Default: 'unset' | |
21359 | === | |
21360 | ||
21361 | This specifies recipients of the message and the contents of the 'Cc:' header | |
21362 | when the message is specified by the transport. | |
21363 | ||
21364 | ||
21365 | oindex:[%file%] | |
21366 | `..'= | |
21367 | %file%, Use: 'autoreply', Type: 'string'!!, Default: 'unset' | |
21368 | === | |
21369 | ||
21370 | The contents of the file are sent as the body of the message when the message | |
21371 | is specified by the transport. If both %file% and %text% are set, the text | |
21372 | string comes first. | |
21373 | ||
21374 | ||
21375 | oindex:[%file_expand%] | |
21376 | `..'= | |
21377 | %file_expand%, Use: 'autoreply', Type: 'boolean', Default: 'false' | |
21378 | === | |
21379 | ||
21380 | If this is set, the contents of the file named by the %file% option are | |
21381 | subjected to string expansion as they are added to the message. | |
21382 | ||
21383 | ||
21384 | oindex:[%file_optional%] | |
21385 | `..'= | |
21386 | %file_optional%, Use: 'autoreply', Type: 'boolean', Default: 'false' | |
21387 | === | |
21388 | ||
21389 | If this option is true, no error is generated if the file named by the %file% | |
21390 | option or passed with the address does not exist or cannot be read. | |
21391 | ||
21392 | ||
21393 | oindex:[%from%] | |
21394 | `..'= | |
21395 | %from%, Use: 'autoreply', Type: 'string'!!, Default: 'unset' | |
21396 | === | |
21397 | ||
21398 | This specifies the contents of the 'From:' header when the message is specified | |
21399 | by the transport. | |
21400 | ||
21401 | ||
21402 | oindex:[%headers%] | |
21403 | `..'= | |
21404 | %headers%, Use: 'autoreply', Type: 'string'!!, Default: 'unset' | |
21405 | === | |
21406 | ||
21407 | This specifies additional RFC 2822 headers that are to be added to the message when | |
21408 | the message is specified by the transport. Several can be given by using ``\n'' | |
21409 | to separate them. There is no check on the format. | |
21410 | ||
21411 | ||
21412 | oindex:[%log%] | |
21413 | `..'= | |
21414 | %log%, Use: 'autoreply', Type: 'string'!!, Default: 'unset' | |
21415 | === | |
21416 | ||
21417 | This option names a file in which a record of every message sent is logged when | |
21418 | the message is specified by the transport. | |
21419 | ||
21420 | ||
21421 | oindex:[%mode%] | |
21422 | `..'= | |
21423 | %mode%, Use: 'autoreply', Type: 'octal integer', Default: '0600' | |
21424 | === | |
21425 | ||
d1e83bff PH |
21426 | If either the log file or the ``once'' file has to be created, this mode is |
21427 | used. | |
168e428f PH |
21428 | |
21429 | ||
21430 | oindex:[%never_mail%] | |
21431 | `..'= | |
21432 | %never_mail%, Use: 'autoreply', Type: 'address list'!!, Default: 'unset' | |
21433 | === | |
21434 | ||
21435 | If any run of the transport creates a message with a recipient that matches any | |
21436 | item in the list, that recipient is quietly discarded. If all recipients are | |
21437 | discarded, no message is created. | |
21438 | ||
21439 | ||
21440 | ||
21441 | oindex:[%once%] | |
21442 | `..'= | |
21443 | %once%, Use: 'autoreply', Type: 'string'!!, Default: 'unset' | |
21444 | === | |
21445 | ||
d1e83bff PH |
21446 | This option names a file or DBM database in which a record of each 'To:' |
21447 | recipient is kept when the message is specified by the transport. *Note*: This | |
21448 | does not apply to 'Cc:' or 'Bcc:' recipients. | |
21449 | ||
21450 | If %once% is unset, or is set to an empty string, the message is always sent. | |
21451 | By default, if %once% is set to a non-empty file name, the message | |
21452 | is not sent if a potential recipient is already listed in the database. | |
21453 | However, if the %once_repeat% option specifies a time greater than zero, the | |
21454 | message is sent if that much time has elapsed since a message was last sent to | |
21455 | this recipient. A setting of zero time for %once_repeat% (the default) prevents | |
21456 | a message from being sent a second time -- in this case, zero means infinity. | |
21457 | ||
21458 | If %once_file_size% is zero, a DBM database is used to remember recipients, and | |
21459 | it is allowed to grow as large as necessary. If %once_file_size% is set greater | |
21460 | than zero, it changes the way Exim implements the %once% option. Instead of | |
21461 | using a DBM file to record every recipient it sends to, it uses a regular file, | |
21462 | whose size will never get larger than the given value. | |
21463 | ||
21464 | In the file, Exim keeps a linear list of recipient addresses and the times at | |
21465 | which they were sent messages. If the file is full when a new address needs to | |
21466 | be added, the oldest address is dropped. If %once_repeat% is not set, this | |
21467 | means that a given recipient may receive multiple messages, but at | |
21468 | unpredictable intervals that depend on the rate of turnover of addresses in the | |
21469 | file. If %once_repeat% is set, it specifies a maximum time between repeats. | |
168e428f PH |
21470 | |
21471 | ||
21472 | oindex:[%once_file_size%] | |
21473 | `..'= | |
21474 | %once_file_size%, Use: 'autoreply', Type: 'integer', Default: '0' | |
21475 | === | |
21476 | ||
21477 | See %once% above. | |
21478 | ||
21479 | ||
21480 | oindex:[%once_repeat%] | |
21481 | `..'= | |
21482 | %once_repeat%, Use: 'autoreply', Type: 'time'!!, Default: '0s' | |
21483 | === | |
21484 | ||
21485 | See %once% above. | |
21486 | After expansion, the value of this option must be a valid time value. | |
21487 | ||
21488 | ||
21489 | oindex:[%reply_to%] | |
21490 | `..'= | |
21491 | %reply_to%, Use: 'autoreply', Type: 'string'!!, Default: 'unset' | |
21492 | === | |
21493 | ||
21494 | This specifies the contents of the 'Reply-To:' header when the message is | |
21495 | specified by the transport. | |
21496 | ||
21497 | ||
21498 | oindex:[%return_message%] | |
21499 | `..'= | |
21500 | %return_message%, Use: 'autoreply', Type: 'boolean', Default: 'false' | |
21501 | === | |
21502 | ||
21503 | If this is set, a copy of the original message is returned with the new | |
21504 | message, subject to the maximum size set in the %return_size_limit% global | |
21505 | configuration option. | |
21506 | ||
21507 | ||
21508 | oindex:[%subject%] | |
21509 | `..'= | |
21510 | %subject%, Use: 'autoreply', Type: 'string'!!, Default: 'unset' | |
21511 | === | |
21512 | ||
21513 | This specifies the contents of the 'Subject:' header when the message is | |
21514 | specified by the transport. | |
21515 | ||
21516 | It is tempting to quote the original subject in automatic responses. For | |
21517 | example: | |
21518 | ||
21519 | subject = Re: $h_subject: | |
21520 | ||
21521 | There is a danger in doing this, however. It may allow a third party to | |
21522 | subscribe your users to an opt-in mailing list, provided that the list accepts | |
21523 | bounce messages as subscription confirmations. Well-managed lists require a | |
21524 | non-bounce message to confirm a subscription, so the danger is relatively | |
21525 | small. | |
21526 | ||
21527 | ||
21528 | ||
21529 | oindex:[%text%] | |
21530 | `..'= | |
21531 | %text%, Use: 'autoreply', Type: 'string'!!, Default: 'unset' | |
21532 | === | |
21533 | ||
21534 | This specifies a single string to be used as the body of the message when the | |
21535 | message is specified by the transport. If both %text% and %file% are set, the | |
21536 | text comes first. | |
21537 | ||
21538 | ||
21539 | oindex:[%to%] | |
21540 | `..'= | |
21541 | %to%, Use: 'autoreply', Type: 'string'!!, Default: 'unset' | |
21542 | === | |
21543 | ||
21544 | This specifies recipients of the message and the contents of the 'To:' header | |
21545 | when the message is specified by the transport. | |
21546 | ||
21547 | ||
21548 | ||
21549 | ||
21550 | //////////////////////////////////////////////////////////////////////////// | |
21551 | //////////////////////////////////////////////////////////////////////////// | |
21552 | ||
21553 | [[CHAPLMTP]] | |
21554 | The lmtp transport | |
21555 | ------------------ | |
21556 | cindex:[transports,^lmtp^] | |
21557 | cindex:[^lmtp^ transport] | |
21558 | cindex:[LMTP,over a pipe] | |
21559 | cindex:[LMTP,over a socket] | |
21560 | The ^lmtp^ transport runs the LMTP protocol (RFC 2033) over a pipe to a | |
21561 | specified command | |
21562 | or by interacting with a Unix domain socket. | |
21563 | This transport is something of a cross between the ^pipe^ and ^smtp^ | |
21564 | transports. Exim also has support for using LMTP over TCP/IP; this is | |
21565 | implemented as an option for the ^smtp^ transport. Because LMTP is expected | |
21566 | to be of minority interest, the default build-time configure in _src/EDITME_ | |
21567 | has it commented out. You need to ensure that | |
21568 | ||
21569 | TRANSPORT_LMTP=yes | |
21570 | ||
21571 | is present in your _Local/Makefile_ in order to have the ^lmtp^ transport | |
21572 | included in the Exim binary. | |
21573 | ||
21574 | cindex:[options,^lmtp^ transport] | |
21575 | The private options of the ^lmtp^ transport are as follows: | |
21576 | ||
21577 | oindex:[%batch_id%] | |
21578 | `..'= | |
21579 | %batch_id%, Use: 'lmtp', Type: 'string'!!, Default: 'unset' | |
21580 | === | |
21581 | ||
21582 | See the description of local delivery batching in chapter <<CHAPbatching>>. | |
21583 | ||
21584 | ||
21585 | oindex:[%batch_max%] | |
21586 | `..'= | |
21587 | %batch_max%, Use: 'lmtp', Type: 'integer', Default: '1' | |
21588 | === | |
21589 | ||
21590 | This limits the number of addresses that can be handled in a single delivery. | |
21591 | Most LMTP servers can handle several addresses at once, so it is normally a | |
21592 | good idea to increase this value. See the description of local delivery | |
21593 | batching in chapter <<CHAPbatching>>. | |
21594 | ||
21595 | ||
21596 | oindex:[%command%] | |
21597 | `..'= | |
21598 | %command%, Use: 'lmtp', Type: 'string'!!, Default: 'unset' | |
21599 | === | |
21600 | ||
068aaea8 PH |
21601 | This option must be set if %socket% is not set. The string is a command which |
21602 | is run in a separate process. It is split up into a command name and list of | |
21603 | arguments, each of which is separately expanded (so expansion cannot change the | |
21604 | number of arguments). The command is run directly, not via a shell. The message | |
21605 | is passed to the new process using the standard input and output to operate the | |
21606 | LMTP protocol. | |
21607 | ||
21608 | oindex:[%ignore_quota%] | |
21609 | `..'= | |
21610 | %ignore_quota%, Use: 'lmtp', Type: 'boolean', Default: 'false' | |
21611 | === | |
21612 | ||
21613 | [revisionflag="changed"] | |
21614 | cindex:[LMTP,ignoring quota errors] | |
21615 | If this option is set true, the string `IGNOREQUOTA` is added to RCPT commands, | |
21616 | provided that the LMTP server has advertised support for IGNOREQUOTA in its | |
21617 | response to the LHLO command. | |
168e428f PH |
21618 | |
21619 | ||
21620 | oindex:[%socket%] | |
21621 | `..'= | |
21622 | %socket%, Use: 'lmtp', Type: 'string'!!, Default: 'unset' | |
21623 | === | |
21624 | ||
21625 | This option must be set if %command% is not set. The result of expansion must | |
21626 | be the name of a Unix domain socket. The transport connects to the socket and | |
21627 | delivers the message to it using the LMTP protocol. | |
21628 | ||
21629 | ||
21630 | oindex:[%timeout%] | |
21631 | `..'= | |
21632 | %timeout%, Use: 'lmtp', Type: 'time', Default: '5m' | |
21633 | === | |
21634 | ||
21635 | The transport is aborted if the created process | |
21636 | or Unix domain socket | |
21637 | does not respond to LMTP commands or message input within this timeout. | |
21638 | ||
21639 | ||
21640 | Here is an example of a typical LMTP transport: | |
21641 | ||
21642 | lmtp: | |
21643 | driver = lmtp | |
21644 | command = /some/local/lmtp/delivery/program | |
21645 | batch_max = 20 | |
21646 | user = exim | |
21647 | ||
21648 | This delivers up to 20 addresses at a time, in a mixture of domains if | |
21649 | necessary, running as the user 'exim'. | |
21650 | ||
21651 | ||
21652 | ||
21653 | //////////////////////////////////////////////////////////////////////////// | |
21654 | //////////////////////////////////////////////////////////////////////////// | |
21655 | ||
21656 | [[CHAPpipetransport]] | |
21657 | The pipe transport | |
21658 | ------------------ | |
21659 | cindex:[transports,^pipe^] | |
21660 | cindex:[^pipe^ transport] | |
21661 | The ^pipe^ transport is used to deliver messages via a pipe to a command | |
21662 | running in another process. | |
21663 | ||
21664 | One example is the | |
21665 | use of ^pipe^ as a pseudo-remote transport for passing messages to some other | |
21666 | delivery mechanism (such as UUCP). Another is the use by individual users to | |
21667 | automatically process their incoming messages. The ^pipe^ transport can be | |
21668 | used in one of the following ways: | |
21669 | ||
068aaea8 PH |
21670 | - cindex:[$local_part$] |
21671 | A router routes one address to a transport in the normal way, and the | |
21672 | transport is configured as a ^pipe^ transport. In this case, $local_part$ | |
21673 | contains the local part of the address (as usual), and the command that is run | |
21674 | is specified by the %command% option on the transport. | |
168e428f | 21675 | |
068aaea8 PH |
21676 | - cindex:[$pipe_addresses$] |
21677 | If the %batch_max% option is set greater than 1 (the default), the transport | |
168e428f PH |
21678 | can be called upon to handle more than one address in a single run. In this |
21679 | case, $local_part$ is not set (because it is not unique). However, the | |
21680 | pseudo-variable $pipe_addresses$ (described in section <<SECThowcommandrun>> | |
21681 | below) contains all the addresses that are being handled. | |
21682 | ||
068aaea8 PH |
21683 | - cindex:[$address_pipe$] |
21684 | A router redirects an address directly to a pipe command (for example, from an | |
168e428f PH |
21685 | alias or forward file). In this case, $local_part$ contains the local part |
21686 | that was redirected, and $address_pipe$ contains the text of the pipe | |
21687 | command itself. The %command% option on the transport is ignored. | |
21688 | ||
21689 | ||
21690 | The ^pipe^ transport is a non-interactive delivery method. Exim can also | |
21691 | deliver messages over pipes using the LMTP interactive protocol. This is | |
21692 | implemented by the ^lmtp^ transport. | |
21693 | ||
21694 | In the case when ^pipe^ is run as a consequence of an entry in a local user's | |
068aaea8 PH |
21695 | _.forward_ file, the command runs under the uid and gid of that user. In other |
21696 | cases, the uid and gid have to be specified explicitly, either on the transport | |
21697 | or on the router that handles the address. Current and ``home'' directories are | |
21698 | also controllable. See chapter <<CHAPenvironment>> for details of the local | |
21699 | delivery environment. | |
168e428f PH |
21700 | |
21701 | ||
21702 | ||
21703 | Concurrent delivery | |
21704 | ~~~~~~~~~~~~~~~~~~~ | |
21705 | If two messages arrive at almost the same time, and both are routed to a pipe | |
21706 | delivery, the two pipe transports may be run concurrently. You must ensure that | |
21707 | any pipe commands you set up are robust against this happening. If the commands | |
21708 | write to a file, the %exim_lock% utility might be of use. | |
21709 | ||
21710 | ||
21711 | ||
21712 | ||
21713 | Returned status and data | |
21714 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
21715 | cindex:[^pipe^ transport,returned data] | |
21716 | If the command exits with a non-zero return code, the delivery is deemed to | |
21717 | have failed, unless either the %ignore_status% option is set (in which case | |
21718 | the return code is treated as zero), or the return code is one of those listed | |
21719 | in the %temp_errors% option, which are interpreted as meaning ``try again | |
21720 | later''. In this case, delivery is deferred. Details of a permanent failure are | |
21721 | logged, but are not included in the bounce message, which merely contains | |
21722 | ``local delivery failed''. | |
21723 | ||
21724 | If the return code is greater than 128 and the command being run is a shell | |
21725 | script, it normally means that the script was terminated by a signal whose | |
21726 | value is the return code minus 128. | |
21727 | ||
21728 | If Exim is unable to run the command (that is, if 'execve()' fails), the | |
21729 | return code is set to 127. This is the value that a shell returns if it is | |
21730 | asked to run a non-existent command. The wording for the log line suggests that | |
21731 | a non-existent command may be the problem. | |
21732 | ||
21733 | The %return_output% option can affect the result of a pipe delivery. If it is | |
21734 | set and the command produces any output on its standard output or standard | |
21735 | error streams, the command is considered to have failed, even if it gave a zero | |
21736 | return code or if %ignore_status% is set. The output from the command is | |
21737 | included as part of the bounce message. The %return_fail_output% option is | |
21738 | similar, except that output is returned only when the command exits with a | |
21739 | failure return code, that is, a value other than zero or a code that matches | |
21740 | %temp_errors%. | |
21741 | ||
21742 | ||
21743 | ||
21744 | [[SECThowcommandrun]] | |
21745 | How the command is run | |
21746 | ~~~~~~~~~~~~~~~~~~~~~~ | |
21747 | cindex:[^pipe^ transport,path for command] | |
21748 | The command line is (by default) broken down into a command name and arguments | |
21749 | by the ^pipe^ transport itself. The %allow_commands% and %restrict_to_path% | |
21750 | options can be used to restrict the commands that may be run. | |
21751 | ||
21752 | cindex:[quoting,in pipe command] | |
21753 | Unquoted arguments are delimited by white space. If an argument appears in | |
21754 | double quotes, backslash is interpreted as an escape character in the usual | |
21755 | way. If an argument appears in single quotes, no escaping is done. | |
21756 | ||
21757 | String expansion is applied to the command line except when it comes from a | |
21758 | traditional _.forward_ file (commands from a filter file are expanded). The | |
21759 | expansion is applied to each argument in turn rather than to the whole line. | |
21760 | For this reason, any string expansion item that contains white space must be | |
21761 | quoted so as to be contained within a single argument. A setting such as | |
21762 | ||
21763 | command = /some/path ${if eq{$local_part}{postmaster}{xxx}{yyy}} | |
21764 | ||
21765 | will not work, because the expansion item gets split between several | |
21766 | arguments. You have to write | |
21767 | ||
21768 | command = /some/path "${if eq{$local_part}{postmaster}{xxx}{yyy}}" | |
21769 | ||
21770 | to ensure that it is all in one argument. The expansion is done in this way, | |
21771 | argument by argument, so that the number of arguments cannot be changed as a | |
21772 | result of expansion, and quotes or backslashes in inserted variables do not | |
21773 | interact with external quoting. | |
21774 | ||
21775 | cindex:[transport,filter] | |
21776 | cindex:[filter,transport filter] | |
068aaea8 | 21777 | cindex:[$pipe_addresses$] |
168e428f PH |
21778 | Special handling takes place when an argument consists of precisely the text |
21779 | `\$pipe_addresses\}`. This is not a general expansion variable; the only | |
21780 | place this string is recognized is when it appears as an argument for a pipe or | |
21781 | transport filter command. It causes each address that is being handled to be | |
21782 | inserted in the argument list at that point 'as a separate argument'. This | |
21783 | avoids any problems with spaces or shell metacharacters, and is of use when a | |
21784 | ^pipe^ transport is handling groups of addresses in a batch. | |
21785 | ||
21786 | After splitting up into arguments and expansion, the resulting command is run | |
21787 | in a subprocess directly from the transport, 'not' under a shell. The | |
21788 | message that is being delivered is supplied on the standard input, and the | |
21789 | standard output and standard error are both connected to a single pipe that is | |
21790 | read by Exim. The %max_output% option controls how much output the command may | |
21791 | produce, and the %return_output% and %return_fail_output% options control | |
21792 | what is done with it. | |
21793 | ||
21794 | Not running the command under a shell (by default) lessens the security risks | |
21795 | in cases when a command from a user's filter file is built out of data that was | |
21796 | taken from an incoming message. If a shell is required, it can of course be | |
21797 | explicitly specified as the command to be run. However, there are circumstances | |
21798 | where existing commands (for example, in _.forward_ files) expect to be run | |
21799 | under a shell and cannot easily be modified. To allow for these cases, there is | |
21800 | an option called %use_shell%, which changes the way the ^pipe^ transport | |
21801 | works. Instead of breaking up the command line as just described, it expands it | |
21802 | as a single string and passes the result to _/bin/sh_. The | |
21803 | %restrict_to_path% option and the $pipe_addresses$ facility cannot be used | |
21804 | with %use_shell%, and the whole mechanism is inherently less secure. | |
21805 | ||
21806 | ||
21807 | ||
21808 | [[SECTpipeenv]] | |
21809 | Environment variables | |
21810 | ~~~~~~~~~~~~~~~~~~~~~ | |
21811 | cindex:[^pipe^ transport,environment for command] | |
21812 | cindex:[environment for pipe transport] | |
21813 | The environment variables listed below are set up when the command is invoked. | |
21814 | This list is a compromise for maximum compatibility with other MTAs. Note that | |
21815 | the %environment% option can be used to add additional variables to this | |
21816 | environment. | |
21817 | ||
21818 | &&& | |
21819 | `DOMAIN ` the domain of the address | |
21820 | `HOME ` the home directory, if set | |
21821 | `HOST ` the host name when called from a router (see below) | |
21822 | `LOCAL_PART ` see below | |
21823 | `LOCAL_PART_PREFIX ` see below | |
21824 | `LOCAL_PART_SUFFIX ` see below | |
21825 | `LOGNAME ` see below | |
068aaea8 | 21826 | `MESSAGE_ID ` Exim's local ID for the message |
168e428f PH |
21827 | `PATH ` as specified by the %path% option below |
21828 | `QUALIFY_DOMAIN ` the sender qualification domain | |
21829 | `RECIPIENT ` the complete recipient address | |
21830 | `SENDER ` the sender of the message (empty if a bounce) | |
21831 | `SHELL ` `/bin/sh` | |
21832 | `TZ ` the value of the %timezone% option, if set | |
21833 | `USER ` see below | |
21834 | &&& | |
21835 | ||
21836 | When a ^pipe^ transport is called directly from (for example) an ^accept^ | |
21837 | router, LOCAL_PART is set to the local part of the address. When it is | |
21838 | called as a result of a forward or alias expansion, LOCAL_PART is set to | |
21839 | the local part of the address that was expanded. In both cases, any affixes are | |
21840 | removed from the local part, and made available in LOCAL_PART_PREFIX and | |
21841 | LOCAL_PART_SUFFIX, respectively. LOGNAME and USER are set to the | |
21842 | same value as LOCAL_PART for compatibility with other MTAs. | |
21843 | ||
21844 | cindex:[HOST] | |
21845 | HOST is set only when a ^pipe^ transport is called from a router that | |
21846 | associates hosts with an address, typically when using ^pipe^ as a | |
21847 | pseudo-remote transport. HOST is set to the first host name specified by | |
21848 | the router. | |
21849 | ||
21850 | cindex:[HOME] | |
21851 | If the transport's generic %home_directory% option is set, its value is used | |
21852 | for the HOME environment variable. Otherwise, a home directory may be set | |
21853 | by the router's %transport_home_directory% option, which defaults to the | |
21854 | user's home directory if %check_local_user% is set. | |
21855 | ||
21856 | ||
21857 | Private options for pipe | |
21858 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
21859 | cindex:[options,^pipe^ transport] | |
21860 | ||
21861 | ||
21862 | ||
21863 | oindex:[%allow_commands%] | |
21864 | `..'= | |
21865 | %allow_commands%, Use: 'pipe', Type: 'string list'!!, Default: 'unset' | |
21866 | === | |
21867 | ||
21868 | cindex:[^pipe^ transport,permitted commands] | |
21869 | The string is expanded, and is then interpreted as a colon-separated list of | |
21870 | permitted commands. If %restrict_to_path% is not set, the only commands | |
21871 | permitted are those in the %allow_commands% list. They need not be absolute | |
21872 | paths; the %path% option is still used for relative paths. If | |
21873 | %restrict_to_path% is set with %allow_commands%, the command must either be | |
21874 | in the %allow_commands% list, or a name without any slashes that is found on | |
21875 | the path. In other words, if neither %allow_commands% nor %restrict_to_path% | |
21876 | is set, there is no restriction on the command, but otherwise only commands | |
21877 | that are permitted by one or the other are allowed. For example, if | |
21878 | ||
21879 | allow_commands = /usr/bin/vacation | |
21880 | ||
21881 | and %restrict_to_path% is not set, the only permitted command is | |
21882 | _/usr/bin/vacation_. The %allow_commands% option may not be set if | |
21883 | %use_shell% is set. | |
21884 | ||
21885 | ||
21886 | oindex:[%batch_id%] | |
21887 | `..'= | |
21888 | %batch_id%, Use: 'pipe', Type: 'string'!!, Default: 'unset' | |
21889 | === | |
21890 | ||
21891 | See the description of local delivery batching in chapter <<CHAPbatching>>. | |
21892 | ||
21893 | ||
21894 | oindex:[%batch_max%] | |
21895 | `..'= | |
21896 | %batch_max%, Use: 'pipe', Type: 'integer', Default: '1' | |
21897 | === | |
21898 | ||
21899 | This limits the number of addresses that can be handled in a single delivery. | |
21900 | See the description of local delivery batching in chapter <<CHAPbatching>>. | |
21901 | ||
21902 | ||
21903 | oindex:[%check_string%] | |
21904 | `..'= | |
21905 | %check_string%, Use: 'pipe', Type: 'string', Default: 'unset' | |
21906 | === | |
21907 | ||
21908 | As ^pipe^ writes the message, the start of each line is tested for matching | |
21909 | %check_string%, and if it does, the initial matching characters are replaced | |
21910 | by the contents of %escape_string%, provided both are set. The value of | |
21911 | %check_string% is a literal string, not a regular expression, and the case of | |
21912 | any letters it contains is significant. When %use_bsmtp% is set, the contents | |
21913 | of %check_string% and %escape_string% are forced to values that implement the | |
21914 | SMTP escaping protocol. Any settings made in the configuration file are | |
21915 | ignored. | |
21916 | ||
21917 | ||
21918 | oindex:[%command%] | |
21919 | `..'= | |
21920 | %command%, Use: 'pipe', Type: 'string'!!, Default: 'unset' | |
21921 | === | |
21922 | ||
21923 | This option need not be set when ^pipe^ is being used to deliver to pipes | |
21924 | obtained directly from address redirections. In other cases, the option must be | |
21925 | set, to provide a command to be run. It need not yield an absolute path (see | |
21926 | the %path% option below). The command is split up into separate arguments by | |
21927 | Exim, and each argument is separately expanded, as described in section | |
21928 | <<SECThowcommandrun>> above. | |
21929 | ||
21930 | ||
21931 | oindex:[%environment%] | |
21932 | `..'= | |
21933 | %environment%, Use: 'pipe', Type: 'string'!!, Default: 'unset' | |
21934 | === | |
21935 | ||
21936 | cindex:[^pipe^ transport,environment for command] | |
21937 | cindex:[environment for ^pipe^ transport] | |
21938 | This option is used to add additional variables to the environment in which the | |
21939 | command runs (see section <<SECTpipeenv>> for the default list). Its value is a | |
21940 | string which is expanded, and then interpreted as a colon-separated list of | |
21941 | environment settings of the form ``<''name'>=<'value'>'. | |
21942 | ||
21943 | ||
21944 | oindex:[%escape_string%] | |
21945 | `..'= | |
21946 | %escape_string%, Use: 'pipe', Type: 'string', Default: 'unset' | |
21947 | === | |
21948 | ||
21949 | See %check_string% above. | |
21950 | ||
21951 | ||
21952 | oindex:[%freeze_exec_fail%] | |
21953 | `..'= | |
21954 | %freeze_exec_fail%, Use: 'pipe', Type: 'boolean', Default: 'false' | |
21955 | === | |
21956 | ||
21957 | cindex:[exec failure] | |
21958 | cindex:[failure of exec] | |
21959 | cindex:[^pipe^ transport,failure of exec] | |
21960 | Failure to exec the command in a pipe transport is by default treated like | |
21961 | any other failure while running the command. However, if %freeze_exec_fail% | |
21962 | is set, failure to exec is treated specially, and causes the message to be | |
21963 | frozen, whatever the setting of %ignore_status%. | |
21964 | ||
21965 | ||
21966 | oindex:[%ignore_status%] | |
21967 | `..'= | |
21968 | %ignore_status%, Use: 'pipe', Type: 'boolean', Default: 'false' | |
21969 | === | |
21970 | ||
21971 | If this option is true, the status returned by the subprocess that is set up to | |
21972 | run the command is ignored, and Exim behaves as if zero had been returned. | |
068aaea8 PH |
21973 | Otherwise, a non-zero status or termination by signal causes an error return |
21974 | from the transport unless the status value is one of those listed in | |
21975 | %temp_errors%; these cause the delivery to be deferred and tried again later. | |
21976 | ||
21977 | [revisionflag="changed"] | |
21978 | *Note*: This option does not apply to timeouts, which do not return a status. | |
21979 | See the %timeout_defer% option for how timeouts are handled. | |
168e428f PH |
21980 | |
21981 | ||
21982 | oindex:[%log_defer_output%] | |
21983 | `..'= | |
21984 | %log_defer_output%, Use: 'pipe', Type: 'boolean', Default: 'false' | |
21985 | === | |
21986 | ||
21987 | cindex:[^pipe^ transport,logging output] | |
21988 | If this option is set, and the status returned by the command is | |
21989 | one of the codes listed in %temp_errors% (that is, delivery was deferred), | |
21990 | and any output was produced, the first line of it is written to the main log. | |
21991 | ||
21992 | ||
21993 | oindex:[%log_fail_output%] | |
21994 | `..'= | |
21995 | %log_fail_output%, Use: 'pipe', Type: 'boolean', Default: 'false' | |
21996 | === | |
21997 | ||
21998 | If this option is set, and the command returns any output, and also ends with a | |
21999 | return code that is neither zero nor one of the return codes listed in | |
22000 | %temp_errors% (that is, the delivery failed), the first line of output is | |
22001 | written to the main log. | |
22002 | ||
22003 | This option and %log_output% are mutually exclusive. Only one of them may be | |
22004 | set. | |
22005 | ||
22006 | ||
22007 | ||
22008 | oindex:[%log_output%] | |
22009 | `..'= | |
22010 | %log_output%, Use: 'pipe', Type: 'boolean', Default: 'false' | |
22011 | === | |
22012 | ||
22013 | If this option is set and the command returns any output, the first line of | |
22014 | output is written to the main log, whatever the return code. | |
22015 | ||
22016 | This option and %log_fail_output% are mutually exclusive. Only one of them | |
22017 | may be set. | |
22018 | ||
22019 | ||
22020 | ||
22021 | oindex:[%max_output%] | |
22022 | `..'= | |
22023 | %max_output%, Use: 'pipe', Type: 'integer', Default: '20K' | |
22024 | === | |
22025 | ||
22026 | This specifies the maximum amount of output that the command may produce on its | |
22027 | standard output and standard error file combined. If the limit is exceeded, the | |
22028 | process running the command is killed. This is intended as a safety measure to | |
22029 | catch runaway processes. The limit is applied independently of the settings of | |
22030 | the options that control what is done with such output (for example, | |
22031 | %return_output%). Because of buffering effects, the amount of output may | |
22032 | exceed the limit by a small amount before Exim notices. | |
22033 | ||
22034 | ||
22035 | oindex:[%message_prefix%] | |
22036 | `..'= | |
22037 | %message_prefix%, Use: 'pipe', Type: 'string'!!, Default: 'see below' | |
22038 | === | |
22039 | ||
22040 | The string specified here is expanded and output at the start of every message. | |
22041 | The default is unset if %use_bsmtp% is set. Otherwise it is | |
22042 | ||
22043 | .... | |
22044 | message_prefix = \ | |
22045 | From ${if def:return_path{$return_path}{MAILER-DAEMON}}\ | |
22046 | ${tod_bsdinbox}\n | |
22047 | .... | |
22048 | ||
22049 | cindex:[Cyrus] | |
22050 | cindex:[%tmail%] | |
22051 | cindex:[``From'' line] | |
22052 | This is required by the commonly used _/usr/bin/vacation_ program. | |
22053 | However, it must 'not' be present if delivery is to the Cyrus IMAP server, | |
22054 | or to the %tmail% local delivery agent. The prefix can be suppressed by setting | |
22055 | ||
22056 | message_prefix = | |
22057 | ||
22058 | ||
22059 | ||
22060 | oindex:[%message_suffix%] | |
22061 | `..'= | |
22062 | %message_suffix%, Use: 'pipe', Type: 'string'!!, Default: 'see below' | |
22063 | === | |
22064 | ||
22065 | The string specified here is expanded and output at the end of every message. | |
22066 | The default is unset if %use_bsmtp% is set. Otherwise it is a single newline. | |
22067 | The suffix can be suppressed by setting | |
22068 | ||
22069 | message_suffix = | |
22070 | ||
22071 | ||
22072 | ||
22073 | oindex:[%path%] | |
22074 | `..'= | |
068aaea8 | 22075 | %path%, Use: 'pipe', Type: 'string', Default: `/bin:/usr/bin` |
168e428f PH |
22076 | === |
22077 | ||
22078 | This option specifies the string that is set up in the PATH environment | |
22079 | variable of the subprocess. If the %command% option does not yield an absolute | |
22080 | path name, the command is sought in the PATH directories, in the usual way. | |
22081 | *Warning*: This does not apply to a command specified as a transport | |
22082 | filter. | |
22083 | ||
22084 | ||
22085 | oindex:[%pipe_as_creator%] | |
22086 | `..'= | |
22087 | %pipe_as_creator%, Use: 'pipe', Type: 'boolean', Default: 'false' | |
22088 | === | |
22089 | ||
22090 | cindex:[uid (user id),local delivery] | |
22091 | If the generic %user% option is not set and this option is true, the delivery | |
22092 | process is run under the uid that was in force when Exim was originally called | |
22093 | to accept the message. If the group id is not otherwise set (via the generic | |
22094 | %group% option), the gid that was in force when Exim was originally called to | |
22095 | accept the message is used. | |
22096 | ||
22097 | ||
22098 | oindex:[%restrict_to_path%] | |
22099 | `..'= | |
22100 | %restrict_to_path%, Use: 'pipe', Type: 'boolean', Default: 'false' | |
22101 | === | |
22102 | ||
22103 | When this option is set, any command name not listed in %allow_commands% must | |
22104 | contain no slashes. The command is searched for only in the directories listed | |
22105 | in the %path% option. This option is intended for use in the case when a pipe | |
22106 | command has been generated from a user's _.forward_ file. This is usually | |
22107 | handled by a ^pipe^ transport called %address_pipe%. | |
22108 | ||
22109 | ||
22110 | oindex:[%return_fail_output%] | |
22111 | `..'= | |
22112 | %return_fail_output%, Use: 'pipe', Type: 'boolean', Default: 'false' | |
22113 | === | |
22114 | ||
22115 | If this option is true, and the command produced any output and ended with a | |
22116 | return code other than zero or one of the codes listed in %temp_errors% (that | |
22117 | is, the delivery failed), the output is returned in the bounce message. | |
22118 | However, if the message has a null sender (that is, it is itself a bounce | |
22119 | message), output from the command is discarded. | |
22120 | ||
22121 | This option and %return_output% are mutually exclusive. Only one of them may | |
22122 | be set. | |
22123 | ||
22124 | ||
22125 | ||
22126 | oindex:[%return_output%] | |
22127 | `..'= | |
22128 | %return_output%, Use: 'pipe', Type: 'boolean', Default: 'false' | |
22129 | === | |
22130 | ||
22131 | If this option is true, and the command produced any output, the delivery is | |
22132 | deemed to have failed whatever the return code from the command, and the output | |
22133 | is returned in the bounce message. Otherwise, the output is just discarded. | |
22134 | However, if the message has a null sender (that is, it is a bounce message), | |
22135 | output from the command is always discarded, whatever the setting of this | |
22136 | option. | |
22137 | ||
22138 | This option and %return_fail_output% are mutually exclusive. Only one of them | |
22139 | may be set. | |
22140 | ||
22141 | ||
22142 | ||
22143 | oindex:[%temp_errors%] | |
22144 | `..'= | |
22145 | %temp_errors%, Use: 'pipe', Type: 'string list', Default: 'see below' | |
22146 | === | |
22147 | ||
22148 | cindex:[^pipe^ transport,temporary failure] | |
22149 | This option contains either a colon-separated list of numbers, or a single | |
22150 | asterisk. If %ignore_status% is false | |
22151 | and %return_output% is not set, | |
22152 | and the command exits with a non-zero return code, the failure is treated as | |
22153 | temporary and the delivery is deferred if the return code matches one of the | |
22154 | numbers, or if the setting is a single asterisk. Otherwise, non-zero return | |
22155 | codes are treated as permanent errors. The default setting contains the codes | |
22156 | defined by EX_TEMPFAIL and EX_CANTCREAT in _sysexits.h_. If Exim is | |
22157 | compiled on a system that does not define these macros, it assumes values of 75 | |
22158 | and 73, respectively. | |
22159 | ||
22160 | ||
22161 | oindex:[%timeout%] | |
22162 | `..'= | |
22163 | %timeout%, Use: 'pipe', Type: 'time', Default: '1h' | |
22164 | === | |
22165 | ||
22166 | If the command fails to complete within this time, it is killed. This normally | |
068aaea8 PH |
22167 | causes the delivery to fail (but see %timeout_defer%). A zero time interval |
22168 | specifies no timeout. In order to ensure that any subprocesses created by the | |
22169 | command are also killed, Exim makes the initial process a process group leader, | |
22170 | and kills the whole process group on a timeout. However, this can be defeated | |
22171 | if one of the processes starts a new process group. | |
22172 | ||
22173 | oindex:[%timeout_defer%] | |
22174 | `..'= | |
22175 | %timeout_defer%, Use: 'pipe', Type: 'boolean', Default: 'false' | |
22176 | === | |
22177 | ||
22178 | [revisionflag="changed"] | |
22179 | A timeout in a ^pipe^ transport, either in the command that the transport runs, | |
22180 | or in a transport filter that is associated with it, is by default treated as a | |
22181 | hard error, and the delivery fails. However, if %timeout_defer% is set true, | |
22182 | both kinds of timeout become temporary errors, causing the delivery to be | |
22183 | deferred. | |
168e428f PH |
22184 | |
22185 | ||
22186 | oindex:[%umask%] | |
22187 | `..'= | |
22188 | %umask%, Use: 'pipe', Type: 'octal integer', Default: '022' | |
22189 | === | |
22190 | ||
22191 | This specifies the umask setting for the subprocess that runs the command. | |
22192 | ||
22193 | ||
22194 | oindex:[%use_bsmtp%] | |
22195 | `..'= | |
22196 | %use_bsmtp%, Use: 'pipe', Type: 'boolean', Default: 'false' | |
22197 | === | |
22198 | ||
22199 | cindex:[envelope sender] | |
22200 | If this option is set true, the ^pipe^ transport writes messages in ``batch | |
22201 | SMTP'' format, with the envelope sender and recipient(s) included as SMTP | |
22202 | commands. If you want to include a leading HELO command with such messages, | |
22203 | you can do so by setting the %message_prefix% option. See section | |
22204 | <<SECTbatchSMTP>> for details of batch SMTP. | |
22205 | ||
22206 | ||
22207 | oindex:[%use_crlf%] | |
22208 | `..'= | |
22209 | %use_crlf%, Use: 'pipe', Type: 'boolean', Default: 'false' | |
22210 | === | |
22211 | ||
22212 | cindex:[carriage return] | |
22213 | cindex:[linefeed] | |
22214 | This option causes lines to be terminated with the two-character CRLF sequence | |
22215 | (carriage return, linefeed) instead of just a linefeed character. In the case | |
22216 | of batched SMTP, the byte sequence written to the pipe is then an exact image | |
22217 | of what would be sent down a real SMTP connection. | |
22218 | ||
22219 | The contents of the %message_prefix% and %message_suffix% options are written | |
22220 | verbatim, so must contain their own carriage return characters if these are | |
22221 | needed. Since the default values for both %message_prefix% and | |
22222 | %message_suffix% end with a single linefeed, their values | |
22223 | must | |
22224 | be changed to end with `\r\n` if %use_crlf% is set. | |
22225 | ||
22226 | ||
22227 | oindex:[%use_shell%] | |
22228 | `..'= | |
22229 | %use_shell%, Use: 'pipe', Type: 'boolean', Default: 'false' | |
22230 | === | |
22231 | ||
068aaea8 | 22232 | cindex:[$pipe_addresses$] |
168e428f PH |
22233 | If this option is set, it causes the command to be passed to _/bin/sh_ |
22234 | instead of being run directly from the transport, as described in section | |
22235 | <<SECThowcommandrun>>. This is less secure, but is needed in some situations | |
22236 | where the command is expected to be run under a shell and cannot easily be | |
22237 | modified. The %allow_commands% and %restrict_to_path% options, and the | |
22238 | `\$pipe_addresses` facility are incompatible with %use_shell%. The | |
22239 | command is expanded as a single string, and handed to _/bin/sh_ as data for | |
22240 | its %-c% option. | |
22241 | ||
22242 | ||
22243 | ||
22244 | Using an external local delivery agent | |
22245 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
22246 | cindex:[local delivery,using an external agent] | |
22247 | cindex:['procmail'] | |
22248 | cindex:[external local delivery] | |
22249 | cindex:[delivery,'procmail'] | |
22250 | cindex:[delivery,by external agent] | |
22251 | The ^pipe^ transport can be used to pass all messages that require local | |
22252 | delivery to a separate local delivery agent such as %procmail%. When doing | |
22253 | this, care must be taken to ensure that the pipe is run under an appropriate | |
22254 | uid and gid. In some configurations one wants this to be a uid that is trusted | |
22255 | by the delivery agent to supply the correct sender of the message. It may be | |
22256 | necessary to recompile or reconfigure the delivery agent so that it trusts an | |
22257 | appropriate user. The following is an example transport and router | |
22258 | configuration for %procmail%: | |
22259 | ||
22260 | # transport | |
22261 | procmail_pipe: | |
22262 | driver = pipe | |
22263 | command = /usr/local/bin/procmail -d $local_part | |
22264 | return_path_add | |
22265 | delivery_date_add | |
22266 | envelope_to_add | |
22267 | check_string = "From " | |
22268 | escape_string = ">From " | |
22269 | user = $local_part | |
22270 | group = mail | |
22271 | ||
22272 | # router | |
22273 | procmail: | |
22274 | driver = accept | |
22275 | check_local_user | |
22276 | transport = procmail_pipe | |
22277 | ||
22278 | ||
22279 | In this example, the pipe is run as the local user, but with the group set to | |
22280 | 'mail'. An alternative is to run the pipe as a specific user such as 'mail' | |
22281 | or 'exim', but in this case you must arrange for %procmail% to trust that | |
22282 | user to supply a correct sender address. If you do not specify either a %group% | |
22283 | or a %user% option, the pipe command is run as the local user. The home | |
22284 | directory is the user's home directory by default. | |
22285 | ||
22286 | Note that the command that the pipe transport runs does 'not' begin with | |
22287 | ||
22288 | IFS=" " | |
22289 | ||
22290 | as shown in the %procmail% documentation, because Exim does not by default use | |
22291 | a shell to run pipe commands. | |
22292 | ||
22293 | cindex:[Cyrus] | |
22294 | The next example shows a transport and a router for a system where local | |
22295 | deliveries are handled by the Cyrus IMAP server. | |
22296 | ||
22297 | .... | |
22298 | # transport | |
22299 | local_delivery_cyrus: | |
22300 | driver = pipe | |
22301 | command = /usr/cyrus/bin/deliver \ | |
22302 | -m ${substr_1:$local_part_suffix} -- $local_part | |
22303 | user = cyrus | |
22304 | group = mail | |
22305 | return_output | |
22306 | log_output | |
22307 | message_prefix = | |
22308 | message_suffix = | |
22309 | ||
22310 | # router | |
22311 | local_user_cyrus: | |
22312 | driver = accept | |
22313 | check_local_user | |
22314 | local_part_suffix = .* | |
22315 | transport = local_delivery_cyrus | |
22316 | .... | |
22317 | ||
22318 | Note the unsetting of %message_prefix% and %message_suffix%, and the use of | |
22319 | %return_output% to cause any text written by Cyrus to be returned to the | |
22320 | sender. | |
22321 | ||
22322 | ||
22323 | //////////////////////////////////////////////////////////////////////////// | |
22324 | //////////////////////////////////////////////////////////////////////////// | |
22325 | ||
22326 | [[CHAPsmtptrans]] | |
22327 | The smtp transport | |
22328 | ------------------ | |
22329 | cindex:[transports,^smtp^] | |
22330 | cindex:[^smtp^ transport] | |
22331 | The ^smtp^ transport delivers messages over TCP/IP connections using the SMTP | |
22332 | or LMTP protocol. The list of hosts to try can either be taken from the address | |
22333 | that is being processed (having been set up by the router), or specified | |
22334 | explicitly for the transport. Timeout and retry processing (see chapter | |
22335 | <<CHAPretry>>) is applied to each IP address independently. | |
22336 | ||
22337 | ||
22338 | Multiple messages on a single connection | |
22339 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
22340 | The sending of multiple messages over a single TCP/IP connection can arise in | |
22341 | two ways: | |
22342 | ||
22343 | - If a message contains more than %max_rcpt% (see below) addresses that are | |
22344 | routed to the same host, more than one copy of the message has to be sent to | |
22345 | that host. In this situation, multiple copies may be sent in a single run of | |
22346 | the ^smtp^ transport over a single TCP/IP connection. (What Exim actually does | |
22347 | when it has too many addresses to send in one message also depends on the value | |
22348 | of the global %remote_max_parallel% option. Details are given in section | |
22349 | <<SECToutSMTPTCP>>.) | |
22350 | ||
22351 | - cindex:[hints database,remembering routing] | |
22352 | When a message has been successfully delivered over a TCP/IP connection, Exim | |
22353 | looks in its hints database to see if there are any other messages awaiting a | |
22354 | connection to the same host. If there are, a new delivery process is started | |
22355 | for one of them, and the current TCP/IP connection is passed on to it. The new | |
22356 | process may in turn send multiple copies and possibly create yet another | |
22357 | process. | |
22358 | ||
22359 | ||
22360 | For each copy sent over the same TCP/IP connection, a sequence counter is | |
22361 | incremented, and if it ever gets to the value of %connection_max_messages%, | |
22362 | no further messages are sent over that connection. | |
22363 | ||
22364 | ||
22365 | ||
22366 | Use of the \$host variable | |
22367 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
22368 | cindex:[$host$] | |
22369 | cindex:[$host_address$] | |
22370 | At the start of a run of the ^smtp^ transport, the values of $host$ and | |
22371 | $host_address$ are the name and IP address of the first host on the host list | |
22372 | passed by the router. However, when the transport is about to connect to a | |
22373 | specific host, and while it is connected to that host, $host$ and | |
22374 | $host_address$ are set to the values for that host. These are the values | |
22375 | that are in force when the %helo_data%, %hosts_try_auth%, %interface%, | |
22376 | %serialize_hosts%, and the various TLS options are expanded. | |
22377 | ||
22378 | ||
22379 | ||
22380 | Private options for smtp | |
22381 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
22382 | cindex:[options,^smtp^ transport] | |
22383 | The private options of the ^smtp^ transport are as follows: | |
22384 | ||
22385 | ||
22386 | oindex:[%allow_localhost%] | |
22387 | `..'= | |
22388 | %allow_localhost%, Use: 'smtp', Type: 'boolean', Default: 'false' | |
22389 | === | |
22390 | ||
22391 | cindex:[local host,sending to] | |
22392 | cindex:[fallback,hosts specified on transport] | |
22393 | When a host specified in %hosts% or %fallback_hosts% (see below) turns out to | |
22394 | be the local host, or is listed in %hosts_treat_as_local%, delivery is | |
22395 | deferred by default. However, if %allow_localhost% is set, Exim goes on to do | |
22396 | the delivery anyway. This should be used only in special cases when the | |
22397 | configuration ensures that no looping will result (for example, a differently | |
22398 | configured Exim is listening on the port to which the message is sent). | |
22399 | ||
22400 | ||
22401 | oindex:[%authenticated_sender%] | |
22402 | `..'= | |
22403 | %authenticated_sender%, Use: 'smtp', Type: 'string'!!, Default: 'unset' | |
22404 | === | |
22405 | ||
22406 | cindex:[Cyrus] | |
22407 | When Exim has authenticated as a client, this option sets a value for the | |
22408 | AUTH= item on outgoing MAIL commands, overriding any existing | |
22409 | authenticated sender value. If the string expansion is forced to fail, the | |
22410 | option is ignored. Other expansion failures cause delivery to be deferred. If | |
22411 | the result of expansion is an empty string, that is also ignored. | |
22412 | ||
22413 | If the SMTP session is not authenticated, the expansion of | |
22414 | %authenticated_sender% still happens (and can cause the delivery to be | |
22415 | deferred if it fails), but no AUTH= item is added to MAIL commands. | |
22416 | ||
22417 | This option allows you to use the ^smtp^ transport in LMTP mode to | |
22418 | deliver mail to Cyrus IMAP and provide the proper local part as the | |
22419 | ``authenticated sender'', via a setting such as: | |
22420 | ||
22421 | authenticated_sender = $local_part | |
22422 | ||
22423 | This removes the need for IMAP subfolders to be assigned special ACLs to | |
22424 | allow direct delivery to those subfolders. | |
22425 | ||
22426 | Because of expected uses such as that just described for Cyrus (when no | |
22427 | domain is involved), there is no checking on the syntax of the provided | |
22428 | value. | |
22429 | ||
22430 | ||
22431 | oindex:[%command_timeout%] | |
22432 | `..'= | |
22433 | %command_timeout%, Use: 'smtp', Type: 'time', Default: '5m' | |
22434 | === | |
22435 | ||
22436 | This sets a timeout for receiving a response to an SMTP command that has been | |
22437 | sent out. It is also used when waiting for the initial banner line from the | |
22438 | remote host. Its value must not be zero. | |
22439 | ||
22440 | ||
22441 | oindex:[%connect_timeout%] | |
22442 | `..'= | |
22443 | %connect_timeout%, Use: 'smtp', Type: 'time', Default: '5m' | |
22444 | === | |
22445 | ||
22446 | This sets a timeout for the 'connect()' function, which sets up a TCP/IP call | |
22447 | to a remote host. A setting of zero allows the system timeout (typically | |
22448 | several minutes) to act. To have any effect, the value of this option must be | |
22449 | less than the system timeout. However, it has been observed that on some | |
22450 | systems there is no system timeout, which is why the default value for this | |
22451 | option is 5 minutes, a value recommended by RFC 1123. | |
22452 | ||
22453 | ||
22454 | oindex:[%connection_max_messages%] | |
22455 | `..'= | |
22456 | %connection_max_messages%, Use: 'smtp', Type: 'integer', Default: '500' | |
22457 | === | |
22458 | ||
22459 | cindex:[SMTP,passed connection] | |
22460 | cindex:[SMTP,multiple deliveries] | |
22461 | cindex:[multiple SMTP deliveries] | |
22462 | This controls the maximum number of separate message deliveries that are sent | |
22463 | over a single TCP/IP connection. If the value is zero, there is no limit. | |
22464 | For testing purposes, this value can be overridden by the %-oB% command line | |
22465 | option. | |
22466 | ||
22467 | ||
22468 | oindex:[%data_timeout%] | |
22469 | `..'= | |
22470 | %data_timeout%, Use: 'smtp', Type: 'time', Default: '5m' | |
22471 | === | |
22472 | ||
22473 | This sets a timeout for the transmission of each block in the data portion of | |
22474 | the message. As a result, the overall timeout for a message depends on the size | |
22475 | of the message. Its value must not be zero. See also %final_timeout%. | |
22476 | ||
22477 | ||
22478 | oindex:[%delay_after_cutoff%] | |
22479 | `..'= | |
22480 | %delay_after_cutoff%, Use: 'smtp', Type: 'boolean', Default: 'true' | |
22481 | === | |
22482 | ||
22483 | This option controls what happens when all remote IP addresses for a given | |
22484 | domain have been inaccessible for so long that they have passed their retry | |
22485 | cutoff times. | |
22486 | ||
22487 | In the default state, if the next retry time has not been reached for any of | |
22488 | them, the address is bounced without trying any deliveries. In other words, | |
22489 | Exim delays retrying an IP address after the final cutoff time until a new | |
22490 | retry time is reached, and can therefore bounce an address without ever trying | |
22491 | a delivery, when machines have been down for a long time. Some people are | |
22492 | unhappy at this prospect, so... | |
22493 | ||
22494 | If %delay_after_cutoff% is set false, Exim behaves differently. If all IP | |
22495 | addresses are past their final cutoff time, Exim tries to deliver to those | |
22496 | IP addresses that have not been tried since the message arrived. If there are | |
22497 | none, of if they all fail, the address is bounced. In other words, it does not | |
22498 | delay when a new message arrives, but immediately tries those expired IP | |
22499 | addresses that haven't been tried since the message arrived. If there is a | |
22500 | continuous stream of messages for the dead hosts, unsetting | |
22501 | %delay_after_cutoff% means that there will be many more attempts to deliver | |
22502 | to them. | |
22503 | ||
22504 | ||
22505 | oindex:[%dns_qualify_single%] | |
22506 | `..'= | |
22507 | %dns_qualify_single%, Use: 'smtp', Type: 'boolean', Default: 'true' | |
22508 | === | |
22509 | ||
22510 | If the %hosts% or %fallback_hosts% option is being used, | |
22511 | and the %gethostbyname% option is false, | |
22512 | the RES_DEFNAMES resolver option is set. See the %qualify_single% option | |
22513 | in chapter <<CHAPdnslookup>> for more details. | |
22514 | ||
22515 | ||
22516 | oindex:[%dns_search_parents%] | |
22517 | `..'= | |
22518 | %dns_search_parents%, Use: 'smtp', Type: 'boolean', Default: 'false' | |
22519 | === | |
22520 | ||
22521 | cindex:[%search_parents%] | |
22522 | If the %hosts% or %fallback_hosts% option is being used, and the | |
22523 | %gethostbyname% option is false, the RES_DNSRCH resolver option is set. | |
22524 | See the %search_parents% option in chapter <<CHAPdnslookup>> for more details. | |
22525 | ||
22526 | ||
22527 | ||
22528 | oindex:[%fallback_hosts%] | |
22529 | `..'= | |
22530 | %fallback_hosts%, Use: 'smtp', Type: 'string list', Default: 'unset' | |
22531 | === | |
22532 | ||
068aaea8 | 22533 | [revisionflag="changed"] |
168e428f PH |
22534 | cindex:[fallback,hosts specified on transport] |
22535 | String expansion is not applied to this option. The argument must be a | |
068aaea8 PH |
22536 | colon-separated list of host names or IP addresses, optionally also including |
22537 | port numbers, though the separator can be changed, as described in section | |
22538 | <<SECTlistconstruct>>. Each individual item in the list is the same as an item | |
22539 | in a %route_list% setting for the ^manualroute^ router, as described in section | |
22540 | <<SECTformatonehostitem>>. | |
22541 | ||
22542 | Fallback hosts can also be specified on routers, which associate them with the | |
22543 | addresses they process. As for the %hosts% option without %hosts_override%, | |
22544 | %fallback_hosts% specified on the transport is used only if the address does | |
22545 | not have its own associated fallback host list. Unlike %hosts%, a setting of | |
22546 | %fallback_hosts% on an address is not overridden by %hosts_override%. However, | |
22547 | %hosts_randomize% does apply to fallback host lists. | |
168e428f PH |
22548 | |
22549 | If Exim is unable to deliver to any of the hosts for a particular address, and | |
22550 | the errors are not permanent rejections, the address is put on a separate | |
22551 | transport queue with its host list replaced by the fallback hosts, unless the | |
22552 | address was routed via MX records and the current host was in the original MX | |
22553 | list. In that situation, the fallback host list is not used. | |
22554 | ||
22555 | Once normal deliveries are complete, the fallback queue is delivered by | |
22556 | re-running the same transports with the new host lists. If several failing | |
22557 | addresses have the same fallback hosts (and %max_rcpt% permits it), a single | |
22558 | copy of the message is sent. | |
22559 | ||
22560 | The resolution of the host names on the fallback list is controlled by the | |
22561 | %gethostbyname% option, as for the %hosts% option. Fallback hosts apply | |
22562 | both to cases when the host list comes with the address and when it is taken | |
22563 | from %hosts%. This option provides a ``use a smart host only if delivery fails'' | |
22564 | facility. | |
22565 | ||
22566 | ||
22567 | oindex:[%final_timeout%] | |
22568 | `..'= | |
22569 | %final_timeout%, Use: 'smtp', Type: 'time', Default: '10m' | |
22570 | === | |
22571 | ||
22572 | This is the timeout that applies while waiting for the response to the final | |
22573 | line containing just ``.'' that terminates a message. Its value must not be zero. | |
22574 | ||
22575 | ||
22576 | oindex:[%gethostbyname%] | |
22577 | `..'= | |
22578 | %gethostbyname%, Use: 'smtp', Type: 'boolean', Default: 'false' | |
22579 | === | |
22580 | ||
22581 | If this option is true when the %hosts% and/or %fallback_hosts% options are | |
22582 | being used, names are looked up using 'gethostbyname()' | |
22583 | (or 'getipnodebyname()' when available) | |
22584 | instead of using the DNS. Of course, that function may in fact use the DNS, but | |
22585 | it may also consult other sources of information such as _/etc/hosts_. | |
22586 | ||
22587 | oindex:[%helo_data%] | |
22588 | `..'= | |
22589 | %helo_data%, Use: 'smtp', Type: 'string'!!, Default: `\$primary_hostname` | |
22590 | === | |
22591 | ||
22592 | cindex:[HELO argument, setting] | |
22593 | cindex:[EHLO argument, setting] | |
22594 | The value of this option is expanded, and used as the argument for the EHLO | |
22595 | or HELO command that starts the outgoing SMTP session. | |
22596 | ||
22597 | ||
22598 | oindex:[%hosts%] | |
22599 | `..'= | |
22600 | %hosts%, Use: 'smtp', Type: 'string list'!!, Default: 'unset' | |
22601 | === | |
22602 | ||
22603 | Hosts are associated with an address by a router such as ^dnslookup^, which | |
068aaea8 PH |
22604 | finds the hosts by looking up the address domain in the DNS, or by |
22605 | ^manualroute^, which has lists of hosts in its configuration. However, | |
22606 | email addresses can be passed to the ^smtp^ transport by any router, and not | |
22607 | all of them can provide an associated list of hosts. | |
22608 | ||
22609 | The %hosts% option specifies a list of hosts to be used if the address being | |
22610 | processed does not have any hosts associated with it. The hosts specified by | |
22611 | %hosts% are also used, whether or not the address has its own hosts, if | |
22612 | %hosts_override% is set. | |
168e428f | 22613 | |
068aaea8 | 22614 | [revisionflag="changed"] |
168e428f | 22615 | The string is first expanded, before being interpreted as a colon-separated |
068aaea8 PH |
22616 | list of host names or IP addresses, possibly including port numbers. The |
22617 | separator may be changed to something other than colon, as described in section | |
22618 | <<SECTlistconstruct>>. Each individual item in the list is the same as an item | |
22619 | in a %route_list% setting for the ^manualroute^ router, as described in section | |
22620 | <<SECTformatonehostitem>>. However, note that the `/MX` facility of the | |
22621 | ^manualroute^ router is not available here. | |
22622 | ||
22623 | If the expansion fails, delivery is deferred. Unless the failure was caused by | |
22624 | the inability to complete a lookup, the error is logged to the panic log as | |
22625 | well as the main log. Host names are looked up either by searching directly for | |
22626 | address records in the DNS or by calling 'gethostbyname()' (or | |
22627 | 'getipnodebyname()' when available), depending on the setting of the | |
22628 | %gethostbyname% option. When Exim is compiled with IPv6 support, if a host that | |
22629 | is looked up in the DNS has both IPv4 and IPv6 addresses, both types of address | |
22630 | are used. | |
168e428f PH |
22631 | |
22632 | During delivery, the hosts are tried in order, subject to their retry status, | |
22633 | unless %hosts_randomize% is set. | |
22634 | ||
22635 | ||
22636 | oindex:[%hosts_avoid_esmtp%] | |
22637 | `..'= | |
22638 | %hosts_avoid_esmtp%, Use: 'smtp', Type: 'host list'!!, Default: 'unset' | |
22639 | === | |
22640 | ||
22641 | cindex:[ESMTP, avoiding use of] | |
22642 | cindex:[HELO,forcing use of] | |
22643 | cindex:[EHLO,avoiding use of] | |
22644 | cindex:[PIPELINING,avoiding the use of] | |
22645 | This option is for use with broken hosts that announce ESMTP facilities (for | |
22646 | example, PIPELINING) and then fail to implement them properly. When a host | |
22647 | matches %hosts_avoid_esmtp%, Exim sends HELO rather than EHLO at the | |
22648 | start of the SMTP session. This means that it cannot use any of the ESMTP | |
22649 | facilities such as AUTH, PIPELINING, SIZE, and STARTTLS. | |
22650 | ||
22651 | ||
22652 | oindex:[%hosts_avoid_tls%] | |
22653 | `..'= | |
22654 | %hosts_avoid_tls%, Use: 'smtp', Type: 'host list'!!, Default: 'unset' | |
22655 | === | |
22656 | ||
22657 | cindex:[TLS,avoiding for certain hosts] | |
22658 | Exim will not try to start a TLS session when delivering to any host that | |
22659 | matches this list. See chapter <<CHAPTLS>> for details of TLS. | |
22660 | ||
22661 | ||
22662 | oindex:[%hosts_max_try%] | |
22663 | `..'= | |
22664 | %hosts_max_try%, Use: 'smtp', Type: 'integer', Default: '5' | |
22665 | === | |
22666 | ||
22667 | cindex:[host,maximum number to try] | |
22668 | cindex:[limit,number of hosts tried] | |
22669 | cindex:[limit,number of MX tried] | |
22670 | cindex:[MX record,maximum tried] | |
22671 | This option limits the number of IP addresses that are tried for any one | |
22672 | delivery in cases where there are temporary delivery errors. Section | |
22673 | <<SECTvalhosmax>> describes in detail how the value of this option is used. | |
22674 | ||
22675 | ||
22676 | oindex:[%hosts_max_try_hardlimit%] | |
22677 | `..'= | |
22678 | %hosts_max_try_hardlimit%, Use: 'smtp', Type: 'integer', Default: '50' | |
22679 | === | |
22680 | ||
22681 | This is an additional check on the maximum number of IP addresses that Exim | |
22682 | tries for any one delivery. Section <<SECTvalhosmax>> describes its use and why | |
22683 | it exists. | |
22684 | ||
22685 | ||
22686 | ||
22687 | oindex:[%hosts_nopass_tls%] | |
22688 | `..'= | |
22689 | %hosts_nopass_tls%, Use: 'smtp', Type: 'host list'!!, Default: 'unset' | |
22690 | === | |
22691 | ||
22692 | cindex:[TLS,passing connection] | |
22693 | cindex:[multiple SMTP deliveries] | |
22694 | cindex:[TLS,multiple message deliveries] | |
22695 | For any host that matches this list, a connection on which a TLS session has | |
22696 | been started will not be passed to a new delivery process for sending another | |
22697 | message on the same connection. See section <<SECTmulmessam>> for an explanation | |
22698 | of when this might be needed. | |
22699 | ||
22700 | ||
22701 | oindex:[%hosts_override%] | |
22702 | `..'= | |
22703 | %hosts_override%, Use: 'smtp', Type: 'boolean', Default: 'false' | |
22704 | === | |
22705 | ||
22706 | If this option is set and the %hosts% option is also set, any hosts that are | |
22707 | attached to the address are ignored, and instead the hosts specified by the | |
22708 | %hosts% option are always used. This option does not apply to | |
22709 | %fallback_hosts%. | |
22710 | ||
22711 | ||
22712 | oindex:[%hosts_randomize%] | |
22713 | `..'= | |
22714 | %hosts_randomize%, Use: 'smtp', Type: 'boolean', Default: 'false' | |
22715 | === | |
22716 | ||
22717 | cindex:[randomized host list] | |
22718 | cindex:[host,list of; randomized] | |
22719 | cindex:[fallback,randomized hosts] | |
22720 | If this option is set, and either the list of hosts is taken from the | |
22721 | %hosts% or the %fallback_hosts% option, or the hosts supplied by the router | |
22722 | were not obtained from MX records (this includes fallback hosts from the | |
22723 | router), and were not randomizied by the router, the order of trying the hosts | |
22724 | is randomized each time the transport runs. Randomizing the order of a host | |
22725 | list can be used to do crude load sharing. | |
22726 | ||
22727 | When %hosts_randomize% is true, a host list may be split into groups whose | |
22728 | order is separately randomized. This makes it possible to set up MX-like | |
22729 | behaviour. The boundaries between groups are indicated by an item that is just | |
22730 | `+` in the host list. For example: | |
22731 | ||
22732 | hosts = host1:host2:host3:+:host4:host5 | |
22733 | ||
22734 | The order of the first three hosts and the order of the last two hosts is | |
22735 | randomized for each use, but the first three always end up before the last two. | |
22736 | If %hosts_randomize% is not set, a `+` item in the list is ignored. | |
22737 | ||
22738 | oindex:[%hosts_require_auth%] | |
22739 | `..'= | |
22740 | %hosts_require_auth%, Use: 'smtp', Type: 'host list'!!, Default: 'unset' | |
22741 | === | |
22742 | ||
22743 | cindex:[authentication,required by client] | |
22744 | This option provides a list of servers for which authentication must succeed | |
22745 | before Exim will try to transfer a message. If authentication fails for | |
22746 | servers which are not in this list, Exim tries to send unauthenticated. If | |
22747 | authentication fails for one of these servers, delivery is deferred. This | |
22748 | temporary error is detectable in the retry rules, so it can be turned into a | |
22749 | hard failure if required. See also %hosts_try_auth%, and chapter | |
22750 | <<CHAPSMTPAUTH>> for details of authentication. | |
22751 | ||
22752 | ||
22753 | oindex:[%hosts_require_tls%] | |
22754 | `..'= | |
22755 | %hosts_require_tls%, Use: 'smtp', Type: 'host list'!!, Default: 'unset' | |
22756 | === | |
22757 | ||
22758 | cindex:[TLS,requiring for certain servers] | |
22759 | Exim will insist on using a TLS session when delivering to any host that | |
22760 | matches this list. See chapter <<CHAPTLS>> for details of TLS. | |
22761 | *Note*: This option affects outgoing mail only. To insist on TLS for | |
22762 | incoming messages, use an appropriate ACL. | |
22763 | ||
22764 | oindex:[%hosts_try_auth%] | |
22765 | `..'= | |
22766 | %hosts_try_auth%, Use: 'smtp', Type: 'host list'!!, Default: 'unset' | |
22767 | === | |
22768 | ||
22769 | cindex:[authentication,optional in client] | |
22770 | This option provides a list of servers to which, provided they announce | |
22771 | authentication support, Exim will attempt to authenticate as a client when it | |
22772 | connects. If authentication fails, Exim will try to transfer the message | |
22773 | unauthenticated. See also %hosts_require_auth%, and chapter <<CHAPSMTPAUTH>> | |
22774 | for details of authentication. | |
22775 | ||
22776 | oindex:[%interface%] | |
22777 | `..'= | |
22778 | %interface%, Use: 'smtp', Type: 'string list'!!, Default: 'unset' | |
22779 | === | |
22780 | ||
22781 | cindex:[bind IP address] | |
22782 | cindex:[IP address,binding] | |
068aaea8 PH |
22783 | cindex:[$host$] |
22784 | cindex:[$host_address$] | |
168e428f PH |
22785 | This option specifies which interface to bind to when making an outgoing SMTP |
22786 | call. The variables $host$ and $host_address$ refer to the host to which a | |
22787 | connection is about to be made during the expansion of the string. Forced | |
22788 | expansion failure, or an empty string result causes the option to be ignored. | |
22789 | Otherwise, after expansion, | |
22790 | the string must be a list of IP addresses, colon-separated by default, but the | |
22791 | separator can be changed in the usual way. | |
22792 | For example: | |
22793 | ||
22794 | interface = <; 192.168.123.123 ; 3ffe:ffff:836f::fe86:a061 | |
22795 | ||
22796 | The first interface of the correct type (IPv4 or IPv6) is used for the outgoing | |
22797 | connection. If none of them are the correct type, the option is ignored. If | |
22798 | %interface% is not set, or is ignored, the system's IP functions choose which | |
22799 | interface to use if the host has more than one. | |
22800 | ||
22801 | ||
22802 | oindex:[%keepalive%] | |
22803 | `..'= | |
22804 | %keepalive%, Use: 'smtp', Type: 'boolean', Default: 'true' | |
22805 | === | |
22806 | ||
22807 | cindex:[keepalive,on outgoing connection] | |
22808 | This option controls the setting of SO_KEEPALIVE on outgoing TCP/IP socket | |
22809 | connections. When set, it causes the kernel to probe idle connections | |
22810 | periodically, by sending packets with ``old'' sequence numbers. The other end of | |
22811 | the connection should send a acknowledgement if the connection is still okay or | |
22812 | a reset if the connection has been aborted. The reason for doing this is that | |
22813 | it has the beneficial effect of freeing up certain types of connection that can | |
22814 | get stuck when the remote host is disconnected without tidying up the TCP/IP | |
22815 | call properly. The keepalive mechanism takes several hours to detect | |
22816 | unreachable hosts. | |
22817 | ||
22818 | ||
068aaea8 PH |
22819 | oindex:[%lmtp_ignore_quota%] |
22820 | `..'= | |
22821 | %lmtp_ignore_quota%, Use: 'smtp', Type: 'boolean', Default: 'false' | |
22822 | === | |
22823 | ||
22824 | [revisionflag="changed"] | |
22825 | cindex:[LMTP,ignoring quota errors] | |
22826 | If this option is set true when the %protocol% option is set to ``lmtp'', the | |
22827 | string `IGNOREQUOTA` is added to RCPT commands, provided that the LMTP server | |
22828 | has advertised support for IGNOREQUOTA in its response to the LHLO command. | |
22829 | ||
22830 | ||
168e428f PH |
22831 | oindex:[%max_rcpt%] |
22832 | `..'= | |
22833 | %max_rcpt%, Use: 'smtp', Type: 'integer', Default: '100' | |
22834 | === | |
22835 | ||
22836 | cindex:[RCPT,maximum number of outgoing] | |
22837 | This option limits the number of RCPT commands that are sent in a single | |
22838 | SMTP message transaction. Each set of addresses is treated independently, and | |
22839 | so can cause parallel connections to the same host if %remote_max_parallel% | |
22840 | permits this. | |
22841 | ||
22842 | ||
22843 | oindex:[%multi_domain%] | |
22844 | `..'= | |
22845 | %multi_domain%, Use: 'smtp', Type: 'boolean', Default: 'true' | |
22846 | === | |
22847 | ||
068aaea8 | 22848 | cindex:[$domain$] |
168e428f PH |
22849 | When this option is set, the ^smtp^ transport can handle a number of addresses |
22850 | containing a mixture of different domains provided they all resolve to the same | |
22851 | list of hosts. Turning the option off restricts the transport to handling only | |
22852 | one domain at a time. This is useful if you want to use $domain$ in an | |
22853 | expansion for the transport, because it is set only when there is a single | |
22854 | domain involved in a remote delivery. | |
22855 | ||
22856 | ||
22857 | oindex:[%port%] | |
22858 | `..'= | |
22859 | %port%, Use: 'smtp', Type: 'string'!!, Default: 'see below' | |
22860 | === | |
22861 | ||
22862 | cindex:[port,sending TCP/IP] | |
22863 | cindex:[TCP/IP,setting outgoing port] | |
22864 | This option specifies the TCP/IP port on the server to which Exim connects. If | |
22865 | it begins with a digit it is taken as a port number; otherwise it is looked up | |
22866 | using 'getservbyname()'. The default value is normally ``smtp'', but if | |
22867 | %protocol% is set to ``lmtp'', the default is ``lmtp''. | |
22868 | If the expansion fails, or if a port number cannot be found, delivery is | |
22869 | deferred. | |
22870 | ||
22871 | ||
22872 | ||
22873 | oindex:[%protocol%] | |
22874 | `..'= | |
22875 | %protocol%, Use: 'smtp', Type: 'string', Default: 'smtp' | |
22876 | === | |
22877 | ||
22878 | cindex:[LMTP,over TCP/IP] | |
22879 | If this option is set to ``lmtp'' instead of ``smtp'', the default value for the | |
22880 | %port% option changes to ``lmtp'', and the transport operates the LMTP protocol | |
22881 | (RFC 2033) instead of SMTP. This protocol is sometimes used for local | |
22882 | deliveries into closed message stores. Exim also has support for running LMTP | |
22883 | over a pipe to a local process -- see chapter <<CHAPLMTP>>. | |
22884 | ||
22885 | ||
22886 | oindex:[%retry_include_ip_address%] | |
22887 | `..'= | |
22888 | %retry_include_ip_address%, Use: 'smtp', Type: 'boolean', Default: 'true' | |
22889 | === | |
22890 | ||
22891 | Exim normally includes both the host name and the IP address in the key it | |
22892 | constructs for indexing retry data after a temporary delivery failure. This | |
22893 | means that when one of several IP addresses for a host is failing, it gets | |
22894 | tried periodically (controlled by the retry rules), but use of the other IP | |
22895 | addresses is not affected. | |
22896 | ||
22897 | However, in some dialup environments hosts are assigned a different IP address | |
22898 | each time they connect. In this situation the use of the IP address as part of | |
22899 | the retry key leads to undesirable behaviour. Setting this option false causes | |
22900 | Exim to use only the host name. This should normally be done on a separate | |
22901 | instance of the ^smtp^ transport, set up specially to handle the dialup hosts. | |
22902 | ||
22903 | ||
22904 | oindex:[%serialize_hosts%] | |
22905 | `..'= | |
22906 | %serialize_hosts%, Use: 'smtp', Type: 'host list'!!, Default: 'unset' | |
22907 | === | |
22908 | ||
22909 | cindex:[serializing connections] | |
22910 | cindex:[host,serializing connections] | |
22911 | Because Exim operates in a distributed manner, if several messages for the same | |
22912 | host arrive at around the same time, more than one simultaneous connection to | |
22913 | the remote host can occur. This is not usually a problem except when there is a | |
22914 | slow link between the hosts. In that situation it may be helpful to restrict | |
22915 | Exim to one connection at a time. This can be done by setting | |
22916 | %serialize_hosts% to match the relevant hosts. | |
22917 | ||
22918 | cindex:[hints database,serializing deliveries to a host] | |
22919 | Exim implements serialization by means of a hints database in which a record is | |
22920 | written whenever a process connects to one of the restricted hosts. The record | |
22921 | is deleted when the connection is completed. Obviously there is scope for | |
22922 | records to get left lying around if there is a system or program crash. To | |
22923 | guard against this, Exim ignores any records that are more than six hours old. | |
22924 | ||
22925 | If you set up this kind of serialization, you should also arrange to delete the | |
22926 | relevant hints database whenever your system reboots. The names of the files | |
22927 | start with _misc_ and they are kept in the _spool/db_ directory. There | |
22928 | may be one or two files, depending on the type of DBM in use. The same files | |
22929 | are used for ETRN serialization. | |
22930 | ||
22931 | ||
22932 | oindex:[%size_addition%] | |
22933 | `..'= | |
22934 | %size_addition%, Use: 'smtp', Type: 'integer', Default: '1024' | |
22935 | === | |
22936 | ||
22937 | cindex:[SMTP,SIZE] | |
22938 | cindex:[message,size issue for transport filter] | |
22939 | cindex:[size,of message] | |
22940 | cindex:[transport,filter] | |
22941 | cindex:[filter,transport filter] | |
22942 | If a remote SMTP server indicates that it supports the SIZE option of the | |
22943 | MAIL command, Exim uses this to pass over the message size at the start of | |
22944 | an SMTP transaction. It adds the value of %size_addition% to the value it | |
22945 | sends, to allow for headers and other text that may be added during delivery by | |
22946 | configuration options or in a transport filter. It may be necessary to increase | |
22947 | this if a lot of text is added to messages. | |
22948 | ||
22949 | Alternatively, if the value of %size_addition% is set negative, it disables | |
22950 | the use of the SIZE option altogether. | |
22951 | ||
22952 | ||
22953 | oindex:[%tls_certificate%] | |
22954 | `..'= | |
22955 | %tls_certificate%, Use: 'smtp', Type: 'string'!!, Default: 'unset' | |
22956 | === | |
22957 | ||
22958 | cindex:[TLS client certificate, location of] | |
22959 | cindex:[certificate for client, location of] | |
068aaea8 PH |
22960 | cindex:[$host$] |
22961 | cindex:[$host_address$] | |
168e428f PH |
22962 | The value of this option must be the absolute path to a file which contains the |
22963 | client's certificate, for use when sending a message over an encrypted | |
22964 | connection. The values of $host$ and $host_address$ are set to the name | |
22965 | and address of the server during the expansion. See chapter <<CHAPTLS>> for | |
22966 | details of TLS. | |
22967 | ||
22968 | *Note*: This option must be set if you want Exim to use TLS when sending | |
22969 | messages as a client. The global option of the same name specifies the | |
22970 | certificate for Exim as a server; it is not automatically assumed that the same | |
22971 | certificate should be used when Exim is operating as a client. | |
22972 | ||
22973 | ||
22974 | oindex:[%tls_crl%] | |
22975 | `..'= | |
22976 | %tls_crl%, Use: 'smtp', Type: 'string'!!, Default: 'unset' | |
22977 | === | |
22978 | ||
22979 | cindex:[TLS,client certificate revocation list] | |
22980 | cindex:[certificate,revocation list for client] | |
22981 | This option specifies a certificate revocation list. The expanded value must | |
22982 | be the name of a file that contains a CRL in PEM format. | |
22983 | ||
22984 | ||
22985 | oindex:[%tls_privatekey%] | |
22986 | `..'= | |
22987 | %tls_privatekey%, Use: 'smtp', Type: 'string'!!, Default: 'unset' | |
22988 | === | |
22989 | ||
22990 | cindex:[TLS client private key, location of] | |
068aaea8 PH |
22991 | cindex:[$host$] |
22992 | cindex:[$host_address$] | |
168e428f PH |
22993 | The value of this option must be the absolute path to a file which contains the |
22994 | client's private key, for use when sending a message over an encrypted | |
22995 | connection. The values of $host$ and $host_address$ are set to the name | |
22996 | and address of the server during the expansion. | |
22997 | If this option is unset, the private key is assumed to be in the same file as | |
22998 | the certificate. | |
22999 | See chapter <<CHAPTLS>> for details of TLS. | |
23000 | ||
23001 | ||
23002 | oindex:[%tls_require_ciphers%] | |
23003 | `..'= | |
23004 | %tls_require_ciphers%, Use: 'smtp', Type: 'string'!!, Default: 'unset' | |
23005 | === | |
23006 | ||
23007 | cindex:[TLS,requiring specific ciphers] | |
23008 | cindex:[cipher,requiring specific] | |
068aaea8 PH |
23009 | cindex:[$host$] |
23010 | cindex:[$host_address$] | |
168e428f PH |
23011 | The value of this option must be a list of permitted cipher suites, for use |
23012 | when setting up an outgoing encrypted connection. (There is a global option of | |
23013 | the same name for controlling incoming connections.) The values of $host$ and | |
23014 | $host_address$ are set to the name and address of the server during the | |
23015 | expansion. See chapter <<CHAPTLS>> for details of TLS; note that this option is | |
23016 | used in different ways by OpenSSL and GnuTLS (see sections <<SECTreqciphssl>> | |
23017 | and <<SECTreqciphgnu>>). For GnuTLS, the order of the ciphers is a preference | |
23018 | order. | |
23019 | ||
23020 | ||
23021 | ||
23022 | oindex:[%tls_tempfail_tryclear%] | |
23023 | `..'= | |
23024 | %tls_tempfail_tryclear%, Use: 'smtp', Type: 'boolean', Default: 'true' | |
23025 | === | |
23026 | ||
23027 | When the server host is not in %hosts_require_tls%, and there is a problem in | |
23028 | setting up a TLS session, this option determines whether or not Exim should try | |
23029 | to deliver the message unencrypted. If it is set false, delivery to the | |
23030 | current host is deferred; if there are other hosts, they are tried. If this | |
23031 | option is set true, Exim attempts to deliver unencrypted after a 4##'xx' | |
23032 | response to STARTTLS. Also, if STARTTLS is accepted, but the subsequent | |
23033 | TLS negotiation fails, Exim closes the current connection (because it is in an | |
23034 | unknown state), opens a new one to the same host, and then tries the delivery | |
23035 | in clear. | |
23036 | ||
23037 | ||
23038 | oindex:[%tls_verify_certificates%] | |
23039 | `..'= | |
23040 | %tls_verify_certificates%, Use: 'smtp', Type: 'string'!!, Default: 'unset' | |
23041 | === | |
23042 | ||
23043 | cindex:[TLS,server certificate verification] | |
23044 | cindex:[certificate,verification of server] | |
068aaea8 PH |
23045 | cindex:[$host$] |
23046 | cindex:[$host_address$] | |
168e428f PH |
23047 | The value of this option must be the absolute path to a file containing |
23048 | permitted server certificates, for use when setting up an encrypted connection. | |
23049 | Alternatively, if you are using OpenSSL, you can set | |
23050 | %tls_verify_certificates% to the name of a directory containing certificate | |
23051 | files. This does not work with GnuTLS; the option must be set to the name of a | |
23052 | single file if you are using GnuTLS. The values of $host$ and | |
23053 | $host_address$ are set to the name and address of the server during the | |
23054 | expansion of this option. See chapter <<CHAPTLS>> for details of TLS. | |
23055 | ||
23056 | ||
23057 | ||
23058 | ||
23059 | [[SECTvalhosmax]] | |
23060 | How the limits for the number of hosts to try are used | |
23061 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
23062 | cindex:[host,maximum number to try] | |
23063 | cindex:[limit,hosts; maximum number tried] | |
23064 | There are two options that are concerned with the number of hosts that are | |
23065 | tried when an SMTP delivery takes place. They are %hosts_max_try% and | |
23066 | %hosts_max_try_hardlimit%. | |
23067 | ||
23068 | ||
23069 | The %hosts_max_try% option limits the number of hosts that are tried | |
23070 | for a single delivery. However, despite the term ``host'' in its name, the option | |
23071 | actually applies to each IP address independently. In other words, a multihomed | |
23072 | host is treated as several independent hosts, just as it is for retrying. | |
23073 | ||
23074 | Many of the larger ISPs have multiple MX records which often point to | |
23075 | multihomed hosts. As a result, a list of a dozen or more IP addresses may be | |
23076 | created as a result of routing one of these domains. | |
23077 | ||
23078 | Trying every single IP address on such a long list does not seem sensible; if | |
23079 | several at the top of the list fail, it is reasonable to assume there is some | |
23080 | problem that is likely to affect all of them. Roughly speaking, the value of | |
23081 | %hosts_max_try% is the maximum number that are tried before deferring the | |
23082 | delivery. However, the logic cannot be quite that simple. | |
23083 | ||
23084 | Firstly, IP addresses that are skipped because their retry times have not | |
23085 | arrived do not count, and in addition, addresses that are past their retry | |
23086 | limits are also not counted, even when they are tried. This means that when | |
23087 | some IP addresses are past their retry limits, more than the value of | |
23088 | %hosts_max_retry% may be tried. The reason for this behaviour is to ensure | |
23089 | that all IP addresses are considered before timing out an email address (but | |
23090 | see below for an exception). | |
23091 | ||
23092 | Secondly, when the %hosts_max_try% limit is reached, Exim looks down the host | |
23093 | list to see if there is a subsequent host with a different (higher valued) MX. | |
23094 | If there is, that host is considered next, and the current IP address is used | |
23095 | but not counted. This behaviour helps in the case of a domain with a retry rule | |
23096 | that hardly ever delays any hosts, as is now explained: | |
23097 | ||
23098 | Consider the case of a long list of hosts with one MX value, and a few with a | |
23099 | higher MX value. If %hosts_max_try% is small (the default is 5) only a few | |
23100 | hosts at the top of the list are tried at first. With the default retry rule, | |
23101 | which specifies increasing retry times, the higher MX hosts are eventually | |
23102 | tried when those at the top of the list are skipped because they have not | |
23103 | reached their retry times. | |
23104 | ||
23105 | However, it is common practice to put a fixed short retry time on domains for | |
23106 | large ISPs, on the grounds that their servers are rarely down for very long. | |
23107 | Unfortunately, these are exactly the domains that tend to resolve to long lists | |
23108 | of hosts. The short retry time means that the lowest MX hosts are tried every | |
23109 | time. The attempts may be in a different order because of random sorting, but | |
23110 | without the special MX check, the higher MX hosts would never be tried | |
23111 | ||
23112 | until all the lower MX hosts had timed out (which might be several days), | |
23113 | because there are always some lower MX hosts that have reached their retry | |
23114 | times. With the special check, Exim considers at least one IP address from each | |
23115 | MX value at every delivery attempt, even if the %hosts_max_try% limit has | |
23116 | already been reached. | |
23117 | ||
23118 | The above logic means that %hosts_max_try% is not a hard limit, and in | |
23119 | particular, Exim normally eventually tries all the IP addresses before timing | |
23120 | out an email address. When %hosts_max_try% was implemented, this seemed a | |
23121 | reasonable thing to do. Recently, however, some lunatic DNS configurations have | |
23122 | been set up with hundreds of IP addresses for some domains. It can | |
23123 | take a very long time indeed for an address to time out in these cases. | |
23124 | ||
23125 | The %hosts_max_try_hardlimit% option was added to help with this problem. | |
23126 | Exim never tries more than this number of IP addresses; if it hits this limit | |
23127 | and they are all timed out, the email address is bounced, even though not all | |
23128 | possible IP addresses have been tried. | |
23129 | ||
23130 | ||
23131 | ||
23132 | ||
23133 | ||
23134 | //////////////////////////////////////////////////////////////////////////// | |
23135 | //////////////////////////////////////////////////////////////////////////// | |
23136 | ||
23137 | [[CHAPrewrite]] | |
23138 | Address rewriting | |
23139 | ----------------- | |
23140 | cindex:[rewriting,addresses] | |
23141 | There are some circumstances in which Exim automatically rewrites domains in | |
23142 | addresses. The two most common are when an address is given without a domain | |
23143 | (referred to as an ``unqualified address'') or when an address contains an | |
23144 | abbreviated domain that is expanded by DNS lookup. | |
23145 | ||
23146 | Unqualified envelope addresses are accepted only for locally submitted | |
23147 | messages, or messages from hosts that match %sender_unqualified_hosts% or | |
23148 | %recipient_unqualified_hosts%, respectively. Unqualified addresses in header | |
23149 | lines are qualified if they are in locally submitted messages, or messages from | |
23150 | hosts that are permitted to send unqualified envelope addresses. Otherwise, | |
23151 | unqualified addresses in header lines are neither qualified nor rewritten. | |
23152 | ||
23153 | One situation in which Exim does 'not' automatically rewrite a domain is | |
23154 | when it is the name of a CNAME record in the DNS. The older RFCs suggest that | |
23155 | such a domain should be rewritten using the ``canonical'' name, and some MTAs do | |
23156 | this. The new RFCs do not contain this suggestion. | |
23157 | ||
23158 | ||
23159 | Explicitly configured address rewriting | |
23160 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
23161 | This chapter describes the rewriting rules that can be used in the | |
23162 | main rewrite section of the configuration file, and also in the generic | |
23163 | %headers_rewrite% option that can be set on any transport. | |
23164 | ||
23165 | Some people believe that configured address rewriting is a Mortal Sin. | |
23166 | Others believe that life is not possible without it. Exim provides the | |
23167 | facility; you do not have to use it. | |
23168 | ||
23169 | The main rewriting rules that appear in the ``rewrite'' section of the | |
23170 | configuration file are applied to addresses in incoming messages, both envelope | |
23171 | addresses and addresses in header lines. Each rule specifies the types of | |
23172 | address to which it applies. | |
23173 | ||
23174 | Rewriting of addresses in header lines applies only to those headers that | |
23175 | were received with the message, and, in the case of transport rewriting, those | |
23176 | that were added by a system filter. That is, it applies only to those headers | |
23177 | that are common to all copies of the message. Header lines that are added by | |
23178 | individual routers or transports (and which are therefore specific to | |
23179 | individual recipient addresses) are not rewritten. | |
23180 | ||
23181 | In general, rewriting addresses from your own system or domain has some | |
23182 | legitimacy. Rewriting other addresses should be done only with great care and | |
23183 | in special circumstances. The author of Exim believes that rewriting should be | |
23184 | used sparingly, and mainly for ``regularizing'' addresses in your own domains. | |
23185 | Although it can sometimes be used as a routing tool, this is very strongly | |
23186 | discouraged. | |
23187 | ||
23188 | There are two commonly encountered circumstances where rewriting is used, as | |
23189 | illustrated by these examples: | |
23190 | ||
23191 | - The company whose domain is 'hitch.fict.example' has a number of hosts that | |
23192 | exchange mail with each other behind a firewall, but there is only a single | |
23193 | gateway to the outer world. The gateway rewrites '*.hitch.fict.example' as | |
23194 | 'hitch.fict.example' when sending mail off-site. | |
23195 | ||
23196 | - A host rewrites the local parts of its own users so that, for example, | |
23197 | 'fp42@hitch.fict.example' becomes 'Ford.Prefect@hitch.fict.example'. | |
23198 | ||
23199 | ||
23200 | ||
23201 | When does rewriting happen? | |
23202 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
23203 | cindex:[rewriting,timing of] | |
23204 | cindex:[{ACL},rewriting addresses in] | |
23205 | Configured address rewriting can take place at several different stages of a | |
23206 | message's processing. | |
23207 | ||
068aaea8 | 23208 | cindex:[$sender_address$] |
168e428f PH |
23209 | At the start of an ACL for MAIL, the sender address may have been rewritten |
23210 | by a special SMTP-time rewrite rule (see section <<SECTrewriteS>>), but no | |
23211 | ordinary rewrite rules have yet been applied. If, however, the sender address | |
23212 | is verified in the ACL, it is rewritten before verification, and remains | |
23213 | rewritten thereafter. The subsequent value of $sender_address$ is the | |
23214 | rewritten address. This also applies if sender verification happens in a | |
23215 | RCPT ACL. Otherwise, when the sender address is not verified, it is | |
23216 | rewritten as soon as a message's header lines have been received. | |
23217 | ||
068aaea8 PH |
23218 | cindex:[$domain$] |
23219 | cindex:[$local_part$] | |
168e428f PH |
23220 | Similarly, at the start of an ACL for RCPT, the current recipient's address |
23221 | may have been rewritten by a special SMTP-time rewrite rule, but no ordinary | |
23222 | rewrite rules have yet been applied to it. However, the behaviour is different | |
23223 | from the sender address when a recipient is verified. The address is rewritten | |
23224 | for the verification, but the rewriting is not remembered at this stage. The | |
23225 | value of $local_part$ and $domain$ after verification are always the same | |
23226 | as they were before (that is, they contain the unrewritten -- except for | |
23227 | SMTP-time rewriting -- address). | |
23228 | ||
23229 | Once a message's header lines have been received, all the envelope recipient | |
23230 | addresses are permanently rewritten, and rewriting is also applied to the | |
23231 | addresses in the header lines (if configured). | |
23232 | cindex:['local_scan()' function,address rewriting; timing of] | |
23233 | Thus, all the rewriting is completed before the DATA ACL and | |
23234 | 'local_scan()' functions are run. | |
23235 | ||
23236 | When an address is being routed, either for delivery or for verification, | |
23237 | rewriting is applied immediately to child addresses that are generated by | |
23238 | redirection, unless %no_rewrite% is set on the router. | |
23239 | ||
23240 | cindex:[envelope sender, rewriting] | |
23241 | cindex:[rewriting,at transport time] | |
23242 | At transport time, additional rewriting of addresses in header lines can be | |
23243 | specified by setting the generic %headers_rewrite% option on a transport. This | |
23244 | option contains rules that are identical in form to those in the rewrite | |
23245 | section of the configuration file. In addition, the outgoing envelope sender | |
23246 | can be rewritten by means of the %return_path% transport option. However, it | |
23247 | is not possible to rewrite envelope recipients at transport time. | |
23248 | ||
23249 | ||
23250 | ||
23251 | ||
23252 | Testing the rewriting rules that apply on input | |
23253 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
23254 | cindex:[rewriting,testing] | |
23255 | cindex:[testing,rewriting] | |
23256 | Exim's input rewriting configuration appears in a part of the run time | |
23257 | configuration file headed by ``begin rewrite''. It can be tested by the %-brw% | |
23258 | command line option. This takes an address (which can be a full RFC 2822 | |
23259 | address) as its argument. The output is a list of how the address would be | |
23260 | transformed by the rewriting rules for each of the different places it might | |
23261 | appear in an incoming message, that is, for each different header and for the | |
23262 | envelope sender and recipient fields. For example, | |
23263 | ||
23264 | exim -brw ph10@exim.workshop.example | |
23265 | ||
23266 | might produce the output | |
23267 | ||
23268 | sender: Philip.Hazel@exim.workshop.example | |
23269 | from: Philip.Hazel@exim.workshop.example | |
23270 | to: ph10@exim.workshop.example | |
23271 | cc: ph10@exim.workshop.example | |
23272 | bcc: ph10@exim.workshop.example | |
23273 | reply-to: Philip.Hazel@exim.workshop.example | |
23274 | env-from: Philip.Hazel@exim.workshop.example | |
23275 | env-to: ph10@exim.workshop.example | |
23276 | ||
23277 | which shows that rewriting has been set up for that address when used in any of | |
23278 | the source fields, but not when it appears as a recipient address. At the | |
23279 | present time, there is no equivalent way of testing rewriting rules that are | |
23280 | set for a particular transport. | |
23281 | ||
23282 | ||
23283 | Rewriting rules | |
23284 | ~~~~~~~~~~~~~~~ | |
23285 | cindex:[rewriting,rules] | |
23286 | The rewrite section of the configuration file consists of lines of rewriting | |
23287 | rules in the form | |
23288 | ||
23289 | <source pattern> <replacement> <flags> | |
23290 | ||
23291 | Rewriting rules that are specified for the %headers_rewrite% generic transport | |
23292 | option are given as a colon-separated list. Each item in the list takes the | |
23293 | same form as a line in the main rewriting configuration | |
23294 | (except that any colons must be doubled, of course). | |
23295 | ||
23296 | The formats of source patterns and replacement strings are described below. | |
23297 | Each is terminated by white space, unless enclosed in double quotes, in which | |
23298 | case normal quoting conventions apply inside the quotes. The flags are single | |
23299 | characters which may appear in any order. Spaces and tabs between them are | |
23300 | ignored. | |
23301 | ||
23302 | For each address that could potentially be rewritten, the rules are scanned in | |
23303 | order, and replacements for the address from earlier rules can themselves be | |
23304 | replaced by later rules (but see the ``q'' and ``R'' flags). | |
23305 | ||
23306 | The order in which addresses are rewritten is undefined, may change between | |
23307 | releases, and must not be relied on, with one exception: when a message is | |
23308 | received, the envelope sender is always rewritten first, before any header | |
23309 | lines are rewritten. For example, the replacement string for a rewrite of an | |
23310 | address in 'To:' must not assume that the message's address in 'From:' has (or | |
23311 | has not) already been rewritten. However, a rewrite of 'From:' may assume that | |
23312 | the envelope sender has already been rewritten. | |
23313 | ||
068aaea8 PH |
23314 | cindex:[$domain$] |
23315 | cindex:[$local_part$] | |
168e428f PH |
23316 | The variables $local_part$ and $domain$ can be used in the replacement |
23317 | string to refer to the address that is being rewritten. Note that lookup-driven | |
23318 | rewriting can be done by a rule of the form | |
23319 | ||
23320 | *@* ${lookup ... | |
23321 | ||
23322 | where the lookup key uses $1$ and $2$ or $local_part$ and $domain$ to | |
23323 | refer to the address that is being rewritten. | |
23324 | ||
23325 | ||
23326 | Rewriting patterns | |
23327 | ~~~~~~~~~~~~~~~~~~ | |
23328 | cindex:[rewriting,patterns] | |
23329 | cindex:[address list,in a rewriting pattern] | |
23330 | The source pattern in a rewriting rule is any item which may appear in an | |
23331 | address list (see section <<SECTaddresslist>>). It is in fact processed as a | |
23332 | single-item address list, which means that it is expanded before being tested | |
068aaea8 PH |
23333 | against the address. As always, if you use a regular expression as a pattern, |
23334 | you must take care to escape dollar and backslash characters, or use the `\N` | |
23335 | facility to suppress string expansion within the regular expression. | |
168e428f PH |
23336 | |
23337 | Domains in patterns should be given in lower case. Local parts in patterns are | |
23338 | case-sensitive. If you want to do case-insensitive matching of local parts, you | |
23339 | can use a regular expression that starts with `^(?i)`. | |
23340 | ||
23341 | cindex:[numerical variables ($1$ $2$ etc),in rewriting rules] | |
23342 | After matching, the numerical variables $1$, $2$, etc. may be set, | |
23343 | depending on the type of match which occurred. These can be used in the | |
23344 | replacement string to insert portions of the incoming address. $0$ always | |
23345 | refers to the complete incoming address. When a regular expression is used, the | |
23346 | numerical variables are set from its capturing subexpressions. For other types | |
23347 | of pattern they are set as follows: | |
23348 | ||
23349 | - If a local part or domain starts with an asterisk, the numerical variables | |
23350 | refer to the character strings matched by asterisks, with $1$ associated with | |
23351 | the first asterisk, and $2$ with the second, if present. For example, if the | |
23352 | pattern | |
23353 | ||
23354 | *queen@*.fict.example | |
23355 | + | |
23356 | is matched against the address 'hearts-queen@wonderland.fict.example' then | |
23357 | ||
23358 | $0 = hearts-queen@wonderland.fict.example | |
23359 | $1 = hearts- | |
23360 | $2 = wonderland | |
23361 | + | |
23362 | Note that if the local part does not start with an asterisk, but the domain | |
23363 | does, it is $1$ that contains the wild part of the domain. | |
23364 | ||
23365 | - If the domain part of the pattern is a partial lookup, the wild and fixed parts | |
23366 | of the domain are placed in the next available numerical variables. Suppose, | |
23367 | for example, that the address 'foo@bar.baz.example' is processed by a | |
23368 | rewriting rule of the form | |
23369 | ||
23370 | *@partial-dbm;/some/dbm/file <replacement string> | |
23371 | + | |
23372 | and the key in the file that matches the domain is `*.baz.example`. Then | |
23373 | ||
23374 | $1 = foo | |
23375 | $2 = bar | |
23376 | $3 = baz.example | |
23377 | + | |
23378 | If the address 'foo@baz.example' is looked up, this matches the same | |
23379 | wildcard file entry, and in this case $2$ is set to the empty string, but | |
23380 | $3$ is still set to 'baz.example'. If a non-wild key is matched in a | |
23381 | partial lookup, $2$ is again set to the empty string and $3$ is set to the | |
23382 | whole domain. For non-partial domain lookups, no numerical variables are set. | |
23383 | ||
23384 | ||
23385 | ||
23386 | Rewriting replacements | |
23387 | ~~~~~~~~~~~~~~~~~~~~~~ | |
23388 | cindex:[rewriting,replacements] | |
23389 | If the replacement string for a rule is a single asterisk, addresses that | |
23390 | match the pattern and the flags are 'not' rewritten, and no subsequent | |
23391 | rewriting rules are scanned. For example, | |
23392 | ||
23393 | hatta@lookingglass.fict.example * f | |
23394 | ||
23395 | specifies that 'hatta@lookingglass.fict.example' is never to be rewritten in | |
23396 | 'From:' headers. | |
23397 | ||
068aaea8 PH |
23398 | cindex:[$domain$] |
23399 | cindex:[$local_part$] | |
168e428f PH |
23400 | If the replacement string is not a single asterisk, it is expanded, and must |
23401 | yield a fully qualified address. Within the expansion, the variables | |
23402 | $local_part$ and $domain$ refer to the address that is being rewritten. | |
23403 | Any letters they contain retain their original case -- they are not lower | |
23404 | cased. The numerical variables are set up according to the type of pattern that | |
23405 | matched the address, as described above. If the expansion is forced to fail by | |
23406 | the presence of ``fail'' in a conditional or lookup item, rewriting by the | |
23407 | current rule is abandoned, but subsequent rules may take effect. Any other | |
23408 | expansion failure causes the entire rewriting operation to be abandoned, and an | |
23409 | entry written to the panic log. | |
23410 | ||
23411 | ||
23412 | ||
23413 | Rewriting flags | |
23414 | ~~~~~~~~~~~~~~~ | |
23415 | There are three different kinds of flag that may appear on rewriting rules: | |
23416 | ||
23417 | - Flags that specify which headers and envelope addresses to rewrite: E, F, T, b, | |
23418 | c, f, h, r, s, t. | |
23419 | ||
23420 | - A flag that specifies rewriting at SMTP time: S. | |
23421 | ||
23422 | - Flags that control the rewriting process: Q, q, R, w. | |
23423 | ||
23424 | For rules that are part of the %headers_rewrite% generic transport option, | |
23425 | E, F, T, and S are not permitted. | |
23426 | ||
23427 | ||
23428 | ||
23429 | Flags specifying which headers and envelope addresses to rewrite | |
23430 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
23431 | cindex:[rewriting,flags] | |
23432 | If none of the following flag letters, nor the ``S'' flag (see section | |
23433 | <<SECTrewriteS>>) are present, a main rewriting rule applies to all headers and | |
23434 | to both the sender and recipient fields of the envelope, whereas a | |
23435 | transport-time rewriting rule just applies to all headers. Otherwise, the | |
23436 | rewriting rule is skipped unless the relevant addresses are being processed. | |
23437 | ||
23438 | &&& | |
23439 | `E` rewrite all envelope fields | |
23440 | `F` rewrite the envelope From field | |
23441 | `T` rewrite the envelope To field | |
23442 | `b` rewrite the 'Bcc:' header | |
23443 | `c` rewrite the 'Cc:' header | |
23444 | `f` rewrite the 'From:' header | |
23445 | `h` rewrite all headers | |
23446 | `r` rewrite the 'Reply-To:' header | |
23447 | `s` rewrite the 'Sender:' header | |
23448 | `t` rewrite the 'To:' header | |
23449 | &&& | |
23450 | ||
23451 | You should be particularly careful about rewriting 'Sender:' headers, and | |
23452 | restrict this to special known cases in your own domains. | |
23453 | ||
23454 | ||
23455 | [[SECTrewriteS]] | |
23456 | The SMTP-time rewriting flag | |
23457 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
23458 | cindex:[SMTP,rewriting malformed addresses] | |
23459 | cindex:[RCPT,rewriting argument of] | |
23460 | cindex:[MAIL,rewriting argument of] | |
23461 | The rewrite flag ``S'' specifies a rewrite of incoming envelope addresses at SMTP | |
23462 | time, as soon as an address is received in a MAIL or RCPT command, and | |
23463 | before any other processing; even before syntax checking. The pattern is | |
23464 | required to be a regular expression, and it is matched against the whole of the | |
23465 | data for the command, including any surrounding angle brackets. | |
23466 | ||
068aaea8 PH |
23467 | cindex:[$domain$] |
23468 | cindex:[$local_part$] | |
168e428f PH |
23469 | This form of rewrite rule allows for the handling of addresses that are not |
23470 | compliant with RFCs 2821 and 2822 (for example, ``bang paths'' in batched SMTP | |
23471 | input). Because the input is not required to be a syntactically valid address, | |
23472 | the variables $local_part$ and $domain$ are not available during the | |
23473 | expansion of the replacement string. The result of rewriting replaces the | |
23474 | original address in the MAIL or RCPT command. | |
23475 | ||
23476 | ||
23477 | Flags controlling the rewriting process | |
23478 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
23479 | There are four flags which control the way the rewriting process works. These | |
23480 | take effect only when a rule is invoked, that is, when the address is of the | |
23481 | correct type (matches the flags) and matches the pattern: | |
23482 | ||
23483 | - If the ``Q'' flag is set on a rule, the rewritten address is permitted to be an | |
23484 | unqualified local part. It is qualified with %qualify_recipient%. In the | |
23485 | absence of ``Q'' the rewritten address must always include a domain. | |
23486 | ||
23487 | - If the ``q'' flag is set on a rule, no further rewriting rules are considered, | |
23488 | even if no rewriting actually takes place because of a ``fail'' in the expansion. | |
23489 | The ``q'' flag is not effective if the address is of the wrong type (does not | |
23490 | match the flags) or does not match the pattern. | |
23491 | ||
23492 | - The ``R'' flag causes a successful rewriting rule to be re-applied to the new | |
23493 | address, up to ten times. It can be combined with the ``q'' flag, to stop | |
23494 | rewriting once it fails to match (after at least one successful rewrite). | |
23495 | ||
23496 | - cindex:[rewriting,whole addresses] | |
23497 | When an address in a header is rewritten, the rewriting normally applies only | |
23498 | to the working part of the address, with any comments and RFC 2822 ``phrase'' | |
23499 | left unchanged. For example, rewriting might change | |
23500 | ||
23501 | From: Ford Prefect <fp42@restaurant.hitch.fict.example> | |
23502 | + | |
23503 | into | |
23504 | ||
23505 | From: Ford Prefect <prefectf@hitch.fict.example> | |
23506 | + | |
d1e83bff | 23507 | cindex:[RFC 2047] |
168e428f PH |
23508 | Sometimes there is a need to replace the whole address item, and this can be |
23509 | done by adding the flag letter ``w'' to a rule. If this is set on a rule that | |
23510 | causes an address in a header line to be rewritten, the entire address is | |
23511 | replaced, not just the working part. The replacement must be a complete RFC | |
23512 | 2822 address, including the angle brackets if necessary. If text outside angle | |
23513 | brackets contains a character whose value is greater than 126 or less than 32 | |
d1e83bff PH |
23514 | (except for tab), the text is encoded according to RFC 2047. The character set |
23515 | is taken from %headers_charset%, which defaults to ISO-8859-1. | |
168e428f PH |
23516 | + |
23517 | When the ``w'' flag is set on a rule that causes an envelope address to be | |
23518 | rewritten, all but the working part of the replacement address is discarded. | |
23519 | ||
23520 | ||
23521 | ||
23522 | Rewriting examples | |
23523 | ~~~~~~~~~~~~~~~~~~ | |
23524 | Here is an example of the two common rewriting paradigms: | |
23525 | ||
23526 | .... | |
23527 | *@*.hitch.fict.example $1@hitch.fict.example | |
23528 | *@hitch.fict.example ${lookup{$1}dbm{/etc/realnames}\ | |
23529 | {$value}fail}@hitch.fict.example bctfrF | |
23530 | .... | |
23531 | ||
23532 | Note the use of ``fail'' in the lookup expansion in the second rule, forcing | |
23533 | the string expansion to fail if the lookup does not succeed. In this context it | |
23534 | has the effect of leaving the original address unchanged, but Exim goes on to | |
23535 | consider subsequent rewriting rules, if any, because the ``q'' flag is not | |
23536 | present in that rule. An alternative to ``fail'' would be to supply $1$ | |
23537 | explicitly, which would cause the rewritten address to be the same as before, | |
23538 | at the cost of a small bit of processing. Not supplying either of these is an | |
23539 | error, since the rewritten address would then contain no local part. | |
23540 | ||
23541 | The first example above replaces the domain with a superior, more general | |
23542 | domain. This may not be desirable for certain local parts. If the rule | |
23543 | ||
23544 | root@*.hitch.fict.example * | |
23545 | ||
23546 | were inserted before the first rule, rewriting would be suppressed for the | |
23547 | local part 'root' at any domain ending in 'hitch.fict.example'. | |
23548 | ||
23549 | Rewriting can be made conditional on a number of tests, by making use of | |
23550 | $\{if$ in the expansion item. For example, to apply a rewriting rule only to | |
23551 | messages that originate outside the local host: | |
23552 | ||
23553 | .... | |
23554 | *@*.hitch.fict.example "${if !eq {$sender_host_address}{}\ | |
23555 | {$1@hitch.fict.example}fail}" | |
23556 | .... | |
23557 | ||
23558 | The replacement string is quoted in this example because it contains white | |
23559 | space. | |
23560 | ||
23561 | cindex:[rewriting,bang paths] | |
23562 | cindex:[bang paths,rewriting] | |
23563 | Exim does not handle addresses in the form of ``bang paths''. If it sees such an | |
23564 | address it treats it as an unqualified local part which it qualifies with the | |
23565 | local qualification domain (if the source of the message is local or if the | |
23566 | remote host is permitted to send unqualified addresses). Rewriting can | |
23567 | sometimes be used to handle simple bang paths with a fixed number of | |
23568 | components. For example, the rule | |
23569 | ||
23570 | \N^([^!]+)!(.*)@your.domain.example$\N $2@$1 | |
23571 | ||
23572 | rewrites a two-component bang path 'host.name!user' as the domain address | |
23573 | 'user@host.name'. However, there is a security implication in using this as | |
23574 | a global rewriting rule for envelope addresses. It can provide a backdoor | |
23575 | method for using your system as a relay, because the incoming addresses appear | |
23576 | to be local. If the bang path addresses are received via SMTP, it is safer to | |
23577 | use the ``S'' flag to rewrite them as they are received, so that relay checking | |
23578 | can be done on the rewritten addresses. | |
23579 | ||
23580 | ||
23581 | ||
23582 | ||
23583 | ||
23584 | //////////////////////////////////////////////////////////////////////////// | |
23585 | //////////////////////////////////////////////////////////////////////////// | |
23586 | ||
23587 | [[CHAPretry]] | |
23588 | Retry configuration | |
23589 | ------------------- | |
23590 | cindex:[retry configuration, description of] | |
23591 | cindex:[configuration file,retry section] | |
23592 | The ``retry'' section of the run time configuration file contains a list of retry | |
23593 | rules which control how often Exim tries to deliver messages that cannot be | |
23594 | delivered at the first attempt. If there are no retry rules, temporary errors | |
23595 | are treated as permanent. The %-brt% command line option can be used to test | |
23596 | which retry rule will be used for a given address or domain. | |
23597 | ||
23598 | The most common cause of retries is temporary failure to deliver to a remote | |
23599 | host because the host is down, or inaccessible because of a network problem. | |
23600 | Exim's retry processing in this case is applied on a per-host (strictly, per IP | |
23601 | address) basis, not on a per-message basis. Thus, if one message has recently | |
23602 | been delayed, delivery of a new message to the same host is not immediately | |
23603 | tried, but waits for the host's retry time to arrive. If the %retry_defer% log | |
23604 | selector is set, the message | |
23605 | cindex:[retry,time not reached] | |
23606 | ``retry time not reached'' is written to the main log whenever a delivery is | |
23607 | skipped for this reason. Section <<SECToutSMTPerr>> contains more details of the | |
23608 | handling of errors during remote deliveries. | |
23609 | ||
23610 | Retry processing applies to routing as well as to delivering, except as covered | |
23611 | in the next paragraph. The retry rules do not distinguish between these | |
23612 | actions. It is not possible, for example, to specify different behaviour for | |
23613 | failures to route the domain 'snark.fict.example' and failures to deliver to | |
23614 | the host 'snark.fict.example'. I didn't think anyone would ever need this | |
23615 | added complication, so did not implement it. However, although they share the | |
23616 | same retry rule, the actual retry times for routing and transporting a given | |
23617 | domain are maintained independently. | |
23618 | ||
23619 | When a delivery is not part of a queue run (typically an immediate delivery on | |
23620 | receipt of a message), the routers are always run, and local deliveries are | |
23621 | always attempted, even if retry times are set for them. This makes for better | |
23622 | behaviour if one particular message is causing problems (for example, causing | |
23623 | quota overflow, or provoking an error in a filter file). If such a delivery | |
23624 | suffers a temporary failure, the retry data is updated as normal, and | |
23625 | subsequent delivery attempts from queue runs occur only when the retry time for | |
23626 | the local address is reached. | |
23627 | ||
23628 | ||
23629 | ||
23630 | Retry rules | |
23631 | ~~~~~~~~~~~ | |
23632 | cindex:[retry,rules] | |
23633 | Each retry rule occupies one line and consists of three or four parts, | |
23634 | separated by white space: a pattern, an error name, an optional list of sender | |
23635 | addresses, and a list of retry parameters. The pattern and sender lists must be | |
23636 | enclosed in double quotes if they contain white space. The rules are searched in | |
23637 | order until one is found where the pattern, error name, and sender list (if | |
23638 | present) match the failing host or address, the error that occurred, and the | |
23639 | message's sender, respectively. | |
23640 | ||
23641 | ||
23642 | The pattern is any single item that may appear in an address list (see section | |
23643 | <<SECTaddresslist>>). It is in fact processed as a one-item address list, which | |
23644 | means that it is expanded before being tested against the address that has | |
23645 | been delayed. Address list processing treats a plain domain name as if it were | |
23646 | preceded by ``\*@'', which makes it possible for many retry rules to start with | |
23647 | just a domain. For example, | |
23648 | ||
23649 | lookingglass.fict.example * F,24h,30m; | |
23650 | ||
23651 | provides a rule for any address in the 'lookingglass.fict.example' domain, | |
23652 | whereas | |
23653 | ||
23654 | alice@lookingglass.fict.example * F,24h,30m; | |
23655 | ||
23656 | applies only to temporary failures involving the local part %alice%. | |
23657 | In practice, almost all rules start with a domain name pattern without a local | |
23658 | part. | |
23659 | ||
23660 | cindex:[regular expressions,in retry rules] | |
23661 | *Warning*: If you use a regular expression in a routing rule pattern, it | |
23662 | must match a complete address, not just a domain, because that is how regular | |
23663 | expressions work in address lists. | |
23664 | ||
23665 | &&& | |
23666 | `\^\Nxyz\d+\.abc\.example\\$\N \* G,1h,10m,2` %Wrong% | |
23667 | `\^\N[^@]+@xyz\d+\.abc\.example\\$\N \* G,1h,10m,2` %Right% | |
23668 | &&& | |
23669 | ||
23670 | ||
23671 | ||
068aaea8 PH |
23672 | Choosing which retry rule to use for address errors |
23673 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
168e428f PH |
23674 | When Exim is looking for a retry rule after a routing attempt has failed (for |
23675 | example, after a DNS timeout), each line in the retry configuration is tested | |
23676 | against the complete address only if %retry_use_local_part% is set for the | |
23677 | router. Otherwise, only the domain is used, except when matching against a | |
23678 | regular expression, when the local part of the address is replaced with ``\*''. | |
23679 | A domain on its own can match a domain pattern, or a pattern that starts with | |
23680 | ``\*@''. By default, %retry_use_local_part% is true for routers where | |
23681 | %check_local_user% is true, and false for other routers. | |
23682 | ||
23683 | Similarly, when Exim is looking for a retry rule after a local delivery has | |
23684 | failed (for example, after a mailbox full error), each line in the retry | |
23685 | configuration is tested against the complete address only if | |
23686 | %retry_use_local_part% is set for the transport (it defaults true for all | |
23687 | local transports). | |
23688 | ||
23689 | When Exim is looking for a retry rule after a remote delivery attempt has | |
23690 | failed, what happens depends on the type of failure. After a 4##'xx' SMTP | |
23691 | response for a recipient address, the whole address is used when searching the | |
23692 | retry rules. The rule that is found is used to create a retry time for the | |
23693 | failing address. | |
23694 | ||
068aaea8 PH |
23695 | |
23696 | Choosing which retry rule to use for host errors | |
23697 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
23698 | For a temporary error that is not related to an individual address (for | |
23699 | example, a connection timeout), each line in the retry configuration is checked | |
23700 | twice. First, the name of the remote host is used as a domain name (preceded by | |
23701 | ``\*@'' when matching a regular expression). If this does not match the line, | |
23702 | the domain from the email address is tried in a similar fashion. For example, | |
23703 | suppose the MX records for 'a.b.c.example' are | |
168e428f PH |
23704 | |
23705 | a.b.c.example MX 5 x.y.z.example | |
23706 | MX 6 p.q.r.example | |
23707 | MX 7 m.n.o.example | |
23708 | ||
23709 | and the retry rules are | |
23710 | ||
23711 | p.q.r.example * F,24h,30m; | |
23712 | a.b.c.example * F,4d,45m; | |
23713 | ||
068aaea8 PH |
23714 | and a delivery to the host 'x.y.z.example' suffers a connection failure. The |
23715 | first rule matches neither the host nor the domain, so Exim looks at the second | |
23716 | rule. This does not match the host, but it does match the domain, so it is used | |
23717 | to calculate the retry time for the host 'x.y.z.example'. Meanwhile, Exim tries | |
23718 | to deliver to 'p.q.r.example'. If this also suffers a host error, the first | |
23719 | retry rule is used, because it matches the host. | |
168e428f | 23720 | |
068aaea8 PH |
23721 | In other words, temporary failures to deliver to host 'p.q.r.example' use the |
23722 | first rule to determine retry times, but for all the other hosts for the domain | |
168e428f PH |
23723 | 'a.b.c.example', the second rule is used. The second rule is also used if |
23724 | routing to 'a.b.c.example' suffers a temporary failure. | |
23725 | ||
068aaea8 PH |
23726 | [revisionflag="changed"] |
23727 | *Note*: the host name is used when matching the patterns, not its IP address. | |
23728 | However, if a message is routed directly to an IP address without the use of a | |
23729 | host name, for example, if a ^manualroute^ router contains a setting such as: | |
23730 | ||
23731 | route_list = *.a.example 192.168.34.23 | |
23732 | ||
23733 | then the ``host name'' that is used when searching for a retry rule is the | |
23734 | textual form of the IP address. | |
23735 | ||
168e428f PH |
23736 | |
23737 | Retry rules for specific errors | |
23738 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
23739 | cindex:[retry,specific errors; specifying] | |
23740 | The second field in a retry rule is the name of a particular error, or an | |
23741 | asterisk, which matches any error. The errors that can be tested for are: | |
23742 | ||
23743 | %auth_failed%:: | |
23744 | Authentication failed when trying to send to a host in the %hosts_require_auth% | |
23745 | list in an ^smtp^ transport. | |
23746 | ||
23747 | %rcpt_4xx%:: | |
23748 | A 4##'xx' error was received for an outgoing RCPT command. Either the first or | |
23749 | both of the x's can be given as specific digits, for example: `rcpt_45x` or | |
23750 | `rcpt_436`. For example, to recognize 452 errors given to RCPT commands by a | |
23751 | particular host, and have retries every ten minutes and a one-hour timeout, you | |
23752 | could set up a retry rule of this form: | |
23753 | ||
23754 | the.host.name rcpt_452 F,1h,10m | |
23755 | + | |
23756 | These errors apply to both outgoing SMTP (the ^smtp^ transport) and outgoing | |
23757 | LMTP (either the ^lmtp^ transport, or the ^smtp^ transport in LMTP mode). | |
23758 | Note, however, that they apply only to responses to RCPT commands. | |
23759 | ||
23760 | %refused_MX%:: | |
23761 | A connection to a host obtained from an MX record was refused. | |
23762 | ||
23763 | %refused_A%:: | |
23764 | A connection to a host not obtained from an MX record was refused. | |
23765 | ||
23766 | %refused%:: | |
23767 | A connection was refused. | |
23768 | ||
23769 | %timeout_connect_MX%:: | |
23770 | A connection attempt to a host obtained from an MX record timed out. | |
23771 | ||
23772 | %timeout_connect_A%:: | |
23773 | A connection attempt to a host not obtained from an MX record timed out. | |
23774 | ||
23775 | %timeout_connect%:: | |
23776 | A connection attempt timed out. | |
23777 | ||
23778 | %timeout_MX%:: | |
23779 | There was a timeout while connecting or during an SMTP session with a host | |
23780 | obtained from an MX record. | |
23781 | ||
23782 | %timeout_A%:: | |
23783 | There was a timeout while connecting or during an SMTP session with a host not | |
23784 | obtained from an MX record. | |
23785 | ||
23786 | %timeout%:: | |
23787 | There was a timeout while connecting or during an SMTP session. | |
23788 | ||
23789 | %quota%:: | |
23790 | A mailbox quota was exceeded in a local delivery by the ^appendfile^ transport. | |
23791 | ||
23792 | %quota_%<'time'>:: | |
23793 | cindex:[quota,error testing in retry rule] | |
23794 | cindex:[retry,quota error testing] | |
23795 | A mailbox quota was exceeded in a local delivery by the ^appendfile^ transport, | |
23796 | and the mailbox has not been accessed for <'time'>. For example, 'quota_4d' | |
23797 | applies to a quota error when the mailbox has not been accessed for four days. | |
23798 | ||
23799 | /// | |
23800 | End of list | |
23801 | /// | |
23802 | ||
23803 | cindex:[mailbox,time of last read] | |
23804 | The idea of %quota_%<'time'> is to make it possible to have shorter timeouts | |
23805 | when the mailbox is full and is not being read by its owner. Ideally, it should | |
23806 | be based on the last time that the user accessed the mailbox. However, it is | |
23807 | not always possible to determine this. Exim uses the following heuristic rules: | |
23808 | ||
23809 | - If the mailbox is a single file, the time of last access (the ``atime'') is used. | |
23810 | As no new messages are being delivered (because the mailbox is over quota), | |
23811 | Exim does not access the file, so this is the time of last user access. | |
23812 | ||
23813 | - cindex:[maildir format,time of last read] | |
23814 | For a maildir delivery, the time of last modification of the _new_ | |
23815 | subdirectory is used. As the mailbox is over quota, no new files are created in | |
23816 | the _new_ subdirectory, because no new messages are being delivered. Any | |
23817 | change to the _new_ subdirectory is therefore assumed to be the result of an | |
23818 | MUA moving a new message to the _cur_ directory when it is first read. The | |
23819 | time that is used is therefore the last time that the user read a new message. | |
23820 | ||
23821 | - For other kinds of multi-file mailbox, the time of last access cannot be | |
23822 | obtained, so a retry rule that uses this type of error field is never matched. | |
23823 | ||
23824 | The quota errors apply both to system-enforced quotas and to Exim's own quota | |
23825 | mechanism in the ^appendfile^ transport. The 'quota' error also applies | |
23826 | when a local delivery is deferred because a partition is full (the ENOSPC | |
23827 | error). | |
23828 | ||
23829 | ||
23830 | ||
23831 | Retry rules for specified senders | |
23832 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
23833 | cindex:[retry,rules; sender-specific] | |
23834 | You can specify retry rules that apply only when the failing message has a | |
23835 | specific sender. In particular, this can be used to define retry rules that | |
23836 | apply only to bounce messages. The third item in a retry rule can be of this | |
23837 | form: | |
23838 | ||
23839 | senders=<address list> | |
23840 | ||
23841 | The retry timings themselves are then the fourth item. For example: | |
23842 | ||
23843 | .... | |
068aaea8 | 23844 | * rcpt_4xx senders=: F,1h,30m |
168e428f PH |
23845 | .... |
23846 | ||
068aaea8 PH |
23847 | matches 4##'xx' errors for bounce messages sent to any host. If the address |
23848 | list contains white space, it must be enclosed in quotes. For example: | |
168e428f | 23849 | |
068aaea8 PH |
23850 | a.domain auth_failed senders="xb.dom : yc.dom" G,8h,10m,1.5 |
23851 | ||
23852 | [revisionflag="changed"] | |
23853 | *Warning*: This facility can be unhelpful if it is used for host errors (those | |
23854 | that do not depend on the recipient). The reason is that the sender is used | |
23855 | only to match the retry rule. Once the rule has been found for a host error, | |
23856 | its contents are used to set a retry time for the host, and this will apply to | |
23857 | all messages, not just those with specific senders. | |
168e428f PH |
23858 | |
23859 | When testing retry rules using %-brt%, you can supply a sender using the %-f% | |
23860 | command line option, like this: | |
23861 | ||
23862 | exim -f "" -brt user@dom.ain | |
23863 | ||
23864 | If you do not set %-f% with %-brt%, a retry rule that contains a senders list | |
23865 | is never matched. | |
23866 | ||
23867 | ||
23868 | ||
23869 | ||
23870 | ||
23871 | Retry parameters | |
23872 | ~~~~~~~~~~~~~~~~ | |
23873 | cindex:[retry,parameters in rules] | |
23874 | The third (or fourth, if a senders list is present) field in a retry rule is a | |
23875 | sequence of retry parameter sets, separated by semicolons. Each set consists of | |
23876 | ||
23877 | <letter>,<cutoff time>,<arguments> | |
23878 | ||
23879 | The letter identifies the algorithm for computing a new retry time; the cutoff | |
23880 | time is the time beyond which this algorithm no longer applies, and the | |
23881 | arguments vary the algorithm's action. The cutoff time is measured from the | |
23882 | time that the first failure for the domain (combined with the local part if | |
23883 | relevant) was detected, not from the time the message was received. | |
23884 | ||
23885 | cindex:[retry,algorithms] | |
068aaea8 PH |
23886 | cindex:[retry,fixed intervals] |
23887 | cindex:[retry,increasing intervals] | |
23888 | cindex:[retry,random intervals] | |
168e428f PH |
23889 | The available algorithms are: |
23890 | ||
23891 | - 'F': retry at fixed intervals. There is a single time parameter specifying | |
23892 | the interval. | |
23893 | ||
23894 | - 'G': retry at geometrically increasing intervals. The first argument | |
23895 | specifies a starting value for the interval, and the second a multiplier, which | |
23896 | is used to increase the size of the interval at each retry. | |
23897 | ||
068aaea8 PH |
23898 | [revisionflag="changed"] |
23899 | - 'H': retry at randomized intervals. The arguments are as for 'G'. For each | |
23900 | retry, the previous interval is multiplied by the factor in order to get a | |
23901 | maximum for the next interval. The mininum interval is the first argument of | |
23902 | the parameter, and an actual interval is chosen randomly between them. Such a | |
23903 | rule has been found to be helpful in cluster configurations when all the | |
23904 | members of the cluster restart at once, and may therefore synchronize their | |
23905 | queue processing times. | |
23906 | ||
168e428f PH |
23907 | When computing the next retry time, the algorithm definitions are scanned in |
23908 | order until one whose cutoff time has not yet passed is reached. This is then | |
23909 | used to compute a new retry time that is later than the current time. In the | |
23910 | case of fixed interval retries, this simply means adding the interval to the | |
23911 | current time. For geometrically increasing intervals, retry intervals are | |
23912 | computed from the rule's parameters until one that is greater than the previous | |
23913 | interval is found. The main configuration variable | |
23914 | cindex:[limit,retry interval] | |
23915 | cindex:[retry interval, maximum] | |
23916 | cindex:[%retry_interval_max%] | |
23917 | %retry_interval_max% limits the maximum interval between retries. | |
23918 | ||
23919 | A single remote domain may have a number of hosts associated with it, and each | |
23920 | host may have more than one IP address. Retry algorithms are selected on the | |
23921 | basis of the domain name, but are applied to each IP address independently. If, | |
23922 | for example, a host has two IP addresses and one is unusable, Exim will | |
23923 | generate retry times for it and will not try to use it until its next retry | |
23924 | time comes. Thus the good IP address is likely to be tried first most of the | |
23925 | time. | |
23926 | ||
23927 | cindex:[hints database,use for retrying] | |
23928 | Retry times are hints rather than promises. Exim does not make any attempt to | |
23929 | run deliveries exactly at the computed times. Instead, a queue runner process | |
23930 | starts delivery processes for delayed messages periodically, and these attempt | |
23931 | new deliveries only for those addresses that have passed their next retry time. | |
23932 | If a new message arrives for a deferred address, an immediate delivery attempt | |
23933 | occurs only if the address has passed its retry time. In the absence of new | |
23934 | messages, the minimum time between retries is the interval between queue runner | |
23935 | processes. There is not much point in setting retry times of five minutes if | |
23936 | your queue runners happen only once an hour, unless there are a significant | |
23937 | number of incoming messages (which might be the case on a system that is | |
23938 | sending everything to a smart host, for example). | |
23939 | ||
23940 | The data in the retry hints database can be inspected by using the | |
23941 | 'exim_dumpdb' or 'exim_fixdb' utility programs (see chapter <<CHAPutils>>). The | |
23942 | latter utility can also be used to change the data. The 'exinext' utility | |
23943 | script can be used to find out what the next retry times are for the hosts | |
23944 | associated with a particular mail domain, and also for local deliveries that | |
23945 | have been deferred. | |
23946 | ||
23947 | ||
23948 | Retry rule examples | |
23949 | ~~~~~~~~~~~~~~~~~~~ | |
23950 | Here are some example retry rules: | |
23951 | ||
23952 | alice@wonderland.fict.example quota_5d F,7d,3h | |
23953 | wonderland.fict.example quota_5d | |
23954 | wonderland.fict.example * F,1h,15m; G,2d,1h,2; | |
23955 | lookingglass.fict.example * F,24h,30m; | |
23956 | * refused_A F,2h,20m; | |
23957 | * * F,2h,15m; G,16h,1h,1.5; F,5d,8h | |
23958 | ||
23959 | The first rule sets up special handling for mail to | |
23960 | 'alice@wonderland.fict.example' when there is an over-quota error and the | |
23961 | mailbox has not been read for at least 5 days. Retries continue every three | |
23962 | hours for 7 days. The second rule handles over-quota errors for all other local | |
23963 | parts at 'wonderland.fict.example'; the absence of a local part has the same | |
23964 | effect as supplying ``\*@''. As no retry algorithms are supplied, messages that | |
23965 | fail are bounced immediately if the mailbox has not been read for at least 5 | |
23966 | days. | |
23967 | ||
23968 | The third rule handles all other errors at 'wonderland.fict.example'; retries | |
23969 | happen every 15 minutes for an hour, then with geometrically increasing | |
23970 | intervals until two days have passed since a delivery first failed. After the | |
23971 | first hour there is a delay of one hour, then two hours, then four hours, and | |
23972 | so on (this is a rather extreme example). | |
23973 | ||
23974 | The fourth rule controls retries for the domain 'lookingglass.fict.example'. | |
23975 | They happen every 30 minutes for 24 hours only. The remaining two rules handle | |
23976 | all other domains, with special action for connection refusal from hosts that | |
23977 | were not obtained from an MX record. | |
23978 | ||
23979 | The final rule in a retry configuration should always have asterisks in the | |
23980 | first two fields so as to provide a general catch-all for any addresses that do | |
23981 | not have their own special handling. This example tries every 15 minutes for 2 | |
23982 | hours, then with intervals starting at one hour and increasing by a factor of | |
23983 | 1.5 up to 16 hours, then every 8 hours up to 5 days. | |
23984 | ||
23985 | ||
23986 | ||
23987 | Timeout of retry data | |
23988 | ~~~~~~~~~~~~~~~~~~~~~ | |
23989 | cindex:[timeout,of retry data] | |
23990 | cindex:[%retry_data_expire%] | |
23991 | cindex:[hints database,data expiry] | |
23992 | cindex:[retry,timeout of data] | |
23993 | Exim timestamps the data that it writes to its retry hints database. When it | |
23994 | consults the data during a delivery it ignores any that is older than the value | |
23995 | set in %retry_data_expire% (default 7 days). If, for example, a host hasn't | |
23996 | been tried for 7 days, Exim will try to deliver to it immediately a message | |
23997 | arrives, and if that fails, it will calculate a retry time as if it were | |
23998 | failing for the first time. | |
23999 | ||
24000 | This improves the behaviour for messages routed to rarely-used hosts such as MX | |
24001 | backups. If such a host was down at one time, and happens to be down again when | |
24002 | Exim tries a month later, using the old retry data would imply that it had been | |
24003 | down all the time, which is not a justified assumption. | |
24004 | ||
24005 | If a host really is permanently dead, this behaviour causes a burst of retries | |
24006 | every now and again, but only if messages routed to it are rare. It there is a | |
24007 | message at least once every 7 days the retry data never expires. | |
24008 | ||
24009 | ||
24010 | ||
24011 | ||
24012 | Long-term failures | |
24013 | ~~~~~~~~~~~~~~~~~~ | |
24014 | cindex:[delivery failure, long-term] | |
24015 | cindex:[retry,after long-term failure] | |
24016 | Special processing happens when an email address has been failing for so long | |
24017 | that the cutoff time for the last algorithm is reached. For example, using the | |
24018 | default retry rule: | |
24019 | ||
24020 | .... | |
24021 | * * F,2h,15m; G,16h,1h,1.5; F,4d,6h | |
24022 | .... | |
24023 | ||
24024 | the cutoff time is four days. Reaching the retry cutoff is independent of how | |
24025 | long any specific message has been failing; it is the length of continuous | |
24026 | failure for the recipient address that counts. | |
24027 | ||
24028 | When the cutoff time is reached for a local delivery, or for all the IP | |
24029 | addresses associated with a remote delivery, a subsequent delivery failure | |
24030 | causes Exim to give up on the address, and a bounce message is generated. | |
24031 | In order to cater for new messages that use the failing address, a next retry | |
24032 | time is still computed from the final algorithm, and is used as follows: | |
24033 | ||
24034 | For local deliveries, one delivery attempt is always made for any subsequent | |
24035 | messages. If this delivery fails, the address fails immediately. The | |
24036 | post-cutoff retry time is not used. | |
24037 | ||
24038 | If the delivery is remote, there are two possibilities, controlled by the | |
24039 | cindex:[%delay_after_cutoff%] | |
24040 | %delay_after_cutoff% option of the ^smtp^ transport. The option is true by | |
24041 | default. Until the post-cutoff retry time for one of the IP addresses is | |
24042 | reached, the failing email address is bounced immediately, without a delivery | |
24043 | attempt taking place. After that time, one new delivery attempt is made to | |
24044 | those IP addresses that are past their retry times, and if that still fails, | |
24045 | the address is bounced and new retry times are computed. | |
24046 | ||
24047 | In other words, when all the hosts for a given email address have been failing | |
24048 | for a long time, Exim bounces rather then defers until one of the hosts' retry | |
24049 | times is reached. Then it tries once, and bounces if that attempt fails. This | |
24050 | behaviour ensures that few resources are wasted in repeatedly trying to deliver | |
24051 | to a broken destination, but if the host does recover, Exim will eventually | |
24052 | notice. | |
24053 | ||
24054 | If %delay_after_cutoff% is set false, Exim behaves differently. If all IP | |
24055 | addresses are past their final cutoff time, Exim tries to deliver to those IP | |
24056 | addresses that have not been tried since the message arrived. If there are | |
24057 | no suitable IP addresses, or if they all fail, the address is bounced. In other | |
24058 | words, it does not delay when a new message arrives, but tries the expired | |
24059 | addresses immediately, unless they have been tried since the message arrived. | |
24060 | If there is a continuous stream of messages for the failing domains, setting | |
24061 | %delay_after_cutoff% false means that there will be many more attempts to | |
24062 | deliver to permanently failing IP addresses than when %delay_after_cutoff% is | |
24063 | true. | |
24064 | ||
24065 | ||
24066 | Ultimate address timeout | |
24067 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
24068 | cindex:[retry,ultimate address timeout] | |
24069 | An additional rule is needed to cope with cases where a host is intermittently | |
24070 | available, or when a message has some attribute that prevents its delivery when | |
24071 | others to the same address get through. In this situation, because some | |
24072 | messages are successfully delivered, the ``retry clock'' for the address keeps | |
24073 | getting restarted, and so a message could remain on the queue for ever. To | |
24074 | prevent this, if a message has been on the queue for longer than the cutoff | |
24075 | time of any applicable retry rule for a given address, a delivery is attempted | |
24076 | for that address, even if it is not yet time, and if this delivery fails, the | |
24077 | address is timed out. A new retry time is not computed in this case, so that | |
24078 | other messages for the same address are considered immediately. | |
24079 | ||
24080 | ||
24081 | ||
24082 | ||
24083 | ||
24084 | //////////////////////////////////////////////////////////////////////////// | |
24085 | //////////////////////////////////////////////////////////////////////////// | |
24086 | ||
24087 | [[CHAPSMTPAUTH]] | |
24088 | SMTP authentication | |
24089 | ------------------- | |
24090 | cindex:[SMTP,authentication configuration] | |
24091 | cindex:[authentication] | |
24092 | The ``authenticators'' section of Exim's run time configuration is concerned with | |
24093 | SMTP authentication. This facility is an extension to the SMTP protocol, | |
24094 | described in RFC 2554, which allows a client SMTP host to authenticate itself | |
24095 | to a server. This is a common way for a server to recognize clients that | |
24096 | are permitted to use it as a relay. SMTP authentication is not of relevance to | |
24097 | the transfer of mail between servers that have no managerial connection with | |
24098 | each other. | |
24099 | ||
24100 | cindex:[AUTH,description of] | |
24101 | Very briefly, the way SMTP authentication works is as follows: | |
24102 | ||
24103 | - The server advertises a number of authentication 'mechanisms' in response to | |
24104 | the client's EHLO command. | |
24105 | ||
24106 | - The client issues an AUTH command, naming a specific mechanism. The command | |
24107 | may, optionally, contain some authentication data. | |
24108 | ||
24109 | - The server may issue one or more 'challenges', to which the client must send | |
24110 | appropriate responses. In simple authentication mechanisms, the challenges are | |
24111 | just prompts for user names and passwords. The server does not have to issue | |
24112 | any challenges -- in some mechanisms the relevant data may all be transmitted | |
24113 | with the AUTH command. | |
24114 | ||
24115 | - The server either accepts or denies authentication. | |
24116 | ||
24117 | - If authentication succeeds, the client may optionally make use of the AUTH | |
24118 | option on the MAIL command to pass an authenticated sender in subsequent | |
24119 | mail transactions. Authentication lasts for the remainder of the SMTP | |
24120 | connection. | |
24121 | ||
24122 | - If authentication fails, the client may give up, or it may try a different | |
24123 | authentication mechanism, or it may try transferring mail over the | |
24124 | unauthenticated connection. | |
24125 | ||
24126 | If you are setting up a client, and want to know which authentication | |
24127 | mechanisms the server supports, you can use Telnet to connect to port 25 (the | |
24128 | SMTP port) on the server, and issue an EHLO command. The response to this | |
24129 | includes the list of supported mechanisms. For example: | |
24130 | ||
24131 | &&& | |
24132 | `\$ `##*`telnet server.example 25`* | |
24133 | `Trying 192.168.34.25...` | |
24134 | `Connected to server.example.` | |
24135 | `Escape character is \'^]\'.` | |
24136 | `220 server.example ESMTP Exim 4.20 ...` | |
24137 | *`ehlo client.example`* | |
24138 | `250-server.example Hello client.example [10.8.4.5]` | |
24139 | `250-SIZE 52428800` | |
24140 | `250-PIPELINING` | |
24141 | `250-AUTH PLAIN` | |
24142 | `250 HELP` | |
24143 | &&& | |
24144 | ||
24145 | The second-last line of this example output shows that the server supports | |
24146 | authentication using the PLAIN mechanism. In Exim, the different authentication | |
24147 | mechanisms are configured by specifying 'authenticator' drivers. Like the | |
24148 | routers and transports, which authenticators are included in the binary is | |
24149 | controlled by build-time definitions. The following are currently available, | |
24150 | included by setting | |
24151 | ||
24152 | AUTH_CRAM_MD5=yes | |
068aaea8 | 24153 | AUTH_CYRUS_SASL=yes |
168e428f PH |
24154 | AUTH_PLAINTEXT=yes |
24155 | AUTH_SPA=yes | |
24156 | ||
24157 | in _Local/Makefile_, respectively. The first of these supports the CRAM-MD5 | |
068aaea8 PH |
24158 | authentication mechanism (RFC 2195), and the second provides an interface to |
24159 | the Cyrus SASL authentication library. The third can be configured to support | |
24160 | the PLAIN authentication mechanism (RFC 2595) or the LOGIN mechanism, which is | |
24161 | not formally documented, but used by several MUAs. The fourth authenticator | |
24162 | supports Microsoft's 'Secure Password Authentication' mechanism. | |
168e428f PH |
24163 | |
24164 | The authenticators are configured using the same syntax as other drivers (see | |
24165 | section <<SECTfordricon>>). If no authenticators are required, no authentication | |
24166 | section need be present in the configuration file. Each authenticator can in | |
24167 | principle have both server and client functions. When Exim is receiving SMTP | |
24168 | mail, it is acting as a server; when it is sending out messages over SMTP, it | |
24169 | is acting as a client. Authenticator configuration options are provided for use | |
24170 | in both these circumstances. | |
24171 | ||
24172 | To make it clear which options apply to which situation, the prefixes | |
24173 | %server_% and %client_% are used on option names that are specific to either | |
24174 | the server or the client function, respectively. Server and client functions | |
24175 | are disabled if none of their options are set. If an authenticator is to be | |
24176 | used for both server and client functions, a single definition, using both sets | |
24177 | of options, is required. For example: | |
24178 | ||
24179 | cram: | |
24180 | driver = cram_md5 | |
24181 | public_name = CRAM-MD5 | |
24182 | server_secret = ${if eq{$1}{ph10}{secret1}fail} | |
24183 | client_name = ph10 | |
24184 | client_secret = secret2 | |
24185 | ||
24186 | The %server_% option is used when Exim is acting as a server, and the | |
24187 | %client_% options when it is acting as a client. | |
24188 | ||
24189 | Descriptions of the individual authenticators are given in subsequent chapters. | |
24190 | The remainder of this chapter covers the generic options for the | |
24191 | authenticators, followed by general discussion of the way authentication works | |
24192 | in Exim. | |
24193 | ||
24194 | ||
24195 | ||
24196 | Generic options for authenticators | |
24197 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
24198 | cindex:[authentication,generic options] | |
24199 | cindex:[options,generic; for authenticators] | |
24200 | ||
24201 | ||
24202 | oindex:[%driver%] | |
24203 | `..'= | |
24204 | %driver%, Use: 'authenticators', Type: 'string', Default: 'unset' | |
24205 | === | |
24206 | ||
24207 | This option must always be set. It specifies which of the available | |
24208 | authenticators is to be used. | |
24209 | ||
24210 | ||
24211 | oindex:[%public_name%] | |
24212 | `..'= | |
24213 | %public_name%, Use: 'authenticators', Type: 'string', Default: 'unset' | |
24214 | === | |
24215 | ||
24216 | This option specifies the name of the authentication mechanism that the driver | |
24217 | implements, and by which it is known to the outside world. These names should | |
24218 | contain only upper case letters, digits, underscores, and hyphens (RFC 2222), | |
24219 | but Exim in fact matches them caselessly. If %public_name% is not set, it | |
24220 | defaults to the driver's instance name. | |
24221 | ||
24222 | ||
24223 | oindex:[%server_advertise_condition%] | |
24224 | `..'= | |
24225 | %server_advertise_condition%, Use: 'authenticators', Type: 'string'!!, Default: 'unset' | |
24226 | === | |
24227 | ||
24228 | When a server is about to advertise an authentication mechanism, the condition | |
24229 | is expanded. If it yields the empty string, ``0'', ``no'', or ``false'', the | |
24230 | mechanism is not advertised. | |
24231 | If the expansion fails, the mechanism is not advertised. If the failure was not | |
24232 | forced, and was not caused by a lookup defer, the incident is logged. | |
24233 | See section <<SECTauthexiser>> below for further discussion. | |
24234 | ||
24235 | ||
24236 | oindex:[%server_debug_print%] | |
24237 | `..'= | |
24238 | %server_debug_print%, Use: 'authenticators', Type: 'string'!!, Default: 'unset' | |
24239 | === | |
24240 | ||
24241 | If this option is set and authentication debugging is enabled (see the %-d% | |
24242 | command line option), the string is expanded and included in the debugging | |
24243 | output when the authenticator is run as a server. This can help with checking | |
24244 | out the values of variables. | |
24245 | If expansion of the string fails, the error message is written to the debugging | |
24246 | output, and Exim carries on processing. | |
24247 | ||
24248 | ||
24249 | oindex:[%server_set_id%] | |
24250 | `..'= | |
24251 | %server_set_id%, Use: 'authenticators', Type: 'string'!!, Default: 'unset' | |
24252 | === | |
24253 | ||
068aaea8 | 24254 | cindex:[$authenticated_id$] |
168e428f PH |
24255 | When an Exim server successfully authenticates a client, this string is |
24256 | expanded using data from the authentication, and preserved for any incoming | |
24257 | messages in the variable $authenticated_id$. It is also included in the log | |
24258 | lines for incoming messages. For example, a user/password authenticator | |
24259 | configuration might preserve the user name that was used to authenticate, and | |
24260 | refer to it subsequently during delivery of the message. | |
24261 | If expansion fails, the option is ignored. | |
24262 | ||
24263 | ||
24264 | oindex:[%server_mail_auth_condition%] | |
24265 | `..'= | |
24266 | %server_mail_auth_condition%, Use: 'authenticators', Type: 'string'!!, Default: 'unset' | |
24267 | === | |
24268 | ||
24269 | This option allows a server to discard authenticated sender addresses supplied | |
24270 | as part of MAIL commands in SMTP connections that are authenticated by the | |
24271 | driver on which %server_mail_auth_condition% is set. The option is not used | |
24272 | as part of the authentication process; instead its (unexpanded) value is | |
24273 | remembered for later use. | |
24274 | How it is used is described in the following section. | |
24275 | ||
24276 | ||
24277 | ||
24278 | ||
24279 | ||
24280 | [[SECTauthparamail]] | |
24281 | The AUTH parameter on MAIL commands | |
24282 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
24283 | cindex:[authentication,sender; authenticated] | |
24284 | cindex:[AUTH,on MAIL command] | |
24285 | When a client supplied an AUTH= item on a MAIL command, Exim applies | |
24286 | the following checks before accepting it as the authenticated sender of the | |
24287 | message: | |
24288 | ||
24289 | - If the connection is not using extended SMTP (that is, HELO was used rather | |
24290 | than EHLO), the use of AUTH= is a syntax error. | |
24291 | ||
24292 | - If the value of the AUTH= parameter is ``<>'', it is ignored. | |
24293 | ||
068aaea8 PH |
24294 | - cindex:[$authenticated_sender$] |
24295 | If %acl_smtp_mailauth% is defined, the ACL it specifies is run. While it is | |
24296 | running, the value of $authenticated_sender$ is set to the value obtained from | |
24297 | the AUTH= parameter. If the ACL does not yield ``accept'', the value of | |
24298 | $authenticated_sender$ is deleted. The %acl_smtp_mailauth% ACL may not return | |
24299 | ``drop'' or ``discard''. If it defers, a temporary error code (451) is given | |
168e428f PH |
24300 | for the MAIL command. |
24301 | ||
24302 | - If %acl_smtp_mailauth% is not defined, the value of the AUTH= parameter | |
24303 | is accepted and placed in $authenticated_sender$ only if the client has | |
24304 | authenticated. | |
24305 | ||
24306 | - If the AUTH= value was accepted by either of the two previous rules, and | |
24307 | the client has authenticated, and the authenticator has a setting for the | |
24308 | %server_mail_auth_condition%, the condition is checked at this point. The | |
24309 | valued that was saved from the authenticator is expanded. If the expansion | |
24310 | fails, or yields an empty string, ``0'', ``no'', or ``false'', the value of | |
24311 | $authenticated_sender$ is deleted. If the expansion yields any other value, | |
24312 | the value of $authenticated_sender$ is retained and passed on with the | |
24313 | message. | |
24314 | ||
24315 | ||
24316 | When $authenticated_sender$ is set for a message, it is passed on to other | |
24317 | hosts to which Exim authenticates as a client. Do not confuse this value with | |
24318 | $authenticated_id$, which is a string obtained from the authentication | |
24319 | process, and which is not usually a complete email address. | |
24320 | ||
068aaea8 | 24321 | cindex:[$sender_address$] |
168e428f PH |
24322 | Whenever an AUTH= value is ignored, the incident is logged. The ACL for |
24323 | MAIL, if defined, is run after AUTH= is accepted or ignored. It can | |
24324 | therefore make use of $authenticated_sender$. The converse is not true: the | |
24325 | value of $sender_address$ is not yet set up when the %acl_smtp_mailauth% | |
24326 | ACL is run. | |
24327 | ||
24328 | ||
24329 | ||
24330 | [[SECTauthexiser]] | |
24331 | Authentication on an Exim server | |
24332 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
24333 | cindex:[authentication,on an Exim server] | |
24334 | When Exim receives an EHLO command, it advertises the public names of those | |
24335 | authenticators that are configured as servers, subject to the following | |
24336 | conditions: | |
24337 | ||
24338 | - The client host must match %auth_advertise_hosts% (default \*). | |
24339 | ||
24340 | - It the %server_advertise_condition% option is set, its expansion must not | |
24341 | yield the empty string, ``0'', ``no'', or ``false''. | |
24342 | ||
24343 | The order in which the authenticators are defined controls the order in which | |
24344 | the mechanisms are advertised. | |
24345 | ||
24346 | Some mail clients (for example, some versions of Netscape) require the user to | |
24347 | provide a name and password for authentication whenever AUTH is advertised, | |
24348 | even though authentication may not in fact be needed (for example, Exim may be | |
24349 | set up to allow unconditional relaying from the client by an IP address check). | |
24350 | You can make such clients more friendly by not advertising AUTH to them. | |
24351 | For example, if clients on the 10.9.8.0/24 network are permitted (by the ACL | |
24352 | that runs for RCPT) to relay without authentication, you should set | |
24353 | ||
24354 | auth_advertise_hosts = ! 10.9.8.0/24 | |
24355 | ||
24356 | so that no authentication mechanisms are advertised to them. | |
24357 | ||
24358 | The %server_advertise_condition% controls the advertisement of individual | |
24359 | authentication mechanisms. For example, it can be used to restrict the | |
24360 | advertisement of a patricular mechanism to encrypted connections, by a setting | |
24361 | such as: | |
24362 | ||
24363 | server_advertise_condition = ${if eq{$tls_cipher}{}{no}{yes}} | |
24364 | ||
068aaea8 | 24365 | cindex:[$tls_cipher$] |
168e428f PH |
24366 | If the session is encrypted, $tls_cipher$ is not empty, and so the expansion |
24367 | yields ``yes'', which allows the advertisement to happen. | |
24368 | ||
24369 | When an Exim server receives an AUTH command from a client, it rejects it | |
24370 | immediately if AUTH was not advertised in response to an earlier EHLO | |
24371 | command. This is the case if | |
24372 | ||
24373 | - The client host does not match %auth_advertise_hosts%; or | |
24374 | ||
24375 | - No authenticators are configured with server options; or | |
24376 | ||
24377 | - Expansion of %server_advertise_condition% blocked the advertising of all the | |
24378 | server authenticators. | |
24379 | ||
24380 | ||
24381 | Otherwise, Exim runs the ACL specified by %acl_smtp_auth% in order | |
24382 | to decide whether to accept the command. If %acl_smtp_auth% is not set, | |
24383 | AUTH is accepted from any client host. | |
24384 | ||
24385 | If AUTH is not rejected by the ACL, Exim searches its configuration for a | |
24386 | server authentication mechanism that was advertised in response to EHLO and | |
24387 | that matches the one named in the AUTH command. If it finds one, it runs | |
24388 | the appropriate authentication protocol, and authentication either succeeds or | |
24389 | fails. If there is no matching advertised mechanism, the AUTH command is | |
24390 | rejected with a 504 error. | |
24391 | ||
068aaea8 PH |
24392 | cindex:[$received_protocol$] |
24393 | cindex:[$sender_host_authenticated$] | |
168e428f | 24394 | When a message is received from an authenticated host, the value of |
068aaea8 PH |
24395 | $received_protocol$ is set to ``esmtpa'' or ``esmtpsa'' instead of ``esmtp'' or |
24396 | ``esmtps'', and $sender_host_authenticated$ contains the name (not the public | |
24397 | name) of the authenticator driver that successfully authenticated the client | |
24398 | from which the message was received. This variable is empty if there was no | |
24399 | successful authentication. | |
168e428f PH |
24400 | |
24401 | ||
24402 | ||
24403 | ||
24404 | Testing server authentication | |
24405 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
24406 | cindex:[authentication,testing a server] | |
24407 | cindex:[AUTH,testing a server] | |
24408 | cindex:[base64 encoding,creating authentication test data] | |
24409 | Exim's %-bh% option can be useful for testing server authentication | |
24410 | configurations. The data for the AUTH command has to be sent using base64 | |
24411 | encoding. A quick way to produce such data for testing is the following Perl | |
24412 | script: | |
24413 | ||
24414 | use MIME::Base64; | |
24415 | printf ("%s", encode_base64(eval "\"$ARGV[0]\"")); | |
24416 | ||
24417 | cindex:[binary zero,in authentication data] | |
24418 | This interprets its argument as a Perl string, and then encodes it. The | |
24419 | interpretation as a Perl string allows binary zeros, which are required for | |
24420 | some kinds of authentication, to be included in the data. For example, a | |
24421 | command line to run this script on such data might be | |
24422 | ||
24423 | encode '\0user\0password' | |
24424 | ||
24425 | Note the use of single quotes to prevent the shell interpreting the | |
24426 | backslashes, so that they can be interpreted by Perl to specify characters | |
24427 | whose code value is zero. | |
24428 | ||
24429 | *Warning 1*: If either of the user or password strings starts with an octal | |
24430 | digit, you must use three zeros instead of one after the leading backslash. If | |
24431 | you do not, the octal digit that starts your string will be incorrectly | |
24432 | interpreted as part of the code for the first character. | |
24433 | ||
24434 | *Warning 2*: If there are characters in the strings that Perl interprets | |
24435 | specially, you must use a Perl escape to prevent them being misinterpreted. For | |
24436 | example, a command such as | |
24437 | ||
24438 | encode '\0user@domain.com\0pas$$word' | |
24439 | ||
24440 | gives an incorrect answer because of the unescaped ``@'' and ``\$'' characters. | |
24441 | ||
24442 | If you have the %mimencode% command installed, another way to do produce | |
24443 | base64-encoded strings is to run the command | |
24444 | ||
24445 | echo -e -n `\0user\0password' | mimencode | |
24446 | ||
24447 | The %-e% option of %echo% enables the interpretation of backslash escapes in | |
24448 | the argument, and the %-n% option specifies no newline at the end of its | |
24449 | output. However, not all versions of %echo% recognize these options, so you | |
24450 | should check your version before relying on this suggestion. | |
24451 | ||
24452 | ||
24453 | ||
24454 | Authentication by an Exim client | |
24455 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
24456 | cindex:[authentication,on an Exim client] | |
24457 | The ^smtp^ transport has two options called %hosts_require_auth% and | |
24458 | %hosts_try_auth%. When the ^smtp^ transport connects to a server that | |
24459 | announces support for authentication, and the host matches an entry in either | |
24460 | of these options, Exim (as a client) tries to authenticate as follows: | |
24461 | ||
24462 | - For each authenticator that is configured as a client, it searches the | |
24463 | authentication mechanisms announced by the server for one whose name | |
24464 | matches the public name of the authenticator. | |
24465 | ||
068aaea8 PH |
24466 | - cindex:[$host$] |
24467 | cindex:[$host_address$] | |
24468 | When it finds one that matches, it runs the authenticator's client code. | |
168e428f PH |
24469 | The variables $host$ and $host_address$ are available for any string |
24470 | expansions that the client might do. They are set to the server's name and | |
24471 | IP address. If any expansion is forced to fail, the authentication attempt | |
24472 | is abandoned, | |
24473 | and Exim moves on to the next authenticator. | |
24474 | Otherwise an expansion failure causes delivery to be | |
24475 | deferred. | |
24476 | ||
24477 | - If the result of the authentication attempt is a temporary error or a timeout, | |
24478 | Exim abandons trying to send the message to the host for the moment. It will | |
24479 | try again later. If there are any backup hosts available, they are tried in the | |
24480 | usual way. | |
24481 | ||
24482 | - If the response to authentication is a permanent error (5xx code), Exim carries | |
24483 | on searching the list of authenticators and tries another one if possible. If | |
24484 | all authentication attempts give permanent errors, or if there are no attempts | |
24485 | because no mechanisms match | |
24486 | (or option expansions force failure), | |
24487 | what happens depends on whether the host matches %hosts_require_auth% or | |
24488 | %hosts_try_auth%. In the first case, a temporary error is generated, and | |
24489 | delivery is deferred. The error can be detected in the retry rules, and thereby | |
24490 | turned into a permanent error if you wish. In the second case, Exim tries to | |
24491 | deliver the message unauthenticated. | |
24492 | ||
24493 | cindex:[AUTH,on MAIL command] | |
24494 | When Exim has authenticated itself to a remote server, it adds the AUTH | |
24495 | parameter to the MAIL commands it sends, if it has an authenticated sender | |
24496 | for the message. | |
24497 | If the message came from a remote host, the authenticated sender is the one | |
24498 | that was receiving on an incoming MAIL command, provided that the incoming | |
24499 | connection was authenticated and the %server_mail_auth% condition allowed the | |
24500 | authenticated sender to be retained. If a local process calls Exim to send a | |
24501 | message, the sender address that is built from the login name and | |
24502 | %qualify_domain% is treated as authenticated. However, if the | |
24503 | %authenticated_sender% option is set on the ^smtp^ transport, it overrides | |
24504 | the authenticated sender that was received with the message. | |
24505 | ||
24506 | ||
24507 | ||
24508 | ||
24509 | ||
24510 | ||
24511 | //////////////////////////////////////////////////////////////////////////// | |
24512 | //////////////////////////////////////////////////////////////////////////// | |
24513 | ||
24514 | [[CHAPplaintext]] | |
24515 | The plaintext authenticator | |
24516 | --------------------------- | |
24517 | cindex:[^plaintext^ authenticator] | |
24518 | cindex:[authenticators,^plaintext^] | |
24519 | The ^plaintext^ authenticator can be configured to support the PLAIN and | |
24520 | LOGIN authentication mechanisms, both of which transfer authentication data as | |
24521 | plain (unencrypted) text (though base64 encoded). The use of plain text is a | |
24522 | security risk. If you use one of these mechanisms without also making use of | |
24523 | SMTP encryption (see chapter <<CHAPTLS>>) you should not use the same passwords | |
24524 | for SMTP connections as you do for login accounts. | |
24525 | ||
24526 | ||
24527 | Using plaintext in a server | |
24528 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
24529 | cindex:[options,^plaintext^ authenticator (server)] | |
24530 | When running as a server, ^plaintext^ performs the authentication test by | |
24531 | expanding a string. It has the following options: | |
24532 | ||
24533 | oindex:[%server_prompts%] | |
24534 | `..'= | |
24535 | %server_prompts%, Use: 'plaintext', Type: 'string'!!, Default: 'unset' | |
24536 | === | |
24537 | ||
24538 | The contents of this option, after expansion, must be a colon-separated list of | |
24539 | prompt strings. If expansion fails, a temporary authentication rejection is | |
24540 | given. | |
24541 | ||
24542 | oindex:[%server_condition%] | |
24543 | `..'= | |
24544 | %server_condition%, Use: 'plaintext', Type: 'string'!!, Default: 'unset' | |
24545 | === | |
24546 | ||
24547 | This option must be set in order to configure the driver as a server. Its use | |
24548 | is described below. | |
24549 | ||
24550 | cindex:[AUTH,in ^plaintext^ authenticator] | |
24551 | cindex:[binary zero,in ^plaintext^ authenticator] | |
24552 | cindex:[numerical variables ($1$ $2$ etc),in ^plaintext^ authenticator] | |
24553 | cindex:[base64 encoding,in ^plaintext^ authenticator] | |
24554 | The data sent by the client with the AUTH command, or in response to | |
24555 | subsequent prompts, is base64 encoded, and so may contain any byte values | |
24556 | when decoded. If any data is supplied with the command, it is treated as a | |
24557 | list of strings, separated by NULs (binary zeros), which are placed in the | |
24558 | expansion variables $1$, $2$, etc. If there are more strings in | |
24559 | %server_prompts% than the number of strings supplied with the AUTH | |
24560 | command, the remaining prompts are used to obtain more data. Each response from | |
24561 | the client may be a list of NUL-separated strings. | |
24562 | ||
068aaea8 PH |
24563 | cindex:[$authenticated_id$] |
24564 | Once a sufficient number of data strings have been received, %server_condition% | |
24565 | is expanded. If the expansion is forced to fail, authentication fails. Any | |
24566 | other expansion failure causes a temporary error code to be returned. If the | |
24567 | result of a successful expansion is an empty string, ``0'', ``no'', or | |
24568 | ``false'', authentication fails. If the result of the expansion is ``1'', | |
24569 | ``yes'', or ``true'', authentication succeeds and the generic %server_set_id% | |
24570 | option is expanded and saved in $authenticated_id$. For any other result, a | |
24571 | temporary error code is returned, with the expanded string as the error text. | |
168e428f PH |
24572 | |
24573 | *Warning*: If you use a lookup in the expansion to find the user's | |
24574 | password, be sure to make the authentication fail if the user is unknown. | |
24575 | There are good and bad examples at the end of the next section. | |
24576 | ||
24577 | ||
24578 | ||
24579 | The PLAIN authentication mechanism | |
24580 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
24581 | cindex:[PLAIN authentication mechanism] | |
24582 | cindex:[authentication,PLAIN mechanism] | |
24583 | cindex:[binary zero,in ^plaintext^ authenticator] | |
24584 | The PLAIN authentication mechanism (RFC 2595) specifies that three strings be | |
24585 | sent as one item of data (that is, one combined string containing two NUL | |
24586 | separators). The data is sent either as part of the AUTH command, or | |
24587 | subsequently in response to an empty prompt from the server. | |
24588 | ||
24589 | The second and third strings are a user name and a corresponding password. | |
24590 | Using a single fixed user name and password as an example, this could be | |
24591 | configured as follows: | |
24592 | ||
24593 | .... | |
24594 | fixed_plain: | |
24595 | driver = plaintext | |
24596 | public_name = PLAIN | |
24597 | server_prompts = : | |
24598 | server_condition = \ | |
24599 | ${if and {{eq{$2}{username}}{eq{$3}{mysecret}}}{yes}{no}} | |
24600 | server_set_id = $2 | |
24601 | .... | |
24602 | ||
24603 | The %server_prompts% setting specifies a single, empty prompt (empty items at | |
24604 | the end of a string list are ignored). If all the data comes as part of the | |
24605 | AUTH command, as is commonly the case, the prompt is not used. This | |
24606 | authenticator is advertised in the response to EHLO as | |
24607 | ||
24608 | 250-AUTH PLAIN | |
24609 | ||
24610 | and a client host can authenticate itself by sending the command | |
24611 | ||
24612 | AUTH PLAIN AHVzZXJuYW1lAG15c2VjcmV0 | |
24613 | ||
24614 | As this contains three strings (more than the number of prompts), no further | |
24615 | data is required from the client. Alternatively, the client may just send | |
24616 | ||
24617 | AUTH PLAIN | |
24618 | ||
24619 | to initiate authentication, in which case the server replies with an empty | |
24620 | prompt. The client must respond with the combined data string. | |
24621 | ||
24622 | The data string is base64 encoded, as required by the RFC. This example, | |
24623 | when decoded, is <'NUL'>`username`<'NUL'>`mysecret`, where <'NUL'> represents a | |
24624 | zero byte. This is split up into three strings, the first of which is empty. | |
24625 | The %server_condition% option in the authenticator checks that the second two | |
24626 | are `username` and `mysecret` respectively. | |
24627 | ||
24628 | Having just one fixed user name and password, as in this example, is not very | |
24629 | realistic, though for a small organization with only a handful of | |
24630 | authenticating clients it could make sense. | |
24631 | ||
24632 | A more sophisticated instance of this authenticator could use the user name in | |
24633 | $2$ to look up a password in a file or database, and maybe do an encrypted | |
24634 | comparison (see %crypteq% in chapter <<CHAPexpand>>). Here is a example of this | |
24635 | approach, where the passwords are looked up in a DBM file. *Warning*: This | |
24636 | is an incorrect example: | |
24637 | ||
24638 | .... | |
24639 | server_condition = \ | |
24640 | ${if eq{$3}{${lookup{$2}dbm{/etc/authpwd}}}{yes}{no}} | |
24641 | .... | |
24642 | ||
24643 | The expansion uses the user name ($2$) as the key to look up a password, | |
24644 | which it then compares to the supplied password ($3$). Why is this example | |
24645 | incorrect? It works fine for existing users, but consider what happens if a | |
24646 | non-existent user name is given. The lookup fails, but as no success/failure | |
24647 | strings are given for the lookup, it yields an empty string. Thus, to defeat | |
24648 | the authentication, all a client has to do is to supply a non-existent user | |
24649 | name and an empty password. The correct way of writing this test is: | |
24650 | ||
24651 | .... | |
24652 | server_condition = ${lookup{$2}dbm{/etc/authpwd}\ | |
24653 | {${if eq{$value}{$3}{yes}{no}}}{no}} | |
24654 | .... | |
24655 | ||
24656 | In this case, if the lookup succeeds, the result is checked; if the lookup | |
24657 | fails, authentication fails. If %crypteq% is being used instead of %eq%, the | |
24658 | first example is in fact safe, because %crypteq% always fails if its second | |
24659 | argument is empty. However, the second way of writing the test makes the logic | |
24660 | clearer. | |
24661 | ||
24662 | ||
24663 | ||
24664 | The LOGIN authentication mechanism | |
24665 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
24666 | cindex:[LOGIN authentication mechanism] | |
24667 | cindex:[authentication,LOGIN mechanism] | |
24668 | The LOGIN authentication mechanism is not documented in any RFC, but is in use | |
24669 | in a number of programs. No data is sent with the AUTH command. Instead, a | |
24670 | user name and password are supplied separately, in response to prompts. The | |
24671 | plaintext authenticator can be configured to support this as in this example: | |
24672 | ||
24673 | .... | |
24674 | fixed_login: | |
24675 | driver = plaintext | |
24676 | public_name = LOGIN | |
24677 | server_prompts = User Name : Password | |
24678 | server_condition = \ | |
24679 | ${if and {{eq{$1}{username}}{eq{$2}{mysecret}}}{yes}{no}} | |
24680 | server_set_id = $1 | |
24681 | .... | |
24682 | ||
24683 | Because of the way plaintext operates, this authenticator accepts data supplied | |
24684 | with the AUTH command (in contravention of the specification of LOGIN), but | |
24685 | if the client does not supply it (as is the case for LOGIN clients), the prompt | |
24686 | strings are used to obtain two data items. | |
24687 | ||
24688 | Some clients are very particular about the precise text of the prompts. For | |
24689 | example, Outlook Express is reported to recognize only ``Username:'' and | |
24690 | ``Password:''. Here is an example of a LOGIN authenticator which uses those | |
24691 | strings, and which uses the %ldapauth% expansion condition to check the user | |
24692 | name and password by binding to an LDAP server: | |
24693 | ||
24694 | .... | |
24695 | login: | |
24696 | driver = plaintext | |
24697 | public_name = LOGIN | |
24698 | server_prompts = Username:: : Password:: | |
24699 | server_condition = ${if ldapauth \ | |
24700 | {user="cn=${quote_ldap_dn:$1},ou=people,o=example.org" \ | |
24701 | pass=${quote:$2} \ | |
24702 | ldap://ldap.example.org/}{yes}{no}} | |
24703 | server_set_id = uid=$1,ou=people,o=example.org | |
24704 | .... | |
24705 | ||
24706 | Note the use of the %quote_ldap_dn% operator to correctly quote the DN for | |
24707 | authentication. However, the basic %quote% operator, rather than any of the | |
24708 | LDAP quoting operators, is the correct one to use for the password, because | |
24709 | quoting is needed only to make the password conform to the Exim syntax. At the | |
24710 | LDAP level, the password is an uninterpreted string. | |
24711 | ||
24712 | ||
24713 | ||
24714 | Support for different kinds of authentication | |
24715 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
24716 | A number of string expansion features are provided for the purpose of | |
24717 | interfacing to different ways of user authentication. These include checking | |
24718 | traditionally encrypted passwords from _/etc/passwd_ (or equivalent), PAM, | |
24719 | Radius, %ldapauth%, and 'pwcheck'. For details see section <<SECTexpcond>>. | |
24720 | ||
24721 | ||
24722 | ||
24723 | ||
24724 | Using plaintext in a client | |
24725 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
24726 | cindex:[options,^plaintext^ authenticator (client)] | |
24727 | The ^plaintext^ authenticator has just one client option: | |
24728 | ||
24729 | ||
24730 | ||
24731 | oindex:[%client_send%] | |
24732 | `..'= | |
24733 | %client_send%, Use: 'plaintext', Type: 'string'!!, Default: 'unset' | |
24734 | === | |
24735 | ||
24736 | The string is a colon-separated list of authentication data strings. Each | |
24737 | string is independently expanded before being sent to the server. The first | |
24738 | string is sent with the AUTH command; any more strings are sent in response | |
24739 | to prompts from the server. | |
24740 | ||
24741 | *Note*: you cannot use expansion to create multiple strings, because | |
24742 | splitting takes priority and happens first. | |
24743 | ||
24744 | Because the PLAIN authentication mechanism requires NUL (binary zero) bytes in | |
24745 | the data, further processing is applied to each string before it is sent. If | |
24746 | there are any single circumflex characters in the string, they are converted to | |
24747 | NULs. Should an actual circumflex be required as data, it must be doubled in | |
24748 | the string. | |
24749 | ||
24750 | This is an example of a client configuration that implements the PLAIN | |
24751 | authentication mechanism with a fixed user name and password: | |
24752 | ||
24753 | fixed_plain: | |
24754 | driver = plaintext | |
24755 | public_name = PLAIN | |
24756 | client_send = ^username^mysecret | |
24757 | ||
24758 | The lack of colons means that the entire text is sent with the AUTH | |
24759 | command, with the circumflex characters converted to NULs. A similar example | |
24760 | that uses the LOGIN mechanism is: | |
24761 | ||
24762 | fixed_login: | |
24763 | driver = plaintext | |
24764 | public_name = LOGIN | |
24765 | client_send = : username : mysecret | |
24766 | ||
24767 | The initial colon means that the first string is empty, so no data is sent with | |
24768 | the AUTH command itself. The remaining strings are sent in response to | |
24769 | prompts. | |
24770 | ||
24771 | ||
24772 | ||
24773 | ||
24774 | //////////////////////////////////////////////////////////////////////////// | |
24775 | //////////////////////////////////////////////////////////////////////////// | |
24776 | ||
24777 | The cram_md5 authenticator | |
24778 | -------------------------- | |
24779 | cindex:[^cram_md5^ authenticator] | |
24780 | cindex:[authenticators,^cram_md5^] | |
24781 | cindex:[CRAM-MD5 authentication mechanism] | |
24782 | cindex:[authentication,CRAM-MD5 mechanism] | |
24783 | The CRAM-MD5 authentication mechanism is described in RFC 2195. The server | |
24784 | sends a challenge string to the client, and the response consists of a user | |
24785 | name and the CRAM-MD5 digest of the challenge string combined with a secret | |
24786 | string (password) which is known to both server and client. Thus, the secret | |
24787 | is not sent over the network as plain text, which makes this authenticator more | |
24788 | secure than ^plaintext^. However, the downside is that the secret has to be | |
24789 | available in plain text at either end. | |
24790 | ||
24791 | ||
24792 | Using cram_md5 as a server | |
24793 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
24794 | cindex:[options,^cram_md5^ authenticator (server)] | |
24795 | This authenticator has one server option, which must be set to configure the | |
24796 | authenticator as a server: | |
24797 | ||
24798 | oindex:[%server_secret%] | |
24799 | `..'= | |
24800 | %server_secret%, Use: 'cram_md5', Type: 'string'!!, Default: 'unset' | |
24801 | === | |
24802 | ||
24803 | cindex:[numerical variables ($1$ $2$ etc),in ^cram_md5^ authenticator] | |
24804 | When the server receives the client's response, the user name is placed in | |
24805 | the expansion variable $1$, and %server_secret% is expanded to obtain the | |
24806 | password for that user. The server then computes the CRAM-MD5 digest that the | |
24807 | client should have sent, and checks that it received the correct string. If the | |
24808 | expansion of %server_secret% is forced to fail, authentication fails. If the | |
24809 | expansion fails for some other reason, a temporary error code is returned to | |
24810 | the client. | |
24811 | ||
24812 | For example, the following authenticator checks that the user name given by the | |
24813 | client is ``ph10'', and if so, uses ``secret'' as the password. For any other user | |
24814 | name, authentication fails. | |
24815 | ||
24816 | fixed_cram: | |
24817 | driver = cram_md5 | |
24818 | public_name = CRAM-MD5 | |
24819 | server_secret = ${if eq{$1}{ph10}{secret}fail} | |
24820 | server_set_id = $1 | |
24821 | ||
068aaea8 | 24822 | cindex:[$authenticated_id$] |
168e428f | 24823 | If authentication succeeds, the setting of %server_set_id% preserves the user |
068aaea8 PH |
24824 | name in $authenticated_id$. A more tyical configuration might look up the |
24825 | secret string in a file, using the user name as the key. For example: | |
168e428f PH |
24826 | |
24827 | lookup_cram: | |
24828 | driver = cram_md5 | |
24829 | public_name = CRAM-MD5 | |
24830 | server_secret = ${lookup{$1}lsearch{/etc/authpwd}{$value}fail} | |
24831 | server_set_id = $1 | |
24832 | ||
24833 | Note that this expansion explicitly forces failure if the lookup fails | |
24834 | because $1$ contains an unknown user name. | |
24835 | ||
24836 | ||
24837 | Using cram_md5 as a client | |
24838 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
24839 | cindex:[options,^cram_md5^ authenticator (client)] | |
24840 | When used as a client, the ^cram_md5^ authenticator has two options: | |
24841 | ||
24842 | ||
24843 | ||
24844 | oindex:[%client_name%] | |
24845 | `..'= | |
24846 | %client_name%, Use: 'cram_md5', Type: 'string'!!, Default: 'the primary host name' | |
24847 | === | |
24848 | ||
24849 | This string is expanded, and the result used as the user name data when | |
24850 | computing the response to the server's challenge. | |
24851 | ||
24852 | ||
24853 | oindex:[%client_secret%] | |
24854 | `..'= | |
24855 | %client_secret%, Use: 'cram_md5', Type: 'string'!!, Default: 'unset' | |
24856 | === | |
24857 | ||
24858 | This option must be set for the authenticator to work as a client. Its value is | |
24859 | expanded and the result used as the secret string when computing the response. | |
24860 | ||
24861 | ||
068aaea8 PH |
24862 | cindex:[$host$] |
24863 | cindex:[$host_address$] | |
168e428f PH |
24864 | Different user names and secrets can be used for different servers by referring |
24865 | to $host$ or $host_address$ in the options. | |
24866 | ||
24867 | Forced failure of either expansion string is treated as an indication that this | |
24868 | authenticator is not prepared to handle this case. Exim moves on to the next | |
24869 | configured client authenticator. Any other expansion failure causes Exim to | |
24870 | give up trying to send the message to the current server. | |
24871 | ||
24872 | A simple example configuration of a ^cram_md5^ authenticator, using fixed | |
24873 | strings, is: | |
24874 | ||
24875 | fixed_cram: | |
24876 | driver = cram_md5 | |
24877 | public_name = CRAM-MD5 | |
24878 | client_name = ph10 | |
24879 | client_secret = secret | |
24880 | ||
24881 | ||
24882 | ||
24883 | ||
24884 | ||
24885 | //////////////////////////////////////////////////////////////////////////// | |
24886 | //////////////////////////////////////////////////////////////////////////// | |
24887 | ||
24888 | The cyrus_sasl authenticator | |
24889 | ---------------------------- | |
24890 | cindex:[^cyrus_sasl^ authenticator] | |
24891 | cindex:[authenticators,^cyrus_sasl^] | |
24892 | cindex:[Cyrus, SASL library] | |
24893 | The code for this authenticator was provided by Matthew Byng-Maddick of A L | |
24894 | Digital Ltd (*http://www.aldigital.co.uk[]*). | |
24895 | ||
24896 | The ^cyrus_sasl^ authenticator provides server support for the Cyrus SASL | |
24897 | library implementation of the RFC 2222 (``Simple Authentication and Security | |
24898 | Layer''). This library supports a number of authentication mechanisms, including | |
24899 | PLAIN and LOGIN, but also several others that Exim does not support directly. | |
24900 | In particular, there is support for Kerberos authentication. | |
24901 | ||
24902 | The ^cyrus_sasl^ authenticator provides a gatewaying mechanism directly to | |
24903 | the Cyrus interface, so if your Cyrus library can do, for example, CRAM-MD5, | |
24904 | then so can the ^cyrus_sasl^ authenticator. By default it uses the public | |
24905 | name of the driver to determine which mechanism to support. | |
24906 | ||
24907 | Where access to some kind of secret file is required, for example in GSSAPI | |
24908 | or CRAM-MD5, it is worth noting that the authenticator runs as the 'exim' | |
24909 | user, and that the Cyrus SASL library has no way of escalating privileges | |
24910 | by default. You may also find you need to set environment variables, | |
24911 | depending on the driver you are using. | |
24912 | ||
24913 | ||
24914 | Using cyrus_sasl as a server | |
24915 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
24916 | The ^cyrus_sasl^ authenticator has four private options. It puts the | |
24917 | username (on a successful authentication) into $1$. | |
24918 | ||
24919 | oindex:[%server_hostname%] | |
24920 | `..'= | |
24921 | %server_hostname%, Use: 'cyrus_sasl', Type: 'string'!!, Default: `$primary_hostname` | |
24922 | === | |
24923 | ||
24924 | This option selects the hostname that is used when communicating with | |
24925 | the library. It is up to the underlying SASL plug-in what it does with | |
24926 | this data. | |
24927 | ||
24928 | ||
24929 | oindex:[%server_mech%] | |
24930 | `..'= | |
24931 | %server_mech%, Use: 'cyrus_sasl', Type: 'string', Default: `public_name` | |
24932 | === | |
24933 | ||
24934 | This option selects the authentication mechanism this driver should | |
24935 | use. It allows you to use a different underlying mechanism from the | |
24936 | advertised name. For example: | |
24937 | ||
24938 | sasl: | |
24939 | driver = cyrus_sasl | |
24940 | public_name = X-ANYTHING | |
24941 | server_mech = CRAM-MD5 | |
24942 | server_set_id = $1 | |
24943 | ||
24944 | ||
24945 | ||
24946 | oindex:[%server_realm%] | |
24947 | `..'= | |
24948 | %server_realm%, Use: 'cyrus_sasl', Type: 'string', Default: 'unset' | |
24949 | === | |
24950 | ||
24951 | This specifies the SASL realm that the server claims to be in. | |
24952 | ||
24953 | ||
24954 | oindex:[%server_service%] | |
24955 | `..'= | |
24956 | %server_service%, Use: 'cyrus_sasl', Type: 'string', Default: `smtp` | |
24957 | === | |
24958 | ||
24959 | This is the SASL service that the server claims to implement. | |
24960 | ||
24961 | ||
24962 | For straightforward cases, you do not need to set any of the authenticator's | |
24963 | private options. All you need to do is to specify an appropriate mechanism as | |
24964 | the public name. Thus, if you have a SASL library that supports CRAM-MD5 and | |
24965 | PLAIN, you could have two authenticators as follows: | |
24966 | ||
24967 | sasl_cram_md5: | |
24968 | driver = cyrus_sasl | |
24969 | public_name = CRAM-MD5 | |
24970 | server_set_id = $1 | |
24971 | ||
24972 | sasl_plain: | |
24973 | driver = cyrus_sasl | |
24974 | public_name = PLAIN | |
24975 | server_set_id = $1 | |
24976 | ||
24977 | ||
24978 | Cyrus SASL does implement the LOGIN authentication method, even though it is | |
24979 | not a standard method. It is disabled by default in the source distribution, | |
24980 | but it is present in many binary distributions. | |
24981 | ||
24982 | ||
24983 | ||
24984 | ||
24985 | //////////////////////////////////////////////////////////////////////////// | |
24986 | //////////////////////////////////////////////////////////////////////////// | |
24987 | ||
24988 | The spa authenticator | |
24989 | --------------------- | |
24990 | cindex:[^spa^ authenticator] | |
24991 | cindex:[authenticators,^spa^] | |
24992 | cindex:[authentication,Microsoft Secure Password] | |
24993 | cindex:[authentication,NTLM] | |
24994 | cindex:[Microsoft Secure Password Authentication] | |
24995 | cindex:[NTLM authentication] | |
24996 | The ^spa^ authenticator provides client support for Microsoft's 'Secure | |
24997 | Password Authentication' mechanism, | |
24998 | which is also sometimes known as NTLM (NT LanMan). The code for client side of | |
24999 | this authenticator was contributed by Marc Prud'hommeaux, and much of it is | |
25000 | taken from the Samba project (*http://www.samba.org[]*). The code for the | |
25001 | server side was subsequently contributed by Tom Kistner. The mechanism works as | |
25002 | follows: | |
25003 | ||
25004 | - After the AUTH command has been accepted, the client sends an SPA | |
25005 | authentication request based on the user name and optional domain. | |
25006 | ||
25007 | - The server sends back a challenge. | |
25008 | ||
25009 | - The client builds a challenge response which makes use of the user's password | |
25010 | and sends it to the server, which then accepts or rejects it. | |
25011 | ||
25012 | Encryption is used to protect the password in transit. | |
25013 | ||
25014 | ||
25015 | ||
25016 | Using spa as a server | |
25017 | ~~~~~~~~~~~~~~~~~~~~~ | |
25018 | cindex:[options,^spa^ authenticator (server)] | |
25019 | The ^spa^ authenticator has just one server option: | |
25020 | ||
25021 | oindex:[%server_password%] | |
25022 | `..'= | |
25023 | %server_password%, Use: 'spa', Type: 'string'!!, Default: 'unset' | |
25024 | === | |
25025 | ||
25026 | cindex:[numerical variables ($1$ $2$ etc),in ^spa^ authenticator] | |
25027 | This option is expanded, and the result must be the cleartext password for the | |
25028 | authenticating user, whose name is at this point in $1$. For example: | |
25029 | ||
068aaea8 PH |
25030 | .... |
25031 | spa: | |
25032 | driver = spa | |
25033 | public_name = NTLM | |
25034 | server_password = ${lookup{$1}lsearch{/etc/exim/spa_clearpass}\ | |
25035 | {$value}fail} | |
25036 | .... | |
168e428f PH |
25037 | |
25038 | If the expansion is forced to fail, authentication fails. Any other expansion | |
25039 | failure causes a temporary error code to be returned. | |
25040 | ||
25041 | ||
25042 | ||
25043 | ||
25044 | ||
25045 | Using spa as a client | |
25046 | ~~~~~~~~~~~~~~~~~~~~~ | |
25047 | cindex:[options,^spa^ authenticator (client)] | |
25048 | The ^spa^ authenticator has the following client options: | |
25049 | ||
25050 | ||
25051 | ||
25052 | oindex:[%client_domain%] | |
25053 | `..'= | |
25054 | %client_domain%, Use: 'spa', Type: 'string'!!, Default: 'unset' | |
25055 | === | |
25056 | ||
25057 | This option specifies an optional domain for the authentication. | |
25058 | ||
25059 | ||
25060 | oindex:[%client_password%] | |
25061 | `..'= | |
25062 | %client_password%, Use: 'spa', Type: 'string'!!, Default: 'unset' | |
25063 | === | |
25064 | ||
25065 | This option specifies the user's password, and must be set. | |
25066 | ||
25067 | ||
25068 | oindex:[%client_username%] | |
25069 | `..'= | |
25070 | %client_username%, Use: 'spa', Type: 'string'!!, Default: 'unset' | |
25071 | === | |
25072 | ||
25073 | This option specifies the user name, and must be set. | |
25074 | ||
25075 | ||
25076 | Here is an example of a configuration of this authenticator for use with the | |
25077 | mail servers at 'msn.com': | |
25078 | ||
25079 | msn: | |
25080 | driver = spa | |
25081 | public_name = MSN | |
25082 | client_username = msn/msn_username | |
25083 | client_password = msn_plaintext_password | |
25084 | client_domain = DOMAIN_OR_UNSET | |
25085 | ||
25086 | ||
25087 | ||
25088 | ||
25089 | ||
25090 | ||
25091 | ||
25092 | //////////////////////////////////////////////////////////////////////////// | |
25093 | //////////////////////////////////////////////////////////////////////////// | |
25094 | ||
25095 | [[CHAPTLS]] | |
25096 | [titleabbrev="Encrypted SMTP connections"] | |
25097 | Encrypted SMTP connections using TLS/SSL | |
25098 | ---------------------------------------- | |
25099 | cindex:[encryption,on SMTP connection] | |
25100 | cindex:[SMTP,encryption] | |
25101 | cindex:[TLS,on SMTP connection] | |
25102 | cindex:[OpenSSL] | |
25103 | cindex:[GnuTLS] | |
25104 | Support for TLS (Transport Layer Security), formerly known as SSL (Secure | |
25105 | Sockets Layer), is implemented by making use of the OpenSSL library or the | |
25106 | GnuTLS library (Exim requires GnuTLS release 1.0 or later). There is no | |
25107 | cryptographic code in the Exim distribution itself for implementing TLS. In | |
25108 | order to use this feature you must install OpenSSL or GnuTLS, and then build a | |
25109 | version of Exim that includes TLS support (see section <<SECTinctlsssl>>). You | |
25110 | also need to understand the basic concepts of encryption at a managerial level, | |
25111 | and in particular, the way that public keys, private keys, and certificates are | |
25112 | used. | |
25113 | ||
068aaea8 | 25114 | RFC 3207 defines how SMTP connections can make use of encryption. Once a |
168e428f PH |
25115 | connection is established, the client issues a STARTTLS command. If the |
25116 | server accepts this, the client and the server negotiate an encryption | |
25117 | mechanism. If the negotiation succeeds, the data that subsequently passes | |
25118 | between them is encrypted. | |
25119 | ||
25120 | Exim's ACLs can detect whether the current SMTP session is encrypted or not, | |
25121 | and if so, what cipher suite is in use, whether the client supplied a | |
25122 | certificate, and whether or not that certificate was verified. This makes it | |
25123 | possible for an Exim server to deny or accept certain commands based on the | |
25124 | encryption state. | |
25125 | ||
25126 | *Warning*: certain types of firewall and certain anti-virus products can | |
25127 | disrupt TLS connections. You need to turn off SMTP scanning for these products | |
25128 | in order to get TLS to work. | |
25129 | ||
25130 | ||
25131 | ||
25132 | Support for the legacy ``ssmtp'' (aka ``smtps'') protocol | |
25133 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
25134 | cindex:[ssmtp protocol] | |
25135 | cindex:[smtps protocol] | |
25136 | cindex:[SMTP,ssmtp protocol] | |
25137 | cindex:[SMTP,smtps protocol] | |
25138 | Early implementations of encrypted SMTP used a different TCP port from normal | |
25139 | SMTP, and expected an encryption negotiation to start immediately, instead of | |
25140 | waiting for a STARTTLS command from the client using the standard SMTP | |
25141 | port. The protocol was called ``ssmtp'' or ``smtps'', and port 465 was allocated | |
25142 | for this purpose. | |
25143 | ||
25144 | This approach was abandoned when encrypted SMTP was standardised, but there are | |
25145 | still some legacy clients that use it. Exim supports these clients by means of | |
25146 | the %tls_on_connect_ports% global option. Its value must be a list of port | |
25147 | numbers; the most common use is expected to be: | |
25148 | ||
25149 | tls_on_connect_ports = 465 | |
25150 | ||
25151 | The port numbers specified by this option apply to all SMTP connections, both | |
25152 | via the daemon and via 'inetd'. You still need to specify all the ports that | |
25153 | the daemon uses (by setting %daemon_smtp_ports% or %local_interfaces% or the | |
25154 | %-oX% command line option) because %tls_on_connect_ports% does not add an | |
25155 | extra port -- rather, it specifies different behaviour on a port that is | |
25156 | defined elsewhere. | |
25157 | ||
25158 | There is also a %-tls-on-connect% command line option. This overrides | |
25159 | %tls_on_connect_ports%; it forces the legacy behaviour for all ports. | |
25160 | ||
25161 | ||
25162 | ||
25163 | ||
25164 | ||
25165 | ||
25166 | [[SECTopenvsgnu]] | |
25167 | OpenSSL vs GnuTLS | |
25168 | ~~~~~~~~~~~~~~~~~ | |
25169 | cindex:[TLS,OpenSSL 'vs' GnuTLS] | |
25170 | The first TLS support in Exim was implemented using OpenSSL. Support for GnuTLS | |
25171 | followed later, when the first versions of GnuTLS were released. To build Exim | |
25172 | to use GnuTLS, you need to set | |
25173 | ||
25174 | USE_GNUTLS=yes | |
25175 | ||
25176 | in Local/Makefile, in addition to | |
25177 | ||
25178 | SUPPORT_TLS=yes | |
25179 | ||
25180 | You must also set TLS_LIBS and TLS_INCLUDE appropriately, so that the | |
25181 | include files and libraries for GnuTLS can be found. | |
25182 | ||
25183 | There are some differences in usage when using GnuTLS instead of OpenSSL: | |
25184 | ||
25185 | - The %tls_verify_certificates% option must contain the name of a file, not the | |
25186 | name of a directory (for OpenSSL it can be either). | |
25187 | ||
25188 | - The %tls_dhparam% option is ignored, because early versions of GnuTLS had no | |
25189 | facility for varying its Diffie-Hellman parameters. I understand that this has | |
25190 | changed, but Exim has not been updated to provide this facility. | |
25191 | ||
068aaea8 PH |
25192 | - cindex:[$tls_peerdn$] |
25193 | Distinguished Name (DN) strings reported by the OpenSSL library use a slash for | |
168e428f PH |
25194 | separating fields; GnuTLS uses commas, in accordance with RFC 2253. This |
25195 | affects the value of the $tls_peerdn$ variable. | |
25196 | ||
25197 | - OpenSSL identifies cipher suites using hyphens as separators, for example: | |
25198 | DES-CBC3-SHA. GnuTLS uses underscores, for example: RSA_ARCFOUR_SHA. What is | |
25199 | more, OpenSSL complains if underscores are present in a cipher list. To make | |
25200 | life simpler, Exim changes underscores to hyhens for OpenSSL and hyphens to | |
25201 | underscores for GnuTLS when processing lists of cipher suites in the | |
25202 | %tls_require_ciphers% options (the global option and the ^smtp^ transport | |
25203 | option). | |
25204 | ||
25205 | - The %tls_require_ciphers% options operate differently, as described in the | |
068aaea8 PH |
25206 | sections <<SECTreqciphssl>> and <<SECTreqciphgnu>>. |
25207 | ||
25208 | ||
25209 | GnuTLS parameter computation | |
25210 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
25211 | ||
25212 | GnuTLS uses RSA and D-H parameters that take a substantial amount of time to | |
25213 | compute. It is unreasonable to re-compute them for every TLS session. | |
25214 | Therefore, Exim keeps this data in a file in its spool directory, called | |
25215 | _gnutls-params_. The file is owned by the Exim user and is readable only by its | |
25216 | owner. Every Exim process that start up GnuTLS reads the RSA and D-H parameters | |
25217 | from this file. If the file does not exist, the first Exim process that needs | |
25218 | it computes the data and writes it to a temporary file which is renamed once it | |
25219 | is complete. It does not matter if several Exim processes do this | |
25220 | simultaneously (apart from wasting a few resources). Once a file is in place, | |
25221 | new Exim processes immediately start using it. | |
25222 | ||
25223 | [revisionflag="changed"] | |
25224 | For maximum security, the parameters that are stored in this file should be | |
25225 | recalculated periodically, the frequency depending on your paranoia level. | |
25226 | Arranging this is easy in principle; just delete the file when you want new | |
25227 | values to be computed. However, there may be a problem. The calculation of new | |
25228 | parameters needs random numbers, and these are obtained from _/dev/random_. If | |
25229 | the system is not very active, _/dev/random_ may delay returning data until | |
25230 | enough randomness (entropy) is available. This may cause Exim to hang for a | |
25231 | substantial amount of time, causing timeouts on incoming connections. | |
25232 | ||
25233 | [revisionflag="changed"] | |
25234 | The solution is to generate the parameters externally to Exim. They are stored | |
25235 | in _gnutls-params_ in PEM format, which means that they can be generated | |
25236 | externally using the ^certtool^ command that is part of GnuTLS. | |
25237 | ||
25238 | [revisionflag="changed"] | |
25239 | To replace the parameters with new ones, instead of deleting the file | |
25240 | and letting Exim re-create it, you can generate new parameters using | |
25241 | ^certtool^ and, when this has been done, replace Exim's cache file by | |
25242 | renaming. The relevant commands are something like this: | |
25243 | ||
25244 | [revisionflag="changed"] | |
25245 | .... | |
25246 | # rm -f new-params | |
25247 | # touch new-params | |
25248 | # chown exim:exim new-params | |
25249 | # chmod 0400 new-params | |
25250 | # certtool --generate-privkey --bits 512 >new-params | |
25251 | # echo "" >>new-params | |
25252 | # certtool --generate-dh-params --bits 1024 >> new-params | |
25253 | # mv new-params gnutls-params | |
25254 | .... | |
25255 | ||
25256 | [revisionflag="changed"] | |
25257 | If Exim never has to generate the parameters itself, the possibility of | |
25258 | stalling is removed. | |
168e428f PH |
25259 | |
25260 | ||
25261 | ||
25262 | [[SECTreqciphssl]] | |
25263 | Requiring specific ciphers in OpenSSL | |
25264 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
25265 | cindex:[TLS,requiring specific ciphers (OpenSSL)] | |
25266 | cindex:[%tls_require_ciphers%,OpenSSL] | |
25267 | There is a function in the OpenSSL library that can be passed a list of cipher | |
25268 | suites before the cipher negotiation takes place. This specifies which ciphers | |
25269 | are acceptable. The list is colon separated and may contain names like | |
25270 | DES-CBC3-SHA. Exim passes the expanded value of %tls_require_ciphers% | |
25271 | directly to this function call. The following quotation from the OpenSSL | |
25272 | documentation specifies what forms of item are allowed in the cipher string: | |
25273 | ||
25274 | - It can consist of a single cipher suite such as RC4-SHA. | |
25275 | ||
25276 | - It can represent a list of cipher suites containing a certain algorithm, | |
25277 | or cipher suites of a certain type. For example SHA1 represents all | |
25278 | ciphers suites using the digest algorithm SHA1 and SSLv3 represents all | |
25279 | SSL v3 algorithms. | |
25280 | ||
25281 | - Lists of cipher suites can be combined in a single cipher string using | |
25282 | the + character. This is used as a logical and operation. For example | |
25283 | SHA1+DES represents all cipher suites containing the SHA1 and the DES | |
25284 | algorithms. | |
25285 | ||
25286 | - Each cipher string can be optionally preceded by the characters `!`, `-` or | |
25287 | `+`. | |
25288 | + | |
25289 | If `!` is used then the ciphers are permanently deleted from the list. The | |
25290 | ciphers deleted can never reappear in the list even if they are explicitly | |
25291 | stated. | |
25292 | + | |
25293 | If `-` is used then the ciphers are deleted from the list, but some or all | |
25294 | of the ciphers can be added again by later options. | |
25295 | + | |
25296 | If `+` is used then the ciphers are moved to the end of the list. This | |
25297 | option doesn't add any new ciphers it just moves matching existing ones. | |
25298 | + | |
25299 | If none of these characters is present then the string is just interpreted as | |
25300 | a list of ciphers to be appended to the current preference list. If the list | |
25301 | includes any ciphers already present they will be ignored: that is, they will | |
25302 | not moved to the end of the list. | |
25303 | ||
25304 | ||
25305 | ||
25306 | ||
25307 | [[SECTreqciphgnu]] | |
25308 | Requiring specific ciphers in GnuTLS | |
25309 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
25310 | cindex:[TLS,requiring specific ciphers (GnuTLS)] | |
25311 | cindex:[%tls_require_ciphers%,GnuTLS] | |
25312 | The GnuTLS library does not have a combined function like OpenSSL. Instead, | |
25313 | it allows the caller to specify separate lists of key-exchange methods, | |
25314 | main cipher algorithms, and MAC algorithms. Unfortunately, these lists are | |
25315 | numerical, and the library does not have a function for turning names into | |
25316 | numbers. Consequently, the list of recognized names has to be built into | |
25317 | the application. | |
25318 | ||
25319 | At present, Exim permits only the list of main cipher algorithms to be | |
25320 | changed. The %tls_require_ciphers% option is in the same format as for | |
25321 | OpenSSL. Exim searches each item for the name of available algorithm. For | |
25322 | example, if the list contains RSA_AES_SHA then AES is recognized. | |
25323 | ||
25324 | The cipher algorithms list starts out with a default set of algorithms. If | |
25325 | the first item in %tls_require_ciphers% does 'not' start with an | |
25326 | exclamation mark, all the default items are deleted. Thus, only those specified | |
25327 | can be used. If the first item in %tls_require_ciphers% 'does' start with | |
25328 | an exclamation mark, the defaults are left on the list. | |
25329 | ||
25330 | Then, any item that starts with an exclamation mark causes the relevent | |
25331 | algorithms to be removed from the list, and any item that does not start | |
25332 | with an exclamation mark causes the relevant algorithms to be added to the | |
25333 | list. Thus, | |
25334 | ||
25335 | tls_require_ciphers = !RSA_ARCFOUR_SHA | |
25336 | ||
25337 | allows all the defaults except those that use ARCFOUR, whereas | |
25338 | ||
25339 | tls_require_ciphers = AES : 3DES | |
25340 | ||
25341 | allows only cipher suites that use AES and 3DES. The currently recognized | |
25342 | algorithms are: AES_256, AES_128, AES (both of the preceding), 3DES, and | |
25343 | ARCFOUR_128. Unrecognized algorithms are ignored. In a server, the order of the | |
25344 | list is unimportant; the server will advertise the availability of all the | |
25345 | relevant cipher suites. However, in a client, the order of the list specifies a | |
25346 | preference order for the algorithms. The first one in the client's list that is | |
25347 | also advertised by the server is tried first. The default order is as listed | |
25348 | above. | |
25349 | ||
25350 | ||
25351 | ||
25352 | ||
25353 | Configuring an Exim server to use TLS | |
25354 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
25355 | cindex:[TLS,configuring an Exim server] | |
25356 | When Exim has been built with TLS support, it advertises the availability of | |
25357 | the STARTTLS command to client hosts that match %tls_advertise_hosts%, | |
25358 | but not to any others. The default value of this option is unset, which means | |
25359 | that STARTTLS is not advertised at all. This default is chosen because you | |
25360 | need to set some other options in order to make TLS avaliable, and also it is | |
25361 | sensible for systems that want to use TLS only as a client. | |
25362 | ||
25363 | If a client issues a STARTTLS command and there is some configuration | |
25364 | problem in the server, the command is rejected with a 454 error. If the client | |
25365 | persists in trying to issue SMTP commands, all except QUIT are rejected | |
25366 | with the error | |
25367 | ||
25368 | 554 Security failure | |
25369 | ||
25370 | If a STARTTLS command is issued within an existing TLS session, it is | |
25371 | rejected with a 554 error code. | |
25372 | ||
25373 | To enable TLS operations on a server, you must set %tls_advertise_hosts% to | |
25374 | match some hosts. You can, of course, set it to \* to match all hosts. | |
25375 | However, this is not all you need to do. TLS sessions to a server won't work | |
25376 | without some further configuration at the server end. | |
25377 | ||
25378 | It is rumoured that all existing clients that support TLS/SSL use RSA | |
25379 | encryption. To make this work you need to set, in the server, | |
25380 | ||
25381 | tls_certificate = /some/file/name | |
25382 | tls_privatekey = /some/file/name | |
25383 | ||
25384 | The first file contains the server's X509 certificate, and the second contains | |
25385 | the private key that goes with it. These files need to be readable by the Exim | |
25386 | user, and must always be given as full path names. They can be the same file if | |
25387 | both the certificate and the key are contained within it. If %tls_privatekey% | |
25388 | is not set, this is assumed to be the case. The certificate file may also | |
25389 | contain intermediate certificates that need to be sent to the client to enable | |
25390 | it to authenticate the server's certificate. | |
25391 | ||
25392 | If you do not understand about certificates and keys, please try to find a | |
25393 | source of this background information, which is not Exim-specific. (There are a | |
25394 | few comments below in section <<SECTcerandall>>.) | |
25395 | ||
25396 | *Note*: These options do not apply when Exim is operating as a client -- | |
25397 | they apply only in the case of a server. For a client, you must set the options | |
25398 | of the same name in an ^smtp^ transport. | |
25399 | ||
25400 | With just these options, Exim will work as a server with clients such as | |
25401 | Netscape. It does not require the client to have a certificate (but see below | |
25402 | for how to insist on this). There is one other option that may be needed in | |
25403 | other situations. If | |
25404 | ||
25405 | tls_dhparam = /some/file/name | |
25406 | ||
25407 | is set, the SSL library is initialized for the use of Diffie-Hellman ciphers | |
25408 | with the parameters contained in the file. This increases the set of cipher | |
25409 | suites that the server supports. See the command | |
25410 | ||
25411 | openssl dhparam | |
25412 | ||
25413 | for a way of generating this data. | |
25414 | At present, %tls_dhparam% is used only when Exim is linked with OpenSSL. It is | |
25415 | ignored if GnuTLS is being used. | |
25416 | ||
25417 | The strings supplied for these three options are expanded every time a client | |
25418 | host connects. It is therefore possible to use different certificates and keys | |
25419 | for different hosts, if you so wish, by making use of the client's IP address | |
25420 | in $sender_host_address$ to control the expansion. If a string expansion is | |
25421 | forced to fail, Exim behaves as if the option is not set. | |
25422 | ||
25423 | cindex:[cipher,logging] | |
25424 | cindex:[log,TLS cipher] | |
068aaea8 | 25425 | cindex:[$tls_cipher$] |
168e428f PH |
25426 | The variable $tls_cipher$ is set to the cipher suite that was negotiated for |
25427 | an incoming TLS connection. It is included in the 'Received:' header of an | |
25428 | incoming message (by default -- you can, of course, change this), and it is | |
25429 | also included in the log line that records a message's arrival, keyed by ``X='', | |
25430 | unless the %tls_cipher% log selector is turned off. | |
25431 | The %encrypted% condition can be used to test for specific cipher suites in | |
25432 | ACLs. | |
25433 | ||
25434 | The ACLs that run for subsequent SMTP commands can check the name of the cipher | |
25435 | suite and vary their actions accordingly. The cipher suite names are those used | |
25436 | by OpenSSL. These may differ from the names used elsewhere. For example, | |
25437 | OpenSSL uses the name DES-CBC3-SHA for the cipher suite which in other contexts | |
25438 | is known as TLS_RSA_WITH_3DES_EDE_CBC_SHA. Check the OpenSSL | |
25439 | documentation for more details. | |
25440 | ||
25441 | ||
25442 | ||
25443 | Requesting and verifying client certificates | |
25444 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
25445 | cindex:[certificate,verification of client] | |
25446 | cindex:[TLS,client certificate verification] | |
25447 | If you want an Exim server to request a certificate when negotiating a TLS | |
25448 | session with a client, you must set either %tls_verify_hosts% or | |
25449 | %tls_try_verify_hosts%. You can, of course, set either of them to \* to | |
25450 | apply to all TLS connections. For any host that matches one of these options, | |
25451 | Exim requests a certificate as part of the setup of the TLS session. The | |
25452 | contents of the certificate are verified by comparing it with a list of | |
25453 | expected certificates. These must be available in a file or, | |
25454 | for OpenSSL only (not GnuTLS), a directory, identified by | |
25455 | %tls_verify_certificates%. | |
25456 | ||
25457 | A file can contain multiple certificates, concatenated end to end. If a | |
25458 | directory is used | |
25459 | (OpenSSL only), | |
25460 | each certificate must be in a separate file, with a name (or a symbolic link) | |
25461 | of the form <'hash'>.0, where <'hash'> is a hash value constructed from the | |
25462 | certificate. You can compute the relevant hash by running the command | |
25463 | ||
25464 | openssl x509 -hash -noout -in /cert/file | |
25465 | ||
25466 | where _/cert/file_ contains a single certificate. | |
25467 | ||
25468 | The difference between %tls_verify_hosts% and %tls_try_verify_hosts% is | |
25469 | what happens if the client does not supply a certificate, or if the certificate | |
25470 | does not match any of the certificates in the collection named by | |
25471 | %tls_verify_certificates%. If the client matches %tls_verify_hosts%, the | |
25472 | attempt to set up a TLS session is aborted, and the incoming connection is | |
25473 | dropped. If the client matches %tls_try_verify_hosts%, the (encrypted) SMTP | |
25474 | session continues. ACLs that run for subsequent SMTP commands can detect the | |
25475 | fact that no certificate was verified, and vary their actions accordingly. For | |
25476 | example, you can insist on a certificate before accepting a message for | |
25477 | relaying, but not when the message is destined for local delivery. | |
25478 | ||
068aaea8 | 25479 | cindex:[$tls_peerdn$] |
168e428f PH |
25480 | When a client supplies a certificate (whether it verifies or not), the value of |
25481 | the Distinguished Name of the certificate is made available in the variable | |
25482 | $tls_peerdn$ during subsequent processing of the message. | |
25483 | ||
25484 | cindex:[log,distinguished name] | |
25485 | Because it is often a long text string, it is not included in the log line or | |
25486 | 'Received:' header by default. You can arrange for it to be logged, keyed by | |
25487 | ``DN='', by setting the %tls_peerdn% log selector, and you can use | |
25488 | %received_header_text% to change the 'Received:' header. When no certificate | |
25489 | is supplied, $tls_peerdn$ is empty. | |
25490 | ||
25491 | ||
25492 | Revoked certificates | |
25493 | ~~~~~~~~~~~~~~~~~~~~ | |
25494 | cindex:[TLS,revoked certificates] | |
25495 | cindex:[revocation list] | |
25496 | cindex:[certificate,revocation list] | |
25497 | Certificate issuing authorities issue Certificate Revocation Lists (CRLs) when | |
25498 | certificates are revoked. If you have such a list, you can pass it to an Exim | |
25499 | server using the global option called %tls_crl% and to an Exim client using an | |
25500 | identically named option for the ^smtp^ transport. In each case, the value of | |
25501 | the option is expanded and must then be the name of a file that contains a CRL | |
25502 | in PEM format. | |
25503 | ||
25504 | ||
25505 | Configuring an Exim client to use TLS | |
25506 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
25507 | cindex:[cipher,logging] | |
25508 | cindex:[log,TLS cipher] | |
25509 | cindex:[log,distinguished name] | |
25510 | cindex:[TLS,configuring an Exim client] | |
25511 | The %tls_cipher% and %tls_peerdn% log selectors apply to outgoing SMTP | |
25512 | deliveries as well as to incoming, the latter one causing logging of the | |
25513 | server certificate's DN. The remaining client configuration for TLS is all | |
25514 | within the ^smtp^ transport. | |
25515 | ||
25516 | It is not necessary to set any options to have TLS work in the ^smtp^ | |
25517 | transport. If Exim is built with TLS support, and TLS is advertised by a | |
25518 | server, the ^smtp^ transport always tries to start a TLS session. However, | |
25519 | this can be prevented by setting %hosts_avoid_tls% (an option of the | |
25520 | transport) to a list of server hosts for which TLS should not be used. | |
25521 | ||
25522 | If you do not want Exim to attempt to send messages unencrypted when an attempt | |
25523 | to set up an encrypted connection fails in any way, you can set | |
25524 | %hosts_require_tls% to a list of hosts for which encryption is mandatory. For | |
25525 | those hosts, delivery is always deferred if an encrypted connection cannot be | |
25526 | set up. If there are any other hosts for the address, they are tried in the | |
25527 | usual way. | |
25528 | ||
25529 | When the server host is not in %hosts_require_tls%, Exim may try to deliver | |
25530 | the message unencrypted. It always does this if the response to STARTTLS is | |
25531 | a 5##'xx' code. For a temporary error code, or for a failure to negotiate a TLS | |
25532 | session after a success response code, what happens is controlled by the | |
25533 | %tls_tempfail_tryclear% option of the ^smtp^ transport. If it is false, | |
25534 | delivery to this host is deferred, and other hosts (if available) are tried. If | |
25535 | it is true, Exim attempts to deliver unencrypted after a 4##'xx' response to | |
25536 | STARTTLS, and if STARTTLS is accepted, but the subsequent TLS | |
25537 | negotiation fails, Exim closes the current connection (because it is in an | |
25538 | unknown state), opens a new one to the same host, and then tries the delivery | |
25539 | unencrypted. | |
25540 | ||
25541 | ||
25542 | The %tls_certificate% and %tls_privatekey% options of the ^smtp^ transport | |
25543 | provide the client with a certificate, which is passed to the server if it | |
25544 | requests it. If the server is Exim, it will request a certificate only if | |
25545 | %tls_verify_hosts% or %tls_try_verify_hosts% matches the client. | |
25546 | *Note*: these options must be set in the ^smtp^ transport for Exim to use | |
25547 | TLS when it is operating as a client. Exim does not assume that a server | |
25548 | certificate (set by the global options of the same name) should also be used | |
25549 | when operating as a client. | |
25550 | ||
25551 | If %tls_verify_certificates% is set, it must name a file or, | |
25552 | for OpenSSL only (not GnuTLS), a directory, that contains a collection of | |
25553 | expected server certificates. The client verifies the server's certificate | |
25554 | against this collection, taking into account any revoked certificates that are | |
25555 | in the list defined by %tls_crl%. | |
25556 | ||
25557 | If | |
25558 | %tls_require_ciphers% is set on the ^smtp^ transport, it must contain a | |
25559 | list of permitted cipher suites. If either of these checks fails, delivery to | |
25560 | the current host is abandoned, and the ^smtp^ transport tries to deliver to | |
25561 | alternative hosts, if any. | |
25562 | ||
068aaea8 PH |
25563 | cindex:[$host$] |
25564 | cindex:[$host_address$] | |
168e428f PH |
25565 | All the TLS options in the ^smtp^ transport are expanded before use, with |
25566 | $host$ and $host_address$ containing the name and address of the server to | |
25567 | which the client is connected. Forced failure of an expansion causes Exim to | |
25568 | behave as if the relevant option were unset. | |
25569 | ||
25570 | ||
25571 | ||
25572 | [[SECTmulmessam]] | |
25573 | Multiple messages on the same encrypted TCP/IP connection | |
25574 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
25575 | cindex:[multiple SMTP deliveries with TLS] | |
25576 | cindex:[TLS,multiple message deliveries] | |
25577 | Exim sends multiple messages down the same TCP/IP connection by starting up | |
25578 | an entirely new delivery process for each message, passing the socket from | |
25579 | one process to the next. This implementation does not fit well with the use | |
25580 | of TLS, because there is quite a lot of state information associated with a TLS | |
25581 | connection, not just a socket identification. Passing all the state information | |
25582 | to a new process is not feasible. Consequently, Exim shuts down an existing TLS | |
25583 | session before passing the socket to a new process. The new process may then | |
25584 | try to start a new TLS session, and if successful, may try to re-authenticate | |
25585 | if AUTH is in use, before sending the next message. | |
25586 | ||
25587 | The RFC is not clear as to whether or not an SMTP session continues in clear | |
25588 | after TLS has been shut down, or whether TLS may be restarted again later, as | |
25589 | just described. However, if the server is Exim, this shutdown and | |
25590 | reinitialization works. It is not known which (if any) other servers operate | |
25591 | successfully if the client closes a TLS session and continues with unencrypted | |
25592 | SMTP, but there are certainly some that do not work. For such servers, Exim | |
25593 | should not pass the socket to another process, because the failure of the | |
25594 | subsequent attempt to use it would cause Exim to record a temporary host error, | |
25595 | and delay other deliveries to that host. | |
25596 | ||
25597 | To test for this case, Exim sends an EHLO command to the server after | |
25598 | closing down the TLS session. If this fails in any way, the connection is | |
25599 | closed instead of being passed to a new delivery process, but no retry | |
25600 | information is recorded. | |
25601 | ||
25602 | There is also a manual override; you can set %hosts_nopass_tls% on the | |
25603 | ^smtp^ transport to match those hosts for which Exim should not pass | |
25604 | connections to new processes if TLS has been used. | |
25605 | ||
25606 | ||
25607 | ||
25608 | ||
25609 | [[SECTcerandall]] | |
25610 | Certificates and all that | |
25611 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
25612 | cindex:[certificate,references to discussion] | |
25613 | In order to understand fully how TLS works, you need to know about | |
25614 | certificates, certificate signing, and certificate authorities. This is not the | |
25615 | place to give a tutorial, especially as I do not know very much about it | |
25616 | myself. Some helpful introduction can be found in the FAQ for the SSL addition | |
25617 | to Apache, currently at | |
25618 | ||
25619 | &&& | |
25620 | *http://www.modssl.org/docs/2.7/ssl_faq.html#ToC24[]* | |
25621 | &&& | |
25622 | ||
25623 | Other parts of the 'modssl' documentation are also helpful, and have | |
25624 | links to further files. | |
25625 | Eric Rescorla's book, 'SSL and TLS', published by Addison-Wesley (ISBN | |
25626 | 0-201-61598-3), contains both introductory and more in-depth descriptions. | |
25627 | Some sample programs taken from the book are available from | |
25628 | ||
25629 | &&& | |
25630 | *http://www.rtfm.com/openssl-examples/[]* | |
25631 | &&& | |
25632 | ||
25633 | ||
25634 | ||
25635 | Certificate chains | |
25636 | ~~~~~~~~~~~~~~~~~~ | |
25637 | The file named by %tls_certificate% may contain more than one | |
25638 | certificate. This is useful in the case where the certificate that is being | |
25639 | sent is validated by an intermediate certificate which the other end does | |
25640 | not have. Multiple certificates must be in the correct order in the file. | |
25641 | First the host's certificate itself, then the first intermediate | |
25642 | certificate to validate the issuer of the host certificate, then the next | |
25643 | intermediate certificate to validate the issuer of the first intermediate | |
25644 | certificate, and so on, until finally (optionally) the root certificate. | |
25645 | The root certificate must already be trusted by the recipient for | |
25646 | validation to succeed, of course, but if it's not preinstalled, sending the | |
25647 | root certificate along with the rest makes it available for the user to | |
25648 | install if the receiving end is a client MUA that can interact with a user. | |
25649 | ||
25650 | ||
25651 | Self-signed certificates | |
25652 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
25653 | cindex:[certificate,self-signed] | |
25654 | You can create a self-signed certificate using the 'req' command provided | |
25655 | with OpenSSL, like this: | |
25656 | ||
25657 | .... | |
25658 | openssl req -x509 -newkey rsa:1024 -keyout file1 -out file2 \ | |
25659 | -days 9999 -nodes | |
25660 | .... | |
25661 | ||
25662 | _file1_ and _file2_ can be the same file; the key and the certificate are | |
25663 | delimited and so can be identified independently. The %-days% option | |
25664 | specifies a period for which the certificate is valid. The %-nodes% option is | |
25665 | important: if you do not set it, the key is encrypted with a passphrase | |
25666 | that you are prompted for, and any use that is made of the key causes more | |
25667 | prompting for the passphrase. This is not helpful if you are going to use | |
25668 | this certificate and key in an MTA, where prompting is not possible. | |
25669 | ||
25670 | A self-signed certificate made in this way is sufficient for testing, and | |
25671 | may be adequate for all your requirements if you are mainly interested in | |
25672 | encrypting transfers, and not in secure identification. | |
25673 | ||
25674 | However, many clients require that the certificate presented by the server be a | |
25675 | user (also called ``leaf'' or ``site'') certificate, and not a self-signed | |
25676 | certificate. In this situation, the self-signed certificate described above | |
25677 | must be installed on the client host as a trusted root 'certification | |
25678 | authority' (CA), and the certificate used by Exim must be a user certificate | |
25679 | signed with that self-signed certificate. | |
25680 | ||
25681 | For information on creating self-signed CA certificates and using them to sign | |
25682 | user certificates, see the 'General implementation overview' chapter of the | |
25683 | Open-source PKI book, available online at *http://ospkibook.sourceforge.net/[]*. | |
25684 | ||
25685 | ||
25686 | ||
25687 | //////////////////////////////////////////////////////////////////////////// | |
25688 | //////////////////////////////////////////////////////////////////////////// | |
25689 | ||
25690 | [[CHAPACL]] | |
25691 | Access control lists | |
25692 | -------------------- | |
25693 | cindex:[{ACL},description] | |
25694 | cindex:[control of incoming mail] | |
25695 | cindex:[message,controlling incoming] | |
25696 | cindex:[policy control,access control lists] | |
25697 | Access Control Lists (ACLs) are defined in a separate section of the run time | |
25698 | configuration file, headed by ``begin acl''. Each ACL definition starts with a | |
25699 | name, terminated by a colon. Here is a complete ACL section that contains just | |
25700 | one very small ACL: | |
25701 | ||
25702 | begin acl | |
25703 | ||
25704 | small_acl: | |
25705 | accept hosts = one.host.only | |
25706 | ||
25707 | You can have as many lists as you like in the ACL section, and the order in | |
25708 | which they appear does not matter. The lists are self-terminating. | |
25709 | ||
25710 | The majority of ACLs are used to control Exim's behaviour when it receives | |
25711 | certain SMTP commands. This applies both to incoming TCP/IP connections, and | |
25712 | when a local process submits a message using SMTP by specifying the %-bs% | |
25713 | option. The most common use is for controlling which recipients are accepted | |
25714 | in incoming messages. In addition, you can define an ACL that is used to check | |
25715 | local non-SMTP messages. The default configuration file contains an example of | |
25716 | a realistic ACL for checking RCPT commands. This is discussed in chapter | |
25717 | <<CHAPdefconfil>>. | |
25718 | ||
25719 | ||
25720 | Testing ACLs | |
25721 | ~~~~~~~~~~~~ | |
25722 | The %-bh% command line option provides a way of testing your ACL configuration | |
25723 | locally by running a fake SMTP session with which you interact. The host | |
25724 | 'relay-test.mail-abuse.org' provides a service for checking your relaying | |
25725 | configuration (see section <<SECTcheralcon>> for more details). | |
25726 | ||
25727 | ||
25728 | ||
25729 | Specifying when ACLs are used | |
25730 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
25731 | cindex:[{ACL},options for specifying] | |
25732 | In order to cause an ACL to be used, you have to name it in one of the relevant | |
25733 | options in the main part of the configuration. These options are: | |
25734 | cindex:[AUTH,ACL for] | |
25735 | cindex:[DATA, ACLs for] | |
25736 | cindex:[ETRN,ACL for] | |
25737 | cindex:[EXPN,ACL for] | |
25738 | cindex:[HELO,ACL for] | |
25739 | cindex:[EHLO,ACL for] | |
25740 | cindex:[MAIL,ACL for] | |
25741 | cindex:[QUIT, ACL for] | |
25742 | cindex:[RCPT,ACL for] | |
25743 | cindex:[STARTTLS, ACL for] | |
25744 | cindex:[VRFY,ACL for] | |
25745 | cindex:[SMTP connection, ACL for] | |
25746 | cindex:[non-smtp message, ACL for] | |
25747 | ||
25748 | [frame="none"] | |
25749 | `--`--------------------`--------------------------------------- | |
25750 | %acl_not_smtp% ACL for non-SMTP messages | |
25751 | %acl_smtp_auth% ACL for AUTH | |
25752 | %acl_smtp_connect% ACL for start of SMTP connection | |
25753 | %acl_smtp_data% ACL after DATA is complete | |
25754 | %acl_smtp_etrn% ACL for ETRN | |
25755 | %acl_smtp_expn% ACL for EXPN | |
25756 | %acl_smtp_helo% ACL for HELO or EHLO | |
25757 | %acl_smtp_mail% ACL for MAIL | |
25758 | %acl_smtp_mailauth% ACL for the AUTH parameter of MAIL | |
25759 | %acl_smtp_mime% ACL for content-scanning MIME parts | |
25760 | %acl_smtp_predata% ACL at start of DATA command | |
25761 | %acl_smtp_quit% ACL for QUIT | |
25762 | %acl_smtp_rcpt% ACL for RCPT | |
25763 | %acl_smtp_starttls% ACL for STARTTLS | |
25764 | %acl_smtp_vrfy% ACL for VRFY | |
25765 | ---------------------------------------------------------------- | |
25766 | ||
25767 | For example, if you set | |
25768 | ||
25769 | acl_smtp_rcpt = small_acl | |
25770 | ||
25771 | the little ACL defined above is used whenever Exim receives a RCPT command | |
25772 | in an SMTP dialogue. The majority of policy tests on incoming messages can be | |
25773 | done when RCPT commands arrive. A rejection of RCPT should cause the | |
25774 | sending MTA to give up on the recipient address contained in the RCPT | |
25775 | command, whereas rejection at other times may cause the client MTA to keep on | |
25776 | trying to deliver the message. It is therefore recommended that you do as much | |
25777 | testing as possible at RCPT time. | |
25778 | ||
25779 | ||
25780 | The non-SMTP ACL | |
25781 | ~~~~~~~~~~~~~~~~ | |
25782 | cindex:[non-smtp message, ACL for] | |
25783 | The non-SMTP ACL applies to all non-interactive incoming messages, that is, it | |
25784 | applies to batch SMTP as well as to non-SMTP messages. (Batch SMTP is not | |
25785 | really SMTP.) This ACL is run just before the 'local_scan()' function. Any | |
25786 | kind of rejection is treated as permanent, because there is no way of sending a | |
25787 | temporary error for these kinds of message. Many of the ACL conditions (for | |
25788 | example, host tests, and tests on the state of the SMTP connection such as | |
25789 | encryption and authentication) are not relevant and are forbidden in this ACL. | |
25790 | ||
25791 | ||
25792 | The connect ACL | |
25793 | ~~~~~~~~~~~~~~~ | |
25794 | cindex:[SMTP connection, ACL for] | |
25795 | The ACL test specified by %acl_smtp_connect% happens after the test specified | |
25796 | by %host_reject_connection% (which is now an anomaly) and any TCP Wrappers | |
25797 | testing (if configured). | |
25798 | ||
25799 | ||
25800 | The DATA ACLs | |
25801 | ~~~~~~~~~~~~~ | |
25802 | cindex:[DATA, ACLs for] | |
25803 | Two ACLs are associated with the DATA command, because it is two-stage | |
25804 | command, with two responses being sent to the client. | |
25805 | When the DATA command is received, the ACL defined by %acl_smtp_predata% | |
25806 | is obeyed. This gives you control after all the RCPT commands, but before | |
25807 | the message itself is received. It offers the opportunity to give a negative | |
25808 | response to the DATA command before the data is transmitted. Header lines | |
25809 | added by MAIL or RCPT ACLs are not visible at this time, but any that | |
25810 | are defined here are visible when the %acl_smtp_data% ACL is run. | |
25811 | ||
25812 | You cannot test the contents of the message, for example, to verify addresses | |
25813 | in the headers, at RCPT time or when the DATA command is received. Such | |
25814 | tests have to appear in the ACL that is run after the message itself has been | |
25815 | received, before the final response to the DATA command is sent. This is | |
25816 | the ACL specified by %acl_smtp_data%, which is the second ACL that is | |
25817 | associated with the DATA command. | |
25818 | ||
25819 | For both of these ACLs, it is not possible to reject individual recipients. An | |
25820 | error response rejects the entire message. Unfortunately, it is known that some | |
25821 | MTAs do not treat hard (5##'xx') responses to the DATA command (either | |
25822 | before or after the data) correctly -- they keep the message on their queues | |
25823 | and try again later, but that is their problem, though it does waste some of | |
25824 | your resources. | |
25825 | ||
25826 | ||
25827 | The MIME ACL | |
25828 | ~~~~~~~~~~~~ | |
25829 | The %acl_smtp_mime% option is available only when Exim is compiled with the | |
25830 | content-scanning extension. For details, see chapter <<CHAPexiscan>>. | |
25831 | ||
25832 | ||
25833 | [[SECTQUITACL]] | |
25834 | The QUIT ACL | |
25835 | ~~~~~~~~~~~~ | |
25836 | cindex:[QUIT, ACL for] | |
068aaea8 PH |
25837 | The ACL for the SMTP QUIT command is anomalous, in that the outcome of the ACL |
25838 | does not affect the response code to QUIT, which is always 221. Thus, the ACL | |
25839 | does not in fact control any access. For this reason, the only verbs that are | |
25840 | permitted are %accept% and %warn%. | |
168e428f PH |
25841 | |
25842 | This ACL can be used for tasks such as custom logging at the end of an SMTP | |
25843 | session. For example, you can use ACL variables in other ACLs to count | |
25844 | messages, recipients, etc., and log the totals at QUIT time using one or | |
25845 | more %logwrite% modifiers on a %warn% verb. | |
25846 | ||
068aaea8 PH |
25847 | [revisionflag="changed"] |
25848 | *Warning*: only the $acl_c$'x' variables can be used for this, because the | |
25849 | $acl_m$'x' variables are reset at the end of each incoming message. | |
25850 | ||
168e428f PH |
25851 | You do not need to have a final %accept%, but if you do, you can use a |
25852 | %message% modifier to specify custom text that is sent as part of the 221 | |
25853 | response to QUIT. | |
25854 | ||
25855 | This ACL is run only for a ``normal'' QUIT. For certain kinds of disastrous | |
25856 | failure (for example, failure to open a log file, or when Exim is bombing out | |
25857 | because it has detected an unrecoverable error), all SMTP commands from the | |
25858 | client are given temporary error responses until QUIT is received or the | |
25859 | connection is closed. In these special cases, the QUIT ACL does not run. | |
25860 | ||
25861 | ||
25862 | ||
25863 | Finding an ACL to use | |
25864 | ~~~~~~~~~~~~~~~~~~~~~ | |
25865 | cindex:[{ACL},finding which to use] | |
25866 | The value of an %acl_smtp_'xxx'% option is expanded before use, so you can | |
25867 | use different ACLs in different circumstances. The resulting string does not | |
25868 | have to be the name of an ACL in the configuration file; there are other | |
25869 | possibilities. Having expanded the string, Exim searches for an ACL as follows: | |
25870 | ||
25871 | - If the string begins with a slash, Exim uses it as a file name, and reads its | |
25872 | contents as an ACL. The lines are processed in the same way as lines in the | |
25873 | Exim configuration file. In particular, continuation lines are supported, blank | |
25874 | lines are ignored, as are lines whose first non-whitespace character is ``#''. | |
25875 | If the file does not exist or cannot be read, an error occurs (typically | |
25876 | causing a temporary failure of whatever caused the ACL to be run). For example: | |
25877 | + | |
25878 | .... | |
25879 | acl_smtp_data = /etc/acls/\ | |
25880 | ${lookup{$sender_host_address}lsearch\ | |
25881 | {/etc/acllist}{$value}{default}} | |
25882 | .... | |
25883 | + | |
25884 | This looks up an ACL file to use on the basis of the host's IP address, falling | |
25885 | back to a default if the lookup fails. If an ACL is successfully read from a | |
25886 | file, it is retained in memory for the duration of the Exim process, so that it | |
25887 | can be re-used without having to re-read the file. | |
25888 | ||
25889 | - If the string does not start with a slash, and does not contain any spaces, | |
25890 | Exim searches the ACL section of the configuration for an ACL whose name | |
25891 | matches the string. | |
25892 | ||
25893 | - If no named ACL is found, or if the string contains spaces, Exim parses | |
25894 | the string as an inline ACL. This can save typing in cases where you just | |
25895 | want to have something like | |
25896 | + | |
25897 | acl_smtp_vrfy = accept | |
25898 | + | |
25899 | in order to allow free use of the VRFY command. Such a string may contain | |
25900 | newlines; it is processed in the same way as an ACL that is read from a file. | |
25901 | ||
25902 | ||
25903 | ||
25904 | ||
25905 | ACL return codes | |
25906 | ~~~~~~~~~~~~~~~~ | |
25907 | cindex:[{ACL},return codes] | |
25908 | Except for the QUIT ACL, which does not affect the SMTP return code (see | |
25909 | section <<SECTQUITACL>> above), the | |
25910 | ||
25911 | result of running an ACL is either ``accept'' or ``deny'', or, if some test | |
25912 | cannot be completed (for example, if a database is down), ``defer''. These | |
25913 | results cause 2##'xx', 5##'xx', and 4##'xx' return codes, respectively, to be | |
25914 | used in the SMTP dialogue. A fourth return, ``error'', occurs when there is an | |
25915 | error such as invalid syntax in the ACL. This also causes a 4'##xx' return | |
25916 | code. | |
25917 | ||
25918 | For the non-SMTP ACL, ``defer'' and ``error'' are treated in the same way as | |
25919 | ``deny'', because there is no mechanism for passing temporary errors to the | |
25920 | submitters of non-SMTP messages. | |
25921 | ||
25922 | ||
25923 | ACLs that are relevant to message reception may also return ``discard''. This | |
25924 | has the effect of ``accept'', but causes either the entire message or an | |
25925 | individual recipient address to be discarded. In other words, it is a | |
25926 | blackholing facility. Use it with care. | |
25927 | ||
25928 | If the ACL for MAIL returns ``discard'', all recipients are discarded, and no | |
25929 | ACL is run for subsequent RCPT commands. The effect of ``discard'' in a | |
25930 | RCPT ACL is to discard just the one recipient address. If there are no | |
25931 | recipients left when the message's data is received, the DATA ACL is not | |
25932 | run. A ``discard'' return from the DATA or the non-SMTP ACL discards all the | |
25933 | remaining recipients. | |
25934 | ||
25935 | The ``discard'' return is not permitted for the %acl_smtp_predata% ACL. | |
25936 | ||
25937 | ||
25938 | cindex:['local_scan()' function,when all recipients discarded] | |
25939 | The 'local_scan()' function is always run, even if there are no remaining | |
25940 | recipients; it may create new recipients. | |
25941 | ||
25942 | ||
25943 | ||
25944 | Unset ACL options | |
25945 | ~~~~~~~~~~~~~~~~~ | |
25946 | cindex:[{ACL},unset options] | |
25947 | The default actions when any of the %acl_'xxx'% options are unset are not | |
25948 | all the same. *Note*: These defaults apply only when the relevant ACL is | |
25949 | not defined at all. For any defined ACL, the default action when control reaches | |
25950 | the end of the ACL statements is ``deny''. | |
25951 | ||
25952 | For %acl_not_smtp%, %acl_smtp_auth%, %acl_smtp_connect%, %acl_smtp_data%, | |
25953 | %acl_smtp_helo%, %acl_smtp_mail%, %acl_smtp_mailauth%, %acl_smtp_mime%, | |
25954 | %acl_smtp_predata%, %acl_smtp_quit%, and %acl_smtp_starttls%, the action when | |
25955 | the ACL is not defined is ``accept''. | |
25956 | ||
25957 | For the others (%acl_smtp_etrn%, %acl_smtp_expn%, %acl_smtp_rcpt%, and | |
25958 | %acl_smtp_vrfy%), the action when the ACL is not defined is ``deny''. | |
25959 | This means that %acl_smtp_rcpt% must be defined in order to receive any | |
25960 | messages over an SMTP connection. For an example, see the ACL in the default | |
25961 | configuration file. | |
25962 | ||
25963 | ||
25964 | ||
25965 | ||
25966 | Data for message ACLs | |
25967 | ~~~~~~~~~~~~~~~~~~~~~ | |
25968 | cindex:[{ACL},data for message ACL] | |
068aaea8 PH |
25969 | cindex:[$domain$] |
25970 | cindex:[$local_part$] | |
25971 | cindex:[$sender_address$] | |
25972 | cindex:[$sender_host_address$] | |
25973 | When a MAIL or RCPT ACL, or either of the DATA ACLs, is running, the variables | |
25974 | that contain information about the host and the message's sender (for example, | |
25975 | $sender_host_address$ and $sender_address$) are set, and can be used in ACL | |
25976 | statements. In the case of RCPT (but not MAIL or DATA), $domain$ and | |
25977 | $local_part$ are set from the argument address. | |
168e428f PH |
25978 | |
25979 | When an ACL for the AUTH parameter of MAIL is running, the variables that | |
25980 | contain information about the host are set, but $sender_address$ is not yet | |
25981 | set. Section <<SECTauthparamail>> contains a discussion of this parameter and | |
25982 | how it is used. | |
25983 | ||
068aaea8 | 25984 | cindex:[$message_size$] |
168e428f PH |
25985 | The $message_size$ variable is set to the value of the SIZE parameter on |
25986 | the MAIL command at MAIL, RCPT and pre-data time, or to -1 if | |
25987 | that parameter is not given. The value is updated to the true message size by | |
25988 | the time the final DATA ACL is run (after the message data has been | |
25989 | received). | |
25990 | ||
068aaea8 PH |
25991 | cindex:[$rcpt_count$] |
25992 | cindex:[$recipients_count$] | |
25993 | The $rcpt_count$ variable increases by one for each RCPT command received. The | |
25994 | $recipients_count$ variable increases by one each time a RCPT command is | |
25995 | accepted, so while an ACL for RCPT is being processed, it contains the number | |
25996 | of previously accepted recipients. At DATA time (for both the DATA ACLs), | |
25997 | $rcpt_count$ contains the total number of RCPT commands, and $recipients_count$ | |
25998 | contains the total number of accepted recipients. | |
168e428f PH |
25999 | |
26000 | ||
26001 | ||
26002 | ||
26003 | ||
26004 | [[SECTdatfornon]] | |
26005 | Data for non-message ACLs | |
26006 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
26007 | cindex:[{ACL},data for non-message ACL] | |
068aaea8 | 26008 | cindex:[$smtp_command_argument$] |
168e428f PH |
26009 | When an ACL is being run for AUTH, EHLO, ETRN, EXPN, HELO, STARTTLS, or VRFY, |
26010 | the remainder of the SMTP command line is placed in $smtp_command_argument$. | |
26011 | This can be tested using a %condition% condition. For example, here is an ACL | |
26012 | for use with AUTH, which insists that either the session is encrypted, or the | |
26013 | CRAM-MD5 authentication method is used. In other words, it does not permit | |
26014 | authentication methods that use cleartext passwords on unencrypted connections. | |
26015 | ||
26016 | .... | |
26017 | acl_check_auth: | |
26018 | accept encrypted = * | |
26019 | accept condition = ${if eq{${uc:$smtp_command_argument}}\ | |
26020 | {CRAM-MD5}} | |
26021 | deny message = TLS encryption or CRAM-MD5 required | |
26022 | .... | |
26023 | ||
26024 | (Another way of applying this restriction is to arrange for the authenticators | |
26025 | that use cleartext passwords not to be advertised when the connection is not | |
26026 | encrypted. You can use the generic %server_advertise_condition% authenticator | |
26027 | option to do this.) | |
26028 | ||
26029 | ||
26030 | ||
26031 | Format of an ACL | |
26032 | ~~~~~~~~~~~~~~~~ | |
26033 | cindex:[{ACL},format of] | |
26034 | cindex:[{ACL},verbs; definition of] | |
26035 | An individual ACL consists of a number of statements. Each statement starts | |
26036 | with a verb, optionally followed by a number of conditions and ``modifiers''. | |
26037 | Modifiers can change the way the verb operates, define error and log messages, | |
26038 | set variables, insert delays, and vary the processing of accepted messages. | |
26039 | ||
26040 | If all the conditions are met, the verb is obeyed. The same condition may be | |
26041 | used (with different arguments) more than once in the same statement. This | |
26042 | provides a means of specifying an ``and'' conjunction between conditions. For | |
26043 | example: | |
26044 | ||
26045 | deny dnslists = list1.example | |
26046 | dnslists = list2.example | |
26047 | ||
26048 | If there are no conditions, the verb is always obeyed. Exim stops evaluating | |
26049 | the conditions and modifiers when it reaches a condition that fails. What | |
26050 | happens then depends on the verb (and in one case, on a special modifier). Not | |
26051 | all the conditions make sense at every testing point. For example, you cannot | |
26052 | test a sender address in the ACL that is run for a VRFY command. | |
26053 | ||
26054 | ||
26055 | ACL verbs | |
26056 | ~~~~~~~~~ | |
26057 | The ACL verbs are as follows: | |
26058 | ||
26059 | - cindex:[%accept%, ACL verb] | |
26060 | %accept%: If all the conditions are met, the ACL returns ``accept''. If any of | |
26061 | the conditions are not met, what happens depends on whether %endpass% appears | |
26062 | among the conditions (for syntax see below). If the failing condition is before | |
26063 | %endpass%, control is passed to the next ACL statement; if it is after | |
26064 | %endpass%, the ACL returns ``deny''. Consider this statement, used to check a | |
26065 | RCPT command: | |
26066 | ||
26067 | accept domains = +local_domains | |
26068 | endpass | |
26069 | verify = recipient | |
26070 | + | |
26071 | If the recipient domain does not match the %domains% condition, control passes | |
26072 | to the next statement. If it does match, the recipient is verified, and the | |
26073 | command is accepted if verification succeeds. However, if verification fails, | |
26074 | the ACL yields ``deny'', because the failing condition is after %endpass%. | |
26075 | ||
26076 | - cindex:[%defer%, ACL verb] | |
26077 | %defer%: If all the conditions are met, the ACL returns ``defer'' which, in an | |
26078 | SMTP session, causes a 4##'xx' response to be given. For a non-SMTP ACL, | |
26079 | %defer% is the same as %deny%, because there is no way of sending a temporary | |
26080 | error. For a RCPT command, %defer% is much the same as using a | |
26081 | ^redirect^ router and `:defer:` while verifying, but the %defer% verb can | |
26082 | be used in any ACL, and even for a recipient it might be a simpler approach. | |
26083 | ||
26084 | - cindex:[%deny%, ACL verb] | |
26085 | %deny%: If all the conditions are met, the ACL returns ``deny''. If any of the | |
26086 | conditions are not met, control is passed to the next ACL statement. For | |
26087 | example, | |
26088 | ||
26089 | deny dnslists = blackholes.mail-abuse.org | |
26090 | + | |
26091 | rejects commands from hosts that are on a DNS black list. | |
26092 | ||
26093 | - cindex:[%discard%, ACL verb] | |
26094 | %discard%: This verb behaves like %accept%, except that it returns ``discard'' | |
26095 | from the ACL instead of ``accept''. It is permitted only on ACLs that are | |
26096 | concerned with receiving messages, and it causes recipients to be discarded. | |
26097 | If the %log_message% modifier is set when %discard% operates, its contents are | |
26098 | added to the line that is automatically written to the log. | |
26099 | + | |
26100 | If %discard% is used in an ACL for RCPT, just the one recipient is | |
26101 | discarded; if used for MAIL, DATA or in the non-SMTP ACL, all the | |
26102 | message's recipients are discarded. Recipients that are discarded before | |
26103 | DATA do not appear in the log line when the %log_recipients% log selector | |
26104 | is set. | |
26105 | ||
26106 | - cindex:[%drop%, ACL verb] | |
26107 | %drop%: This verb behaves like %deny%, except that an SMTP connection is | |
26108 | forcibly closed after the 5##'xx' error message has been sent. For example: | |
26109 | ||
26110 | drop message = I don't take more than 20 RCPTs | |
26111 | ||
26112 | condition = ${if > {$rcpt_count}{20}} | |
26113 | + | |
26114 | There is no difference between %deny% and %drop% for the connect-time ACL. The | |
26115 | connection is always dropped after sending a 550 response. | |
26116 | ||
26117 | - cindex:[%require%, ACL verb] | |
26118 | %require%: If all the conditions are met, control is passed to the next ACL | |
26119 | statement. If any of the conditions are not met, the ACL returns ``deny''. For | |
26120 | example, when checking a RCPT command, | |
26121 | ||
26122 | require verify = sender | |
26123 | + | |
26124 | passes control to subsequent statements only if the message's sender can be | |
26125 | verified. Otherwise, it rejects the command. | |
26126 | ||
26127 | - cindex:[%warn%, ACL verb] | |
26128 | %warn%: If all the conditions are met, a header line is added to an incoming | |
26129 | message and/or a line is written to Exim's main log. In all cases, control | |
26130 | passes to the next ACL statement. The text of the added header line and the log | |
26131 | line are specified by modifiers; if they are not present, a %warn% verb just | |
26132 | checks its conditions and obeys any ``immediate'' modifiers such as %set% and | |
26133 | %logwrite%. There is more about adding header lines in section | |
26134 | <<SECTaddheadwarn>>. | |
26135 | + | |
26136 | If any condition on a %warn% statement cannot be completed (that is, there is | |
26137 | some sort of defer), no header lines are added and the configured log line is | |
26138 | not written. No further conditions or modifiers in the %warn% statement are | |
26139 | processed. The incident is logged, but the ACL continues to be processed, from | |
26140 | the next statement onwards. | |
26141 | + | |
26142 | If a %message% modifier is present on a %warn% verb in an ACL that is not | |
26143 | testing an incoming message, it is ignored, and the incident is logged. | |
26144 | + | |
26145 | A %warn% statement may use the %log_message% modifier to cause a line to be | |
26146 | written to the main log when the statement's conditions are true. | |
26147 | If an identical log line is requested several times in the same message, only | |
26148 | one copy is actually written to the log. If you want to force duplicates to be | |
26149 | written, use the %logwrite% modifier instead. | |
26150 | + | |
068aaea8 | 26151 | cindex:[$acl_verify_message$] |
168e428f PH |
26152 | When one of the %warn% conditions is an address verification that fails, the |
26153 | text of the verification failure message is in $acl_verify_message$. If you | |
26154 | want this logged, you must set it up explicitly. For example: | |
26155 | ||
26156 | warn !verify = sender | |
26157 | log_message = sender verify failed: $acl_verify_message | |
26158 | ||
26159 | At the end of each ACL there is an implicit unconditional %deny%. | |
26160 | ||
26161 | As you can see from the examples above, the conditions and modifiers are | |
26162 | written one to a line, with the first one on the same line as the verb, and | |
26163 | subsequent ones on following lines. If you have a very long condition, you can | |
26164 | continue it onto several physical lines by the usual backslash continuation | |
26165 | mechanism. It is conventional to align the conditions vertically. | |
26166 | ||
26167 | ||
26168 | ||
26169 | [[SECTaclvariables]] | |
26170 | ACL variables | |
26171 | ~~~~~~~~~~~~~ | |
26172 | cindex:[{ACL},variables] | |
26173 | There are some special variables that can be set during ACL processing. They | |
26174 | can be used to pass information between different ACLs, different invocations | |
26175 | of the same ACL in the same SMTP connection, and between ACLs and the routers, | |
26176 | transports, and filters that are used to deliver a message. There are two sets | |
26177 | of these variables: | |
26178 | ||
26179 | - The values of $acl_c0$ to $acl_c9$ persist throughout an SMTP connection. | |
26180 | They are never reset. Thus, a value that is set while receiving one message is | |
26181 | still available when receiving the next message on the same SMTP connection. | |
26182 | ||
26183 | - The values of $acl_m0$ to $acl_m9$ persist only while a message is being | |
26184 | received. They are reset afterwards. They are also reset by MAIL, RSET, | |
26185 | EHLO, HELO, and after starting up a TLS session. | |
26186 | ||
26187 | When a message is accepted, the current values of all the ACL variables are | |
26188 | preserved with the message and are subsequently made available at delivery | |
26189 | time. The ACL variables are set by modifier called %set%. For example: | |
26190 | ||
26191 | accept hosts = whatever | |
26192 | set acl_m4 = some value | |
26193 | ||
26194 | *Note*: a leading dollar sign is not used when naming a variable that is to | |
26195 | be set. If you want to set a variable without taking any action, you can use a | |
26196 | %warn% verb without any other modifiers or conditions. | |
26197 | ||
26198 | ||
26199 | ||
26200 | Condition and modifier processing | |
26201 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
26202 | cindex:[{ACL},conditions; processing] | |
26203 | cindex:[{ACL},modifiers; processing] | |
068aaea8 | 26204 | An exclamation mark preceding a condition negates its result. For example: |
168e428f PH |
26205 | |
26206 | deny domains = *.dom.example | |
26207 | !verify = recipient | |
26208 | ||
068aaea8 PH |
26209 | [revisionflag="changed"] |
26210 | causes the ACL to return ``deny'' if the recipient domain ends in 'dom.example' | |
26211 | and the recipient address cannot be verified. Sometimes negation can be used on | |
26212 | the right-hand side of a condition. For example, these two statements are | |
26213 | equivalent: | |
26214 | ||
26215 | [revisionflag="changed"] | |
26216 | .... | |
26217 | deny hosts = !192.168.3.4 | |
26218 | deny !hosts = 192.168.3.4 | |
26219 | .... | |
26220 | ||
26221 | [revisionflag="changed"] | |
26222 | However, for many conditions (%verify% being a good example), only left-hand | |
26223 | side negation of the whole condition is possible. | |
168e428f PH |
26224 | |
26225 | The arguments of conditions and modifiers are expanded. A forced failure | |
26226 | of an expansion causes a condition to be ignored, that is, it behaves as if the | |
26227 | condition is true. Consider these two statements: | |
26228 | ||
26229 | .... | |
26230 | accept senders = ${lookup{$host_name}lsearch\ | |
26231 | {/some/file}{$value}fail} | |
26232 | accept senders = ${lookup{$host_name}lsearch\ | |
26233 | {/some/file}{$value}{}} | |
26234 | .... | |
26235 | ||
26236 | Each attempts to look up a list of acceptable senders. If the lookup succeeds, | |
26237 | the returned list is searched, but if the lookup fails the behaviour is | |
26238 | different in the two cases. The %fail% in the first statement causes the | |
26239 | condition to be ignored, leaving no further conditions. The %accept% verb | |
26240 | therefore succeeds. The second statement, however, generates an empty list when | |
26241 | the lookup fails. No sender can match an empty list, so the condition fails, | |
26242 | and therefore the %accept% also fails. | |
26243 | ||
26244 | ACL modifiers appear mixed in with conditions in ACL statements. Some of them | |
26245 | specify actions that are taken as the conditions for a statement are checked; | |
26246 | others specify text for messages that are used when access is denied or a | |
26247 | warning is generated. The %control% modifier affects the way an incoming | |
26248 | message is handled. | |
26249 | ||
26250 | The positioning of the modifiers in an ACL statement important, because the | |
26251 | processing of a verb ceases as soon as its outcome is known. Only those | |
26252 | modifiers that have already been encountered will take effect. For example, | |
26253 | consider this use of the %message% modifier: | |
26254 | ||
26255 | require message = Can't verify sender | |
26256 | verify = sender | |
26257 | message = Can't verify recipient | |
26258 | verify = recipient | |
26259 | message = This message cannot be used | |
26260 | ||
26261 | If sender verification fails, Exim knows that the result of the statement is | |
26262 | ``deny'', so it goes no further. The first %message% modifier has been seen, so | |
26263 | its text is used as the error message. If sender verification succeeds, but | |
26264 | recipient verification fails, the second message is used. If recipient | |
26265 | verification succeeds, the third message becomes ``current'', but is never used | |
26266 | because there are no more conditions to cause failure. | |
26267 | ||
26268 | For the %deny% verb, on the other hand, it is always the last %message% | |
26269 | modifier that is used, because all the conditions must be true for rejection to | |
26270 | happen. Specifying more than one %message% modifier does not make sense, and | |
26271 | the message can even be specified after all the conditions. For example: | |
26272 | ||
26273 | deny hosts = ... | |
26274 | !senders = *@my.domain.example | |
26275 | message = Invalid sender from client host | |
26276 | ||
26277 | The ``deny'' result does not happen until the end of the statement is reached, | |
26278 | by which time Exim has set up the message. | |
26279 | ||
26280 | ||
26281 | ||
26282 | [[SECTACLmodi]] | |
26283 | ACL modifiers | |
26284 | ~~~~~~~~~~~~~ | |
26285 | cindex:[{ACL},modifiers; list of] | |
26286 | The ACL modifiers are as follows: | |
26287 | ||
26288 | *control*~=~<'text'>:: | |
26289 | cindex:[%control%, ACL modifier] | |
26290 | This modifier affects the subsequent processing of the SMTP connection or of an | |
26291 | incoming message that is accepted. The effect of the first type of control | |
26292 | lasts for the duration of the connection, whereas the effect of the second type | |
26293 | lasts only until the current message has been received. The message-specific | |
26294 | controls always apply to the whole message, not to individual recipients, | |
26295 | even if the %control% modifier appears in a RCPT ACL. | |
26296 | + | |
26297 | As there are now quite a few controls that can be applied, they are described | |
26298 | separately in section <<SECTcontrols>>. The %control% modifier can be used in | |
26299 | several different ways. For example: | |
26300 | + | |
26301 | - It can be at the end of an %accept% statement: | |
26302 | + | |
26303 | .... | |
26304 | accept ...some conditions | |
26305 | control = queue_only | |
26306 | .... | |
26307 | + | |
26308 | In this case, the control is applied when this statement yields ``accept'', in | |
26309 | other words, when the conditions are all true. | |
26310 | ||
26311 | - It can be in the middle of an %accept% statement: | |
26312 | + | |
26313 | .... | |
26314 | accept ...some conditions... | |
26315 | control = queue_only | |
26316 | ...some more conditions... | |
26317 | .... | |
26318 | + | |
26319 | If the first set of conditions are true, the control is applied, even if the | |
26320 | statement does not accept because one of the second set of conditions is false. | |
26321 | In this case, some subsequent statement must yield ``accept'' for the control to | |
26322 | be relevant. | |
26323 | ||
26324 | - It can be used with %warn% to apply the control, leaving the | |
26325 | decision about accepting or denying to a subsequent verb. For | |
26326 | example: | |
26327 | + | |
26328 | .... | |
26329 | warn ...some conditions... | |
26330 | control = freeze | |
26331 | accept ... | |
26332 | .... | |
26333 | + | |
26334 | This example of %warn% does not contain %message%, %log_message%, or | |
26335 | %logwrite%, so it does not add anything to the message and does not write a log | |
26336 | entry. | |
26337 | ||
26338 | - If you want to apply a control unconditionally, you can use it with a | |
26339 | %require% verb. For example: | |
26340 | + | |
26341 | .... | |
26342 | require control = no_multiline_response | |
26343 | .... | |
26344 | ||
26345 | /// | |
26346 | End of bulleted list, continue with variable list | |
26347 | /// | |
26348 | ||
26349 | ||
26350 | *delay*~=~<'time'>:: | |
26351 | cindex:[%delay%, ACL modifier] | |
26352 | cindex:[%-bh% option] | |
26353 | This modifier causes Exim to wait for the time interval before proceeding. The | |
26354 | time is given in the usual Exim notation. This modifier may appear in any ACL. | |
26355 | The delay happens as soon as the modifier is processed. However, when testing | |
26356 | Exim using the %-bh% option, the delay is not actually imposed (an appropriate | |
26357 | message is output instead). | |
26358 | + | |
26359 | Like %control%, %delay% can be used with %accept% or | |
26360 | %deny%, for example: | |
26361 | ||
26362 | deny ...some conditions... | |
26363 | delay = 30s | |
26364 | + | |
26365 | The delay happens if all the conditions are true, before the statement returns | |
26366 | ``deny''. Compare this with: | |
26367 | ||
26368 | deny delay = 30s | |
26369 | ...some conditions... | |
26370 | + | |
26371 | which waits for 30s before processing the conditions. The %delay% modifier can | |
26372 | also be used with %warn% and together with %control%: | |
26373 | ||
26374 | warn ...some conditions... | |
26375 | delay = 2m | |
26376 | control = freeze | |
26377 | accept ... | |
26378 | ||
26379 | *endpass*:: | |
26380 | cindex:[%endpass%, ACL modifier] | |
26381 | This modifier, which has no argument, is recognized only in %accept% | |
26382 | statements. It marks the boundary between the conditions whose failure causes | |
26383 | control to pass to the next statement, and the conditions whose failure causes | |
26384 | the ACL to return ``deny''. See the description of %accept% above. | |
26385 | ||
26386 | *log_message*~=~<'text'>:: | |
26387 | cindex:[%log_message%, ACL modifier] | |
26388 | This modifier sets up a message that is used as part of the log message if the | |
26389 | ACL denies access or a %warn% statement's conditions are true. For example: | |
26390 | ||
26391 | require log_message = wrong cipher suite $tls_cipher | |
26392 | encrypted = DES-CBC3-SHA | |
26393 | + | |
26394 | %log_message% adds to any underlying error message that may exist because of | |
26395 | the condition failure. For example, while verifying a recipient address, a | |
26396 | ':fail:' redirection might have already set up a message. Although the message | |
26397 | is usually defined before the conditions to which it applies, the expansion | |
26398 | does not happen until Exim decides that access is to be denied. This means that | |
26399 | any variables that are set by the condition are available for inclusion in the | |
26400 | message. For example, the $dnslist_$<'xxx'> variables are set after a DNS | |
26401 | black list lookup succeeds. If the expansion of %log_message% fails, or if the | |
26402 | result is an empty string, the modifier is ignored. | |
26403 | + | |
068aaea8 | 26404 | cindex:[$acl_verify_message$] |
168e428f PH |
26405 | If you want to use a %warn% statement to log the result of an address |
26406 | verification, you can use $acl_verify_message$ to include the verification | |
26407 | error message. | |
26408 | + | |
26409 | If %log_message% is used with a %warn% statement, ``Warning:'' is added to the | |
26410 | start of the logged message. If the same warning log message is requested more | |
26411 | than once while receiving a single email message, only one copy is actually | |
26412 | logged. If you want to log multiple copies, use %logwrite% instead of | |
26413 | %log_message%. In the absence of %log_message% and %logwrite%, nothing is | |
26414 | logged for a succesful %warn% statement. | |
26415 | + | |
26416 | If %log_message% is not present and there is no underlying error message (for | |
26417 | example, from the failure of address verification), but %message% is present, | |
26418 | the %message% text is used for logging rejections. However, if any text for | |
26419 | logging contains newlines, only the first line is logged. In the absence of | |
26420 | both %log_message% and %message%, a default built-in message is used for | |
26421 | logging rejections. | |
26422 | ||
26423 | *logwrite*~=~<'text'>:: | |
26424 | cindex:[%logwrite%, ACL modifier] | |
26425 | cindex:[logging in ACL, immediate] | |
26426 | This modifier writes a message to a log file as soon as it is encountered when | |
26427 | processing an ACL. (Compare %log_message%, which, except in the case of | |
26428 | %warn%, is used only if the ACL statement denies access.) The %logwrite% | |
26429 | modifier can be used to log special incidents in ACLs. For example: | |
26430 | ||
26431 | accept <some special conditions> | |
26432 | control = freeze | |
26433 | logwrite = froze message because ... | |
26434 | + | |
26435 | By default, the message is written to the main log. However, it may begin | |
26436 | with a colon, followed by a comma-separated list of log names, and then | |
26437 | another colon, to specify exactly which logs are to be written. For | |
26438 | example: | |
26439 | ||
26440 | logwrite = :main,reject: text for main and reject logs | |
26441 | logwrite = :panic: text for panic log only | |
26442 | ||
26443 | *message*~=~<'text'>:: | |
26444 | cindex:[%message%, ACL modifier] | |
26445 | This modifier sets up a text string that is expanded and used as an error | |
26446 | message if the current statement causes the ACL to deny access. The expansion | |
26447 | happens at the time Exim decides that access is to be denied, not at the time | |
26448 | it processes %message%. If the expansion fails, or generates an empty string, | |
26449 | the modifier is ignored. For ACLs that are triggered by SMTP commands, the | |
26450 | message is returned as part of the SMTP error response. | |
26451 | + | |
26452 | The %message% modifier is also used with the %warn% verb to specify one or more | |
26453 | header lines to be added to an incoming message when all the conditions are | |
26454 | true. See section <<SECTaddheadwarn>> for more details. If %message% is used | |
26455 | with %warn% in an ACL that is not concerned with receiving a message, it has no | |
26456 | effect. | |
26457 | + | |
26458 | The text is literal; any quotes are taken as literals, but because the string | |
26459 | is expanded, backslash escapes are processed anyway. If the message contains | |
26460 | newlines, this gives rise to a multi-line SMTP response. Like %log_message%, | |
26461 | the contents of %message% are not expanded until after a condition has failed. | |
26462 | + | |
068aaea8 | 26463 | cindex:[$acl_verify_message$] |
168e428f PH |
26464 | If %message% is used on a statement that verifies an address, the message |
26465 | specified overrides any message that is generated by the verification process. | |
26466 | However, the original message is available in the variable | |
068aaea8 PH |
26467 | $acl_verify_message$, so you can incorporate it into your message if you wish. |
26468 | In particular, if you want the text from %:fail:% items in ^redirect^ routers | |
26469 | to be passed back as part of the SMTP response, you should either not use a | |
26470 | %message% modifier, or make use of $acl_verify_message$. | |
168e428f PH |
26471 | |
26472 | *set*~<'acl_name'>~=~<'value'>:: | |
26473 | cindex:[%set%, ACL modifier] | |
26474 | This modifier puts a value into one of the ACL variables (see section | |
26475 | <<SECTaclvariables>>). | |
26476 | ||
26477 | ||
26478 | ||
26479 | [[SECTcontrols]] | |
26480 | Use of the control modifier | |
26481 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
26482 | cindex:[%control%, ACL modifier] | |
26483 | The %control% modifier supports the following settings: | |
26484 | ||
26485 | *control~=~caseful_local_part*:: | |
26486 | See below. | |
26487 | ||
26488 | *control~=~caselower_local_part*:: | |
26489 | cindex:[{ACL},case of local part in] | |
26490 | cindex:[case of local parts] | |
068aaea8 | 26491 | cindex:[$local_part$] |
168e428f PH |
26492 | These two controls are permitted only in the ACL specified by %acl_smtp_rcpt% |
26493 | (that is, during RCPT processing). By default, the contents of $local_part$ are | |
26494 | lower cased before ACL processing. If ``caseful_local_part'' is specified, any | |
26495 | uppercase letters in the original local part are restored in $local_part$ for | |
26496 | the rest of the ACL, or until a control that sets ``caselower_local_part'' is | |
26497 | encountered. | |
26498 | + | |
26499 | These controls affect only the current recipient. Moreover, they apply only to | |
26500 | local part handling that takes place directly in the ACL (for example, as a key | |
26501 | in lookups). If a test to verify the recipient is obeyed, the case-related | |
26502 | handling of the local part during the verification is controlled by the router | |
26503 | configuration (see the %caseful_local_part% generic router option). | |
26504 | + | |
26505 | This facility could be used, for example, to add a spam score to local parts | |
26506 | containing upper case letters. For example, using $acl_m4$ to accumulate the | |
26507 | spam score: | |
26508 | + | |
26509 | .... | |
26510 | warn control = caseful_local_part | |
26511 | set acl_m4 = ${eval:\ | |
26512 | $acl_m4 + \ | |
26513 | ${if match{$local_part}{[A-Z]}{1}{0}}\ | |
26514 | } | |
26515 | control = caselower_local_part | |
26516 | .... | |
26517 | + | |
26518 | Notice that we put back the lower cased version afterwards, assuming that | |
26519 | is what is wanted for subsequent tests. | |
26520 | ||
26521 | *control~=~enforce_sync*:: | |
26522 | See below. | |
26523 | ||
26524 | *control~=~no_enforce_sync*:: | |
26525 | cindex:[SMTP,synchronization checking] | |
26526 | cindex:[synchronization checking in SMTP] | |
26527 | These controls make it possible to be selective about when SMTP synchronization | |
26528 | is enforced. The global option %smtp_enforce_sync% specifies the initial | |
26529 | state of the switch (it is true by default). See the description of this option | |
26530 | in chapter <<CHAPmainconfig>> for details of SMTP synchronization checking. | |
26531 | + | |
26532 | The effect of these two controls lasts for the remainder of the SMTP | |
26533 | connection. They can appear in any ACL except the one for the non-SMTP | |
26534 | messages. The most straightforward place to put them is in the ACL defined by | |
26535 | %acl_smtp_connect%, which is run at the start of an incoming SMTP connection, | |
26536 | before the first synchronization check. The expected use is to turn off the | |
26537 | synchronization checks for badly-behaved hosts that you nevertheless need to | |
26538 | work with. | |
26539 | ||
068aaea8 PH |
26540 | |
26541 | [revisionflag="changed"] | |
26542 | *control~=~fakedefer/*<'message'>:: | |
26543 | cindex:[fake defer] | |
26544 | cindex:[defer,fake] | |
26545 | This control works in exactly the same way as %fakereject% (described below) | |
26546 | except that it causes an SMTP 450 response after the message data instead of a | |
26547 | 550 response. You must take care when using %fakedefer% because it causes the | |
26548 | messages to be duplicated when the sender retries. Therefore, you should not | |
26549 | use %fakedefer% if the message is to be delivered normally. | |
26550 | ||
26551 | ||
168e428f PH |
26552 | *control~=~fakereject/*<'message'>:: |
26553 | cindex:[fake rejection] | |
26554 | cindex:[rejection, fake] | |
26555 | This control is permitted only for the MAIL, RCPT, and DATA ACLs, in other | |
26556 | words, only when an SMTP message is being received. If Exim accepts the | |
26557 | message, instead the final 250 response, a 550 rejection message is sent. | |
26558 | However, Exim proceeds to deliver the message as normal. The control applies | |
26559 | only to the current message, not to any subsequent ones that may be received in | |
26560 | the same SMTP connection. | |
26561 | + | |
26562 | The text for the 550 response is taken from the %control% modifier. If no | |
26563 | message is supplied, the following is used: | |
26564 | ||
26565 | 550-Your message has been rejected but is being | |
26566 | 550-kept for evaluation. | |
26567 | 550-If it was a legitimate message, it may still be | |
26568 | 550 delivered to the target recipient(s). | |
26569 | + | |
26570 | This facilty should be used with extreme caution. | |
26571 | ||
26572 | *control~=~freeze*:: | |
26573 | cindex:[frozen messages,forcing in ACL] | |
26574 | This control is permitted only for the MAIL, RCPT, DATA, and non-SMTP ACLs, in | |
26575 | other words, only when a message is being received. If the message is accepted, | |
26576 | it is placed on Exim's queue and frozen. The control applies only to the | |
26577 | current message, not to any subsequent ones that may be received in the same | |
26578 | SMTP connection. | |
26579 | ||
26580 | *control~=~no_mbox_unspool*:: | |
26581 | This control is available when Exim is compiled with the content scanning | |
26582 | extension. Content scanning may require a copy of the current message, or parts | |
26583 | of it, to be written in ``mbox format'' to a spool file, for passing to a virus | |
26584 | or spam scanner. Normally, such copies are deleted when they are no longer | |
26585 | needed. If this control is set, the copies are not deleted. The control applies | |
26586 | only to the current message, not to any subsequent ones that may be received in | |
26587 | the same SMTP connection. It is provided for debugging purposes and is unlikely | |
26588 | to be useful in production. | |
26589 | ||
26590 | *control~=~no_multiline_response*:: | |
26591 | cindex:[multiline responses, suppressing] | |
26592 | This control is permitted for any ACL except the one for non-SMTP messages. | |
26593 | It seems that there are broken clients in use that cannot handle multiline | |
26594 | SMTP responses, despite the fact that RFC 821 defined them over 20 years ago. | |
26595 | + | |
26596 | If this control is set, multiline SMTP responses from ACL rejections are | |
26597 | suppressed. One way of doing this would have been to put out these responses as | |
26598 | one long line. However, RFC 2821 specifies a maximum of 512 bytes per response | |
26599 | (``use multiline responses for more'' it says -- ha!), and some of the responses | |
26600 | might get close to that. So this facility, which is after all only a sop to | |
26601 | broken clients, is implemented by doing two very easy things: | |
26602 | + | |
26603 | -- | |
26604 | . Extra information that is normally output as part of a rejection caused by | |
26605 | sender verification failure is omitted. Only the final line (typically ``sender | |
26606 | verification failed'') is sent. | |
26607 | ||
26608 | . If a %message% modifier supplies a multiline response, only the first | |
26609 | line is output. | |
26610 | -- | |
26611 | + | |
26612 | The setting of the switch can, of course, be made conditional on the | |
26613 | calling host. Its effect lasts until the end of the SMTP connection. | |
26614 | ||
26615 | *control~=~queue_only*:: | |
26616 | cindex:[%queue_only%] | |
26617 | cindex:[queueing incoming messages] | |
26618 | This control is permitted only for the MAIL, RCPT, DATA, and non-SMTP ACLs, in | |
26619 | other words, only when a message is being received. If the message is accepted, | |
26620 | it is placed on Exim's queue and left there for delivery by a subsequent queue | |
26621 | runner. No immediate delivery process is started. In other words, it has the | |
26622 | effect as the %queue_only% global option. However, the control applies only to | |
26623 | the current message, not to any subsequent ones that may be received in the | |
26624 | same SMTP connection. | |
26625 | ||
26626 | *control~=~submission/*<'options'>:: | |
26627 | cindex:[message,submission] | |
26628 | cindex:[submission mode] | |
26629 | This control is permitted only for the MAIL, RCPT, and start of data ACLs (the | |
26630 | latter is the one defined by %acl_smtp_predata%). Setting it tells Exim that | |
26631 | the current message is a submission from a local MUA. In this case, Exim | |
26632 | operates in ``submission mode'', and applies certain fixups to the message if | |
26633 | necessary. For example, it add a 'Date:' header line if one is not present. | |
26634 | This control is not permitted in the %acl_smtp_data% ACL, because that is too | |
26635 | late (the message has already been created). | |
26636 | + | |
26637 | Chapter <<CHAPmsgproc>> describes the processing that Exim applies to messages. | |
26638 | Section <<SECTsubmodnon>> covers the processing that happens in submission mode; | |
26639 | the available options for this control are described there. The control applies | |
26640 | only to the current message, not to any subsequent ones that may be received in | |
26641 | the same SMTP connection. | |
26642 | ||
068aaea8 PH |
26643 | [revisionflag="changed"] |
26644 | *control~=~suppress_local_fixups*:: | |
26645 | cindex:[submission fixups,suppressing] | |
26646 | This control applies to locally submitted (non TCP/IP) messages, and is the | |
26647 | complement of `control = submission`. It disables the fixups that are normally | |
26648 | applied to locally-submitted messages. Specifically: | |
26649 | + | |
26650 | -- | |
26651 | [revisionflag="changed"] | |
26652 | - Any 'Sender:' header line is left alone (in this respect, it is a | |
26653 | dynamic version of %local_sender_retain%). | |
26654 | ||
26655 | [revisionflag="changed"] | |
26656 | - No 'Message-ID:', 'From:', or 'Date:' header lines are added. | |
26657 | ||
26658 | [revisionflag="changed"] | |
26659 | - There is no check that 'From:' corresponds to the actual sender. | |
26660 | -- | |
26661 | + | |
26662 | [revisionflag="changed"] | |
26663 | This feature may be useful when a remotely-originated message is accepted, | |
26664 | passed to some scanning program, and then re-submitted for delivery. | |
26665 | ||
26666 | [revisionflag="changed"] | |
26667 | All four possibilities for message fixups can be specified: | |
26668 | ||
26669 | [revisionflag="changed"] | |
26670 | - Locally submitted, fixups applied: the default. | |
26671 | ||
26672 | [revisionflag="changed"] | |
26673 | - Locally submitted, no fixups applied: use `control = suppress_local_fixups`. | |
26674 | ||
26675 | [revisionflag="changed"] | |
26676 | - Remotely submitted, no fixups applied: the default. | |
26677 | ||
26678 | [revisionflag="changed"] | |
26679 | - Remotely submitted, fixups applied: use `control = submission`. | |
26680 | ||
26681 | ||
26682 | ||
168e428f PH |
26683 | |
26684 | ||
26685 | [[SECTaddheadwarn]] | |
26686 | Adding header lines with the warn verb | |
26687 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
26688 | cindex:[header lines,adding in an ACL] | |
26689 | cindex:[header lines,position of added lines] | |
26690 | cindex:[%warn%, ACL verb] | |
26691 | cindex:[%message%, ACL modifier] | |
26692 | The %message% modifier can be used on a %warn% statement to add an extra header | |
26693 | line to an incoming message, as in this example: | |
26694 | ||
26695 | .... | |
26696 | warn message = X-blacklisted-at: $dnslist_domain | |
26697 | dnslists = sbl.spamhaus.org : \ | |
26698 | dialup.mail-abuse.org | |
26699 | .... | |
26700 | ||
26701 | If an identical header line is requested several times (provoked, for example, | |
26702 | by multiple RCPT commands), only one copy is actually added to the message. | |
26703 | If the text of the %message% modifier contains one or more newlines that are | |
26704 | not followed by a space or a tab, it is assumed to contain multiple header | |
26705 | lines. Each one is checked for valid syntax; `X-ACL-Warn:` is added to the | |
26706 | front of any line that is not a valid header line. | |
26707 | ||
26708 | By default, new lines are added at the end of the existing header lines. | |
26709 | However, you can specify that any particular header line should be added right | |
26710 | at the start (before all the 'Received:' lines), immediately after the first | |
26711 | block of 'Received:' lines, or immediately before any line that is not a | |
26712 | 'Received:' or 'Resent-something:' header. | |
26713 | ||
26714 | This is done by specifying ``:at_start:'', ``:after_received:'', or | |
26715 | ``:at_start_rfc:'' (or, for completeness, ``:at_end:'') before the text of the | |
26716 | header line, respectively. (Header text cannot start with a colon, as there has | |
26717 | to be a header name first.) For example: | |
26718 | ||
26719 | warn message = :after_received:X-My-Header: something or other... | |
26720 | ||
26721 | ||
26722 | If more than one header is supplied in a single warn statement, each one is | |
26723 | treated independently and can therefore be placed differently. If you add | |
26724 | more than one line at the start, or after the Received: block, they will | |
26725 | end up in reverse order. | |
26726 | ||
26727 | *Warning*: This facility currently applies only to header lines that are | |
26728 | added in an ACL. It does NOT work for header lines that are added in a | |
26729 | system filter or in a router or transport. | |
26730 | ||
068aaea8 | 26731 | [revisionflag="changed"] |
168e428f | 26732 | cindex:[header lines,added; visibility of] |
068aaea8 PH |
26733 | Header lines that are added by an ACL at MAIL or RCPT time are not visible in |
26734 | string expansions in ACLs for subsequent RCPT commands or in the | |
168e428f | 26735 | %acl_smtp_predata% ACL. However, they are visible in string expansions in the |
068aaea8 PH |
26736 | ACL that is run after DATA is complete (the %acl_smtp_data% ACL). This is also |
26737 | true for header lines that are added in the %acl_smtp_predata% ACL. However, | |
26738 | header lines that are added in the %acl_smtp_data% itself are not visible | |
26739 | during that ACL. If a message is rejected after DATA, all added header lines | |
26740 | are included in the entry that is written to the reject log. | |
168e428f PH |
26741 | |
26742 | If you want to preserve data between MAIL, RCPT, and the | |
26743 | %acl_smtp_predata% ACLs, you can use ACL variables, as described in section | |
26744 | <<SECTaclvariables>>. | |
26745 | ||
26746 | ||
26747 | ||
26748 | ||
26749 | ||
26750 | [[SECTaclconditions]] | |
26751 | ACL conditions | |
26752 | ~~~~~~~~~~~~~~ | |
26753 | cindex:[{ACL},conditions; list of] | |
26754 | Some of conditions listed in this section are available only when Exim is | |
26755 | compiled with the content-scanning extension. They are included here briefly | |
26756 | for completeness. More detailed descriptions can be found in the discussion on | |
26757 | content scanning in chapter <<CHAPexiscan>>. | |
26758 | ||
26759 | Not all conditions are relevant in all circumstances. For example, testing | |
26760 | senders and recipients does not make sense in an ACL that is being run as the | |
26761 | result of the arrival of an ETRN command, and checks on message headers can be | |
26762 | done only in the ACLs specified by %acl_smtp_data% and %acl_not_smtp%. You can | |
26763 | use the same condition (with different parameters) more than once in the same | |
26764 | ACL statement. This provides a way of specifying an ``and'' conjunction. The | |
26765 | conditions are as follows: | |
26766 | ||
26767 | ||
26768 | *acl~=~*<'name~of~acl~or~ACL~string~or~file~name~'>:: | |
26769 | cindex:[{ACL},nested] | |
26770 | cindex:[{ACL},indirect] | |
26771 | cindex:[%acl%, ACL condition] | |
26772 | The possible values of the argument are the same as for the %acl_smtp_%##'xxx' | |
26773 | options. The named or inline ACL is run. If it returns ``accept'' the condition | |
26774 | is true; if it returns ``deny'' the condition is false. If it returns | |
26775 | ``defer'', the current ACL returns ``defer'' unless the condition is on a | |
26776 | %warn% verb. In that case, a ``defer'' return makes the condition false. This | |
26777 | means that further processing of the %warn% verb ceases, but processing of the | |
26778 | ACL continues. | |
26779 | + | |
26780 | If the nested %acl% returns ``drop'' and the outer condition denies access, the | |
26781 | connection is dropped. If it returns ``discard'', the verb must be %accept% or | |
26782 | %discard%, and the action is taken immediately -- no further conditions are | |
26783 | tested. | |
26784 | + | |
26785 | ACLs may be nested up to 20 deep; the limit exists purely to catch runaway | |
26786 | loops. This condition allows you to use different ACLs in different | |
26787 | circumstances. For example, different ACLs can be used to handle RCPT commands | |
26788 | for different local users or different local domains. | |
26789 | ||
26790 | *authenticated~=~*<'string~list'>:: | |
26791 | cindex:[%authenticated%, ACL condition] | |
26792 | cindex:[authentication,ACL checking] | |
26793 | cindex:[{ACL},testing for authentication] | |
26794 | If the SMTP connection is not authenticated, the condition is false. Otherwise, | |
26795 | the name of the authenticator is tested against the list. To test for | |
26796 | authentication by any authenticator, you can set | |
26797 | ||
26798 | authenticated = * | |
26799 | ||
26800 | *condition~=~*<'string'>:: | |
26801 | cindex:[%condition%, ACL condition] | |
26802 | cindex:[customizing,ACL condition] | |
26803 | cindex:[{ACL},customized test] | |
26804 | cindex:[{ACL},testing; customized] | |
26805 | This feature allows you to make up custom conditions. If the result of | |
26806 | expanding the string is an empty string, the number zero, or one of the strings | |
26807 | ``no'' or ``false'', the condition is false. If the result is any non-zero | |
26808 | number, or one of the strings ``yes'' or ``true'', the condition is true. For | |
26809 | any other values, some error is assumed to have occured, and the ACL returns | |
26810 | ``defer''. | |
26811 | ||
26812 | *decode~=~*<'location'>:: | |
26813 | cindex:[%decode%, ACL condition] | |
26814 | This condition is available only when Exim is compiled with the | |
26815 | content-scanning extension, and it is allowed only the the ACL defined by | |
26816 | %acl_smtp_mime%. It causes the current MIME part to be decoded into a file. For | |
26817 | details, see chapter <<CHAPexiscan>>. | |
26818 | ||
068aaea8 PH |
26819 | *demime~=~*<'extension~list'>:: |
26820 | cindex:[%demime%, ACL condition] | |
26821 | This condition is available only when Exim is compiled with the | |
26822 | content-scanning extension. Its use is described in section <<SECTdemimecond>>. | |
26823 | ||
168e428f PH |
26824 | *dnslists~=~*<'list~of~domain~names~and~other~data'>:: |
26825 | cindex:[%dnslists%, ACL condition] | |
26826 | cindex:[DNS list,in ACL] | |
26827 | cindex:[black list (DNS)] | |
26828 | cindex:[{ACL},testing a DNS list] | |
26829 | This condition checks for entries in DNS black lists. These are also known as | |
26830 | ``RBL lists'', after the original Realtime Blackhole List, but note that the | |
26831 | use of the lists at 'mail-abuse.org' now carries a charge. There are too many | |
26832 | different variants of this condition to describe briefly here. See sections | |
26833 | <<SECTmorednslists>>--<<SECTmorednslistslast>> for details. | |
26834 | ||
26835 | *domains~=~*<'domain~list'>:: | |
26836 | cindex:[%domains%, ACL condition] | |
26837 | cindex:[domain,ACL checking] | |
26838 | cindex:[{ACL},testing a recipient domain] | |
068aaea8 | 26839 | cindex:[$domain_data$] |
168e428f PH |
26840 | This condition is relevant only after a RCPT command. It checks that the domain |
26841 | of the recipient address is in the domain list. If percent-hack processing is | |
26842 | enabled, it is done before this test is done. If the check succeeds with a | |
26843 | lookup, the result of the lookup is placed in $domain_data$ until the next | |
26844 | %domains% test. | |
26845 | ||
26846 | *encrypted~=~*<'string~list'>:: | |
26847 | cindex:[%encrypted%, ACL condition] | |
26848 | cindex:[encryption,checking in an ACL] | |
26849 | cindex:[{ACL},testing for encryption] | |
26850 | If the SMTP connection is not encrypted, the condition is false. Otherwise, the | |
26851 | name of the cipher suite in use is tested against the list. To test for | |
26852 | encryption without testing for any specific cipher suite(s), set | |
26853 | ||
26854 | encrypted = * | |
26855 | ||
26856 | *hosts~=~*<'~host~list'>:: | |
26857 | cindex:[%hosts%, ACL condition] | |
26858 | cindex:[host,ACL checking] | |
26859 | cindex:[{ACL},testing the client host] | |
26860 | This condition tests that the calling host matches the host list. If you have | |
26861 | name lookups or wildcarded host names and IP addresses in the same host list, | |
26862 | you should normally put the IP addresses first. For example, you could have: | |
26863 | ||
26864 | accept hosts = 10.9.8.7 : dbm;/etc/friendly/hosts | |
26865 | + | |
26866 | The reason for this lies in the left-to-right way that Exim processes lists. | |
26867 | It can test IP addresses without doing any DNS lookups, but when it reaches an | |
26868 | item that requires a host name, it fails if it cannot find a host name to | |
26869 | compare with the pattern. If the above list is given in the opposite order, the | |
26870 | %accept% statement fails for a host whose name cannot be found, even if its | |
26871 | IP address is 10.9.8.7. | |
26872 | + | |
26873 | If you really do want to do the name check first, and still recognize the IP | |
26874 | address even if the name lookup fails, you can rewrite the ACL like this: | |
26875 | ||
26876 | accept hosts = dbm;/etc/friendly/hosts | |
26877 | accept hosts = 10.9.8.7 | |
26878 | + | |
26879 | The default action on failing to find the host name is to assume that the host | |
26880 | is not in the list, so the first %accept% statement fails. The second statement | |
26881 | can then check the IP address. | |
26882 | + | |
068aaea8 | 26883 | cindex:[$host_data$] |
168e428f PH |
26884 | If a %hosts% condition is satisfied by means of a lookup, the result |
26885 | of the lookup is made available in the $host_data$ variable. This | |
26886 | allows you, for example, to set up a statement like this: | |
26887 | ||
26888 | deny hosts = net-lsearch;/some/file | |
26889 | message = $host_data | |
26890 | + | |
26891 | which gives a custom error message for each denied host. | |
26892 | ||
26893 | *local_parts~=~*<'local~part~list'>:: | |
26894 | cindex:[%local_parts%, ACL condition] | |
26895 | cindex:[local part,ACL checking] | |
26896 | cindex:[{ACL},testing a local part] | |
068aaea8 | 26897 | cindex:[$local_part_data$] |
168e428f PH |
26898 | This condition is relevant only after a RCPT command. It checks that the local |
26899 | part of the recipient address is in the list. If percent-hack processing is | |
26900 | enabled, it is done before this test. If the check succeeds with a lookup, the | |
068aaea8 PH |
26901 | result of the lookup is placed in $local_part_data$, which remains set until |
26902 | the next %local_parts% test. | |
168e428f PH |
26903 | |
26904 | *malware~=~*<'option'>:: | |
26905 | cindex:[%malware%, ACL condition] | |
26906 | cindex:[{ACL},virus scanning] | |
26907 | cindex:[{ACL},scanning for viruses] | |
26908 | This condition is available only when Exim is compiled with the | |
26909 | content-scanning extension. It causes the incoming message to be scanned for | |
26910 | viruses. For details, see chapter <<CHAPexiscan>>. | |
26911 | ||
26912 | *mime_regex~=~*<'list~of~regular~expressions'>:: | |
26913 | cindex:[%mime_regex%, ACL condition] | |
26914 | cindex:[{ACL},testing by regex matching] | |
26915 | This condition is available only when Exim is compiled with the | |
26916 | content-scanning extension, and it is allowed only the the ACL defined by | |
26917 | %acl_smtp_mime%. It causes the current MIME part to be scanned for a match with | |
26918 | any of the regular expressions. For details, see chapter <<CHAPexiscan>>. | |
26919 | ||
068aaea8 PH |
26920 | [revisionflag="changed"] |
26921 | *ratelimit~=~*<'parameters'>:: | |
26922 | cindex:[rate limiting] | |
26923 | This condition can be used to limit the rate at which a user or host submits | |
26924 | messages. Details are given in section <<SECTratelimiting>>. | |
26925 | ||
168e428f PH |
26926 | *recipients~=~*<'address~list'>:: |
26927 | cindex:[%recipients%, ACL condition] | |
26928 | cindex:[recipient,ACL checking] | |
26929 | cindex:[{ACL},testing a recipient] | |
26930 | This condition is relevant only after a RCPT command. It checks the entire | |
26931 | recipient address against a list of recipients. | |
26932 | ||
26933 | *regex~=~*<'list~of~regular~expressions'>:: | |
26934 | cindex:[%regex%, ACL condition] | |
26935 | cindex:[{ACL},testing by regex matching] | |
26936 | This condition is available only when Exim is compiled with the | |
068aaea8 PH |
26937 | content-scanning extension, and is available only in the DATA, MIME, and |
26938 | non-SMTP ACLs. It causes the incoming message to be scanned for a match with | |
26939 | any of the regular expressions. For details, see chapter <<CHAPexiscan>>. | |
168e428f PH |
26940 | |
26941 | *sender_domains~=~*<'domain~list'>:: | |
26942 | cindex:[%sender_domains%, ACL condition] | |
26943 | cindex:[sender,ACL checking] | |
26944 | cindex:[{ACL},testing a sender domain] | |
068aaea8 PH |
26945 | cindex:[$domain$] |
26946 | cindex:[$sender_address_domain$] | |
168e428f PH |
26947 | This condition tests the domain of the sender of the message against the given |
26948 | domain list. *Note*: the domain of the sender address is in | |
26949 | $sender_address_domain$. It is 'not' put in $domain$ during the testing of this | |
26950 | condition. This is an exception to the general rule for testing domain lists. | |
26951 | It is done this way so that, if this condition is used in an ACL for a RCPT | |
26952 | command, the recipient's domain (which is in $domain$) can be used to influence | |
26953 | the sender checking. | |
068aaea8 PH |
26954 | + |
26955 | [revisionflag="changed"] | |
26956 | *Note*: it is a bad idea to use this condition on its own as a control on | |
26957 | relaying, because sender addresses are easily, and commonly, forged. | |
168e428f PH |
26958 | |
26959 | *senders~=~*<'address~list'>:: | |
26960 | cindex:[%senders%, ACL condition] | |
26961 | cindex:[sender,ACL checking] | |
26962 | cindex:[{ACL},testing a sender] | |
26963 | This condition tests the sender of the message against the given list. To test | |
26964 | for a bounce message, which has an empty sender, set | |
26965 | ||
26966 | senders = : | |
068aaea8 PH |
26967 | + |
26968 | [revisionflag="changed"] | |
26969 | *Note*: it is a bad idea to use this condition on its own as a control on | |
26970 | relaying, because sender addresses are easily, and commonly, forged. | |
168e428f PH |
26971 | |
26972 | *spam~=~*<'username'>:: | |
26973 | cindex:[%spam%, ACL condition] | |
26974 | cindex:[{ACL},scanning for spam] | |
26975 | This condition is available only when Exim is compiled with the | |
26976 | content-scanning extension. It causes the incoming message to be scanned by | |
26977 | SpamAssassin. For details, see chapter <<CHAPexiscan>>. | |
26978 | ||
26979 | *verify~=~certificate*:: | |
26980 | cindex:[%verify%, ACL condition] | |
26981 | cindex:[TLS,client certificate verification] | |
26982 | cindex:[certificate,verification of client] | |
26983 | cindex:[{ACL},certificate verification] | |
26984 | cindex:[{ACL},testing a TLS certificate] | |
26985 | This condition is true in an SMTP session if the session is encrypted, and a | |
26986 | certificate was received from the client, and the certificate was verified. The | |
26987 | server requests a certificate only if the client matches %tls_verify_hosts% or | |
26988 | %tls_try_verify_hosts% (see chapter <<CHAPTLS>>). | |
26989 | ||
068aaea8 PH |
26990 | [revisionflag="changed"] |
26991 | *verify~=~csa*:: | |
26992 | cindex:[CSA verification] | |
26993 | This condition checks whether the sending host (the client) is authorized to | |
26994 | send email. Details of how this works are given in section | |
26995 | <<SECTverifyCSA>>. | |
26996 | ||
168e428f PH |
26997 | *verify~=~header_sender/*<'options'>:: |
26998 | cindex:[%verify%, ACL condition] | |
26999 | cindex:[{ACL},verifying sender in the header] | |
27000 | cindex:[header lines,verifying the sender in] | |
27001 | cindex:[sender,verifying in header] | |
27002 | cindex:[verifying,sender in header] | |
27003 | This condition is relevant only in an ACL that is run after a message has been | |
27004 | received, that is, in an ACL specified by %acl_smtp_data% or %acl_not_smtp%. It | |
27005 | checks that there is a verifiable address in at least one of the 'Sender:', | |
27006 | 'Reply-To:', or 'From:' header lines. Such an address is loosely thought of as | |
27007 | a ``sender'' address (hence the name of the test). However, an address that | |
27008 | appears in one of these headers need not be an address that accepts bounce | |
27009 | messages; only sender addresses in envelopes are required to accept bounces. | |
27010 | Therefore, if you use the callout option on this check, you might want to | |
27011 | arrange for a non-empty address in the MAIL command. | |
27012 | + | |
27013 | Details of address verification and the options are given later, starting at | |
27014 | section <<SECTaddressverification>> (callouts are described in section | |
27015 | <<SECTcallver>>). You can combine this condition with the %senders% condition to | |
27016 | restrict it to bounce messages only: | |
27017 | ||
27018 | deny senders = : | |
27019 | message = A valid sender header is required for bounces | |
27020 | !verify = header_sender | |
27021 | ||
27022 | *verify~=~header_syntax*:: | |
27023 | cindex:[%verify%, ACL condition] | |
27024 | cindex:[{ACL},verifying header syntax] | |
27025 | cindex:[header lines,verifying syntax] | |
27026 | cindex:[verifying,header syntax] | |
27027 | This condition is relevant only in an ACL that is run after a message has been | |
27028 | received, that is, in an ACL specified by %acl_smtp_data% or %acl_not_smtp%. It | |
27029 | checks the syntax of all header lines that can contain lists of addresses | |
27030 | ('Sender:', 'From:', 'Reply-To:', 'To:', 'Cc:', and 'Bcc:'). Unqualified | |
27031 | addresses (local parts without domains) are permitted only in locally generated | |
27032 | messages and from hosts that match %sender_unqualified_hosts% or | |
27033 | %recipient_unqualified_hosts%, as appropriate. | |
27034 | + | |
27035 | Note that this condition is a syntax check only. However, a common spamming | |
27036 | ploy used to be to send syntactically invalid headers such as | |
27037 | ||
27038 | To: @ | |
27039 | + | |
27040 | and this condition can be used to reject such messages, though they are not as | |
27041 | common as they used to be. | |
27042 | ||
068aaea8 | 27043 | [revisionflag="changed"] |
168e428f PH |
27044 | *verify~=~helo*:: |
27045 | cindex:[%verify%, ACL condition] | |
27046 | cindex:[{ACL},verifying HELO/EHLO] | |
27047 | cindex:[HELO,verifying] | |
27048 | cindex:[EHLO,verifying] | |
27049 | cindex:[verifying,EHLO] | |
27050 | cindex:[verifying,HELO] | |
27051 | This condition is true if a HELO or EHLO command has been received from the | |
068aaea8 PH |
27052 | client host, and its contents have been verified. It there has been no previous |
27053 | attempt to verify the the HELO/EHLO contents, it is carried out when this | |
27054 | condition is encountered. See the description of the %helo_verify_hosts% and | |
27055 | %helo_try_verify_hosts% options for details of how to request verification | |
27056 | independently of this condition. | |
27057 | ||
27058 | [revisionflag="changed"] | |
27059 | *verify~=~not_blind*:: | |
27060 | cindex:[verifying,not blind] | |
27061 | cindex:[bcc recipients,verifying none] | |
27062 | This condition checks that there are no blind (bcc) recipients in the message. | |
27063 | Every envelope recipient must appear either in a 'To:' header line or in a | |
27064 | 'Cc:' header line for this condition to be true. Local parts are checked | |
27065 | case-sensitively; domains are checked case-insensitively. If 'Resent-To:' or | |
27066 | 'Resent-Cc:' header lines exist, they are also checked. This condition can be | |
27067 | used only in a DATA or non-SMTP ACL. | |
27068 | + | |
27069 | [revisionflag="changed"] | |
27070 | There are, of course, many legitimate messages that make use of blind | |
27071 | (bcc) recipients. This check should not be used on its own for blocking | |
27072 | messages. | |
27073 | ||
27074 | ||
168e428f PH |
27075 | |
27076 | *verify~=~recipient/*<'options'>:: | |
27077 | cindex:[%verify%, ACL condition] | |
27078 | cindex:[{ACL},verifying recipient] | |
27079 | cindex:[recipient,verifying] | |
27080 | cindex:[verifying,recipient] | |
068aaea8 | 27081 | cindex:[$address_data$] |
168e428f PH |
27082 | This condition is relevant only after a RCPT command. It verifies the current |
27083 | recipient. Details of address verification are given later, starting at section | |
27084 | <<SECTaddressverification>>. After a recipient has been verified, the value of | |
27085 | $address_data$ is the last value that was set while routing the address. This | |
27086 | applies even if the verification fails. When an address that is being verified | |
27087 | is redirected to a single address, verification continues with the new address, | |
27088 | and in that case, the subsequent value of $address_data$ is the value for the | |
27089 | child address. | |
27090 | ||
27091 | *verify~=~reverse_host_lookup*:: | |
27092 | cindex:[%verify%, ACL condition] | |
27093 | cindex:[{ACL},verifying host reverse lookup] | |
27094 | cindex:[host,verifying reverse lookup] | |
27095 | This condition ensures that a verified host name has been looked up from the IP | |
27096 | address of the client host. (This may have happened already if the host name | |
27097 | was needed for checking a host list, or if the host matched %host_lookup%.) | |
27098 | Verification ensures that the host name obtained from a reverse DNS lookup, or | |
27099 | one of its aliases, does, when it is itself looked up in the DNS, yield the | |
27100 | original IP address. | |
27101 | + | |
27102 | If this condition is used for a locally generated message (that is, when there | |
27103 | is no client host involved), it always succeeds. | |
27104 | ||
27105 | *verify~=~sender/*<'options'>:: | |
27106 | cindex:[%verify%, ACL condition] | |
27107 | cindex:[{ACL},verifying sender] | |
27108 | cindex:[sender,verifying] | |
27109 | cindex:[verifying,sender] | |
27110 | This condition is relevant only after a MAIL or RCPT command, or after a | |
27111 | message has been received (the %acl_smtp_data% or %acl_not_smtp% ACLs). If the | |
27112 | message's sender is empty (that is, this is a bounce message), the condition is | |
27113 | true. Otherwise, the sender address is verified. | |
27114 | + | |
068aaea8 PH |
27115 | cindex:[$address_data$] |
27116 | cindex:[$sender_address_data$] | |
168e428f PH |
27117 | If there is data in the $address_data$ variable at the end of routing, its |
27118 | value is placed in $sender_address_data$ at the end of verification. This | |
27119 | value can be used in subsequent conditions and modifiers in the same ACL | |
27120 | statement. It does not persist after the end of the current statement. If you | |
27121 | want to preserve the value for longer, you can save it in an ACL variable. | |
27122 | + | |
27123 | Details of verification are given later, starting at section | |
27124 | <<SECTaddressverification>>. Exim caches the result of sender verification, to | |
27125 | avoid doing it more than once per message. | |
27126 | ||
27127 | *verify~=~sender=*<'address'>*/*<'options'>:: | |
27128 | cindex:[%verify%, ACL condition] | |
27129 | This is a variation of the previous option, in which a modified address is | |
27130 | verified as a sender. | |
27131 | ||
27132 | ||
27133 | ||
27134 | [[SECTmorednslists]] | |
27135 | Using DNS lists | |
27136 | ~~~~~~~~~~~~~~~ | |
27137 | cindex:[DNS list,in ACL] | |
27138 | cindex:[black list (DNS)] | |
27139 | cindex:[{ACL},testing a DNS list] | |
27140 | In its simplest form, the %dnslists% condition tests whether the calling host | |
27141 | is on at least one of a number of DNS lists by looking up the inverted IP | |
27142 | address in one or more DNS domains. For example, if the calling host's IP | |
27143 | address is 192.168.62.43, and the ACL statement is | |
27144 | ||
27145 | .... | |
27146 | deny dnslists = blackholes.mail-abuse.org : \ | |
27147 | dialups.mail-abuse.org | |
27148 | .... | |
27149 | ||
27150 | the following records are looked up: | |
27151 | ||
27152 | 43.62.168.192.blackholes.mail-abuse.org | |
27153 | 43.62.168.192.dialups.mail-abuse.org | |
27154 | ||
27155 | As soon as Exim finds an existing DNS record, processing of the list stops. | |
27156 | Thus, multiple entries on the list provide an ``or'' conjunction. If you want to | |
27157 | test that a host is on more than one list (an ``and'' conjunction), you can use | |
27158 | two separate conditions: | |
27159 | ||
27160 | deny dnslists = blackholes.mail-abuse.org | |
27161 | dnslists = dialups.mail-abuse.org | |
27162 | ||
27163 | If a DNS lookup times out or otherwise fails to give a decisive answer, Exim | |
27164 | behaves as if the host does not match the list item, that is, as if the DNS | |
27165 | record does not exist. If there are further items in the DNS list, they are | |
27166 | processed. | |
27167 | ||
27168 | This is usually the required action when %dnslists% is used with %deny% (which | |
27169 | is the most common usage), because it prevents a DNS failure from blocking | |
27170 | mail. However, you can change this behaviour by putting one of the following | |
27171 | special items in the list: | |
27172 | ||
27173 | cindex:[`+include_unknown`] | |
27174 | cindex:[`+exclude_unknown`] | |
27175 | cindex:[`+defer_unknown`] | |
27176 | &&& | |
27177 | `+include_unknown ` behave as if the item is on the list | |
27178 | `+exclude_unknown ` behave as if the item is not on the list (default) | |
27179 | `+defer_unknown ` give a temporary error | |
27180 | &&& | |
27181 | Each of these applies to any subsequent items on the list. For example: | |
27182 | ||
27183 | deny dnslists = +defer_unknown : foo.bar.example | |
27184 | ||
27185 | ||
27186 | Testing the list of domains stops as soon as a match is found. If you want to | |
27187 | warn for one list and block for another, you can use two different statements: | |
27188 | ||
27189 | deny dnslists = blackholes.mail-abuse.org | |
27190 | warn message = X-Warn: sending host is on dialups list | |
27191 | dnslists = dialups.mail-abuse.org | |
27192 | ||
27193 | ||
27194 | DNS list lookups are cached by Exim for the duration of the SMTP session, | |
27195 | so a lookup based on the IP address is done at most once for any incoming | |
27196 | connection. Exim does not share information between multiple incoming | |
27197 | connections (but your local name server cache should be active). | |
27198 | ||
27199 | ||
27200 | ||
27201 | Specifying the IP address for a DNS list lookup | |
27202 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
27203 | cindex:[DNS list,keyed by explicit IP address] | |
27204 | By default, the IP address that is used in a DNS list lookup is the IP address | |
27205 | of the calling host. However, you can specify another IP address by listing it | |
27206 | after the domain name, introduced by a slash. For example: | |
27207 | ||
068aaea8 | 27208 | deny dnslists = black.list.tld/192.168.1.2 |
168e428f PH |
27209 | |
27210 | This feature is not very helpful with explicit IP addresses; it is intended for | |
27211 | use with IP addresses that are looked up, for example, the IP addresses of the | |
27212 | MX hosts or nameservers of an email sender address. For an example, see section | |
27213 | <<SECTmulkeyfor>> below. | |
27214 | ||
27215 | ||
27216 | ||
27217 | ||
27218 | DNS lists keyed on domain names | |
27219 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
27220 | cindex:[DNS list,keyed by domain name] | |
27221 | There are some lists that are keyed on domain names rather than inverted IP | |
27222 | addresses (see for example the 'domain based zones' link at | |
27223 | *http://www.rfc-ignorant.org/[]*). No reversing of components is used with | |
27224 | these lists. You can change the name that is looked up in a DNS list by listing | |
27225 | it after the domain name, introduced by a slash. For example, | |
27226 | ||
27227 | deny message = Sender's domain is listed at $dnslist_domain | |
27228 | dnslists = dsn.rfc-ignorant.org/$sender_address_domain | |
27229 | ||
27230 | This particular example is useful only in ACLs that are obeyed after the | |
27231 | RCPT or DATA commands, when a sender address is available. If (for | |
27232 | example) the message's sender is 'user@tld.example' the name that is looked | |
27233 | up by this example is | |
27234 | ||
27235 | tld.example.dsn.rfc-ignorant.org | |
27236 | ||
27237 | A single %dnslists% condition can contain entries for both names and IP | |
27238 | addresses. For example: | |
27239 | ||
27240 | .... | |
27241 | deny dnslists = sbl.spamhaus.org : \ | |
27242 | dsn.rfc-ignorant.org/$sender_address_domain | |
27243 | .... | |
27244 | ||
27245 | The first item checks the sending host's IP address; the second checks a domain | |
27246 | name. The whole condition is true if either of the DNS lookups succeeds. | |
27247 | ||
27248 | ||
27249 | ||
27250 | ||
27251 | [[SECTmulkeyfor]] | |
27252 | Multiple explicit keys for a DNS list | |
27253 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
27254 | cindex:[DNS list,multiple keys for] | |
27255 | The syntax described above for looking up explicitly-defined values (either | |
27256 | names or IP addresses) in a DNS blacklist is a simplification. After the domain | |
27257 | name for the DNS list, what follows the slash can in fact be a list of items. | |
27258 | As with all lists in Exim, the default separator is a colon. However, because | |
27259 | this is a sublist within the list of DNS blacklist domains, it is necessary | |
27260 | either to double the separators like this: | |
27261 | ||
27262 | dnslists = black.list.tld/name.1::name.2 | |
27263 | ||
27264 | or to change the separator character, like this: | |
27265 | ||
27266 | dnslists = black.list.tld/<;name.1;name.2 | |
27267 | ||
27268 | If an item in the list is an IP address, it is inverted before the DNS | |
27269 | blacklist domain is appended. If it is not an IP address, no inversion | |
27270 | occurs. Consider this condition: | |
27271 | ||
27272 | dnslists = black.list.tld/<;192.168.1.2;a.domain | |
27273 | ||
27274 | The DNS lookups that occur are: | |
27275 | ||
27276 | 2.1.168.192.black.list.tld | |
27277 | a.domain.black.list.tld | |
27278 | ||
27279 | Once a DNS record has been found (that matches a specific IP return | |
27280 | address, if specified -- see section <<SECTaddmatcon>>), no further lookups are | |
27281 | done. If there is a temporary DNS error, the rest of the sublist of domains or | |
27282 | IP addresses is tried. A temporary error for the whole dnslists item occurs | |
27283 | only if no other DNS lookup in this sublist succeeds. In other words, a | |
27284 | successful lookup for any of the items in the sublist overrides a temporary | |
27285 | error for a previous item. | |
27286 | ||
27287 | The ability to supply a list of items after the slash is in some sense just a | |
27288 | syntactic convenience. These two examples have the same effect: | |
27289 | ||
27290 | dnslists = black.list.tld/a.domain : black.list.tld/b.domain | |
27291 | dnslists = black.list.tld/a.domain::b.domain | |
27292 | ||
27293 | However, when the data for the list is obtained from a lookup, the second form | |
27294 | is usually much more convenient. Consider this example: | |
27295 | ||
27296 | .... | |
27297 | deny message = The mail servers for the domain \ | |
27298 | $sender_address_domain \ | |
27299 | are listed at $dnslist_domain ($dnslist_value); \ | |
27300 | see $dnslist_text. | |
27301 | dnslists = sbl.spamhaus.org/<|${lookup dnsdb {>|a=<|\ | |
27302 | ${lookup dnsdb {>|mxh=\ | |
27303 | $sender_address_domain} }} } | |
27304 | .... | |
27305 | ||
27306 | Note the use of `>|` in the dnsdb lookup to specify the separator for | |
27307 | multiple DNS records. The inner dnsdb lookup produces a list of MX hosts | |
27308 | and the outer dnsdb lookup finds the IP addresses for these hosts. The result | |
27309 | of expanding the condition might be something like this: | |
27310 | ||
27311 | dnslists = sbl.spahmaus.org/<|192.168.2.3|192.168.5.6|... | |
27312 | ||
27313 | Thus, this example checks whether or not the IP addresses of the sender | |
27314 | domain's mail servers are on the Spamhaus black list. | |
27315 | ||
27316 | ||
27317 | ||
27318 | ||
27319 | ||
27320 | Data returned by DNS lists | |
27321 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
27322 | cindex:[DNS list,data returned from] | |
27323 | DNS lists are constructed using address records in the DNS. The original RBL | |
27324 | just used the address 127.0.0.1 on the right hand side of each record, but the | |
27325 | RBL+ list and some other lists use a number of values with different meanings. | |
27326 | The values used on the RBL+ list are: | |
27327 | ||
27328 | &&& | |
27329 | 127.1.0.1 RBL | |
27330 | 127.1.0.2 DUL | |
27331 | 127.1.0.3 DUL and RBL | |
27332 | 127.1.0.4 RSS | |
27333 | 127.1.0.5 RSS and RBL | |
27334 | 127.1.0.6 RSS and DUL | |
27335 | 127.1.0.7 RSS and DUL and RBL | |
27336 | &&& | |
27337 | ||
27338 | Some DNS lists may return more than one address record. | |
27339 | ||
27340 | ||
27341 | Variables set from DNS lists | |
27342 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
27343 | cindex:[DNS list,variables set from] | |
068aaea8 PH |
27344 | cindex:[$dnslist_domain$] |
27345 | cindex:[$dnslist_text$] | |
27346 | cindex:[$dnslist_value$] | |
168e428f PH |
27347 | When an entry is found in a DNS list, the variable $dnslist_domain$ |
27348 | contains the name of the domain that matched, $dnslist_value$ contains the | |
27349 | data from the entry, and $dnslist_text$ contains the contents of any | |
27350 | associated TXT record. If more than one address record is returned by the DNS | |
27351 | lookup, all the IP addresses are included in $dnslist_value$, separated by | |
27352 | commas and spaces. | |
27353 | ||
27354 | You can use these variables in %message% or %log_message% modifiers -- | |
27355 | although these appear before the condition in the ACL, they are not expanded | |
27356 | until after it has failed. For example: | |
27357 | ||
27358 | .... | |
27359 | deny hosts = !+local_networks | |
27360 | message = $sender_host_address is listed \ | |
27361 | at $dnslist_domain | |
27362 | dnslists = rbl-plus.mail-abuse.example | |
27363 | .... | |
27364 | ||
27365 | ||
27366 | ||
27367 | ||
27368 | [[SECTaddmatcon]] | |
27369 | Additional matching conditions for DNS lists | |
27370 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
27371 | cindex:[DNS list,matching specific returned data] | |
27372 | You can add an equals sign and an IP address after a %dnslists% domain name in | |
27373 | order to restrict its action to DNS records with a matching right hand side. | |
27374 | For example, | |
27375 | ||
27376 | deny dnslists = rblplus.mail-abuse.org=127.0.0.2 | |
27377 | ||
27378 | rejects only those hosts that yield 127.0.0.2. Without this additional data, | |
27379 | any address record is considered to be a match. If more than one address record | |
27380 | is found on the list, they are all checked for a matching right-hand side. | |
27381 | ||
27382 | More than one IP address may be given for checking, using a comma as a | |
27383 | separator. These are alternatives -- if any one of them matches, the %dnslists% | |
27384 | condition is true. For example: | |
27385 | ||
27386 | deny dnslists = a.b.c=127.0.0.2,127.0.0.3 | |
27387 | ||
27388 | ||
27389 | If you want to specify a constraining address list and also specify names or IP | |
27390 | addresses to be looked up, the constraining address list must be specified | |
27391 | first. For example: | |
27392 | ||
27393 | .... | |
27394 | deny dnslists = dsn.rfc-ignorant.org\ | |
27395 | =127.0.0.2/$sender_address_domain | |
27396 | .... | |
27397 | ||
27398 | ||
27399 | If the character ``&'' is used instead of ``='', the comparison for each listed | |
27400 | IP address is done by a bitwise ``and'' instead of by an equality test. In | |
27401 | other words, the listed addresses are used as bit masks. The comparison is | |
27402 | true if all the bits in the mask are present in the address that is being | |
27403 | tested. For example: | |
27404 | ||
27405 | dnslists = a.b.c&0.0.0.3 | |
27406 | ||
27407 | matches if the address is 'x.x.x.'3, 'x.x.x.'7, 'x.x.x.'11, etc. If you | |
27408 | want to test whether one bit or another bit is present (as opposed to both | |
27409 | being present), you must use multiple values. For example: | |
27410 | ||
27411 | dnslists = a.b.c&0.0.0.1,0.0.0.2 | |
27412 | ||
27413 | matches if the final component of the address is an odd number or two times | |
27414 | an odd number. | |
27415 | ||
27416 | ||
27417 | ||
27418 | Negated DNS matching conditions | |
27419 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
27420 | You can supply a negative list of IP addresses as part of a %dnslists% | |
27421 | condition. Whereas | |
27422 | ||
27423 | deny dnslists = a.b.c=127.0.0.2,127.0.0.3 | |
27424 | ||
27425 | means ``deny if the host is in the black list at the domain 'a.b.c' and the IP | |
27426 | address yielded by the list is either 127.0.0.2 or 127.0.0.3'', | |
27427 | ||
27428 | deny dnslists = a.b.c!=127.0.0.2,127.0.0.3 | |
27429 | ||
27430 | means ``deny if the host is in the black list at the domain 'a.b.c' and the IP | |
27431 | address yielded by the list is not 127.0.0.2 and not 127.0.0.3''. In other | |
27432 | words, the result of the test is inverted if an exclamation mark appears before | |
27433 | the ``='' (or the ``&'') sign. | |
27434 | ||
27435 | *Note*: this kind of negation is not the same as negation in a domain, | |
27436 | host, or address list (which is why the syntax is different). | |
27437 | ||
27438 | If you are using just one list, the negation syntax does not gain you much. The | |
27439 | previous example is precisely equivalent to | |
27440 | ||
27441 | deny dnslists = a.b.c | |
27442 | !dnslists = a.b.c=127.0.0.2,127.0.0.3 | |
27443 | ||
27444 | However, if you are using multiple lists, the negation syntax is clearer. | |
27445 | Consider this example: | |
27446 | ||
27447 | .... | |
27448 | deny dnslists = sbl.spamhaus.org : \ | |
27449 | list.dsbl.org : \ | |
27450 | dnsbl.njabl.org!=127.0.0.3 : \ | |
27451 | relays.ordb.org | |
27452 | .... | |
27453 | ||
27454 | Using only positive lists, this would have to be: | |
27455 | ||
27456 | .... | |
27457 | deny dnslists = sbl.spamhaus.org : \ | |
27458 | list.dsbl.org | |
27459 | deny dnslists = dnsbl.njabl.org | |
27460 | !dnslists = dnsbl.njabl.org=127.0.0.3 | |
27461 | deny dnslists = relays.ordb.org | |
27462 | .... | |
27463 | ||
27464 | which is less clear, and harder to maintain. | |
27465 | ||
27466 | ||
27467 | ||
27468 | ||
27469 | [[SECTmorednslistslast]] | |
27470 | DNS lists and IPv6 | |
27471 | ~~~~~~~~~~~~~~~~~~ | |
27472 | cindex:[IPv6,DNS black lists] | |
27473 | cindex:[DNS list,IPv6 usage] | |
27474 | If Exim is asked to do a dnslist lookup for an IPv6 address, it inverts it | |
27475 | nibble by nibble. For example, if the calling host's IP address is | |
27476 | 3ffe:ffff:836f:0a00:000a:0800:200a:c031, Exim might look up | |
27477 | ||
27478 | 1.3.0.c.a.0.0.2.0.0.8.0.a.0.0.0.0.0.a.0.f.6.3.8. | |
27479 | f.f.f.f.e.f.f.3.blackholes.mail-abuse.org | |
27480 | ||
27481 | (split over two lines here to fit on the page). Unfortunately, some of the DNS | |
27482 | lists contain wildcard records, intended for IPv4, that interact badly with | |
27483 | IPv6. For example, the DNS entry | |
27484 | ||
27485 | *.3.some.list.example. A 127.0.0.1 | |
27486 | ||
27487 | is probably intended to put the entire 3.0.0.0/8 IPv4 network on the list. | |
27488 | Unfortunately, it also matches the entire 3::/4 IPv6 network. | |
27489 | ||
27490 | You can exclude IPv6 addresses from DNS lookups by making use of a suitable | |
27491 | %condition% condition, as in this example: | |
27492 | ||
27493 | deny condition = ${if isip4{$sender_host_address}} | |
27494 | dnslists = some.list.example | |
27495 | ||
27496 | ||
27497 | ||
068aaea8 PH |
27498 | [[SECTratelimiting]] |
27499 | Rate limiting senders | |
27500 | ~~~~~~~~~~~~~~~~~~~~~ | |
27501 | [revisionflag="changed"] | |
27502 | cindex:[rate limiting,client sending] | |
27503 | cindex:[limiting client sending rates] | |
27504 | oindex:[%smpt_ratelimit_*%] | |
27505 | The %ratelimit% ACL condition can be used to measure and control the rate at | |
27506 | which clients can send email. This is more powerful than the %smtp_ratelimit_*% | |
27507 | options, because those options control the rate of commands in a single SMTP | |
27508 | session only, whereas the %ratelimit% condition works across all connections | |
27509 | (concurrent and sequential) from the same client host. There's a script in | |
27510 | _util/ratelimit.pl_ which extracts sending rates from log files, to assist with | |
27511 | choosing appropriate settings when deploying the %ratelimit% ACL condition. | |
27512 | The syntax of the %ratelimit% condition is: | |
27513 | ||
27514 | [revisionflag="changed"] | |
27515 | &&& | |
27516 | `ratelimit =` <'m'> `/` <'p'> `/` <'options'> `/` <'key'> | |
27517 | &&& | |
27518 | ||
27519 | [revisionflag="changed"] | |
27520 | If the average client sending rate is less than 'm' messages per time | |
27521 | period 'p' then the condition is false; otherwise it is true. | |
27522 | ||
27523 | [revisionflag="changed"] | |
27524 | The parameter 'p' is the smoothing time constant, in the form of an Exim | |
27525 | time interval, for example, `8h` for eight hours. A larger time constant means | |
27526 | that it takes Exim longer to forget a client's past behaviour. The parameter | |
27527 | 'm' is the maximum number of messages that a client is permitted to send in a | |
27528 | fast burst. By increasing both 'm' and 'p' but keeping 'm/p' constant, you can | |
27529 | allow a client to send more messages in a burst without changing its overall | |
27530 | sending rate limit. Conversely, if 'm' and 'p' are both small, messages must be | |
27531 | sent at an even rate. | |
27532 | ||
27533 | [revisionflag="changed"] | |
27534 | The key is used to look up the data for calculating the client's average | |
27535 | sending rate. This data is stored in a database maintained by Exim in its spool | |
27536 | directory, alongside the retry and other hints databases. You can limit the | |
27537 | sending rate of each authenticated user, independent of the computer they are | |
27538 | sending from, by setting the key to $authenticated_id$. The default key is | |
27539 | $sender_host_address$, which applies the limit to the client host, independent | |
27540 | of the sender. | |
27541 | ||
27542 | [revisionflag="changed"] | |
27543 | Internally, Exim includes the smoothing constant 'p' and the options in the | |
27544 | lookup key because they alter the meaning of the stored data. This is not true | |
27545 | for the limit 'm', so you can alter the configured maximum rate and Exim will | |
27546 | still remember clients' past behaviour, but if you alter the other ratelimit | |
27547 | parameters Exim forgets past behaviour. | |
27548 | ||
27549 | [revisionflag="changed"] | |
27550 | Each %ratelimit% condition can have up to two options. The first option | |
27551 | specifies what Exim measures the rate of, and the second specifies how Exim | |
27552 | handles excessively fast clients. The options are separated by a slash, like | |
27553 | the other parameters. | |
27554 | ||
27555 | [revisionflag="changed"] | |
27556 | The %per_conn% option limits the client's connection rate. The %per_mail% | |
27557 | option limits the client's rate of sending messages. This is the default if | |
27558 | none of the %per_*% options is specified. | |
27559 | ||
27560 | [revisionflag="changed"] | |
27561 | The %per_byte% option limits the sender's email bandwidth. Note that it is best | |
27562 | to use this option in the DATA ACL; if it is used in an earlier ACL it relies | |
27563 | on the SIZE parameter on the MAIL command, which may be inaccurate or | |
27564 | completely missing. You can follow the limit 'm' in the configuration with K, | |
27565 | M, or G to specify limits in kilobytes, megabytes, or gigabytes, respectively. | |
27566 | ||
27567 | [revisionflag="changed"] | |
27568 | The %per_cmd% option causes Exim to recompute the rate every time the condition | |
27569 | is processed. This can be used to limit the SMTP command rate. The alias | |
27570 | %per_rcpt% is provided for use in the RCPT ACL instead of %per_cmd% to make it | |
27571 | clear that the effect is to limit the rate at which recipients are accepted. | |
27572 | Note that in this case the rate limiting engine will see a message with many | |
27573 | recipients as a large high-speed burst. | |
27574 | ||
27575 | [revisionflag="changed"] | |
27576 | If a client's average rate is greater than the maximum, the rate limiting | |
27577 | engine can react in two possible ways, depending on the presence of the | |
27578 | %strict% or %leaky% options. This is independent of the other counter-measures | |
27579 | (such as rejecting the message) that may be specified by the rest of the ACL. | |
27580 | The default mode is leaky, which avoids a sender's over-aggressive retry rate | |
27581 | preventing it from getting any email through. | |
27582 | ||
27583 | [revisionflag="changed"] | |
27584 | The %strict% option means that the client's recorded rate is always updated. | |
27585 | The effect of this is that Exim measures the client's average rate of attempts | |
27586 | to send email, which can be much higher than the maximum. If the client is over | |
27587 | the limit it will be subjected to counter-measures until it slows down below | |
27588 | the maximum rate. The smoothing period determines the time it takes for a high | |
27589 | sending rate to decay exponentially to 37% of its peak value, which means that | |
27590 | you can work out the time (the number of smoothing periods) that a client is | |
27591 | subjected to counter-measures after an over-limit burst with this formula: | |
27592 | ||
27593 | ln(peakrate/maxrate) | |
27594 | ||
27595 | [revisionflag="changed"] | |
27596 | The %leaky% option means that the client's recorded rate is not updated if it | |
27597 | is above the limit. The effect of this is that Exim measures the client's | |
27598 | average rate of successfully sent email, which cannot be greater than the | |
27599 | maximum. If the client is over the limit it will suffer some counter-measures, | |
27600 | but it will still be able to send email at the configured maximum rate, | |
27601 | whatever the rate of its attempts. | |
27602 | ||
27603 | [revisionflag="changed"] | |
27604 | As a side-effect, the %ratelimit% condition sets the expansion variable | |
27605 | $sender_rate$ to the client's computed rate, $sender_rate_limit$ to the | |
27606 | configured value of 'm', and $sender_rate_period$ to the configured value of | |
27607 | 'p'. | |
27608 | ||
27609 | [revisionflag="changed"] | |
27610 | Exim's other ACL facilities are used to define what counter-measures are taken | |
27611 | when the rate limit is exceeded. This might be anything from logging a warning | |
27612 | (for example, while measuring existing sending rates in order to define | |
27613 | policy), through time delays to slow down fast senders, up to rejecting the | |
27614 | message. For example: | |
27615 | ||
27616 | [revisionflag="changed"] | |
27617 | .... | |
27618 | # Log all senders' rates | |
27619 | warn | |
27620 | ratelimit = 0 / 1h / strict | |
27621 | log_message = Sender rate $sender_rate / $sender_rate_period | |
27622 | ||
27623 | # Slow down fast senders | |
27624 | warn | |
27625 | ratelimit = 100 / 1h / per_rcpt / strict | |
27626 | delay = ${eval: $sender_rate - $sender_rate_limit }s | |
27627 | ||
27628 | # Keep authenticated users under control | |
27629 | deny | |
27630 | ratelimit = 100 / 1d / strict / $authenticated_id | |
27631 | ||
27632 | # System-wide rate limit | |
27633 | defer | |
27634 | message = Sorry, too busy. Try again later. | |
27635 | ratelimit = 10 / 1s / $primary_hostname | |
27636 | ||
27637 | # Restrict incoming rate from each host, with a default | |
27638 | # set using a macro and special cases looked up in a table. | |
27639 | defer | |
27640 | message = Sender rate exceeds $sender_rate_limit \ | |
27641 | messages per $sender_rate_period | |
27642 | ratelimit = ${lookup {$sender_host_address} \ | |
27643 | cdb {DB/ratelimits.cdb} \ | |
27644 | {$value} {RATELIMIT} } | |
27645 | .... | |
27646 | ||
27647 | [revisionflag="changed"] | |
27648 | *Warning*: if you have a busy server with a lot of %ratelimit% tests, | |
27649 | especially with the %per_rcpt% option, you may suffer from a performance | |
27650 | bottleneck caused by locking on the ratelimit hints database. Apart from | |
27651 | making your ACLs less complicated, you can reduce the problem by using a | |
27652 | RAM disk for Exim's hints directory (usually _/var/spool/exim/db/_). However | |
27653 | this means that Exim will lose its hints data after a reboot (including retry | |
27654 | hints, the callout cache, and ratelimit data). | |
27655 | ||
27656 | ||
168e428f PH |
27657 | |
27658 | [[SECTaddressverification]] | |
27659 | Address verification | |
27660 | ~~~~~~~~~~~~~~~~~~~~ | |
27661 | cindex:[verifying address, options for] | |
27662 | cindex:[policy control,address verification] | |
27663 | Several of the %verify% conditions described in section <<SECTaclconditions>> | |
27664 | cause addresses to be verified. These conditions can be followed by options | |
27665 | that modify the verification process. The options are separated from the | |
27666 | keyword and from each other by slashes, and some of them contain parameters. | |
27667 | For example: | |
27668 | ||
27669 | verify = sender/callout | |
27670 | verify = recipient/defer_ok/callout=10s,defer_ok | |
27671 | ||
27672 | The first stage of address verification, which always happens, is to run the | |
27673 | address through the routers, in ``verify mode''. Routers can detect the | |
27674 | difference between verification and routing for delivery, and their actions can | |
27675 | be varied by a number of generic options such as %verify% and %verify_only% | |
27676 | (see chapter <<CHAProutergeneric>>). If routing fails, verification fails. | |
27677 | The available options are as follows: | |
27678 | ||
27679 | - If the %callout% option is specified, successful routing to one or more remote | |
27680 | hosts is followed by a ``callout'' to those hosts as an additional check. | |
27681 | Callouts and their sub-options are discussed in the next section. | |
27682 | ||
27683 | - If there is a defer error while doing verification routing, the ACL | |
27684 | normally returns ``defer''. However, if you include %defer_ok% in the options, | |
27685 | the condition is forced to be true instead. Note that this is a main | |
27686 | verification option as well as a suboption for callouts. | |
27687 | ||
068aaea8 PH |
27688 | - The %no_details% option is covered in section <<SECTsenaddver>>, which |
27689 | discusses the reporting of sender address verification failures. | |
27690 | ||
27691 | [revisionflag="changed"] | |
27692 | - The %success_on_redirect% option causes verification always to succeed | |
27693 | immediately after a successful redirection. By default, if a redirection | |
27694 | generates just one address, that address is also verified. See further | |
27695 | discussion in section <<SECTredirwhilveri>>. | |
168e428f | 27696 | |
068aaea8 | 27697 | [revisionflag="changed"] |
168e428f | 27698 | cindex:[verifying address, differentiating failures] |
068aaea8 PH |
27699 | cindex:[$recipient_verify_failure$] |
27700 | cindex:[$sender_verify_failure$] | |
27701 | cindex:[$acl_verify_message$] | |
27702 | After an address verification failure, $acl_verify_message$ contains the error | |
27703 | message that is associated with the failure. It can be preserved by coding like | |
27704 | this: | |
27705 | ||
27706 | warn !verify = sender | |
27707 | set acl_m0 = $acl_verify_message | |
27708 | ||
27709 | [revisionflag="changed"] | |
27710 | If you are writing your own custom rejection message or log message when | |
27711 | denying access, you can use this variable to include information about the | |
27712 | verification failure. | |
27713 | ||
27714 | In addition, $sender_verify_failure$ or $recipient_verify_failure$ (as | |
27715 | appropriate) contains one of the following words: | |
168e428f PH |
27716 | |
27717 | - %qualify%: The address was unqualified (no domain), and the message | |
27718 | was neither local nor came from an exempted host. | |
27719 | ||
27720 | - %route%: Routing failed. | |
27721 | ||
27722 | - %mail%: Routing succeeded, and a callout was attempted; rejection | |
27723 | occurred at or before the MAIL command (that is, on initial | |
27724 | connection, HELO, or MAIL). | |
27725 | ||
27726 | - %recipient%: The RCPT command in a callout was rejected. | |
27727 | ||
27728 | - %postmaster%: The postmaster check in a callout was rejected. | |
27729 | ||
168e428f PH |
27730 | The main use of these variables is expected to be to distinguish between |
27731 | rejections of MAIL and rejections of RCPT in callouts. | |
27732 | ||
27733 | ||
27734 | ||
27735 | ||
27736 | [[SECTcallver]] | |
27737 | Callout verification | |
27738 | ~~~~~~~~~~~~~~~~~~~~ | |
068aaea8 | 27739 | [revisionflag="changed"] |
168e428f PH |
27740 | cindex:[verifying address, by callout] |
27741 | cindex:[callout,verification] | |
27742 | cindex:[SMTP,callout verification] | |
27743 | For non-local addresses, routing verifies the domain, but is unable to do any | |
27744 | checking of the local part. There are situations where some means of verifying | |
27745 | the local part is desirable. One way this can be done is to make an SMTP | |
068aaea8 PH |
27746 | 'callback' to a delivery host for the sender address or a 'callforward' to a |
27747 | subsequent host for a recipient address, to see if the host accepts the | |
27748 | address. We use the term 'callout' to cover both cases. Note that for a sender | |
27749 | address, the callback is not to the client host that is trying to deliver the | |
27750 | message, but to one of the hosts that accepts incoming mail for the sender's | |
27751 | domain. | |
27752 | ||
27753 | [revisionflag="changed"] | |
27754 | Exim does not do callouts by default. If you want them to happen, you must | |
27755 | request them by setting appropriate options on the %verify% condition, as | |
27756 | described below. This facility should be used with care, because it can add a | |
27757 | lot of resource usage to the cost of verifying an address. However, Exim does | |
27758 | cache the results of callouts, which helps to reduce the cost. Details of | |
27759 | caching are in section <<SECTcallvercache>>. | |
168e428f PH |
27760 | |
27761 | Recipient callouts are usually used only between hosts that are controlled by | |
27762 | the same administration. For example, a corporate gateway host could use | |
068aaea8 PH |
27763 | callouts to check for valid recipients on an internal mailserver. A successful |
27764 | callout does not guarantee that a real delivery to the address would succeed; | |
27765 | on the other hand, a failing callout does guarantee that a delivery would fail. | |
168e428f PH |
27766 | |
27767 | If the %callout% option is present on a condition that verifies an address, a | |
27768 | second stage of verification occurs if the address is successfully routed to | |
27769 | one or more remote hosts. The usual case is routing by a ^dnslookup^ or a | |
27770 | ^manualroute^ router, where the router specifies the hosts. However, if a | |
27771 | router that does not set up hosts routes to an ^smtp^ transport with a | |
27772 | %hosts% setting, the transport's hosts are used. If an ^smtp^ transport has | |
27773 | %hosts_override% set, its hosts are always used, whether or not the router | |
27774 | supplies a host list. | |
27775 | ||
27776 | The port that is used is taken from the transport, if it is specified and is a | |
27777 | remote transport. (For routers that do verification only, no transport need be | |
27778 | specified.) Otherwise, the default SMTP port is used. If a remote transport | |
27779 | specifies an outgoing interface, this is used; otherwise the interface is not | |
27780 | specified. | |
27781 | ||
27782 | For a sender callout check, Exim makes SMTP connections to the remote hosts, to | |
27783 | test whether a bounce message could be delivered to the sender address. The | |
27784 | following SMTP commands are sent: | |
27785 | ||
27786 | &&& | |
27787 | `HELO `<'smtp active host name'> | |
27788 | `MAIL FROM:<>` | |
27789 | `RCPT TO:`<'the address to be tested'> | |
27790 | `QUIT` | |
27791 | &&& | |
27792 | ||
27793 | LHLO is used instead of HELO if the transport's %protocol% option is | |
27794 | set to ``lmtp''. | |
27795 | ||
27796 | A recipient callout check is similar. By default, it also uses an empty address | |
27797 | for the sender. This default is chosen because most hosts do not make use of | |
27798 | the sender address when verifying a recipient. Using the same address means | |
27799 | that a single cache entry can be used for each recipient. Some sites, however, | |
27800 | do make use of the sender address when verifying. These are catered for by the | |
27801 | %use_sender% and %use_postmaster% options, described in the next section. | |
27802 | ||
27803 | If the response to the RCPT command is a 2'##xx' code, the verification | |
27804 | succeeds. If it is 5##'xx', the verification fails. For any other condition, | |
27805 | Exim tries the next host, if any. If there is a problem with all the remote | |
27806 | hosts, the ACL yields ``defer'', unless the %defer_ok% parameter of the | |
27807 | %callout% option is given, in which case the condition is forced to succeed. | |
27808 | ||
27809 | ||
27810 | ||
27811 | ||
27812 | ||
27813 | [[CALLaddparcall]] | |
27814 | Additional parameters for callouts | |
27815 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
27816 | cindex:[callout,additional parameters for] | |
27817 | The %callout% option can be followed by an equals sign and a number of optional | |
27818 | parameters, separated by commas. For example: | |
27819 | ||
27820 | verify = recipient/callout=10s,defer_ok | |
27821 | ||
27822 | The old syntax, which had %callout_defer_ok% and %check_postmaster% as | |
27823 | separate verify options, is retained for backwards compatibility, but is now | |
27824 | deprecated. The additional parameters for %callout% are as follows: | |
27825 | ||
27826 | ||
27827 | <'a~time~interval'>:: | |
27828 | cindex:[callout timeout, specifying] | |
27829 | This specifies the timeout that applies for the callout attempt to each host. | |
27830 | For example: | |
27831 | ||
27832 | verify = sender/callout=5s | |
27833 | + | |
27834 | The default is 30 seconds. The timeout is used for each response from the | |
27835 | remote host. It is also used for the intial connection, unless overridden by | |
27836 | the %connect% parameter. | |
27837 | ||
27838 | ||
27839 | *connect~=~*<'time~interval'>:: | |
27840 | cindex:[callout connection timeout, specifying] | |
27841 | This parameter makes it possible to set a different (usually smaller) timeout | |
27842 | for making the SMTP connection. For example: | |
27843 | ||
27844 | verify = sender/callout=5s,connect=1s | |
27845 | + | |
27846 | If not specified, this timeout defaults to the general timeout value. | |
27847 | ||
27848 | *defer_ok*:: | |
27849 | cindex:[callout defer, action on] | |
27850 | When this parameter is present, failure to contact any host, or any other kind | |
27851 | of temporary error, is treated as success by the ACL. However, the cache is not | |
27852 | updated in this circumstance. | |
27853 | ||
068aaea8 PH |
27854 | [revisionflag="changed"] |
27855 | *fullpostmaster*:: | |
27856 | cindex:[callout,full postmaster check] | |
27857 | This operates like the %postmaster% option (see below), but if the check for | |
27858 | 'postmaster@domain' fails, it tries just 'postmaster', without a domain, in | |
27859 | accordance with the specification in RFC 2821. The RFC states that the | |
27860 | unqualified address 'postmaster' should be accepted. | |
27861 | ||
27862 | ||
27863 | ||
168e428f PH |
27864 | *mailfrom~=~*<'email~address'>:: |
27865 | cindex:[callout,sender when verifying header] | |
27866 | When verifying addresses in header lines using the %header_sender% verification | |
27867 | option, Exim behaves by default as if the addresses are envelope sender | |
27868 | addresses from a message. Callout verification therefore tests to see whether a | |
27869 | bounce message could be delivered, by using an empty address in the MAIL | |
27870 | command. However, it is arguable that these addresses might never be used as | |
27871 | envelope senders, and could therefore justifiably reject bounce messages (empty | |
27872 | senders). The %mailfrom% callout parameter allows you to specify what address | |
27873 | to use in the MAIL command. For example: | |
27874 | ||
27875 | require verify = header_sender/callout=mailfrom=abcd@x.y.z | |
27876 | + | |
27877 | This parameter is available only for the %header_sender% verification option. | |
27878 | ||
27879 | ||
27880 | *maxwait~=~*<'time~interval'>:: | |
27881 | cindex:[callout overall timeout, specifying] | |
27882 | This parameter sets an overall timeout for performing a callout verification. | |
27883 | For example: | |
27884 | ||
27885 | verify = sender/callout=5s,maxwait=30s | |
27886 | + | |
27887 | This timeout defaults to four times the callout timeout for individual SMTP | |
27888 | commands. The overall timeout applies when there is more than one host that can | |
27889 | be tried. The timeout is checked before trying the next host. This prevents | |
27890 | very long delays if there are a large number of hosts and all are timing out | |
27891 | (for example, when network connections are timing out). | |
27892 | ||
27893 | ||
27894 | *no_cache*:: | |
27895 | cindex:[callout cache, suppressing] | |
27896 | cindex:[caching callout, suppressing] | |
27897 | When this parameter is given, the callout cache is neither read nor updated. | |
27898 | ||
27899 | *postmaster*:: | |
27900 | cindex:[callout,postmaster; checking] | |
27901 | When this parameter is set, a sucessful callout check is followed by a similar | |
27902 | check for the local part 'postmaster' at the same domain. If this address is | |
068aaea8 PH |
27903 | rejected, the callout fails (but see %fullpostmaster% above). The result of the |
27904 | postmaster check is recorded in a cache record; if it is a failure, this is | |
27905 | used to fail subsequent callouts for the domain without a connection being | |
27906 | made, until the cache record expires. | |
168e428f PH |
27907 | |
27908 | *postmaster_mailfrom~=~*<'email~address'>:: | |
27909 | The postmaster check uses an empty sender in the MAIL command by default. | |
27910 | You can use this parameter to do a postmaster check using a different address. | |
27911 | For example: | |
27912 | ||
27913 | require verify = sender/callout=postmaster_mailfrom=abc@x.y.z | |
27914 | + | |
27915 | If both %postmaster% and %postmaster_mailfrom% are present, the rightmost one | |
27916 | overrides. The %postmaster% parameter is equivalent to this example: | |
27917 | ||
27918 | require verify = sender/callout=postmaster_mailfrom= | |
27919 | + | |
27920 | *Warning*: The caching arrangements for postmaster checking do not take | |
27921 | account of the sender address. It is assumed that either the empty address or | |
27922 | a fixed non-empty address will be used. All that Exim remembers is that the | |
27923 | postmaster check for the domain succeeded or failed. | |
27924 | ||
27925 | ||
27926 | *random*:: | |
27927 | cindex:[callout,``random'' check] | |
27928 | When this parameter is set, before doing the normal callout check, Exim does a | |
27929 | check for a ``random'' local part at the same domain. The local part is not | |
27930 | really random -- it is defined by the expansion of the option | |
27931 | %callout_random_local_part%, which defaults to | |
27932 | ||
27933 | $primary_host_name-$tod_epoch-testing | |
27934 | + | |
27935 | The idea here is to try to determine whether the remote host accepts all local | |
27936 | parts without checking. If it does, there is no point in doing callouts for | |
27937 | specific local parts. If the ``random'' check succeeds, the result is saved in | |
27938 | a cache record, and used to force the current and subsequent callout checks to | |
27939 | succeed without a connection being made, until the cache record expires. | |
27940 | ||
27941 | *use_postmaster*:: | |
27942 | cindex:[callout,sender for recipient check] | |
27943 | This parameter applies to recipient callouts only. For example: | |
27944 | ||
27945 | deny !verify = recipient/callout=use_postmaster | |
27946 | + | |
068aaea8 PH |
27947 | [revisionflag="changed"] |
27948 | cindex:[$qualify_domain$] | |
27949 | It causes a non-empty postmaster address to be used in the MAIL command when | |
27950 | performing the callout for the recipient, and also for a ``random'' check if | |
27951 | that is configured. The local part of the address is `postmaster` and the | |
27952 | domain is the contents of $qualify_domain$. | |
168e428f PH |
27953 | |
27954 | *use_sender*:: | |
27955 | This option applies to recipient callouts only. For example: | |
27956 | ||
27957 | require verify = recipient/callout=use_sender | |
27958 | + | |
27959 | It causes the message's actual sender address to be used in the MAIL | |
27960 | command when performing the callout, instead of an empty address. There is no | |
27961 | need to use this option unless you know that the called hosts make use of the | |
27962 | sender when checking recipients. If used indiscriminately, it reduces the | |
27963 | usefulness of callout caching. | |
27964 | ||
27965 | /// | |
27966 | End of list | |
27967 | /// | |
27968 | ||
27969 | If you use any of the parameters that set a non-empty sender for the MAIL | |
27970 | command (%mailfrom%, %postmaster_mailfrom%, %use_postmaster%, or | |
27971 | %use_sender%), you should think about possible loops. Recipient checking is | |
27972 | usually done between two hosts that are under the same management, and the host | |
27973 | that receives the callouts is not normally configured to do callouts itself. | |
27974 | Therefore, it is normally safe to use %use_postmaster% or %use_sender% in | |
27975 | these circumstances. | |
27976 | ||
27977 | However, if you use a non-empty sender address for a callout to an arbitrary | |
27978 | host, there is the likelihood that the remote host will itself initiate a | |
27979 | callout check back to your host. As it is checking what appears to be a message | |
27980 | sender, it is likely to use an empty address in MAIL, thus avoiding a | |
27981 | callout loop. However, to be on the safe side it would be best to set up your | |
27982 | own ACLs so that they do not do sender verification checks when the recipient | |
27983 | is the address you use for header sender or postmaster callout checking. | |
27984 | ||
27985 | Another issue to think about when using non-empty senders for callouts is | |
27986 | caching. When you set %mailfrom% or %use_sender%, the cache record is keyed by | |
27987 | the sender/recipient combination; thus, for any given recipient, many more | |
27988 | actual callouts are performed than when an empty sender or postmaster is used. | |
27989 | ||
27990 | ||
27991 | ||
27992 | ||
27993 | [[SECTcallvercache]] | |
27994 | Callout caching | |
27995 | ~~~~~~~~~~~~~~~ | |
27996 | cindex:[hints database,callout cache] | |
27997 | cindex:[callout,caching] | |
27998 | cindex:[caching,callout] | |
27999 | Exim caches the results of callouts in order to reduce the amount of resources | |
28000 | used, unless you specify the %no_cache% parameter with the %callout% option. | |
28001 | A hints database called ``callout'' is used for the cache. Two different record | |
28002 | types are used: one records the result of a callout check for a specific | |
28003 | address, and the other records information that applies to the entire domain | |
28004 | (for example, that it accepts the local part 'postmaster'). | |
28005 | ||
28006 | When an original callout fails, a detailed SMTP error message is given about | |
28007 | the failure. However, for subsequent failures use the cache data, this message | |
28008 | is not available. | |
28009 | ||
28010 | The expiry times for negative and positive address cache records are | |
28011 | independent, and can be set by the global options %callout_negative_expire% | |
28012 | (default 2h) and %callout_positive_expire% (default 24h), respectively. | |
28013 | ||
28014 | If a host gives a negative response to an SMTP connection, or rejects any | |
28015 | commands up to and including | |
28016 | ||
28017 | MAIL FROM:<> | |
28018 | ||
28019 | (but not including the MAIL command with a non-empty address), | |
28020 | any callout attempt is bound to fail. Exim remembers such failures in a | |
28021 | domain cache record, which it uses to fail callouts for the domain without | |
28022 | making new connections, until the domain record times out. There are two | |
28023 | separate expiry times for domain cache records: | |
28024 | %callout_domain_negative_expire% (default 3h) and | |
28025 | %callout_domain_positive_expire% (default 7d). | |
28026 | ||
28027 | Domain records expire when the negative expiry time is reached if callouts | |
28028 | cannot be made for the domain, or if the postmaster check failed. | |
28029 | Otherwise, they expire when the positive expiry time is reached. This | |
28030 | ensures that, for example, a host that stops accepting ``random'' local parts | |
28031 | will eventually be noticed. | |
28032 | ||
28033 | The callout caching mechanism is based on the domain of the address that is | |
28034 | being tested. If the domain routes to several hosts, it is assumed that their | |
28035 | behaviour will be the same. | |
28036 | ||
28037 | ||
28038 | ||
28039 | [[SECTsenaddver]] | |
28040 | Sender address verification reporting | |
28041 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
28042 | cindex:[verifying,suppressing error details] | |
28043 | When sender verification fails in an ACL, the details of the failure are | |
28044 | given as additional output lines before the 550 response to the relevant | |
28045 | SMTP command (RCPT or DATA). For example, if sender callout is in use, | |
28046 | you might see: | |
28047 | ||
28048 | MAIL FROM:<xyz@abc.example> | |
28049 | 250 OK | |
28050 | RCPT TO:<pqr@def.example> | |
28051 | 550-Verification failed for <xyz@abc.example> | |
28052 | 550-Called: 192.168.34.43 | |
28053 | 550-Sent: RCPT TO:<xyz@abc.example> | |
28054 | 550-Response: 550 Unknown local part xyz in <xyz@abc.example> | |
28055 | 550 Sender verification failed | |
28056 | ||
28057 | If more than one RCPT command fails in the same way, the details are given | |
28058 | only for the first of them. However, some administrators do not want to send | |
28059 | out this much information. You can suppress the details by adding | |
28060 | ``/no_details'' to the ACL statement that requests sender verification. For | |
28061 | example: | |
28062 | ||
28063 | verify = sender/no_details | |
28064 | ||
28065 | ||
28066 | ||
068aaea8 | 28067 | [[SECTredirwhilveri]] |
168e428f PH |
28068 | Redirection while verifying |
28069 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
28070 | cindex:[verifying,redirection while] | |
28071 | cindex:[address redirection,while verifying] | |
28072 | A dilemma arises when a local address is redirected by aliasing or forwarding | |
28073 | during verification: should the generated addresses themselves be verified, | |
28074 | or should the successful expansion of the original address be enough to verify | |
068aaea8 | 28075 | it? By default, Exim takes the following pragmatic approach: |
168e428f PH |
28076 | |
28077 | - When an incoming address is redirected to just one child address, verification | |
28078 | continues with the child address, and if that fails to verify, the original | |
28079 | verification also fails. | |
28080 | ||
28081 | - When an incoming address is redirected to more than one child address, | |
28082 | verification does not continue. A success result is returned. | |
28083 | ||
28084 | This seems the most reasonable behaviour for the common use of aliasing as a | |
28085 | way of redirecting different local parts to the same mailbox. It means, for | |
28086 | example, that a pair of alias entries of the form | |
28087 | ||
28088 | A.Wol: aw123 | |
28089 | aw123: :fail: Gone away, no forwarding address | |
28090 | ||
28091 | work as expected, with both local parts causing verification failure. When a | |
28092 | redirection generates more than one address, the behaviour is more like a | |
28093 | mailing list, where the existence of the alias itself is sufficient for | |
28094 | verification to succeed. | |
28095 | ||
068aaea8 PH |
28096 | [revisionflag="changed"] |
28097 | It is possible, however, to change the default behaviour so that all successful | |
28098 | redirections count as successful verifications, however many new addresses are | |
28099 | generated. This is specified by the %success_on_redirect% verification option. | |
28100 | For example: | |
28101 | ||
28102 | [revisionflag="changed"] | |
28103 | require verify = recipient/success_on_redirect/callout=10s | |
28104 | ||
28105 | [revisionflag="changed"] | |
28106 | In this example, verification succeeds if a router generates a new address, and | |
28107 | the callout does not occur, because no address was routed to a remote host. | |
28108 | ||
28109 | ||
28110 | ||
28111 | ||
28112 | ||
28113 | [[SECTverifyCSA]] | |
28114 | Client SMTP authorization (CSA) | |
28115 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
28116 | [revisionflag="changed"] | |
28117 | cindex:[CSA,verifying] | |
28118 | Client SMTP Authorization is a system that allows a site to advertise | |
28119 | which machines are and are not permitted to send email. This is done by placing | |
28120 | special SRV records in the DNS; these are looked up using the client's HELO | |
28121 | domain. At the time of writing, CSA is still an Internet Draft. Client SMTP | |
28122 | Authorization checks in Exim are performed by the ACL condition: | |
28123 | ||
28124 | verify = csa | |
28125 | ||
28126 | [revisionflag="changed"] | |
28127 | This fails if the client is not authorized. If there is a DNS problem, or if no | |
28128 | valid CSA SRV record is found, or if the client is authorized, the condition | |
28129 | succeeds. These three cases can be distinguished using the expansion variable | |
28130 | $csa_status$, which can take one of the values ``fail'', ``defer'', | |
28131 | ``unknown'', or ``ok''. The condition does not itself defer because that would | |
28132 | be likely to cause problems for legitimate email. | |
28133 | ||
28134 | [revisionflag="changed"] | |
28135 | The error messages produced by the CSA code include slightly more | |
28136 | detail. If $csa_status$ is ``defer'', this may be because of problems | |
28137 | looking up the CSA SRV record, or problems looking up the CSA target | |
28138 | address record. There are four reasons for $csa_status$ being ``fail'': | |
28139 | ||
28140 | [revisionflag="changed"] | |
28141 | - The client's host name is explicitly not authorized. | |
28142 | ||
28143 | [revisionflag="changed"] | |
28144 | - The client's IP address does not match any of the CSA target IP addresses. | |
28145 | ||
28146 | [revisionflag="changed"] | |
28147 | - The client's host name is authorized but it has no valid target IP addresses | |
28148 | (for example, the target's addresses are IPv6 and the client is using IPv4). | |
28149 | ||
28150 | [revisionflag="changed"] | |
28151 | - The client's host name has no CSA SRV record but a parent domain has asserted | |
28152 | that all subdomains must be explicitly authorized. | |
28153 | ||
28154 | [revisionflag="changed"] | |
28155 | The %csa% verification condition can take an argument which is the domain to | |
28156 | use for the DNS query. The default is: | |
28157 | ||
28158 | verify = csa/$sender_helo_name | |
28159 | ||
28160 | [revisionflag="changed"] | |
28161 | This implementation includes an extension to CSA. If the query domain | |
28162 | is an address literal such as [192.0.2.95], or if it is a bare IP | |
28163 | address, Exim searches for CSA SRV records in the reverse DNS as if | |
28164 | the HELO domain was (for example) '95.2.0.192.in-addr.arpa'. Therefore it is | |
28165 | meaningful to say: | |
28166 | ||
28167 | verify = csa/$sender_host_address | |
28168 | ||
28169 | [revisionflag="changed"] | |
28170 | In fact, this is the check that Exim performs if the client does not say HELO. | |
28171 | This extension can be turned off by setting the main configuration option | |
28172 | %dns_csa_use_reverse% to be false. | |
28173 | ||
28174 | [revisionflag="changed"] | |
28175 | If a CSA SRV record is not found for the domain itself, a search | |
28176 | is performed through its parent domains for a record which might be | |
28177 | making assertions about subdomains. The maximum depth of this search is limited | |
28178 | using the main configuration option %dns_csa_search_limit%, which is 5 by | |
28179 | default. Exim does not look for CSA SRV records in a top level domain, so the | |
28180 | default settings handle HELO domains as long as seven | |
28181 | ('hostname.five.four.three.two.one.com'). This encompasses the vast majority of | |
28182 | legitimate HELO domains. | |
28183 | ||
28184 | [revisionflag="changed"] | |
28185 | The 'dnsdb' lookup also has support for CSA. Although 'dnsdb' also supports | |
28186 | direct SRV lookups, this is not sufficient because of the extra parent domain | |
28187 | search behaviour of CSA, and (as with PTR lookups) 'dnsdb' also turns IP | |
28188 | addresses into lookups in the reverse DNS space. The result of a successful | |
28189 | lookup such as: | |
28190 | ||
28191 | [revisionflag="changed"] | |
28192 | .... | |
28193 | ${lookup dnsdb {csa=$sender_helo_name}} | |
28194 | .... | |
28195 | ||
28196 | [revisionflag="changed"] | |
28197 | has two space-separated fields: an authorization code and a target host name. | |
28198 | The authorization code can be ``Y'' for yes, ``N'' for no, ``X'' for explicit | |
28199 | authorization required but absent, or ``?'' for unknown. | |
28200 | ||
28201 | ||
28202 | ||
28203 | ||
28204 | [[SECTverifyPRVS]] | |
28205 | Bounce address tag validation | |
28206 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
28207 | [revisionflag="changed"] | |
28208 | cindex:[BATV,verifying] | |
28209 | Bounce address tag validation (BATV) is a scheme whereby the envelope senders | |
28210 | of outgoing messages have a cryptographic, timestamped ``tag'' added to them. | |
28211 | Genuine incoming bounce messages should therefore always be addressed to | |
28212 | recipients that have a valid tag. This scheme is a way of detecting unwanted | |
28213 | bounce messages caused by sender address forgeries (often called ``collateral | |
28214 | spam''), because the recipients of such messages will not include valid tags. | |
28215 | ||
28216 | [revisionflag="changed"] | |
28217 | There are two expansion items to help with the implementation of the BATV | |
28218 | ``prvs'' (private signature) scheme in an Exim configuration. This scheme signs | |
28219 | the original envelope sender address by using a simple shared key to add a hash | |
28220 | of the address and some time-based randomizing information. The %prvs% | |
28221 | expansion item creates a signed address, and the %prvscheck% expansion item | |
28222 | checks one. The syntax of these expansion items is described in section | |
28223 | <<SECTexpansionitems>>. | |
28224 | ||
28225 | [revisionflag="changed"] | |
28226 | As an example, suppose the secret per-address keys are stored in an MySQL | |
28227 | database. A query to look up the key for an address could be defined as a macro | |
28228 | like this: | |
28229 | ||
28230 | [revisionflag="changed"] | |
28231 | .... | |
28232 | PRVSCHECK_SQL = ${lookup mysql{SELECT secret FROM batv_prvs \ | |
28233 | WHERE sender='${quote_mysql:$prvscheck_address}'\ | |
28234 | }{$value}} | |
28235 | .... | |
28236 | ||
28237 | [revisionflag="changed"] | |
28238 | Suppose also that the senders who make use of BATV are defined by an address | |
28239 | list called %batv_senders%. Then, in the ACL for RCPT commands, you could | |
28240 | use this: | |
28241 | ||
28242 | [revisionflag="changed"] | |
28243 | .... | |
28244 | # Bounces: drop unsigned addresses for BATV senders | |
28245 | deny message = This address does not send an unsigned reverse path. | |
28246 | senders = : | |
28247 | recipients = +batv_senders | |
28248 | ||
28249 | # Bounces: In case of prvs-signed address, check signature. | |
28250 | deny message = Invalid reverse path signature. | |
28251 | senders = : | |
28252 | condition = ${prvscheck {$local_part@$domain}\ | |
28253 | {PRVSCHECK_SQL}{1}} | |
28254 | !condition = $prvscheck_result | |
28255 | .... | |
28256 | ||
28257 | [revisionflag="changed"] | |
28258 | The first statement rejects recipients for bounce messages that are addressed | |
28259 | to plain BATV sender addresses, because it is known that BATV senders do not | |
28260 | send out messages with plain sender addresses. The second statement rejects | |
28261 | recipients that are prvs-signed, but with invalid signatures (either because | |
28262 | the key is wrong, or the signature has timed out). | |
28263 | ||
28264 | [revisionflag="changed"] | |
28265 | A non-prvs-signed address is not rejected by the second statement, because the | |
28266 | %prvscheck% expansion yields an empty string if its first argument is not a | |
28267 | prvs-signed address, thus causing the %condition% condition to be false. If the | |
28268 | first argument is a syntactically valid prvs-signed address, the yield is the | |
28269 | third string (in this case ``1''), whether or not the cryptographic and timeout | |
28270 | checks succeed. The $prvscheck_result$ variable contains the result of the | |
28271 | checks (empty for failure, ``1'' for success). | |
28272 | ||
28273 | [revisionflag="changed"] | |
28274 | Of course, when you accept a prvs-signed address, you have to ensure that the | |
28275 | routers accept it and deliver it correctly. The easiest way to handle this is | |
28276 | to use a ^redirect^ router to remove the signature with a configuration along | |
28277 | these lines: | |
28278 | ||
28279 | [revisionflag="changed"] | |
28280 | .... | |
28281 | batv_redirect: | |
28282 | driver = redirect | |
28283 | data = ${prvscheck {$local_part@$domain}{PRVSCHECK_SQL}} | |
28284 | .... | |
28285 | ||
28286 | [revisionflag="changed"] | |
28287 | This works because, if the third argument of %prvscheck% is empty, the result | |
28288 | of the expansion of a prvs-signed address is the decoded value of the original | |
28289 | address. This router should probably be the first of your routers that handles | |
28290 | local addresses. | |
28291 | ||
28292 | [revisionflag="changed"] | |
28293 | To create BATV-signed addresses in the first place, a transport of this form | |
28294 | can be used: | |
28295 | ||
28296 | [revisionflag="changed"] | |
28297 | .... | |
28298 | external_smtp_batv: | |
28299 | driver = smtp | |
28300 | return_path = ${prvs {$return_path} \ | |
28301 | {${lookup mysql{SELECT \ | |
28302 | secret FROM batv_prvs WHERE \ | |
28303 | sender='${quote_mysql:$sender_address}'} \ | |
28304 | {$value}fail}}} | |
28305 | .... | |
28306 | ||
28307 | [revisionflag="changed"] | |
28308 | If no key can be found for the existing return path, no signing takes place. | |
28309 | ||
28310 | ||
168e428f PH |
28311 | |
28312 | ||
28313 | [[SECTrelaycontrol]] | |
28314 | Using an ACL to control relaying | |
28315 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
28316 | cindex:[{ACL},relay control] | |
28317 | cindex:[relaying,control by ACL] | |
28318 | cindex:[policy control,relay control] | |
28319 | An MTA is said to 'relay' a message if it receives it from some host and | |
28320 | delivers it directly to another host as a result of a remote address contained | |
28321 | within it. Redirecting a local address via an alias or forward file and then | |
28322 | passing the message on to another host is not relaying, | |
168e428f PH |
28323 | cindex:[``percent hack''] |
28324 | but a redirection as a result of the ``percent hack'' is. | |
28325 | ||
28326 | Two kinds of relaying exist, which are termed ``incoming'' and ``outgoing''. | |
28327 | A host which is acting as a gateway or an MX backup is concerned with incoming | |
28328 | relaying from arbitrary hosts to a specific set of domains. On the other hand, | |
28329 | a host which is acting as a smart host for a number of clients is concerned | |
28330 | with outgoing relaying from those clients to the Internet at large. Often the | |
28331 | same host is fulfilling both functions, | |
28332 | /// | |
28333 | as illustrated in the diagram below, | |
28334 | /// | |
28335 | but in principle these two kinds of relaying are entirely independent. What is | |
28336 | not wanted is the transmission of mail from arbitrary remote hosts through your | |
28337 | system to arbitrary domains. | |
28338 | ||
28339 | ||
28340 | You can implement relay control by means of suitable statements in the ACL that | |
28341 | runs for each RCPT command. For convenience, it is often easiest to use | |
28342 | Exim's named list facility to define the domains and hosts involved. For | |
28343 | example, suppose you want to do the following: | |
28344 | ||
28345 | - Deliver a number of domains to mailboxes on the local host (or process them | |
28346 | locally in some other way). Let's say these are 'my.dom1.example' and | |
28347 | 'my.dom2.example'. | |
28348 | ||
28349 | - Relay mail for a number of other domains for which you are the secondary MX. | |
28350 | These might be 'friend1.example' and 'friend2.example'. | |
28351 | ||
28352 | - Relay mail from the hosts on your local LAN, to whatever domains are involved. | |
28353 | Suppose your LAN is 192.168.45.0/24. | |
28354 | ||
28355 | ||
28356 | In the main part of the configuration, you put the following definitions: | |
28357 | ||
28358 | domainlist local_domains = my.dom1.example : my.dom2.example | |
28359 | domainlist relay_domains = friend1.example : friend2.example | |
28360 | hostlist relay_hosts = 192.168.45.0/24 | |
28361 | ||
28362 | Now you can use these definitions in the ACL that is run for every RCPT | |
28363 | command: | |
28364 | ||
28365 | acl_check_rcpt: | |
28366 | accept domains = +local_domains : +relay_domains | |
28367 | accept hosts = +relay_hosts | |
28368 | ||
28369 | The first statement accepts any RCPT command that contains an address in | |
28370 | the local or relay domains. For any other domain, control passes to the second | |
28371 | statement, which accepts the command only if it comes from one of the relay | |
28372 | hosts. In practice, you will probably want to make your ACL more sophisticated | |
28373 | than this, for example, by including sender and recipient verification. The | |
28374 | default configuration includes a more comprehensive example, which is described | |
28375 | in chapter <<CHAPdefconfil>>. | |
28376 | ||
28377 | ||
28378 | ||
28379 | [[SECTcheralcon]] | |
28380 | Checking a relay configuration | |
28381 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
28382 | cindex:[relaying,checking control of] | |
28383 | You can check the relay characteristics of your configuration in the same way | |
28384 | that you can test any ACL behaviour for an incoming SMTP connection, by using | |
28385 | the %-bh% option to run a fake SMTP session with which you interact. | |
28386 | ||
28387 | For specifically testing for unwanted relaying, the host | |
28388 | 'relay-test.mail-abuse.org' provides a useful service. If you telnet to this | |
28389 | host from the host on which Exim is running, using the normal telnet port, you | |
28390 | will see a normal telnet connection message and then quite a long delay. Be | |
28391 | patient. The remote host is making an SMTP connection back to your host, and | |
28392 | trying a number of common probes to test for open relay vulnerability. The | |
28393 | results of the tests will eventually appear on your terminal. | |
28394 | ||
28395 | ||
28396 | ||
28397 | ||
28398 | //////////////////////////////////////////////////////////////////////////// | |
28399 | //////////////////////////////////////////////////////////////////////////// | |
28400 | ||
28401 | [[CHAPexiscan]] | |
068aaea8 PH |
28402 | Content scanning at ACL time |
28403 | ---------------------------- | |
28404 | cindex:[content scanning,at ACL time] | |
28405 | The extension of Exim to include content scanning at ACL time, formerly known | |
28406 | as ``exiscan'', was originally implemented as a patch by Tom Kistner. The code | |
28407 | was integrated into the main source for Exim release 4.50, and Tom continues to | |
28408 | maintain it. Most of the wording of this chapter is taken from Tom's | |
28409 | specification. | |
28410 | ||
28411 | [revisionflag="changed"] | |
28412 | It is also possible to scan the content of messages at other times. The | |
28413 | 'local_scan()' function (see chapter <<CHAPlocalscan>>) allows for content | |
28414 | scanning after all the ACLs have run. A transport filter can be used to scan | |
28415 | messages at delivery time (see the %transport_filter% option, described in | |
28416 | chapter <<CHAPtransportgeneric>>). | |
28417 | ||
28418 | If you want to include the ACL-time content-scanning features when you compile | |
28419 | Exim, you need to arrange for WITH_CONTENT_SCAN to be defined in your | |
168e428f PH |
28420 | _Local/Makefile_. When you do that, the Exim binary is built with: |
28421 | ||
068aaea8 PH |
28422 | [revisionflag="changed"] |
28423 | - Two additional ACLs (%acl_smtp_mime% and %acl_not_smtp_mime%) that are run for | |
28424 | all MIME parts for SMTP and non-SMTP messages, respectively. | |
168e428f PH |
28425 | |
28426 | - Additional ACL conditions and modifiers: %decode%, %malware%, %mime_regex%, | |
28427 | %regex%, and %spam%. These can be used in the ACL that is run at the end of | |
28428 | message reception (the %acl_smtp_data% ACL). | |
28429 | ||
28430 | - An additional control feature (``no_mbox_unspool'') that saves spooled copies | |
28431 | of messages, or parts of messages, for debugging purposes. | |
28432 | ||
28433 | - Additional expansion variables that are set in the new ACL and by the new | |
28434 | conditions. | |
28435 | ||
28436 | - Two new main configuration options: %av_scanner% and %spamd_address%. | |
28437 | ||
28438 | There is another content-scanning configuration option for _Local/Makefile_, | |
28439 | called WITH_OLD_DEMIME. If this is set, the old, deprecated %demime% ACL | |
28440 | condition is compiled, in addition to all the other content-scanning features. | |
28441 | ||
28442 | Content-scanning is continually evolving, and new features are still being | |
28443 | added. While such features are still unstable and liable to incompatible | |
28444 | changes, they are made available in Exim by setting options whose names begin | |
28445 | EXPERIMENTAL_ in _Local/Makefile_. Such features are not documented in | |
28446 | this manual. You can find out about them by reading the file called | |
28447 | _doc/experimental.txt_. | |
28448 | ||
28449 | All the content-scanning facilites work on a MBOX copy of the message that is | |
28450 | temporarily created in a file called: | |
28451 | ||
28452 | <spool_directory>/scan/<message_id>/<message_id>.eml | |
28453 | ||
28454 | The _.eml_ extension is a friendly hint to virus scanners that they can | |
28455 | expect an MBOX-like structure inside that file. The file is created when the | |
28456 | first content scanning facility is called. Subsequent calls to content | |
28457 | scanning conditions open the same file again. The directory is recursively | |
28458 | removed when the %acl_smtp_data% ACL has finished running, unless | |
28459 | ||
28460 | control = no_mbox_unspool | |
28461 | ||
28462 | has been encountered. When the MIME ACL decodes files, they are put into the | |
28463 | same directory by default. | |
28464 | ||
28465 | ||
28466 | ||
28467 | [[SECTscanvirus]] | |
28468 | Scanning for viruses | |
28469 | ~~~~~~~~~~~~~~~~~~~~ | |
28470 | cindex:[virus scanning] | |
28471 | cindex:[content scanning,for viruses] | |
28472 | cindex:[content scanning,the %malware% condition] | |
28473 | The %malware% ACL condition lets you connect virus scanner software to Exim. It | |
28474 | supports a ``generic'' interface to scanners called via the shell, and | |
28475 | specialized interfaces for ``daemon'' type virus scanners, which are resident in | |
28476 | memory and thus are much faster. | |
28477 | ||
28478 | cindex:[%av_scanner%] | |
28479 | You can set the %av_scanner% option in first part of the Exim configuration | |
28480 | file to specify which scanner to use, together with any additional options that | |
28481 | are needed. The basic syntax is as follows: | |
28482 | ||
28483 | av_scanner = <scanner-type>:<option1>:<option2>:[...] | |
28484 | ||
28485 | If you do not set %av_scanner%, it defaults to | |
28486 | ||
28487 | av_scanner = sophie:/var/run/sophie | |
28488 | ||
28489 | If the value of %av_scanner% starts with dollar character, it is expanded | |
28490 | before use. | |
28491 | ||
28492 | The following scanner types are supported in this release: | |
28493 | ||
28494 | %aveserver%:: | |
28495 | cindex:[virus scanners,Kaspersky] | |
28496 | This is the scanner daemon of Kaspersky Version 5. You can get a trial version | |
28497 | at *http://www.kaspersky.com[]*. This scanner type takes one option, which is | |
28498 | the path to the daemon's UNIX socket. The default is shown in this example: | |
28499 | ||
28500 | av_scanner = aveserver:/var/run/aveserver | |
28501 | ||
28502 | %clamd%:: | |
28503 | cindex:[virus scanners,clamd] | |
28504 | This daemon-type scanner is GPL and free. You can get it at | |
068aaea8 PH |
28505 | *http://www.clamav.net/[]*. Some older versions of clamd do not seem to unpack |
28506 | MIME containers, so it used to be recommended to unpack MIME attachments in the | |
28507 | MIME ACL. This no longer believed to be necessary. One option is required: | |
28508 | either the path and name of a UNIX socket file, or a hostname or IP number, and | |
28509 | a port, separated by space, as in the second of these examples: | |
168e428f PH |
28510 | |
28511 | av_scanner = clamd:/opt/clamd/socket | |
28512 | av_scanner = clamd:192.168.2.100 1234 | |
28513 | + | |
28514 | If the option is unset, the default is _/tmp/clamd_. Thanks to David Saez for | |
28515 | contributing the code for this scanner. | |
28516 | ||
28517 | %cmdline%:: | |
28518 | cindex:[virus scanners,command line interface] | |
28519 | This is the keyword for the generic command line scanner interface. It can be | |
28520 | used to attach virus scanners that are invoked from the shell. This scanner | |
28521 | type takes 3 mandatory options: | |
28522 | + | |
28523 | -- | |
28524 | . The full path and name of the scanner binary, with all command line options, | |
28525 | and a placeholder (%s) for the directory to scan. | |
28526 | ||
28527 | . A regular expression to match against the STDOUT and STDERR output of the | |
28528 | virus scanner. If the expression matches, a virus was found. You must make | |
28529 | absolutely sure that this expression matches on ``virus found''. This is called | |
28530 | the ``trigger'' expression. | |
28531 | ||
28532 | . Another regular expression, containing exactly one pair of parentheses, to | |
28533 | match the name of the virus found in the scanners output. This is called the | |
28534 | ``name'' expression. | |
28535 | -- | |
28536 | + | |
28537 | For example, Sophos Sweep reports a virus on a line like this: | |
28538 | ||
28539 | Virus 'W32/Magistr-B' found in file ./those.bat | |
28540 | + | |
28541 | For the trigger expression, we can just match the word ``found''. For the name | |
28542 | expression, we want to extract the W32/Magistr-B string, so we can match for | |
28543 | the single quotes left and right of it. Altogether, this makes the | |
28544 | configuration setting: | |
28545 | + | |
28546 | .... | |
28547 | av_scanner = cmdline:\ | |
28548 | /path/to/sweep -all -rec -archive %s:\ | |
28549 | found:'(.+)' | |
28550 | .... | |
28551 | ||
28552 | ||
28553 | %drweb%:: | |
28554 | cindex:[virus scanners,DrWeb] | |
28555 | The DrWeb daemon scanner (*http://www.sald.com/[]*) interface takes one | |
28556 | argument, either a full path to a UNIX socket, or an IP address and port | |
068aaea8 | 28557 | separated by white space, as in these examples: |
168e428f PH |
28558 | |
28559 | av_scanner = drweb:/var/run/drwebd.sock | |
28560 | av_scanner = drweb:192.168.2.20 31337 | |
28561 | + | |
28562 | If you omit the argument, the default path _/usr/local/drweb/run/drwebd.sock_ | |
28563 | is used. Thanks to Alex Miller for contributing the code for this scanner. | |
28564 | ||
28565 | %fsecure%:: | |
28566 | cindex:[virus scanners,F-Secure] | |
28567 | The F-Secure daemon scanner (*http://www.f-secure.com[]*) takes one argument | |
28568 | which is the path to a UNIX socket. For example: | |
28569 | ||
28570 | av_scanner = fsecure:/path/to/.fsav | |
28571 | + | |
28572 | If no argument is given, the default is _/var/run/.fsav_. Thanks to Johan | |
28573 | Thelmen for contributing the code for this scanner. | |
28574 | ||
28575 | %kavdaemon%:: | |
28576 | cindex:[virus scanners,Kaspersky] | |
28577 | This is the scanner daemon of Kaspersky Version 4. This version of the | |
28578 | Kaspersky scanner is outdated. Please upgrade (see %aveserver% above). This | |
28579 | scanner type takes one option, which is the path to the daemon's UNIX socket. | |
28580 | For example: | |
28581 | ||
28582 | av_scanner = kavdaemon:/opt/AVP/AvpCtl | |
28583 | + | |
28584 | The default path is _/var/run/AvpCtl_. | |
28585 | ||
28586 | %mksd%:: | |
28587 | cindex:[virus scanners,mksd] | |
28588 | This is a daemon type scanner that is aimed mainly at Polish users, though some | |
28589 | parts of documentation are now available in English. You can get it at | |
28590 | *http://linux.mks.com.pl/[]*. The only option for this scanner type is the | |
28591 | maximum number of processes used simultaneously to scan the attachments, | |
28592 | provided that the demime facility is employed and also provided that mksd has | |
28593 | been run with at least the same number of child processes. For example: | |
28594 | ||
28595 | av_scanner = mksd:2 | |
28596 | + | |
28597 | You can safely omit this option (the default value is 1). | |
28598 | ||
28599 | %sophie%:: | |
28600 | cindex:[virus scanners,Sophos and Sophie] | |
28601 | Sophie is a daemon that uses Sophos' %libsavi% library to scan for viruses. You | |
28602 | can get Sophie at *http://www.vanja.com/tools/sophie/[]*. The only option for | |
28603 | this scanner type is the path to the UNIX socket that Sophie uses for client | |
28604 | communication. For example: | |
28605 | ||
28606 | av_scanner = sophie:/tmp/sophie | |
28607 | + | |
28608 | The default path is _/var/run/sophie_, so if you are using this, you can omit | |
28609 | the option. | |
28610 | ||
28611 | /// | |
28612 | End of list | |
28613 | /// | |
28614 | ||
068aaea8 | 28615 | [revisionflag="changed"] |
168e428f | 28616 | When %av_scanner% is correctly set, you can use the %malware% condition in the |
068aaea8 PH |
28617 | DATA ACL. *Note*: you cannot use the %malware% condition in the MIME ACL. |
28618 | ||
28619 | The %av_scanner% option is expanded each time %malware% is called. This makes | |
28620 | it possible to use different scanners. See further below for an example. The | |
28621 | %malware% condition caches its results, so when you use it multiple times for | |
28622 | the same message, the actual scanning process is only carried out once. | |
28623 | However, using expandable items in %av_scanner% disables this caching, in which | |
28624 | case each use of the %malware% condition causes a new scan of the message. | |
168e428f PH |
28625 | |
28626 | The %malware% condition takes a right-hand argument that is expanded before | |
28627 | use. It can then be one of | |
28628 | ||
28629 | - ``true'', ``\*'', or ``1'', in which case the message is scanned for viruses. | |
28630 | The condition succeeds if a virus was found, and fail otherwise. This is the | |
28631 | recommended usage. | |
28632 | ||
28633 | - ``false'' or ``0'', in which case no scanning is done and the condition fails | |
28634 | immediately. | |
28635 | ||
28636 | - A regular expression, in which case the message is scanned for viruses. The | |
28637 | condition succeeds if a virus is found and its name matches the regular | |
28638 | expression. This allows you to take special actions on certain types of virus. | |
28639 | ||
28640 | You can append `/defer_ok` to the %malware% condition to accept messages even | |
28641 | if there is a problem with the virus scanner. | |
28642 | ||
28643 | cindex:[$malware_name$] | |
28644 | When a virus is found, the condition sets up an expansion variable called | |
28645 | $malware_name$ that contains the name of the virus. You can use it in a | |
28646 | %message% modifier that specifies the error returned to the sender, and/or in | |
28647 | logging data. | |
28648 | ||
28649 | If your virus scanner cannot unpack MIME and TNEF containers itself, you should | |
28650 | use the %demime% condition (see section <<SECTdemimecond>>) before the %malware% | |
28651 | condition. | |
28652 | ||
28653 | Here is a very simple scanning example: | |
28654 | ||
28655 | deny message = This message contains malware ($malware_name) | |
28656 | demime = * | |
28657 | malware = * | |
28658 | ||
28659 | The next example accepts messages when there is a problem with the scanner: | |
28660 | ||
28661 | deny message = This message contains malware ($malware_name) | |
28662 | demime = * | |
28663 | malware = */defer_ok | |
28664 | ||
28665 | The next example shows how to use an ACL variable to scan with both sophie and | |
28666 | aveserver. It assumes you have set: | |
28667 | ||
28668 | av_scanner = $acl_m0 | |
28669 | ||
28670 | in the main Exim configuration. | |
28671 | ||
28672 | deny message = This message contains malware ($malware_name) | |
28673 | set acl_m0 = sophie | |
28674 | malware = * | |
28675 | ||
28676 | deny message = This message contains malware ($malware_name) | |
28677 | set acl_m0 = aveserver | |
28678 | malware = * | |
28679 | ||
28680 | ||
28681 | ||
28682 | ||
28683 | [[SECTscanspamass]] | |
28684 | Scanning with SpamAssassin | |
28685 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
28686 | cindex:[content scanning,for spam] | |
28687 | cindex:[spam scanning] | |
28688 | cindex:[SpamAssassin, scanning with] | |
28689 | The %spam% ACL condition calls SpamAssassin's %spamd% daemon to get a spam | |
28690 | score and a report for the message. You can get SpamAssassin at | |
28691 | *http://www.spamassassin.org[]*, or, if you have a working Perl installation, | |
28692 | you can use CPAN by running: | |
28693 | ||
28694 | perl -MCPAN -e 'install Mail::SpamAssassin' | |
28695 | ||
28696 | SpamAssassin has its own set of configuration files. Please review its | |
28697 | documentation to see how you can tweak it. The default installation should work | |
28698 | nicely, however. | |
28699 | ||
28700 | cindex:[%spamd_address%] | |
28701 | After having installed and configured SpamAssassin, start the %spamd% daemon. | |
28702 | By default, it listens on 127.0.0.1, TCP port 783. If you use another host or | |
28703 | port for %spamd%, you must set the %spamd_address% option in the global part | |
28704 | of the Exim configuration as follows (example): | |
28705 | ||
28706 | spamd_address = 192.168.99.45 387 | |
28707 | ||
28708 | You do not need to set this option if you use the default. As of version 2.60, | |
28709 | %spamd% also supports communication over UNIX sockets. If you want to use | |
28710 | these, supply %spamd_address% with an absolute file name instead of a | |
28711 | address/port pair: | |
28712 | ||
28713 | spamd_address = /var/run/spamd_socket | |
28714 | ||
168e428f PH |
28715 | You can have multiple %spamd% servers to improve scalability. These can reside |
28716 | on other hardware reachable over the network. To specify multiple %spamd% | |
28717 | servers, put multiple address/port pairs in the %spamd_address% option, | |
28718 | separated with colons: | |
28719 | ||
28720 | .... | |
28721 | spamd_address = 192.168.2.10 783 : \ | |
28722 | 192.168.2.11 783 : \ | |
28723 | 192.168.2.12 783 | |
28724 | .... | |
28725 | ||
068aaea8 PH |
28726 | Up to 32 %spamd% servers are supported. The servers are queried in a random |
28727 | fashion. When a server fails to respond to the connection attempt, all other | |
28728 | servers are tried until one succeeds. If no server responds, the %spam% | |
168e428f PH |
28729 | condition defers. |
28730 | ||
28731 | *Warning*: It is not possible to use the UNIX socket connection method with | |
28732 | multiple %spamd% servers. | |
28733 | ||
068aaea8 PH |
28734 | |
28735 | Calling SpamAssassin from an Exim ACL | |
28736 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
168e428f PH |
28737 | Here is a simple example of the use of the %spam% condition in a DATA ACL: |
28738 | ||
28739 | deny message = This message was classified as SPAM | |
28740 | spam = joe | |
28741 | ||
28742 | The right-hand side of the %spam% condition specifies the username that | |
28743 | SpamAssassin should scan for. If you do not want to scan for a particular user, | |
28744 | but rather use the SpamAssassin system-wide default profile, you can scan for | |
068aaea8 PH |
28745 | an unknown user, or simply use ``nobody''. However, you must put something on |
28746 | the right-hand side. | |
168e428f PH |
28747 | |
28748 | The username allows you to use per-domain or per-user antispam profiles. The | |
28749 | right-hand side is expanded before being used, so you can put lookups or | |
28750 | conditions there. When the right-hand side evaluates to ``0'' or ``false'', no | |
28751 | scanning is done and the condition fails immediately. | |
28752 | ||
068aaea8 PH |
28753 | [revisionflag="changed"] |
28754 | Scanning with SpamAssassin uses a lot of resources. If you scan every message, | |
28755 | large ones may cause significant performance degredation. As most spam messages | |
28756 | are quite small, it is recommended that you do not scan the big ones. For | |
28757 | example: | |
28758 | ||
28759 | [revisionflag="changed"] | |
28760 | .... | |
28761 | deny message = This message was classified as SPAM | |
28762 | condition = ${if < {$message_size}{10K}} | |
28763 | spam = nobody | |
28764 | .... | |
28765 | ||
168e428f PH |
28766 | The %spam% condition returns true if the threshold specified in the user's |
28767 | SpamAssassin profile has been matched or exceeded. If you want to use the | |
28768 | %spam% condition for its side effects (see the variables below), you can make | |
28769 | it always return ``true'' by appending `:true` to the username. | |
28770 | ||
28771 | cindex:[spam scanning,returned variables] | |
28772 | When the %spam% condition is run, it sets up the following expansion | |
28773 | variables: | |
28774 | ||
28775 | $spam_score$:: | |
28776 | The spam score of the message, for example ``3.4'' or ``30.5''. This is useful | |
28777 | for inclusion in log or reject messages. | |
28778 | ||
28779 | $spam_score_int$:: | |
28780 | The spam score of the message, multiplied by ten, as an integer value. For | |
28781 | example ``34'' or ``305''. This is useful for numeric comparisons in | |
28782 | conditions. This variable is special; it is saved with the message, and written | |
28783 | to Exim's spool file. This means that it can be used during the whole life of | |
28784 | the message on your Exim system, in particular, in routers or transports during | |
28785 | the later delivery phase. | |
28786 | ||
28787 | $spam_bar$:: | |
28788 | A string consisting of a number of ``+'' or ``-'' characters, representing the | |
28789 | integer part of the spam score value. A spam score of 4.4 would have a | |
28790 | $spam_bar$ value of ``++++''. This is useful for inclusion in warning headers, | |
28791 | since MUAs can match on such strings. | |
28792 | ||
28793 | $spam_report$:: | |
28794 | A multiline text table, containing the full SpamAssassin report for the | |
28795 | message. Useful for inclusion in headers or reject messages. | |
28796 | ||
28797 | /// | |
28798 | End of list | |
28799 | /// | |
28800 | ||
28801 | The %spam% condition caches its results. If you call it again with the same | |
28802 | user name, it does not scan again, but rather returns the same values as | |
28803 | before. | |
28804 | ||
28805 | The %spam% condition returns DEFER if there is any error while running the | |
28806 | message through SpamAssassin. If you want to treat DEFER as FAIL (to pass on to | |
28807 | the next ACL statement block), append `/defer_ok` to the right-hand side of | |
28808 | the spam condition, like this: | |
28809 | ||
28810 | deny message = This message was classified as SPAM | |
28811 | spam = joe/defer_ok | |
28812 | ||
28813 | This causes messages to be accepted even if there is a | |
28814 | problem with %spamd%. | |
28815 | ||
28816 | Here is a longer, commented example of the use of the %spam% | |
28817 | condition: | |
28818 | ||
28819 | # put headers in all messages (no matter if spam or not) | |
28820 | warn message = X-Spam-Score: $spam_score ($spam_bar) | |
28821 | spam = nobody:true | |
28822 | warn message = X-Spam-Report: $spam_report | |
28823 | spam = nobody:true | |
28824 | ||
28825 | # add second subject line with *SPAM* marker when message | |
28826 | # is over threshold | |
28827 | warn message = Subject: *SPAM* $h_Subject: | |
28828 | spam = nobody | |
28829 | ||
28830 | # reject spam at high scores (> 12) | |
28831 | deny message = This message scored $spam_score spam points. | |
28832 | spam = nobody:true | |
28833 | condition = ${if >{$spam_score_int}{120}{1}{0}} | |
28834 | ||
28835 | ||
28836 | ||
28837 | ||
28838 | ||
28839 | [[SECTscanmimepart]] | |
28840 | Scanning MIME parts | |
28841 | ~~~~~~~~~~~~~~~~~~~ | |
068aaea8 | 28842 | [revisionflag="changed"] |
168e428f PH |
28843 | cindex:[content scanning,MIME parts] |
28844 | cindex:[MIME content scanning] | |
28845 | cindex:[%acl_smtp_mime%] | |
068aaea8 PH |
28846 | The %acl_smtp_mime% global option specifies an ACL that is called once for each |
28847 | MIME part of an SMTP message, including multipart types, in the sequence of | |
28848 | their position in the message. Similarly, the %acl_not_smtp_mime% option | |
28849 | specifies an ACL that is used for the MIME parts of non-SMTP messages. These | |
28850 | options may both refer to the same ACL if you want the same processing in both | |
28851 | cases. | |
28852 | ||
28853 | [revisionflag="changed"] | |
28854 | These ACLs are called (possibly many times) just before the %acl_smtp_data% ACL | |
28855 | in the case of an SMTP message, or just before a non-SMTP message is accepted. | |
28856 | However, a MIME ACL is called only if the message contains a 'MIME-Version:' | |
28857 | header line. When a call to a MIME ACL does not yield ``accept'', ACL | |
28858 | processing is aborted and the appropriate result code is sent to the client. In | |
28859 | the case of an SMTP message, the %acl_smtp_data% ACL is not called when this | |
28860 | happens. | |
168e428f | 28861 | |
068aaea8 PH |
28862 | [revisionflag="changed"] |
28863 | You cannot use the %malware% or %spam% conditions in a MIME ACL; these can only | |
28864 | be used in the DATA or non-SMTP ACLs. However, you can use the %regex% | |
28865 | condition to match against the raw MIME part. You can also use the %mime_regex% | |
28866 | condition to match against the decoded MIME part (see section | |
28867 | <<SECTscanregex>>). | |
168e428f | 28868 | |
068aaea8 | 28869 | At the start of a MIME ACL, a number of variables are set from the header |
168e428f PH |
28870 | information for the relevant MIME part. These are described below. The contents |
28871 | of the MIME part are not by default decoded into a disk file except for MIME | |
068aaea8 PH |
28872 | parts whose content-type is ``message/rfc822''. If you want to decode a MIME |
28873 | part into a disk file, you can use the %decode% modifier. The general syntax | |
28874 | is: | |
168e428f PH |
28875 | |
28876 | decode = [/<path>/]<filename> | |
28877 | ||
28878 | The right hand side is expanded before use. After expansion, | |
28879 | the value can be: | |
28880 | ||
28881 | . ``0'' or ``false'', in which case no decoding is done. | |
28882 | ||
28883 | . The string ``default''. In that case, the file is put in the temporary | |
28884 | ``default'' directory <'spool_directory'>_/scan/_<'message_id'>_/_ with a | |
28885 | sequential file name consisting of the message id and a sequence number. The | |
28886 | full path and name is available in $mime_decoded_filename$ after decoding. | |
28887 | ||
28888 | . A full path name starting with a slash. If the full name is an existing | |
28889 | directory, it is used as a replacement for the default directory. The filename | |
28890 | is then sequentially assigned. If the path does not exist, it is used as | |
28891 | the full path and file name. | |
28892 | ||
28893 | . If the string does not start with a slash, it is used as the | |
28894 | filename, and the default path is then used. | |
28895 | ||
28896 | /// | |
28897 | End of list | |
28898 | /// | |
28899 | ||
28900 | You can easily decode a file with its original, proposed filename using | |
28901 | ||
28902 | decode = $mime_filename | |
28903 | ||
28904 | However, you should keep in mind that $mime_filename$ might contain | |
28905 | anything. If you place files outside of the default path, they are not | |
28906 | automatically unlinked. | |
28907 | ||
28908 | For RFC822 attachments (these are messages attached to messages, with a | |
28909 | content-type of ``message/rfc822''), the ACL is called again in the same manner | |
28910 | as for the primary message, only that the $mime_is_rfc822$ expansion | |
28911 | variable is set (see below). Attached messages are always decoded to disk | |
28912 | before being checked, and the files are unlinked once the check is done. | |
28913 | ||
28914 | The MIME ACL supports the %regex% and %mime_regex% conditions. These can be | |
28915 | used to match regular expressions against raw and decoded MIME parts, | |
28916 | respectively. They are described in section <<SECTscanregex>>. | |
28917 | ||
28918 | cindex:[MIME content scanning,returned variables] | |
28919 | The following list describes all expansion variables that are | |
28920 | available in the MIME ACL: | |
28921 | ||
28922 | $mime_boundary$:: | |
28923 | If the current part is a multipart (see $mime_is_multipart$) below, it should | |
28924 | have a boundary string, which is stored in this variable. If the current part | |
28925 | has no boundary parameter in the 'Content-Type:' header, this variable contains | |
28926 | the empty string. | |
28927 | ||
28928 | $mime_charset$:: | |
28929 | This variable contains the character set identifier, if one was found in the | |
28930 | 'Content-Type:' header. Examples for charset identifiers are: | |
28931 | ||
28932 | us-ascii | |
28933 | gb2312 (Chinese) | |
28934 | iso-8859-1 | |
28935 | + | |
28936 | Please note that this value is not normalized, so you should do matches | |
28937 | case-insensitively. | |
28938 | ||
28939 | $mime_content_description$:: | |
28940 | This variable contains the normalized content of the 'Content-Description:' | |
28941 | header. It can contain a human-readable description of the parts content. Some | |
28942 | implementations repeat the filename for attachments here, but they are usually | |
28943 | only used for display purposes. | |
28944 | ||
28945 | $mime_content_disposition$:: | |
28946 | This variable contains the normalized content of the 'Content-Disposition:' | |
28947 | header. You can expect strings like ``attachment'' or ``inline'' here. | |
28948 | ||
28949 | $mime_content_id$:: | |
28950 | This variable contains the normalized content of the 'Content-ID:' header. | |
28951 | This is a unique ID that can be used to reference a part from another part. | |
28952 | ||
28953 | $mime_content_size$:: | |
28954 | This variable is set only after the %decode% modifier (see above) has been | |
28955 | successfully run. It contains the size of the decoded part in kilobytes. The | |
28956 | size is always rounded up to full kilobytes, so only a completely empty part | |
28957 | has a $mime_content_size$ of zero. | |
28958 | ||
28959 | $mime_content_transfer_encoding$:: | |
28960 | This variable contains the normalized content of the | |
28961 | 'Content-transfer-encoding:' header. This is a symbolic name for an encoding | |
28962 | type. Typical values are ``base64'' and ``quoted-printable''. | |
28963 | ||
28964 | $mime_content_type$:: | |
28965 | If the MIME part has a 'Content-Type:' header, this variable contains its | |
28966 | value, lowercased, and without any options (like ``name'' or ``charset''). Here | |
28967 | are some examples of popular MIME types, as they may appear in this variable: | |
28968 | ||
28969 | text/plain | |
28970 | text/html | |
28971 | application/octet-stream | |
28972 | image/jpeg | |
28973 | audio/midi | |
28974 | + | |
28975 | If the MIME part has no 'Content-Type:' header, this variable contains the | |
28976 | empty string. | |
28977 | ||
28978 | $mime_decoded_filename$:: | |
28979 | This variable is set only after the %decode% modifier (see above) has been | |
28980 | successfully run. It contains the full path and file name of the file | |
28981 | containing the decoded data. | |
28982 | ||
d1e83bff | 28983 | cindex:[RFC 2047] |
168e428f PH |
28984 | $mime_filename$:: |
28985 | This is perhaps the most important of the MIME variables. It contains a | |
28986 | proposed filename for an attachment, if one was found in either the | |
28987 | 'Content-Type:' or 'Content-Disposition:' headers. The filename will be RFC2047 | |
28988 | decoded, but no additional sanity checks are done. If no filename was found, | |
28989 | this variable contains the empty string. | |
28990 | ||
28991 | $mime_is_coverletter$:: | |
28992 | This variable attempts to differentiate the ``cover letter'' of an e-mail from | |
28993 | attached data. It can be used to clamp down on flashy or unneccessarily encoded | |
28994 | content in the cover letter, while not restricting attachments at all. | |
28995 | + | |
28996 | The variable contains 1 (true) for a MIME part believed to be part of the | |
28997 | cover letter, and 0 (false) for an attachment. At present, the algorithm is as | |
28998 | follows: | |
28999 | + | |
29000 | -- | |
29001 | . The outermost MIME part of a message is always a cover letter. | |
29002 | ||
d1e83bff PH |
29003 | . If a multipart/alternative or multipart/related MIME part is a cover letter, |
29004 | so are all MIME subparts within that multipart. | |
168e428f PH |
29005 | |
29006 | . If any other multipart is a cover letter, the first subpart is a cover letter, | |
29007 | and the rest are attachments. | |
29008 | ||
29009 | . All parts contained within an attachment multipart are attachments. | |
29010 | -- | |
29011 | + | |
29012 | As an example, the following will ban ``HTML mail'' (including that sent with | |
29013 | alternative plain text), while allowing HTML files to be attached. HTML | |
29014 | coverletter mail attached to non-HMTL coverletter mail will also be allowed: | |
29015 | ||
29016 | deny message = HTML mail is not accepted here | |
29017 | !condition = $mime_is_rfc822 | |
29018 | condition = $mime_is_coverletter | |
29019 | condition = ${if eq{$mime_content_type}{text/html}{1}{0}} | |
29020 | ||
29021 | $mime_is_multipart$:: | |
29022 | This variable has the value 1 (true) when the current part has the main type | |
29023 | ``multipart'', for example ``multipart/alternative'' or ``multipart/mixed''. | |
29024 | Since multipart entities only serve as containers for other parts, you may not | |
29025 | want to carry out specific actions on them. | |
29026 | ||
29027 | $mime_is_rfc822$:: | |
29028 | This variable has the value 1 (true) if the current part is not a part of the | |
29029 | checked message itself, but part of an attached message. Attached message | |
29030 | decoding is fully recursive. | |
29031 | ||
29032 | $mime_part_count$:: | |
29033 | This variable is a counter that is raised for each processed MIME part. It | |
29034 | starts at zero for the very first part (which is usually a multipart). The | |
29035 | counter is per-message, so it is reset when processing RFC822 attachments (see | |
29036 | $mime_is_rfc822$). The counter stays set after %acl_smtp_mime% is | |
29037 | complete, so you can use it in the DATA ACL to determine the number of MIME | |
29038 | parts of a message. For non-MIME messages, this variable contains the value -1. | |
29039 | ||
29040 | ||
29041 | ||
29042 | [[SECTscanregex]] | |
29043 | Scanning with regular expressions | |
29044 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
29045 | cindex:[content scanning,with regular expressions] | |
29046 | cindex:[regular expressions,content scanning with] | |
29047 | You can specify your own custom regular expression matches on the full body of | |
29048 | the message, or on individual MIME parts. | |
29049 | ||
29050 | The %regex% condition takes one or more regular expressions as arguments and | |
29051 | matches them against the full message (when called in the DATA ACL) or a raw | |
29052 | MIME part (when called in the MIME ACL). The %regex% condition matches | |
29053 | linewise, with a maximum line length of 32K characters. That means you cannot | |
29054 | have multiline matches with the %regex% condition. | |
29055 | ||
29056 | The %mime_regex% condition can be called only in the MIME ACL. It matches up | |
29057 | to 32K of decoded content (the whole content at once, not linewise). If the | |
29058 | part has not been decoded with the %decode% modifier earlier in the ACL, it is | |
29059 | decoded automatically when %mime_regex% is executed (using default path and | |
29060 | filename values). If the decoded data is larger than 32K, only the first 32K | |
29061 | characters are checked. | |
29062 | ||
29063 | The regular expressions are passed as a colon-separated list. To include a | |
29064 | literal colon, you must double it. Since the whole right-hand side string is | |
29065 | expanded before being used, you must also escape dollar signs and backslashes | |
29066 | with more backslashes, or use the `\N` facility to disable expansion. | |
29067 | Here is a simple example that contains two regular expressions: | |
29068 | ||
29069 | deny message = contains blacklisted regex ($regex_match_string) | |
29070 | regex = [Mm]ortgage : URGENT BUSINESS PROPOSAL | |
29071 | ||
29072 | The conditions returns true if any one of the regular expressions matches. The | |
29073 | $regex_match_string$ expansion variable is then set up and contains the | |
29074 | matching regular expression. | |
29075 | ||
29076 | *Warning*: With large messages, these conditions can be fairly | |
29077 | CPU-intensive. | |
29078 | ||
29079 | ||
29080 | ||
29081 | ||
29082 | [[SECTdemimecond]] | |
29083 | The demime condition | |
29084 | ~~~~~~~~~~~~~~~~~~~~ | |
29085 | cindex:[content scanning,MIME checking] | |
29086 | cindex:[MIME content scanning] | |
29087 | The %demime% ACL condition provides MIME unpacking, sanity checking and file | |
068aaea8 PH |
29088 | extension blocking. It is usable only in the DATA and non-SMTP ACLs. The |
29089 | %demime% condition uses a simpler interface to MIME decoding than the MIME ACL | |
29090 | functionality, but provides no additional facilities. Please note that this | |
29091 | condition is deprecated and kept only for backward compatibility. You must set | |
29092 | the WITH_OLD_DEMIME option in _Local/Makefile_ at build time to be able to use | |
29093 | the %demime% condition. | |
168e428f PH |
29094 | |
29095 | The %demime% condition unpacks MIME containers in the message. It detects | |
29096 | errors in MIME containers and can match file extensions found in the message | |
29097 | against a list. Using this facility produces files containing the unpacked MIME | |
29098 | parts of the message in the temporary scan directory. If you do antivirus | |
29099 | scanning, it is recommened that you use the %demime% condition before the | |
29100 | antivirus (%malware%) condition. | |
29101 | ||
29102 | On the right-hand side of the %demime% condition you can pass a colon-separated | |
29103 | list of file extensions that it should match against. For example: | |
29104 | ||
29105 | deny message = Found blacklisted file attachment | |
29106 | demime = vbs:com:bat:pif:prf:lnk | |
29107 | ||
29108 | If one of the file extensions is found, the condition is true, otherwise it is | |
29109 | false. If there is a temporary error while demimeing (for example, ``disk | |
29110 | full''), the condition defers, and the message is temporarily rejected (unless | |
29111 | the condition is on a %warn% verb). | |
29112 | ||
29113 | The right-hand side is expanded before being treated as a list, so you can have | |
29114 | conditions and lookups there. If it expands to an empty string, ``false'', or | |
29115 | zero (``0''), no demimeing is done and the condition is false. | |
29116 | ||
29117 | The %demime% condition set the following variables: | |
29118 | ||
29119 | $demime_errorlevel$:: | |
068aaea8 | 29120 | cindex:[$demime_errorlevel$] |
168e428f PH |
29121 | When an error is detected in a MIME container, this variable contains the |
29122 | severity of the error, as an integer number. The higher the value, the more | |
068aaea8 PH |
29123 | severe the error (the current maximum value is 3). If this variable is unset or |
29124 | zero, no error occurred. | |
168e428f PH |
29125 | |
29126 | $demime_reason$:: | |
068aaea8 | 29127 | cindex:[$demime_reason$] |
168e428f PH |
29128 | When $demime_errorlevel$ is greater than zero, this variable contains a |
29129 | human-readable text string describing the MIME error that occurred. | |
29130 | ||
068aaea8 | 29131 | cindex:[$found_extension$] |
168e428f PH |
29132 | $found_extension$:: |
29133 | When the %demime% condition is true, this variable contains the file extension | |
29134 | it found. | |
29135 | ||
29136 | /// | |
29137 | End of list | |
29138 | /// | |
29139 | ||
29140 | Both $demime_errorlevel$ and $demime_reason$ are set by the first call of | |
29141 | the %demime% condition, and are not changed on subsequent calls. | |
29142 | ||
29143 | If you do not want to check for file extensions, but rather use the %demime% | |
29144 | condition for unpacking or error checking purposes, pass ``\*'' as the | |
29145 | right-hand side value. Here is a more elaborate example of how to use this | |
29146 | facility: | |
29147 | ||
29148 | # Reject messages with serious MIME container errors | |
29149 | deny message = Found MIME error ($demime_reason). | |
29150 | demime = * | |
29151 | condition = ${if >{$demime_errorlevel}{2}{1}{0}} | |
29152 | ||
29153 | # Reject known virus spreading file extensions. | |
29154 | # Accepting these is pretty much braindead. | |
29155 | deny message = contains $found_extension file (blacklisted). | |
29156 | demime = com:vbs:bat:pif:scr | |
29157 | ||
29158 | # Freeze .exe and .doc files. Postmaster can | |
29159 | # examine them and eventually thaw them. | |
29160 | deny log_message = Another $found_extension file. | |
29161 | demime = exe:doc | |
29162 | control = freeze | |
29163 | ||
29164 | ||
29165 | ||
29166 | ||
29167 | ||
29168 | ||
29169 | //////////////////////////////////////////////////////////////////////////// | |
29170 | //////////////////////////////////////////////////////////////////////////// | |
29171 | ||
29172 | [[CHAPlocalscan]] | |
29173 | [titleabbrev="Local scan function"] | |
29174 | Adding a local scan function to Exim | |
29175 | ------------------------------------ | |
29176 | cindex:['local_scan()' function,description of] | |
29177 | cindex:[customizing,input scan using C function] | |
29178 | cindex:[policy control,by local scan function] | |
29179 | In these days of email worms, viruses, and ever-increasing spam, some sites | |
29180 | want to apply a lot of checking to messages before accepting them. | |
29181 | ||
29182 | The content scanning extension (chapter <<CHAPexiscan>>) has facilities for | |
29183 | passing messages to external virus and spam scanning software. You can also do | |
29184 | ||
29185 | a certain amount in Exim itself through string expansions and the %condition% | |
29186 | condition in the ACL that runs after the SMTP DATA command or the ACL for | |
29187 | non-SMTP messages (see chapter <<CHAPACL>>), but this has its limitations. | |
29188 | ||
29189 | To allow for further customization to a site's own requirements, there is the | |
29190 | possibility of linking Exim with a private message scanning function, written | |
29191 | in C. If you want to run code that is written in something other than C, you | |
29192 | can of course use a little C stub to call it. | |
29193 | ||
29194 | The local scan function is run once for every incoming message, at the point | |
29195 | when Exim is just about to accept the message. | |
29196 | It can therefore be used to control non-SMTP messages from local processes as | |
29197 | well as messages arriving via SMTP. | |
29198 | ||
29199 | Exim applies a timeout to calls of the local scan function, and there is an | |
29200 | option called %local_scan_timeout% for setting it. The default is 5 minutes. | |
29201 | Zero means ``no timeout''. | |
29202 | Exim also sets up signal handlers for SIGSEGV, SIGILL, SIGFPE, and SIGBUS | |
29203 | before calling the local scan function, so that the most common types of crash | |
29204 | are caught. If the timeout is exceeded or one of those signals is caught, the | |
29205 | incoming message is rejected with a temporary error if it is an SMTP message. | |
29206 | For a non-SMTP message, the message is dropped and Exim ends with a non-zero | |
29207 | code. The incident is logged on the main and reject logs. | |
29208 | ||
29209 | ||
29210 | ||
29211 | Building Exim to use a local scan function | |
29212 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
29213 | cindex:['local_scan()' function,building Exim to use] | |
29214 | To make use of the local scan function feature, you must tell Exim where your | |
29215 | function is before building Exim, by setting LOCAL_SCAN_SOURCE in your | |
29216 | _Local/Makefile_. A recommended place to put it is in the _Local_ | |
29217 | directory, so you might set | |
29218 | ||
29219 | LOCAL_SCAN_SOURCE=Local/local_scan.c | |
29220 | ||
29221 | for example. The function must be called 'local_scan()'. It is called by | |
29222 | Exim after it has received a message, when the success return code is about to | |
29223 | be sent. This is after all the ACLs have been run. The return code from your | |
29224 | function controls whether the message is actually accepted or not. There is a | |
29225 | commented template function (that just accepts the message) in the file | |
29226 | _src/local_scan.c_. | |
29227 | ||
29228 | If you want to make use of Exim's run time configuration file to set options | |
29229 | for your 'local_scan()' function, you must also set | |
29230 | ||
29231 | LOCAL_SCAN_HAS_OPTIONS=yes | |
29232 | ||
29233 | in _Local/Makefile_ (see section <<SECTconoptloc>> below). | |
29234 | ||
29235 | ||
29236 | ||
29237 | ||
29238 | [[SECTapiforloc]] | |
29239 | API for local_scan() | |
29240 | ~~~~~~~~~~~~~~~~~~~~ | |
29241 | cindex:['local_scan()' function,API description] | |
29242 | You must include this line near the start of your code: | |
29243 | ||
29244 | #include "local_scan.h" | |
29245 | ||
29246 | This header file defines a number of variables and other values, and the | |
29247 | prototype for the function itself. Exim is coded to use unsigned char values | |
29248 | almost exclusively, and one of the things this header defines is a shorthand | |
29249 | for `unsigned char` called `uschar`. | |
29250 | It also contains the following macro definitions, to simplify casting character | |
29251 | strings and pointers to character strings: | |
29252 | ||
29253 | #define CS (char *) | |
29254 | #define CCS (const char *) | |
29255 | #define CSS (char **) | |
29256 | #define US (unsigned char *) | |
29257 | #define CUS (const unsigned char *) | |
29258 | #define USS (unsigned char **) | |
29259 | ||
29260 | ||
29261 | The function prototype for 'local_scan()' is: | |
29262 | ||
29263 | extern int local_scan(int fd, uschar **return_text); | |
29264 | ||
29265 | The arguments are as follows: | |
29266 | ||
29267 | - %fd% is a file descriptor for the file that contains the body of the message | |
29268 | (the -D file). The file is open for reading and writing, but updating it is not | |
29269 | recommended. *Warning*: You must 'not' close this file descriptor. | |
29270 | + | |
29271 | The descriptor is positioned at character 19 of the file, which is the first | |
29272 | character of the body itself, because the first 19 characters are the message | |
29273 | id followed by `-D` and a newline. If you rewind the file, you should use the | |
29274 | macro SPOOL_DATA_START_OFFSET to reset to the start of the data, just in | |
29275 | case this changes in some future version. | |
29276 | ||
29277 | - %return_text% is an address which you can use to return a pointer to a text | |
29278 | string at the end of the function. The value it points to on entry is NULL. | |
29279 | ||
29280 | The function must return an %int% value which is one of the following macros: | |
29281 | ||
29282 | `LOCAL_SCAN_ACCEPT`:: | |
068aaea8 | 29283 | cindex:[$local_scan_data$] |
168e428f PH |
29284 | The message is accepted. If you pass back a string of text, it is saved with |
29285 | the message, and made available in the variable $local_scan_data$. No | |
29286 | newlines are permitted (if there are any, they are turned into spaces) and the | |
29287 | maximum length of text is 1000 characters. | |
29288 | ||
29289 | `LOCAL_SCAN_ACCEPT_FREEZE`:: | |
29290 | This behaves as LOCAL_SCAN_ACCEPT, except that the accepted message is | |
29291 | queued without immediate delivery, and is frozen. | |
29292 | ||
29293 | `LOCAL_SCAN_ACCEPT_QUEUE`:: | |
29294 | This behaves as LOCAL_SCAN_ACCEPT, except that the accepted message is | |
29295 | queued without immediate delivery. | |
29296 | ||
29297 | `LOCAL_SCAN_REJECT`:: | |
29298 | The message is rejected; the returned text is used as an error message which is | |
29299 | passed back to the sender and which is also logged. Newlines are permitted -- | |
29300 | they cause a multiline response for SMTP rejections, but are converted to `\n` | |
29301 | in log lines. If no message is given, ``Administrative prohibition'' is used. | |
29302 | ||
29303 | `LOCAL_SCAN_TEMPREJECT`:: | |
29304 | The message is temporarily rejected; the returned text is used as an error | |
29305 | message as for LOCAL_SCAN_REJECT. If no message is given, ``Temporary local | |
29306 | problem'' is used. | |
29307 | ||
29308 | `LOCAL_SCAN_REJECT_NOLOGHDR`:: | |
29309 | This behaves as LOCAL_SCAN_REJECT, except that the header of the rejected | |
29310 | message is not written to the reject log. It has the effect of unsetting the | |
29311 | %rejected_header% log selector for just this rejection. If %rejected_header% | |
29312 | is already unset (see the discussion of the %log_selection% option in section | |
29313 | <<SECTlogselector>>), this code is the same as LOCAL_SCAN_REJECT. | |
29314 | ||
29315 | `LOCAL_SCAN_TEMPREJECT_NOLOGHDR`:: | |
29316 | This code is a variation of LOCAL_SCAN_TEMPREJECT in the same way that | |
29317 | LOCAL_SCAN_REJECT_NOLOGHDR is a variation of LOCAL_SCAN_REJECT. | |
29318 | ||
29319 | /// | |
29320 | End of list | |
29321 | /// | |
29322 | ||
29323 | If the message is not being received by interactive SMTP, rejections are | |
29324 | reported by writing to %stderr% or by sending an email, as configured by the | |
29325 | %-oe% command line options. | |
29326 | ||
29327 | ||
29328 | ||
29329 | [[SECTconoptloc]] | |
29330 | Configuration options for local_scan() | |
29331 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
29332 | cindex:['local_scan()' function,configuration options] | |
29333 | It is possible to have option settings in the main configuration file | |
29334 | that set values in static variables in the 'local_scan()' module. If you | |
29335 | want to do this, you must have the line | |
29336 | ||
29337 | LOCAL_SCAN_HAS_OPTIONS=yes | |
29338 | ||
29339 | in your _Local/Makefile_ when you build Exim. (This line is in | |
29340 | _OS/Makefile-Default_, commented out). Then, in the 'local_scan()' source | |
29341 | file, you must define static variables to hold the option values, and a table to | |
29342 | define them. | |
29343 | ||
29344 | The table must be a vector called %local_scan_options%, of type | |
29345 | `optionlist`. Each entry is a triplet, consisting of a name, an option type, | |
29346 | and a pointer to the variable that holds the value. The entries must appear in | |
29347 | alphabetical order. Following %local_scan_options% you must also define a | |
29348 | variable called %local_scan_options_count% that contains the number of | |
29349 | entries in the table. Here is a short example, showing two kinds of option: | |
29350 | ||
29351 | static int my_integer_option = 42; | |
29352 | static uschar *my_string_option = US"a default string"; | |
29353 | ||
29354 | optionlist local_scan_options[] = { | |
29355 | { "my_integer", opt_int, &my_integer_option }, | |
29356 | { "my_string", opt_stringptr, &my_string_option } | |
29357 | }; | |
29358 | int local_scan_options_count = | |
29359 | sizeof(local_scan_options)/sizeof(optionlist); | |
29360 | ||
29361 | The values of the variables can now be changed from Exim's runtime | |
29362 | configuration file by including a local scan section as in this example: | |
29363 | ||
29364 | begin local_scan | |
29365 | my_integer = 99 | |
29366 | my_string = some string of text... | |
29367 | ||
29368 | The available types of option data are as follows: | |
29369 | ||
29370 | *opt_bool*:: | |
29371 | This specifies a boolean (true/false) option. The address should point to a | |
29372 | variable of type `BOOL`, which will be set to TRUE or FALSE, which are macros | |
29373 | that are defined as ``1'' and ``0'', respectively. If you want to detect | |
29374 | whether such a variable has been set at all, you can initialize it to | |
29375 | TRUE_UNSET. (BOOL variables are integers underneath, so can hold more than two | |
29376 | values.) | |
29377 | ||
29378 | *opt_fixed*:: | |
29379 | This specifies a fixed point number, such as is used for load averages. | |
29380 | The address should point to a variable of type `int`. The value is stored | |
29381 | multiplied by 1000, so, for example, 1.4142 is truncated and stored as 1414. | |
29382 | ||
29383 | *opt_int*:: | |
29384 | This specifies an integer; the address should point to a variable of type | |
29385 | `int`. The value may be specified in any of the integer formats accepted by | |
29386 | Exim. | |
29387 | ||
29388 | *opt_mkint*:: | |
29389 | This is the same as %opt_int%, except that when such a value is output in a | |
29390 | %-bP% listing, if it is an exact number of kilobytes or megabytes, it is | |
29391 | printed with the suffix K or M. | |
29392 | ||
29393 | *opt_octint*:: | |
29394 | This also specifies an integer, but the value is always interpeted as an | |
29395 | octal integer, whether or not it starts with the digit zero, and it is | |
29396 | always output in octal. | |
29397 | ||
29398 | *opt_stringptr*:: | |
29399 | This specifies a string value; the address must be a pointer to a | |
29400 | variable that points to a string (for example, of type `uschar \*`). | |
29401 | ||
29402 | *opt_time*:: | |
29403 | This specifies a time interval value. The address must point to a variable of | |
29404 | type `int`. The value that is placed there is a number of seconds. | |
29405 | ||
29406 | /// | |
29407 | End of list | |
29408 | /// | |
29409 | ||
29410 | If the %-bP% command line option is followed by `local_scan`, Exim prints | |
29411 | out the values of all the 'local_scan()' options. | |
29412 | ||
29413 | ||
29414 | ||
29415 | Available Exim variables | |
29416 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
29417 | cindex:['local_scan()' function,available Exim variables] | |
29418 | The header _local_scan.h_ gives you access to a number of C variables. These | |
29419 | are the only ones that are guaranteed to be maintained from release to release. | |
29420 | Note, however, that you can obtain the value of any Exim variable by calling | |
29421 | 'expand_string()'. The exported variables are as follows: | |
29422 | ||
29423 | *unsigned~int~debug_selector*:: | |
29424 | This variable is set to zero when no debugging is taking place. Otherwise, it | |
29425 | is a bitmap of debugging selectors. Two bits are identified for use in | |
29426 | 'local_scan()'; they are defined as macros: | |
29427 | + | |
29428 | -- | |
29429 | - The `D_v` bit is set when %-v% was present on the command line. This is a | |
29430 | testing option that is not privileged -- any caller may set it. All the | |
29431 | other selector bits can be set only by admin users. | |
29432 | ||
29433 | - The `D_local_scan` bit is provided for use by 'local_scan()'; it is set | |
29434 | by the `+local_scan` debug selector. It is not included in the default set | |
29435 | of debugging bits. | |
29436 | -- | |
29437 | + | |
29438 | Thus, to write to the debugging output only when `+local_scan` has been | |
29439 | selected, you should use code like this: | |
29440 | ||
29441 | if ((debug_selector & D_local_scan) != 0) | |
29442 | debug_printf("xxx", ...); | |
29443 | ||
29444 | ||
29445 | *uschar~\*expand_string_message*:: | |
29446 | After a failing call to 'expand_string()' (returned value NULL), the | |
29447 | variable %expand_string_message% contains the error message, zero-terminated. | |
29448 | ||
29449 | *header_line~\*header_list*:: | |
29450 | A pointer to a chain of header lines. The %header_line% structure is discussed | |
29451 | below. | |
29452 | ||
29453 | *header_line~\*header_last*:: | |
29454 | A pointer to the last of the header lines. | |
29455 | ||
29456 | *uschar~\*headers_charset*:: | |
29457 | The value of the %headers_charset% configuration option. | |
29458 | ||
29459 | *BOOL~host_checking*:: | |
29460 | This variable is TRUE during a host checking session that is initiated by the | |
29461 | %-bh% command line option. | |
29462 | ||
29463 | *uschar~\*interface_address*:: | |
29464 | The IP address of the interface that received the message, as a string. This | |
29465 | is NULL for locally submitted messages. | |
29466 | ||
29467 | *int~interface_port*:: | |
29468 | The port on which this message was received. | |
29469 | ||
29470 | *uschar~\*message_id*:: | |
d1e83bff PH |
29471 | This variable contains Exim's message id for the incoming message (the value of |
29472 | $message_exim_id$) as a zero-terminated string. | |
168e428f PH |
29473 | |
29474 | *uschar~\*received_protocol*:: | |
29475 | The name of the protocol by which the message was received. | |
29476 | ||
29477 | *int~recipients_count*:: | |
29478 | The number of accepted recipients. | |
29479 | ||
29480 | *recipient_item~\*recipients_list*:: | |
29481 | cindex:[recipient,adding in local scan] | |
29482 | cindex:[recipient,removing in local scan] | |
29483 | The list of accepted recipients, held in a vector of length %recipients_count%. | |
29484 | The %recipient_item% structure is discussed below. You can add additional | |
29485 | recipients by calling 'receive_add_recipient()' (see below). You can delete | |
29486 | recipients by removing them from the vector and adusting the value in | |
29487 | %recipients_count%. In particular, by setting %recipients_count% to zero you | |
29488 | remove all recipients. If you then return the value `LOCAL_SCAN_ACCEPT`, the | |
29489 | message is accepted, but immediately blackholed. To replace the recipients, set | |
29490 | %recipients_count% to zero and then call 'receive_add_recipient()' as often as | |
29491 | needed. | |
29492 | ||
29493 | *uschar~\*sender_address*:: | |
29494 | The envelope sender address. For bounce messages this is the empty string. | |
29495 | ||
29496 | *uschar~\*sender_host_address*:: | |
29497 | The IP address of the sending host, as a string. This is NULL for | |
29498 | locally-submitted messages. | |
29499 | ||
29500 | *uschar~\*sender_host_authenticated*:: | |
29501 | The name of the authentication mechanism that was used, or NULL if the message | |
29502 | was not received over an authenticated SMTP connection. | |
29503 | ||
29504 | *uschar~\*sender_host_name*:: | |
29505 | The name of the sending host, if known. | |
29506 | ||
29507 | *int~sender_host_port*:: | |
29508 | The port on the sending host. | |
29509 | ||
29510 | *BOOL~smtp_input*:: | |
29511 | This variable is TRUE for all SMTP input, including BSMTP. | |
29512 | ||
29513 | *BOOL~smtp_batched_input*:: | |
29514 | This variable is TRUE for BSMTP input. | |
29515 | ||
29516 | *int~store_pool*:: | |
29517 | The contents of this variable control which pool of memory is used for new | |
29518 | requests. See section <<SECTmemhanloc>> for details. | |
29519 | ||
29520 | /// | |
29521 | End of list | |
29522 | /// | |
29523 | ||
29524 | ||
29525 | ||
29526 | Structure of header lines | |
29527 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
29528 | The %header_line% structure contains the members listed below. | |
29529 | You can add additional header lines by calling the 'header_add()' function | |
29530 | (see below). You can cause header lines to be ignored (deleted) by setting | |
29531 | their type to \*. | |
29532 | ||
29533 | ||
29534 | *struct~header_line~\*next*:: | |
29535 | A pointer to the next header line, or NULL for the last line. | |
29536 | ||
29537 | *int~type*:: | |
29538 | A code identifying certain headers that Exim recognizes. The codes are printing | |
29539 | characters, and are documented in chapter <<CHAPspool>> of this manual. Notice | |
29540 | in particular that any header line whose type is \* is not transmitted with the | |
29541 | message. This flagging is used for header lines that have been rewritten, or | |
29542 | are to be removed (for example, 'Envelope-sender:' header lines.) Effectively, | |
29543 | \* means ``deleted''. | |
29544 | ||
29545 | *int~slen*:: | |
29546 | The number of characters in the header line, including the terminating and any | |
29547 | internal newlines. | |
29548 | ||
29549 | *uschar~\*text*:: | |
29550 | A pointer to the text of the header. It always ends with a newline, followed by | |
29551 | a zero byte. Internal newlines are preserved. | |
29552 | ||
29553 | ||
29554 | ||
29555 | Structure of recipient items | |
29556 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
29557 | The %recipient_item% structure contains these members: | |
29558 | ||
29559 | *uschar~\*address*:: | |
29560 | This is a pointer to the recipient address as it was received. | |
29561 | ||
29562 | *int~pno*:: | |
29563 | This is used in later Exim processing when top level addresses are created by | |
29564 | the %one_time% option. It is not relevant at the time 'local_scan()' is run and | |
29565 | must always contain -1 at this stage. | |
29566 | ||
29567 | *uschar~\*errors_to*:: | |
29568 | If this value is not NULL, bounce messages caused by failing to deliver to the | |
29569 | recipient are sent to the address it contains. In other words, it overrides the | |
29570 | envelope sender for this one recipient. (Compare the %errors_to% generic router | |
29571 | option.) If a 'local_scan()' function sets an %errors_to% field to an | |
29572 | unqualified address, Exim qualifies it using the domain from | |
29573 | %qualify_recipient%. When 'local_scan()' is called, the %errors_to% field is | |
29574 | NULL for all recipients. | |
29575 | ||
29576 | ||
29577 | ||
29578 | Available Exim functions | |
29579 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
29580 | cindex:['local_scan()' function,available Exim functions] | |
29581 | The header _local_scan.h_ gives you access to a number of Exim functions. | |
29582 | These are the only ones that are guaranteed to be maintained from release to | |
29583 | release: | |
29584 | ||
29585 | *pid_t~child_open(uschar~{star}{star}argv,~uschar~{star}{star}envp,~int~newumask,~int~{star}infdptr,~int~{star}outfdptr,~BOOL~make_leader)*:: | |
29586 | ||
29587 | This function creates a child process that runs the command specified by | |
29588 | %argv%. The environment for the process is specified by %envp%, which can be | |
29589 | NULL if no environment variables are to be passed. A new umask is supplied for | |
29590 | the process in %newumask%. | |
29591 | + | |
29592 | Pipes to the standard input and output of the new process are set up | |
29593 | and returned to the caller via the %infdptr% and %outfdptr% arguments. The | |
29594 | standard error is cloned to the standard output. If there are any file | |
29595 | descriptors ``in the way'' in the new process, they are closed. If the final | |
29596 | argument is TRUE, the new process is made into a process group leader. | |
29597 | + | |
29598 | The function returns the pid of the new process, or -1 if things go wrong. | |
29599 | ||
29600 | *int~child_close(pid_t~pid,~int~timeout)*:: | |
29601 | This function waits for a child process to terminate, or for a timeout (in | |
29602 | seconds) to expire. A timeout value of zero means wait as long as it takes. The | |
29603 | return value is as follows: | |
29604 | + | |
29605 | - >= 0 | |
29606 | + | |
29607 | The process terminated by a normal exit and the value is the process ending | |
29608 | status. | |
29609 | ||
29610 | - < 0 and > --256 | |
29611 | + | |
29612 | The process was terminated by a signal and the value is the negation of the | |
29613 | signal number. | |
29614 | ||
29615 | - --256 | |
29616 | + | |
29617 | The process timed out. | |
29618 | ||
29619 | - --257 | |
29620 | + | |
29621 | The was some other error in wait(); %errno% is still set. | |
29622 | ||
29623 | ||
29624 | *pid_t~child_open_exim(int~{star}fd)*:: | |
29625 | This function provide you with a means of submitting a new message to | |
29626 | Exim. (Of course, you can also call _/usr/sbin/sendmail_ yourself if you | |
29627 | want, but this packages it all up for you.) The function creates a pipe, | |
29628 | forks a subprocess that is running | |
29629 | ||
29630 | exim -t -oem -oi -f <> | |
29631 | + | |
29632 | and returns to you (via the `int *` argument) a file descriptor for the pipe | |
29633 | that is connected to the standard input. The yield of the function is the PID | |
29634 | of the subprocess. You can then write a message to the file descriptor, with | |
29635 | recipients in 'To:', 'Cc:', and/or 'Bcc:' header lines. | |
29636 | + | |
29637 | When you have finished, call 'child_close()' to wait for the process to | |
29638 | finish and to collect its ending status. A timeout value of zero is usually | |
29639 | fine in this circumstance. Unless you have made a mistake with the recipient | |
29640 | addresses, you should get a return code of zero. | |
29641 | ||
29642 | *void~debug_printf(char~{star},~...)*:: | |
29643 | This is Exim's debugging function, with arguments as for '(printf()'. The | |
29644 | output is written to the standard error stream. If no debugging is selected, | |
29645 | calls to 'debug_printf()' have no effect. Normally, you should make calls | |
29646 | conditional on the `local_scan` debug selector by coding like this: | |
29647 | ||
29648 | if ((debug_selector & D_local_scan) != 0) | |
29649 | debug_printf("xxx", ...); | |
29650 | ||
29651 | *uschar~{star}expand_string(uschar~{star}string)*:: | |
29652 | This is an interface to Exim's string expansion code. The return value is the | |
29653 | expanded string, or NULL if there was an expansion failure. | |
29654 | The C variable %expand_string_message% contains an error message after an | |
29655 | expansion failure. If expansion does not change the string, the return value is | |
29656 | the pointer to the input string. Otherwise, the return value points to a new | |
29657 | block of memory that was obtained by a call to 'store_get()'. See section | |
29658 | <<SECTmemhanloc>> below for a discussion of memory handling. | |
29659 | ||
29660 | *void~header_add(int~type,~char~{star}format,~...)*:: | |
29661 | This function allows you to an add additional header line at the end of the | |
29662 | existing ones. The first argument is the type, and should normally be a space | |
29663 | character. The second argument is a format string and any number of | |
29664 | substitution arguments as for 'sprintf()'. You may include internal newlines if | |
29665 | you want, and you must ensure that the string ends with a newline. | |
29666 | ||
29667 | *void~header_add_at_position(BOOL~after,~uschar~{star}name,~BOOL~topnot,~int~type,~char~{star}format,~...)*:: | |
29668 | This function adds a new header line at a specified point in the header | |
29669 | chain. The header itself is specified as for 'header_add()'. | |
29670 | + | |
29671 | If %name% is NULL, the new header is added at the end of the chain if %after% | |
29672 | is true, or at the start if %after% is false. If %name% is not NULL, the header | |
29673 | lines are searched for the first non-deleted header that matches the name. If | |
29674 | one is found, the new header is added before it if %after% is false. If %after% | |
29675 | is true, the new header is added after the found header and any adjacent | |
29676 | subsequent ones with the same name (even if marked ``deleted''). If no matching | |
29677 | non-deleted header is found, the %topnot% option controls where the header is | |
29678 | added. If it is true, addition is at the top; otherwise at the bottom. Thus, to | |
29679 | add a header after all the 'Received:' headers, or at the top if there are no | |
29680 | 'Received:' headers, you could use | |
29681 | ||
29682 | header_add_at_position(TRUE, US"Received", TRUE, | |
29683 | ' ', "X-xxx: ..."); | |
29684 | + | |
29685 | Normally, there is always at least one non-deleted 'Received:' header, but | |
29686 | there may not be if %received_header_text% expands to an empty string. | |
29687 | ||
29688 | ||
29689 | *void~header_remove(int~occurrence,~uschar~{star}name)*:: | |
29690 | This function removes header lines. If %occurrence% is zero or negative, all | |
29691 | occurrences of the header are removed. If occurrence is greater than zero, that | |
29692 | particular instance of the header is removed. If no header(s) can be found that | |
29693 | match the specification, the function does nothing. | |
29694 | ||
29695 | ||
29696 | *BOOL~header_testname(header_line~{star}hdr,~uschar~{star}name,~int~length,~BOOL~notdel)*:: | |
29697 | This function tests whether the given header has the given name. It is not just | |
068aaea8 | 29698 | a string comparison, because white space is permitted between the name and the |
168e428f PH |
29699 | colon. If the %notdel% argument is true, a false return is forced for all |
29700 | ``deleted'' headers; otherwise they are not treated specially. For example: | |
29701 | ||
29702 | if (header_testname(h, US"X-Spam", 6, TRUE)) ... | |
29703 | ||
29704 | ||
29705 | *uschar~{star}lss_b64encode(uschar~{star}cleartext,~int~length)*:: | |
29706 | cindex:[base64 encoding,functions for 'local_scan()' use] | |
29707 | This function base64-encodes a string, which is passed by address and length. | |
29708 | The text may contain bytes of any value, including zero. The result is passed | |
29709 | back in dynamic memory that is obtained by calling 'store_get()'. It is | |
29710 | zero-terminated. | |
29711 | ||
29712 | *int~lss_b64decode(uschar~{star}codetext,~uschar~{star}{star}cleartext)*:: | |
29713 | This function decodes a base64-encoded string. Its arguments are a | |
29714 | zero-terminated base64-encoded string and the address of a variable that is set | |
29715 | to point to the result, which is in dynamic memory. The length of the decoded | |
29716 | string is the yield of the function. If the input is invalid base64 data, the | |
29717 | yield is -1. A zero byte is added to the end of the output string to make it | |
29718 | easy to interpret as a C string (assuming it contains no zeros of its own). The | |
29719 | added zero byte is not included in the returned count. | |
29720 | ||
29721 | *int~lss_match_domain(uschar~{star}domain,~uschar~{star}list)*:: | |
29722 | This function checks for a match in a domain list. Domains are always | |
29723 | matched caselessly. The return value is one of the following: | |
29724 | + | |
29725 | &&& | |
29726 | `OK ` match succeeded | |
29727 | `FAIL ` match failed | |
29728 | `DEFER ` match deferred | |
29729 | &&& | |
29730 | + | |
29731 | DEFER is usually caused by some kind of lookup defer, such as the | |
29732 | inability to contact a database. | |
29733 | ||
29734 | *int~lss_match_local_part(uschar~{star}localpart,~uschar~{star}list,~BOOL~caseless)*:: | |
29735 | This function checks for a match in a local part list. The third argument | |
29736 | controls case-sensitivity. The return values are as for | |
29737 | 'lss_match_domain()'. | |
29738 | ||
29739 | *int~lss_match_address(uschar~{star}address,~uschar~{star}list,~BOOL~caseless)*:: | |
29740 | This function checks for a match in an address list. The third argument | |
29741 | controls the case-sensitivity of the local part match. The domain is always | |
29742 | matched caselessly. The return values are as for 'lss_match_domain()'. | |
29743 | ||
29744 | *int~lss_match_host(uschar~{star}host_name,~uschar~{star}host_address,~uschar~{star}list)*:: | |
29745 | This function checks for a match in a host list. The most common usage is | |
29746 | expected to be | |
29747 | ||
29748 | lss_match_host(sender_host_name, sender_host_address, ...) | |
29749 | + | |
068aaea8 PH |
29750 | cindex:[$sender_host_address$] |
29751 | An empty address field matches an empty item in the host list. If the host name | |
29752 | is NULL, the name corresponding to $sender_host_address$ is automatically | |
29753 | looked up if a host name is required to match an item in the list. The return | |
29754 | values are as for 'lss_match_domain()', but in addition, 'lss_match_host()' | |
29755 | returns ERROR in the case when it had to look up a host name, but the lookup | |
29756 | failed. | |
168e428f PH |
29757 | |
29758 | *void~log_write(unsigned~int~selector,~int~which,~char~{star}format,~...)*:: | |
29759 | This function writes to Exim's log files. The first argument should be zero (it | |
29760 | is concerned with %log_selector%). The second argument can be `LOG_MAIN` or | |
29761 | `LOG_REJECT` or `LOG_PANIC` or the inclusive ``or'' of any combination of them. | |
29762 | It specifies to which log or logs the message is written. The remaining | |
29763 | arguments are a format and relevant insertion arguments. The string should not | |
29764 | contain any newlines, not even at the end. | |
29765 | ||
29766 | ||
29767 | *void~receive_add_recipient(uschar~{star}address,~int~pno)*:: | |
29768 | This function adds an additional recipient to the message. The first argument | |
29769 | is the recipient address. If it is unqualified (has no domain), it is qualified | |
29770 | with the %qualify_recipient% domain. The second argument must always be -1. | |
29771 | + | |
29772 | This function does not allow you to specify a private %errors_to% address (as | |
29773 | described with the structure of %recipient_item% above), because it pre-dates | |
29774 | the addition of that field to the structure. However, it is easy to add such a | |
29775 | value afterwards. For example: | |
29776 | ||
29777 | receive_add_recipient(US"monitor@mydom.example", -1); | |
29778 | recipients_list[recipients_count-1].errors_to = | |
29779 | US"postmaster@mydom.example"; | |
29780 | ||
29781 | *BOOL~receive_remove_recipient(uschar~{star}recipient)*:: | |
29782 | This is a convenience function to remove a named recipient from the list of | |
29783 | recipients. It returns true if a recipient was removed, and false if no | |
29784 | matching recipient could be found. The argument must be a complete email | |
29785 | address. | |
29786 | ||
29787 | ||
d1e83bff | 29788 | cindex:[RFC 2047] |
168e428f PH |
29789 | *uschar~*rfc2047_decode(uschar~{star}string,~BOOL~lencheck,~uschar~{star}target,~int~zeroval,~int~{star}lenptr,~uschar~{star}{star}error)*:: |
29790 | This function decodes strings that are encoded according to RFC 2047. Typically | |
d1e83bff | 29791 | these are the contents of header lines. First, each ``encoded word'' is decoded |
168e428f PH |
29792 | from the Q or B encoding into a byte-string. Then, if provided with the name of |
29793 | a charset encoding, and if the 'iconv()' function is available, an attempt is | |
29794 | made to translate the result to the named character set. If this fails, the | |
29795 | binary string is returned with an error message. | |
29796 | + | |
29797 | The first argument is the string to be decoded. If %lencheck% is TRUE, the | |
29798 | maximum MIME word length is enforced. The third argument is the target | |
29799 | encoding, or NULL if no translation is wanted. | |
29800 | + | |
29801 | cindex:[binary zero,in RFC 2047 decoding] | |
d1e83bff | 29802 | cindex:[RFC 2047,binary zero in] |
168e428f PH |
29803 | If a binary zero is encountered in the decoded string, it is replaced by the |
29804 | contents of the %zeroval% argument. For use with Exim headers, the value must | |
29805 | not be 0 because header lines are handled as zero-terminated strings. | |
29806 | + | |
29807 | The function returns the result of processing the string, zero-terminated; if | |
29808 | %lenptr% is not NULL, the length of the result is set in the variable to which | |
29809 | it points. When %zeroval% is 0, %lenptr% should not be NULL. | |
29810 | + | |
29811 | If an error is encountered, the function returns NULL and uses the %error% | |
29812 | argument to return an error message. The variable pointed to by %error% is set | |
29813 | to NULL if there is no error; it may be set non-NULL even when the function | |
29814 | returns a non-NULL value if decoding was successful, but there was a problem | |
29815 | with translation. | |
29816 | ||
29817 | ||
29818 | *int~smtp_fflush(void)*:: | |
29819 | This function is used in conjunction with 'smtp_printf()', as described | |
29820 | below. | |
29821 | ||
29822 | *void~smtp_printf(char~{star},~...)*:: | |
29823 | The arguments of this function are like 'printf()'; it writes to the SMTP | |
29824 | output stream. You should use this function only when there is an SMTP output | |
29825 | stream, that is, when the incoming message is being received via interactive | |
29826 | SMTP. This is the case when %smtp_input% is TRUE and %smtp_batched_input% is | |
29827 | FALSE. If you want to test for an incoming message from another host (as | |
29828 | opposed to a local process that used the %-bs% command line option), you can | |
29829 | test the value of %sender_host_address%, which is non-NULL when a remote host | |
29830 | is involved. | |
29831 | + | |
29832 | If an SMTP TLS connection is established, 'smtp_printf()' uses the TLS | |
29833 | output function, so it can be used for all forms of SMTP connection. | |
29834 | + | |
29835 | Strings that are written by 'smtp_printf()' from within 'local_scan()' | |
29836 | must start with an appropriate response code: 550 if you are going to return | |
29837 | LOCAL_SCAN_REJECT, 451 if you are going to return | |
29838 | LOCAL_SCAN_TEMPREJECT, and 250 otherwise. Because you are writing the | |
29839 | initial lines of a multi-line response, the code must be followed by a hyphen | |
29840 | to indicate that the line is not the final response line. You must also ensure | |
29841 | that the lines you write terminate with CRLF. For example: | |
29842 | ||
29843 | smtp_printf("550-this is some extra info\r\n"); | |
29844 | return LOCAL_SCAN_REJECT; | |
29845 | + | |
29846 | Note that you can also create multi-line responses by including newlines in | |
29847 | the data returned via the %return_text% argument. The added value of using | |
29848 | 'smtp_printf()' is that, for instance, you could introduce delays between | |
29849 | multiple output lines. | |
29850 | + | |
29851 | The 'smtp_printf()' function does not return any error indication, because it | |
29852 | does not automatically flush pending output, and therefore does not test | |
29853 | the state of the stream. (In the main code of Exim, flushing and error | |
29854 | detection is done when Exim is ready for the next SMTP input command.) If | |
29855 | you want to flush the output and check for an error (for example, the | |
29856 | dropping of a TCP/IP connection), you can call 'smtp_fflush()', which has no | |
29857 | arguments. It flushes the output stream, and returns a non-zero value if there | |
29858 | is an error. | |
29859 | ||
29860 | *void~{star}store_get(int)*:: | |
29861 | This function accesses Exim's internal store (memory) manager. It gets a new | |
29862 | chunk of memory whose size is given by the argument. Exim bombs out if it ever | |
29863 | runs out of memory. See the next section for a discussion of memory handling. | |
29864 | ||
29865 | *void~{star}store_get_perm(int)*:: | |
29866 | This function is like 'store_get()', but it always gets memory from the | |
29867 | permanent pool. See the next section for a discussion of memory handling. | |
29868 | ||
29869 | *uschar~{star}string_copy(uschar~{star}string)*:: | |
29870 | See below. | |
29871 | ||
29872 | *uschar~{star}string_copyn(uschar~{star}string,~int~length)*:: | |
29873 | See below. | |
29874 | ||
29875 | *uschar~{star}string_sprintf(char~{star}format,~...)*:: | |
29876 | These three functions create strings using Exim's dynamic memory facilities. | |
29877 | The first makes a copy of an entire string. The second copies up to a maximum | |
29878 | number of characters, indicated by the second argument. The third uses a format | |
29879 | and insertion arguments to create a new string. In each case, the result is a | |
29880 | pointer to a new string in the current memory pool. See the next section for | |
29881 | more discussion. | |
29882 | ||
29883 | /// | |
29884 | End of list | |
29885 | /// | |
29886 | ||
29887 | ||
29888 | ||
29889 | ||
29890 | [[SECTmemhanloc]] | |
29891 | More about Exim's memory handling | |
29892 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
29893 | cindex:['local_scan()' function,memory handling] | |
29894 | No function is provided for freeing memory, because that is never needed. | |
29895 | The dynamic memory that Exim uses when receiving a message is automatically | |
29896 | recycled if another message is received by the same process (this applies only | |
29897 | to incoming SMTP connections -- other input methods can supply only one message | |
29898 | at a time). After receiving the last message, a reception process terminates. | |
29899 | ||
29900 | Because it is recycled, the normal dynamic memory cannot be used for holding | |
29901 | data that must be preserved over a number of incoming messages on the same SMTP | |
29902 | connection. However, Exim in fact uses two pools of dynamic memory; the second | |
29903 | one is not recycled, and can be used for this purpose. | |
29904 | ||
29905 | If you want to allocate memory that remains available for subsequent messages | |
29906 | in the same SMTP connection, you should set | |
29907 | ||
29908 | store_pool = POOL_PERM | |
29909 | ||
29910 | before calling the function that does the allocation. There is no need to | |
29911 | restore the value if you do not need to; however, if you do want to revert to | |
29912 | the normal pool, you can either restore the previous value of %store_pool% or | |
29913 | set it explicitly to POOL_MAIN. | |
29914 | ||
29915 | The pool setting applies to all functions that get dynamic memory, including | |
29916 | 'expand_string()', 'store_get()', and the 'string_xxx()' functions. | |
29917 | There is also a convenience function called 'store_get_perm()' that gets a | |
29918 | block of memory from the permanent pool while preserving the value of | |
29919 | %store_pool%. | |
29920 | ||
29921 | ||
29922 | ||
29923 | ||
29924 | ||
29925 | //////////////////////////////////////////////////////////////////////////// | |
29926 | //////////////////////////////////////////////////////////////////////////// | |
29927 | ||
29928 | [[CHAPsystemfilter]] | |
29929 | System-wide message filtering | |
29930 | ----------------------------- | |
29931 | cindex:[filter,system filter] | |
29932 | cindex:[filtering all mail] | |
29933 | cindex:[system filter] | |
29934 | The previous chapters (on ACLs and the local scan function) describe checks | |
29935 | that can be applied to messages before they are accepted by a host. There is | |
29936 | also a mechanism for checking messages once they have been received, but before | |
29937 | they are delivered. This is called the 'system filter'. | |
29938 | ||
29939 | The system filter operates in a similar manner to users' filter files, but it | |
29940 | is run just once per message (however many recipients the message has). | |
29941 | It should not normally be used as a substitute for routing, because %deliver% | |
29942 | commands in a system router provide new envelope recipient addresses. | |
29943 | The system filter must be an Exim filter. It cannot be a Sieve filter. | |
29944 | ||
29945 | The system filter is run at the start of a delivery attempt, before any routing | |
29946 | is done. If a message fails to be completely delivered at the first attempt, | |
29947 | the system filter is run again at the start of every retry. | |
29948 | If you want your filter to do something only once per message, you can make use | |
29949 | of the %first_delivery% condition in an %if% command in the filter to prevent | |
29950 | it happening on retries. | |
29951 | ||
068aaea8 PH |
29952 | cindex:[$domain$] |
29953 | cindex:[$local_part$] | |
168e428f PH |
29954 | *Warning*: Because the system filter runs just once, variables that are |
29955 | specific to individual recipient addresses, such as $local_part$ and | |
29956 | $domain$, are not set, and the ``personal'' condition is not meaningful. If you | |
29957 | want to run a centrally-specified filter for each recipient address | |
29958 | independently, you can do so by setting up a suitable ^redirect^ router, as | |
29959 | described in section <<SECTperaddfil>> below. | |
29960 | ||
29961 | ||
29962 | Specifying a system filter | |
29963 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
29964 | cindex:[uid (user id),system filter] | |
29965 | cindex:[gid (group id),system filter] | |
29966 | The name of the file that contains the system filter must be specified by | |
29967 | setting %system_filter%. If you want the filter to run under a uid and gid | |
29968 | other than root, you must also set %system_filter_user% and | |
29969 | %system_filter_group% as appropriate. For example: | |
29970 | ||
29971 | system_filter = /etc/mail/exim.filter | |
29972 | system_filter_user = exim | |
29973 | ||
29974 | If a system filter generates any deliveries directly to files or pipes (via the | |
29975 | %save% or %pipe% commands), transports to handle these deliveries must be | |
29976 | specified by setting %system_filter_file_transport% and | |
29977 | %system_filter_pipe_transport%, respectively. Similarly, | |
29978 | %system_filter_reply_transport% must be set to handle any messages generated | |
29979 | by the %reply% command. | |
29980 | ||
29981 | ||
29982 | Testing a system filter | |
29983 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
29984 | You can run simple tests of a system filter in the same way as for a user | |
29985 | filter, but you should use %-bF% rather than %-bf%, so that features that | |
29986 | are permitted only in system filters are recognized. | |
29987 | ||
29988 | If you want to test the combined effect of a system filter and a user filter, | |
29989 | you can use both %-bF% and %-bf% on the same command line. | |
29990 | ||
29991 | ||
29992 | ||
29993 | Contents of a system filter | |
29994 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
29995 | The language used to specify system filters is the same as for users' filter | |
29996 | files. It is described in the separate end-user document 'Exim's interface to | |
29997 | mail filtering'. However, there are some additional features that are | |
29998 | available only in system filters; these are described in subsequent sections. | |
29999 | If they are encountered in a user's filter file or when testing with %-bf%, | |
30000 | they cause errors. | |
30001 | ||
30002 | cindex:[frozen messages,manual thaw; testing in filter] | |
30003 | There are two special conditions which, though available in users' filter | |
30004 | files, are designed for use in system filters. The condition %first_delivery% | |
30005 | is true only for the first attempt at delivering a message, and | |
30006 | %manually_thawed% is true only if the message has been frozen, and | |
30007 | subsequently thawed by an admin user. An explicit forced delivery counts as a | |
30008 | manual thaw, but thawing as a result of the %auto_thaw% setting does not. | |
30009 | ||
30010 | *Warning*: If a system filter uses the %first_delivery% condition to | |
30011 | specify an ``unseen'' (non-significant) delivery, and that delivery does not | |
30012 | succeed, it will not be tried again. | |
30013 | If you want Exim to retry an unseen delivery until it succeeds, you should | |
30014 | arrange to set it up every time the filter runs. | |
30015 | ||
30016 | When a system filter finishes running, the values of the variables $n0$ -- | |
30017 | $n9$ are copied into $sn0$ -- $sn9$ and are thereby made available to | |
30018 | users' filter files. Thus a system filter can, for example, set up ``scores'' to | |
30019 | which users' filter files can refer. | |
30020 | ||
30021 | ||
30022 | ||
30023 | Additional variable for system filters | |
30024 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
068aaea8 | 30025 | cindex:[$recipients$] |
168e428f PH |
30026 | The expansion variable $recipients$, containing a list of all the recipients |
30027 | of the message (separated by commas and white space), is available in system | |
30028 | filters. It is not available in users' filters for privacy reasons. | |
30029 | ||
30030 | ||
30031 | ||
30032 | Defer, freeze, and fail commands for system filters | |
30033 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
30034 | cindex:[freezing messages] | |
30035 | cindex:[message,freezing] | |
30036 | cindex:[message,forced failure] | |
30037 | cindex:[%fail%,in system filter] | |
30038 | cindex:[%freeze% in system filter] | |
30039 | cindex:[%defer% in system filter] | |
30040 | There are three extra commands (%defer%, %freeze% and %fail%) which are always | |
30041 | available in system filters, but are not normally enabled in users' filters. | |
30042 | (See the %allow_defer%, | |
30043 | %allow_freeze% and %allow_fail% options for the ^redirect^ router.) These | |
30044 | commands can optionally be followed by the word %text% and a string containing | |
30045 | an error message, for example: | |
30046 | ||
30047 | fail text "this message looks like spam to me" | |
30048 | ||
30049 | The keyword %text% is optional if the next character is a double quote. | |
30050 | ||
30051 | The %defer% command defers delivery of the original recipients of the message. | |
30052 | The %fail% command causes all the original recipients to be failed, and a | |
30053 | bounce message to be created. The %freeze% command suspends all delivery | |
30054 | attempts for the original recipients. In all cases, any new deliveries that are | |
30055 | specified by the filter are attempted as normal after the filter has run. | |
30056 | ||
30057 | The %freeze% command is ignored if the message has been manually unfrozen and | |
30058 | not manually frozen since. This means that automatic freezing by a system | |
30059 | filter can be used as a way of checking out suspicious messages. If a message | |
30060 | is found to be all right, manually unfreezing it allows it to be delivered. | |
30061 | ||
30062 | cindex:[log,%fail% command log line] | |
30063 | cindex:[%fail%,log line; reducing] | |
30064 | The text given with a fail command is used as part of the bounce message as | |
30065 | well as being written to the log. If the message is quite long, this can fill | |
30066 | up a lot of log space when such failures are common. To reduce the size of the | |
30067 | log message, Exim interprets the text in a special way if it starts with the | |
30068 | two characters `<<` and contains `>>` later. The text between these two | |
30069 | strings is written to the log, and the rest of the text is used in the bounce | |
30070 | message. For example: | |
30071 | ||
30072 | .... | |
30073 | fail "<<filter test 1>>Your message is rejected \ | |
30074 | because it contains attachments that we are \ | |
30075 | not prepared to receive." | |
30076 | .... | |
30077 | ||
30078 | ||
30079 | cindex:[loop,caused by %fail%] | |
30080 | Take great care with the %fail% command when basing the decision to fail on the | |
30081 | contents of the message, because the bounce message will of course include the | |
30082 | contents of the original message and will therefore trigger the %fail% command | |
30083 | again (causing a mail loop) unless steps are taken to prevent this. Testing the | |
30084 | %error_message% condition is one way to prevent this. You could use, for | |
30085 | example | |
30086 | ||
30087 | if $message_body contains "this is spam" and not error_message | |
30088 | then fail text "spam is not wanted here" endif | |
30089 | ||
30090 | though of course that might let through unwanted bounce messages. The | |
30091 | alternative is clever checking of the body and/or headers to detect bounces | |
30092 | generated by the filter. | |
30093 | ||
30094 | The interpretation of a system filter file ceases after a | |
30095 | %defer%, | |
30096 | %freeze%, or %fail% command is obeyed. However, any deliveries that were set up | |
30097 | earlier in the filter file are honoured, so you can use a sequence such as | |
30098 | ||
30099 | mail ... | |
30100 | freeze | |
30101 | ||
30102 | to send a specified message when the system filter is freezing (or deferring or | |
30103 | failing) a message. The normal deliveries for the message do not, of course, | |
30104 | take place. | |
30105 | ||
30106 | ||
30107 | ||
30108 | [[SECTaddremheasys]] | |
30109 | Adding and removing headers in a system filter | |
30110 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
30111 | cindex:[header lines,adding; in system filter] | |
30112 | cindex:[header lines,removing; in system filter] | |
30113 | cindex:[filter,header lines; adding/removing] | |
30114 | Two filter commands that are available only in system filters are: | |
30115 | ||
30116 | headers add <string> | |
30117 | headers remove <string> | |
30118 | ||
30119 | The argument for the %headers add% is a string that is expanded and then added | |
30120 | to the end of the message's headers. It is the responsibility of the filter | |
30121 | maintainer to make sure it conforms to RFC 2822 syntax. Leading white space is | |
30122 | ignored, and if the string is otherwise empty, or if the expansion is forced to | |
30123 | fail, the command has no effect. | |
30124 | ||
30125 | You can use ``\n'' within the string, followed by white space, to specify | |
30126 | continued header lines. More than one header may be added in one command by | |
30127 | including ``\n'' within the string without any following white space. For | |
30128 | example: | |
30129 | ||
30130 | .... | |
30131 | headers add "X-header-1: ....\n \ | |
30132 | continuation of X-header-1 ...\n\ | |
30133 | X-header-2: ...." | |
30134 | .... | |
30135 | ||
30136 | Note that the header line continuation white space after the first newline must | |
30137 | be placed before the backslash that continues the input string, because white | |
30138 | space after input continuations is ignored. | |
30139 | ||
30140 | The argument for %headers remove% is a colon-separated list of header names. | |
30141 | This command applies only to those headers that are stored with the message; | |
30142 | those that are added at delivery time (such as 'Envelope-To:' and | |
30143 | 'Return-Path:') cannot be removed by this means. If there is more than one | |
30144 | header with the same name, they are all removed. | |
30145 | ||
30146 | The %headers% command in a system filter makes an immediate change to the set | |
30147 | of header lines that was received with the message (with possible additions | |
30148 | from ACL processing). Subsequent commands in the system filter operate on the | |
30149 | modified set, which also forms the basis for subsequent message delivery. | |
30150 | Unless further modified during routing or transporting, this set of headers is | |
30151 | used for all recipients of the message. | |
30152 | ||
30153 | During routing and transporting, the variables that refer to the contents of | |
30154 | header lines refer only to those lines that are in this set. Thus, header lines | |
30155 | that are added by a system filter are visible to users' filter files and to all | |
30156 | routers and transports. This contrasts with the manipulation of header lines by | |
30157 | routers and transports, which is not immediate, but which instead is saved up | |
30158 | until the message is actually being written (see section <<SECTheadersaddrem>>). | |
30159 | ||
30160 | If the message is not delivered at the first attempt, header lines that were | |
30161 | added by the system filter are stored with the message, and so are still | |
30162 | present at the next delivery attempt. Header lines that were removed are still | |
30163 | present, but marked ``deleted'' so that they are not transported with the | |
30164 | message. For this reason, it is usual to make the %headers% command conditional | |
30165 | on %first_delivery% so that the set of header lines is not modified more than | |
30166 | once. | |
30167 | ||
30168 | Because header modification in a system filter acts immediately, you have to | |
30169 | use an indirect approach if you want to modify the contents of a header line. | |
30170 | For example: | |
30171 | ||
30172 | headers add "Old-Subject: $h_subject:" | |
30173 | headers remove "Subject" | |
30174 | headers add "Subject: new subject (was: $h_old-subject:)" | |
30175 | headers remove "Old-Subject" | |
30176 | ||
30177 | ||
30178 | ||
30179 | ||
30180 | ||
30181 | Setting an errors address in a system filter | |
30182 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
30183 | cindex:[envelope sender] | |
30184 | In a system filter, if a %deliver% command is followed by | |
30185 | ||
30186 | errors_to <some address> | |
30187 | ||
30188 | in order to change the envelope sender (and hence the error reporting) for that | |
30189 | delivery, any address may be specified. (In a user filter, only the current | |
30190 | user's address can be set.) For example, if some mail is being monitored, you | |
30191 | might use | |
30192 | ||
30193 | unseen deliver monitor@spying.example errors_to root@local.example | |
30194 | ||
30195 | to take a copy which would not be sent back to the normal error reporting | |
30196 | address if its delivery failed. | |
30197 | ||
30198 | ||
30199 | ||
30200 | [[SECTperaddfil]] | |
30201 | Per-address filtering | |
30202 | ~~~~~~~~~~~~~~~~~~~~~ | |
068aaea8 PH |
30203 | cindex:[$domain$] |
30204 | cindex:[$local_part$] | |
168e428f PH |
30205 | In contrast to the system filter, which is run just once per message for each |
30206 | delivery attempt, it is also possible to set up a system-wide filtering | |
30207 | operation that runs once for each recipient address. In this case, variables | |
30208 | such as $local_part$ and $domain$ can be used, and indeed, the choice of | |
30209 | filter file could be made dependent on them. This is an example of a router | |
30210 | which implements such a filter: | |
30211 | ||
30212 | central_filter: | |
30213 | check_local_user | |
30214 | driver = redirect | |
30215 | domains = +local_domains | |
30216 | file = /central/filters/$local_part | |
30217 | no_verify | |
30218 | allow_filter | |
30219 | allow_freeze | |
30220 | ||
30221 | The filter is run in a separate process under its own uid. Therefore, either | |
30222 | %check_local_user% must be set (as above), in which case the filter is run as | |
30223 | the local user, or the %user% option must be used to specify which user to use. | |
30224 | If both are set, %user% overrides. | |
30225 | ||
30226 | Care should be taken to ensure that none of the commands in the filter file | |
30227 | specify a significant delivery if the message is to go on to be delivered to | |
30228 | its intended recipient. The router will not then claim to have dealt with the | |
30229 | address, so it will be passed on to subsequent routers to be delivered in the | |
30230 | normal way. | |
30231 | ||
30232 | ||
30233 | ||
30234 | ||
30235 | ||
30236 | ||
30237 | //////////////////////////////////////////////////////////////////////////// | |
30238 | //////////////////////////////////////////////////////////////////////////// | |
30239 | ||
30240 | [[CHAPmsgproc]] | |
30241 | Message processing | |
30242 | ------------------ | |
30243 | cindex:[message,general processing] | |
30244 | Exim performs various transformations on the sender and recipient addresses of | |
30245 | all messages that it handles, and also on the messages' header lines. Some of | |
30246 | these are optional and configurable, while others always take place. All of | |
30247 | this processing, except rewriting as a result of routing, and the addition or | |
30248 | removal of header lines while delivering, happens when a message is received, | |
30249 | before it is placed on Exim's queue. | |
30250 | ||
30251 | Some of the automatic processing takes place by default only for | |
30252 | ``locally-originated'' messages. This adjective is used to describe messages that | |
30253 | are not received over TCP/IP, but instead are passed to an Exim process on its | |
30254 | standard input. This includes the interactive ``local SMTP'' case that is set up | |
30255 | by the %-bs% command line option. | |
30256 | ||
30257 | *Note*: messages received over TCP/IP on the loopback interface (127.0.0.1 | |
30258 | or ::1) are not considered to be locally-originated. Exim does not treat the | |
30259 | loopback interface specially in any way. | |
30260 | ||
30261 | If you want the loopback interface to be treated specially, you must ensure | |
30262 | that there are appropriate entries in your ACLs. | |
30263 | ||
30264 | ||
30265 | ||
30266 | ||
30267 | [[SECTsubmodnon]] | |
30268 | Submission mode for non-local messages | |
30269 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
068aaea8 | 30270 | [revisionflag="changed"] |
168e428f PH |
30271 | cindex:[message,submission] |
30272 | cindex:[submission mode] | |
068aaea8 PH |
30273 | Processing that happens automatically for locally-originated messages (unless |
30274 | %suppress_local_fixups% is set) can also be requested for messages that are | |
30275 | received over TCP/IP. The term ``submission mode'' is used to describe this | |
30276 | state. Submisssion mode is set by the modifier | |
168e428f PH |
30277 | |
30278 | control = submission | |
30279 | ||
068aaea8 PH |
30280 | in a MAIL, RCPT, or pre-data ACL for an incoming message (see sections |
30281 | <<SECTACLmodi>> and <<SECTcontrols>>). This makes Exim treat the message as a | |
30282 | local submission, and is normally used when the source of the message is known | |
30283 | to be an MUA running on a client host (as opposed to an MTA). For example, to | |
30284 | set submission mode for messages originating on the IPv4 loopback interface, | |
30285 | you could include the following in the MAIL ACL: | |
168e428f PH |
30286 | |
30287 | warn hosts = 127.0.0.1 | |
30288 | control = submission | |
30289 | ||
068aaea8 | 30290 | cindex:[%sender_retain%] |
168e428f PH |
30291 | There are some options that can be used when setting submission mode. A slash |
30292 | is used to separate options. For example: | |
30293 | ||
30294 | control = submission/sender_retain | |
30295 | ||
30296 | Specifying %sender_retain% has the effect of setting %local_sender_retain% | |
30297 | true and %local_from_check% false for the current incoming message. The first | |
30298 | of these allows an existing 'Sender:' header in the message to remain, and the | |
30299 | second suppresses the check to ensure that 'From:' matches the authenticated | |
30300 | sender. With this setting, Exim still fixes up messages by adding 'Date:' and | |
30301 | 'Message-ID:' header lines if they are missing, but makes no attempt to check | |
30302 | sender authenticity in header lines. | |
30303 | ||
068aaea8 PH |
30304 | When %sender_retain% is not set, a submission mode setting may specify a domain |
30305 | to be used when generating a 'From:' or 'Sender:' header line. For example: | |
168e428f PH |
30306 | |
30307 | control = submission/domain=some.domain | |
30308 | ||
068aaea8 | 30309 | [revisionflag="changed"] |
168e428f | 30310 | The domain may be empty. How this value is used is described in sections |
068aaea8 PH |
30311 | <<SECTthefrohea>> and <<SECTthesenhea>>. There is also a %name% option that |
30312 | allows you to specify the user's full name for inclusion in a created | |
30313 | 'Sender:' or 'From:' header line. For example: | |
168e428f | 30314 | |
068aaea8 PH |
30315 | [revisionflag="changed"] |
30316 | .... | |
30317 | accept authenticated = * | |
30318 | control = submission/domain=wonderland.example/\ | |
30319 | name=${lookup {$authenticated_id} \ | |
30320 | lsearch {/etc/exim/namelist}} | |
30321 | .... | |
168e428f | 30322 | |
068aaea8 PH |
30323 | [revisionflag="changed"] |
30324 | Because the name may contain any characters, including slashes, the %name% | |
30325 | option must be given last. The remainder of the string is used as the name. For | |
30326 | the example above, if _/etc/exim/namelist_ contains: | |
30327 | ||
30328 | [revisionflag="changed"] | |
30329 | .... | |
30330 | bigegg: Humpty Dumpty | |
30331 | .... | |
168e428f | 30332 | |
068aaea8 PH |
30333 | [revisionflag="changed"] |
30334 | then when the sender has authenticated as 'bigegg', the generated 'Sender:' | |
30335 | line would be: | |
30336 | ||
30337 | [revisionflag="changed"] | |
30338 | .... | |
30339 | Sender: Humpty Dumpty <bigegg@wonderland.example> | |
30340 | .... | |
30341 | ||
30342 | [revisionflag="changed"] | |
30343 | cindex:[return path,in submission mode] | |
30344 | By default, submission mode forces the return path to the same address as is | |
30345 | used to create the 'Sender:' header. However, if %sender_retain% is specified, | |
30346 | the return path is also left unchanged. | |
30347 | ||
30348 | [revisionflag="changed"] | |
30349 | *Note*: the changes caused by submission mode take effect after the predata | |
30350 | ACL. This means that any sender checks performed before the fix-ups use the | |
30351 | untrusted sender address specified by the user, not the trusted sender address | |
30352 | specified by submission mode. Although this might be slightly unexpected, it | |
30353 | does mean that you can configure ACL checks to spot that a user is trying to | |
30354 | spoof another's address. | |
168e428f PH |
30355 | |
30356 | ||
30357 | [[SECTlineendings]] | |
30358 | Line endings | |
30359 | ~~~~~~~~~~~~ | |
30360 | cindex:[line endings] | |
30361 | cindex:[carriage return] | |
30362 | cindex:[linefeed] | |
30363 | RFC 2821 specifies that CRLF (two characters: carriage-return, followed by | |
30364 | linefeed) is the line ending for messages transmitted over the Internet using | |
30365 | SMTP over TCP/IP. However, within individual operating systems, different | |
30366 | conventions are used. For example, Unix-like systems use just LF, but others | |
30367 | use CRLF or just CR. | |
30368 | ||
30369 | Exim was designed for Unix-like systems, and internally, it stores messages | |
30370 | using the system's convention of a single LF as a line terminator. When | |
30371 | receiving a message, all line endings are translated to this standard format. | |
30372 | Originally, it was thought that programs that passed messages directly to an | |
30373 | MTA within an operating system would use that system's convention. Experience | |
30374 | has shown that this is not the case; for example, there are Unix applications | |
30375 | that use CRLF in this circumstance. For this reason, and for compatibility with | |
30376 | other MTAs, the way Exim handles line endings for all messages is now as | |
30377 | follows: | |
30378 | ||
30379 | - LF not preceded by CR is treated as a line ending. | |
30380 | ||
30381 | - CR is treated as a line ending; if it is immediately followed by LF, the LF | |
30382 | is ignored. | |
30383 | ||
30384 | - The sequence ``CR, dot, CR'' does not terminate an incoming SMTP message, | |
30385 | nor a local message in the state where a line containing only a dot is a | |
30386 | terminator. | |
30387 | ||
30388 | - If a bare CR is encountered within a header line, an extra space is added after | |
30389 | the line terminator so as not to end the header line. The reasoning behind this | |
30390 | is that bare CRs in header lines are most likely either to be mistakes, or | |
30391 | people trying to play silly games. | |
30392 | ||
30393 | - If the first header line received in a message ends with CRLF, a subsequent | |
30394 | bare LF in a header line is treated in the same way as a bare CR in a header | |
30395 | line. | |
30396 | ||
30397 | ||
30398 | ||
30399 | ||
30400 | ||
30401 | Unqualified addresses | |
30402 | ~~~~~~~~~~~~~~~~~~~~~ | |
30403 | cindex:[unqualified addresses] | |
30404 | cindex:[address,qualification] | |
30405 | By default, Exim expects every envelope address it receives from an external | |
30406 | host to be fully qualified. Unqualified addresses cause negative responses to | |
30407 | SMTP commands. However, because SMTP is used as a means of transporting | |
30408 | messages from MUAs running on personal workstations, there is sometimes a | |
30409 | requirement to accept unqualified addresses from specific hosts or IP networks. | |
30410 | ||
30411 | Exim has two options that separately control which hosts may send unqualified | |
30412 | sender or receipient addresses in SMTP commands, namely | |
30413 | %sender_unqualified_hosts% and %recipient_unqualified_hosts%. In both | |
30414 | cases, if an unqualified address is accepted, it is qualified by adding the | |
30415 | value of %qualify_domain% or %qualify_recipient%, as appropriate. | |
30416 | ||
30417 | cindex:[%qualify_domain%] | |
30418 | cindex:[%qualify_recipient%] | |
30419 | Unqualified addresses in header lines are automatically qualified for messages | |
30420 | that are locally originated, unless the %-bnq% option is given on the command | |
30421 | line. For messages received over SMTP, unqualified addresses in header lines | |
30422 | are qualified only if unqualified addresses are permitted in SMTP commands. In | |
30423 | other words, such qualification is also controlled by | |
30424 | %sender_unqualified_hosts% and %recipient_unqualified_hosts%, | |
30425 | ||
30426 | ||
30427 | ||
30428 | ||
30429 | The UUCP From line | |
30430 | ~~~~~~~~~~~~~~~~~~ | |
30431 | cindex:[``From'' line] | |
30432 | cindex:[UUCP,``From'' line] | |
30433 | cindex:[sender,address] | |
30434 | cindex:[%uucp_from_pattern%] | |
30435 | cindex:[%uucp_from_sender%] | |
30436 | cindex:[envelope sender] | |
30437 | cindex:[Sendmail compatibility,``From'' line] | |
30438 | Messages that have come from UUCP (and some other applications) often begin | |
30439 | with a line containing the envelope sender and a timestamp, following the word | |
30440 | ``From''. Examples of two common formats are: | |
30441 | ||
30442 | From a.oakley@berlin.mus Fri Jan 5 12:35 GMT 1996 | |
30443 | From f.butler@berlin.mus Fri, 7 Jan 97 14:00:00 GMT | |
30444 | ||
30445 | This line precedes the RFC 2822 header lines. For compatibility with Sendmail, | |
30446 | Exim recognizes such lines at the start of messages that are submitted to it | |
30447 | via the command line (that is, on the standard input). It does not recognize | |
30448 | such lines in incoming SMTP messages, unless the sending host matches | |
30449 | %ignore_fromline_hosts% or the %-bs% option was used for a local message and | |
30450 | %ignore_fromline_local% is set. The recognition is controlled by a regular | |
30451 | expression that is defined by the %uucp_from_pattern% option, whose default | |
30452 | value matches the two common cases shown above and puts the address that | |
30453 | follows ``From'' into $1$. | |
30454 | ||
30455 | cindex:[numerical variables ($1$ $2$ etc),in ``From '' line handling] | |
30456 | When the caller of Exim for a non-SMTP message that contains a ``From'' line is a | |
30457 | trusted user, the message's sender address is constructed by expanding the | |
30458 | contents of %uucp_sender_address%, whose default value is ``\$1''. This is then | |
30459 | parsed as an RFC 2822 address. If there is no domain, the local part is | |
30460 | qualified with %qualify_domain% unless it is the empty string. However, if the | |
30461 | command line %-f% option is used, it overrides the ``From'' line. | |
30462 | ||
30463 | If the caller of Exim is not trusted, the ``From'' line is recognized, but the | |
30464 | sender address is not changed. This is also the case for incoming SMTP messages | |
30465 | that are permitted to contain ``From'' lines. | |
30466 | ||
30467 | Only one ``From'' line is recognized. If there is more than one, the second is | |
30468 | treated as a data line that starts the body of the message, as it is not valid | |
30469 | as a header line. This also happens if a ``From'' line is present in an incoming | |
30470 | SMTP message from a source that is not permitted to send them. | |
30471 | ||
30472 | ||
30473 | ||
30474 | Resent- header lines | |
30475 | ~~~~~~~~~~~~~~~~~~~~ | |
30476 | cindex:[%Resent-% header lines] | |
30477 | RFC 2822 makes provision for sets of header lines starting with the string | |
30478 | `Resent-` to be added to a message when it is resent by the original | |
30479 | recipient to somebody else. These headers are 'Resent-Date:', 'Resent-From:', | |
30480 | 'Resent-Sender:', 'Resent-To:', 'Resent-Cc:', 'Resent-Bcc:' and | |
30481 | 'Resent-Message-ID:'. The RFC says: | |
30482 | ||
30483 | 'Resent fields are strictly informational. They MUST NOT be used in the normal | |
30484 | processing of replies or other such automatic actions on messages.' | |
30485 | ||
30486 | This leaves things a bit vague as far as other processing actions such as | |
30487 | address rewriting are concerned. Exim treats %Resent-% header lines as | |
30488 | follows: | |
30489 | ||
30490 | - A 'Resent-From:' line that just contains the login id of the submitting user | |
30491 | is automatically rewritten in the same way as 'From:' (see below). | |
30492 | ||
30493 | - If there's a rewriting rule for a particular header line, it is also applied to | |
30494 | %Resent-% header lines of the same type. For example, a rule that rewrites | |
30495 | 'From:' also rewrites 'Resent-From:'. | |
30496 | ||
30497 | - For local messages, if 'Sender:' is removed on input, 'Resent-Sender:' is also | |
30498 | removed. | |
30499 | ||
30500 | - For a locally-submitted message, | |
30501 | if there are any %Resent-% header lines but no 'Resent-Date:', | |
30502 | 'Resent-From:', or 'Resent-Message-Id:', they are added as necessary. It is | |
30503 | the contents of 'Resent-Message-Id:' (rather than 'Message-Id:') which are | |
30504 | included in log lines in this case. | |
30505 | ||
30506 | - The logic for adding 'Sender:' is duplicated for 'Resent-Sender:' when any | |
30507 | %Resent-% header lines are present. | |
30508 | ||
30509 | ||
30510 | ||
30511 | ||
30512 | The Auto-Submitted: header line | |
30513 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
30514 | Whenever Exim generates a bounce or a delay warning message, it includes the | |
30515 | header line | |
30516 | ||
30517 | Auto-Submitted: auto-generated | |
30518 | ||
30519 | ||
30520 | ||
30521 | ||
30522 | The Bcc: header line | |
30523 | ~~~~~~~~~~~~~~~~~~~~ | |
30524 | cindex:['Bcc:' header line] | |
30525 | If Exim is called with the %-t% option, to take recipient addresses from a | |
30526 | message's header, it removes any 'Bcc:' header line that may exist (after | |
30527 | extracting its addresses). If %-t% is not present on the command line, any | |
30528 | existing 'Bcc:' is not removed. | |
30529 | ||
30530 | ||
30531 | The Date: header line | |
30532 | ~~~~~~~~~~~~~~~~~~~~~ | |
068aaea8 | 30533 | [revisionflag="changed"] |
168e428f | 30534 | cindex:['Date:' header line] |
068aaea8 PH |
30535 | If a locally-generated or submission-mode message has no 'Date:' header line, |
30536 | Exim adds one, using the current date and time, unless the | |
30537 | %suppress_local_fixups% control has been specified. | |
168e428f PH |
30538 | |
30539 | ||
30540 | The Delivery-date: header line | |
30541 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
30542 | cindex:['Delivery-date:' header line] | |
30543 | cindex:[%delivery_date_remove%] | |
30544 | 'Delivery-date:' header lines are not part of the standard RFC 2822 header | |
30545 | set. Exim can be configured to add them to the final delivery of messages. (See | |
30546 | the generic %delivery_date_add% transport option.) They should not be present | |
30547 | in messages in transit. If the %delivery_date_remove% configuration option is | |
30548 | set (the default), Exim removes 'Delivery-date:' header lines from incoming | |
30549 | messages. | |
30550 | ||
30551 | ||
30552 | The Envelope-to: header line | |
30553 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
30554 | cindex:['Envelope-to:' header line] | |
30555 | cindex:[%envelope_to_remove%] | |
30556 | 'Envelope-to:' header lines are not part of the standard RFC 2822 header set. | |
30557 | Exim can be configured to add them to the final delivery of messages. (See the | |
30558 | generic %envelope_to_add% transport option.) They should not be present in | |
30559 | messages in transit. If the %envelope_to_remove% configuration option is set | |
30560 | (the default), Exim removes 'Envelope-to:' header lines from incoming | |
30561 | messages. | |
30562 | ||
30563 | ||
30564 | [[SECTthefrohea]] | |
30565 | The From: header line | |
30566 | ~~~~~~~~~~~~~~~~~~~~~ | |
30567 | cindex:['From:' header line] | |
30568 | cindex:[Sendmail compatibility,``From'' line] | |
30569 | cindex:[message,submission] | |
30570 | cindex:[submission mode] | |
30571 | If a submission-mode message does not contain a 'From:' header line, Exim adds | |
30572 | one if either of the following conditions is true: | |
30573 | ||
30574 | - The envelope sender address is not empty (that is, this is not a bounce | |
30575 | message). The added header line copies the envelope sender address. | |
30576 | ||
068aaea8 PH |
30577 | - cindex:[$authenticated_id$] |
30578 | The SMTP session is authenticated and $authenticated_id$ is not empty. | |
168e428f | 30579 | |
068aaea8 PH |
30580 | .. cindex:[$qualify_domain$] |
30581 | If no domain is specified by the submission control, the local part is | |
168e428f PH |
30582 | $authenticated_id$ and the domain is $qualify_domain$. |
30583 | ||
30584 | .. If a non-empty domain is specified by the submission control, the local | |
30585 | part is $authenticated_id$, and the the domain is the specified domain. | |
30586 | ||
30587 | .. If an empty domain is specified by the submission control, | |
30588 | $authenticated_id$ is assumed to be the complete address. | |
30589 | ||
30590 | A non-empty envelope sender takes precedence. | |
30591 | ||
068aaea8 PH |
30592 | [revisionflag="changed"] |
30593 | If a locally-generated incoming message does not contain a 'From:' header line, | |
30594 | and the %suppress_local_fixups% control is not set, Exim adds one containing | |
30595 | the sender's address. The calling user's login name and full name are used to | |
30596 | construct the address, as described in section <<SECTconstr>>. They are | |
30597 | obtained from the password data by calling 'getpwuid()' (but see the | |
30598 | %unknown_login% configuration option). The address is qualified with | |
30599 | %qualify_domain%. | |
168e428f PH |
30600 | |
30601 | For compatibility with Sendmail, if an incoming, non-SMTP message has a | |
30602 | 'From:' header line containing just the unqualified login name of the calling | |
30603 | user, this is replaced by an address containing the user's login name and full | |
30604 | name as described in section <<SECTconstr>>. | |
30605 | ||
30606 | ||
30607 | The Message-ID: header line | |
30608 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
068aaea8 | 30609 | [revisionflag="changed"] |
168e428f PH |
30610 | cindex:['Message-ID:' header line] |
30611 | cindex:[message,submission] | |
068aaea8 | 30612 | cindex:[%message_id_header_text%] |
168e428f | 30613 | If a locally-generated or submission-mode incoming message does not contain a |
068aaea8 PH |
30614 | 'Message-ID:' or 'Resent-Message-ID:' header line, and the |
30615 | %suppress_local_fixups% control is not set, Exim adds a suitable header line to | |
30616 | the message. If there are any 'Resent-:' headers in the message, it creates | |
168e428f PH |
30617 | 'Resent-Message-ID:'. The id is constructed from Exim's internal message id, |
30618 | preceded by the letter E to ensure it starts with a letter, and followed by @ | |
30619 | and the primary host name. Additional information can be included in this | |
068aaea8 PH |
30620 | header line by setting the %message_id_header_text% and/or |
30621 | %message_id_header_domain% options. | |
168e428f PH |
30622 | |
30623 | ||
30624 | ||
30625 | The Received: header line | |
30626 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
30627 | cindex:['Received:' header line] | |
30628 | A 'Received:' header line is added at the start of every message. The contents | |
30629 | are defined by the %received_header_text% configuration option, and Exim | |
30630 | automatically adds a semicolon and a timestamp to the configured string. | |
30631 | ||
30632 | The 'Received:' header is generated as soon as the message's header lines have | |
30633 | been received. At this stage, the timestamp in the 'Received:' header line is | |
30634 | the time that the message started to be received. This is the value that is | |
30635 | seen by the DATA ACL and by the 'local_scan()' function. | |
30636 | ||
30637 | Once a message is accepted, the timestamp in the 'Received:' header line is | |
30638 | changed to the time of acceptance, which is (apart from a small delay while the | |
30639 | -H spool file is written) the earliest time at which delivery could start. | |
30640 | ||
30641 | ||
30642 | ||
30643 | The Return-path: header line | |
30644 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
30645 | cindex:['Return-path:' header line] | |
30646 | cindex:[%return_path_remove%] | |
30647 | 'Return-path:' header lines are defined as something an MTA may insert when | |
30648 | it does the final delivery of messages. (See the generic %return_path_add% | |
30649 | transport option.) Therefore, they should not be present in messages in | |
30650 | transit. If the %return_path_remove% configuration option is set (the | |
30651 | default), Exim removes 'Return-path:' header lines from incoming messages. | |
30652 | ||
30653 | ||
30654 | ||
30655 | [[SECTthesenhea]] | |
30656 | The Sender: header line | |
30657 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
068aaea8 | 30658 | [revisionflag="changed"] |
168e428f PH |
30659 | cindex:['Sender:' header line] |
30660 | cindex:[message,submission] | |
30661 | For a locally-originated message from an untrusted user, Exim may remove an | |
30662 | existing 'Sender:' header line, and it may add a new one. You can modify these | |
068aaea8 PH |
30663 | actions by setting the %local_sender_retain% option true, the |
30664 | %local_from_check% option false, or by using the %suppress_local_fixups% | |
30665 | control setting. | |
168e428f | 30666 | |
068aaea8 PH |
30667 | [revisionflag="changed"] |
30668 | When a local message is received from an untrusted user and %local_from_check% | |
30669 | is true (the default), and the %suppress_local_fixups% control has not been | |
30670 | set, a check is made to see if the address given in the 'From:' header line is | |
30671 | the correct (local) sender of the message. The address that is expected has the | |
30672 | login name as the local part and the value of %qualify_domain% as the domain. | |
30673 | Prefixes and suffixes for the local part can be permitted by setting | |
30674 | %local_from_prefix% and %local_from_suffix% appropriately. If 'From:' does not | |
30675 | contain the correct sender, a 'Sender:' line is added to the message. | |
168e428f PH |
30676 | |
30677 | If you set %local_from_check% false, this checking does not occur. However, | |
30678 | the removal of an existing 'Sender:' line still happens, unless you also set | |
30679 | %local_sender_retain% to be true. It is not possible to set both of these | |
30680 | options true at the same time. | |
30681 | ||
30682 | cindex:[submission mode] | |
30683 | By default, no processing of 'Sender:' header lines is done for messages | |
30684 | received over TCP/IP or for messages submitted by trusted users. However, when | |
30685 | a message is received over TCP/IP in submission mode, and %sender_retain% is | |
30686 | not specified on the submission control, the following processing takes place: | |
30687 | ||
068aaea8 | 30688 | cindex:[$authenticated_id$] |
168e428f PH |
30689 | First, any existing 'Sender:' lines are removed. Then, if the SMTP session is |
30690 | authenticated, and $authenticated_id$ is not empty, a sender address is | |
30691 | created as follows: | |
30692 | ||
068aaea8 PH |
30693 | - cindex:[$qualify_domain$] |
30694 | If no domain is specified by the submission control, the local part is | |
168e428f PH |
30695 | $authenticated_id$ and the domain is $qualify_domain$. |
30696 | ||
068aaea8 PH |
30697 | - If a non-empty domain is specified by the submission control, the local part |
30698 | is $authenticated_id$, and the the domain is the specified domain. | |
168e428f PH |
30699 | |
30700 | - If an empty domain is specified by the submission control, | |
30701 | $authenticated_id$ is assumed to be the complete address. | |
30702 | ||
30703 | This address is compared with the address in the 'From:' header line. If they | |
30704 | are different, a 'Sender:' header line containing the created address is | |
30705 | added. Prefixes and suffixes for the local part in 'From:' can be permitted by | |
30706 | setting %local_from_prefix% and %local_from_suffix% appropriately. | |
30707 | ||
068aaea8 PH |
30708 | [revisionflag="changed"] |
30709 | cindex:[return path,created from 'Sender:'] | |
30710 | *Note*: whenever a 'Sender:' header line is created, the return path for the | |
30711 | message (the envelope sender address) is changed to be the same address, except | |
30712 | in the case of submission mode when %sender_retain% is specified. | |
30713 | ||
168e428f PH |
30714 | |
30715 | ||
30716 | ||
30717 | [[SECTheadersaddrem]] | |
30718 | Adding and removing header lines in routers and transports | |
30719 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
068aaea8 | 30720 | [revisionflag="changed"] |
168e428f PH |
30721 | cindex:[header lines,adding; in router or transport] |
30722 | cindex:[header lines,removing; in router or transport] | |
30723 | When a message is delivered, the addition and removal of header lines can be | |
30724 | specified in a system filter, or on any of the routers and transports that | |
30725 | process the message. Section <<SECTaddremheasys>> contains details about | |
068aaea8 PH |
30726 | modifying headers in a system filter. Header lines can also be added in an ACL |
30727 | as a message is received (see section <<SECTaddheadwarn>>). | |
168e428f PH |
30728 | |
30729 | In contrast to what happens in a system filter, header modifications that are | |
30730 | specified on routers and transports apply only to the particular recipient | |
30731 | addresses that are being processed by those routers and transports. These | |
30732 | changes do not actually take place until a copy of the message is being | |
30733 | transported. Therefore, they do not affect the basic set of header lines, and | |
30734 | they do not affect the values of the variables that refer to header lines. | |
30735 | ||
068aaea8 PH |
30736 | [revisionflag="changed"] |
30737 | *Note*: in particular, this means that any expansions in the configuration of | |
30738 | the transport cannot refer to the modified header lines, because such | |
30739 | expansions all occur before the message is actually transported. | |
30740 | ||
168e428f PH |
30741 | For both routers and transports, the result of expanding a %headers_add% |
30742 | option must be in the form of one or more RFC 2822 header lines, separated by | |
30743 | newlines (coded as ``\n''). For example: | |
30744 | ||
30745 | .... | |
30746 | headers_add = X-added-header: added by $primary_hostname\n\ | |
30747 | X-added-second: another added header line | |
30748 | .... | |
30749 | ||
30750 | Exim does not check the syntax of these added header lines. | |
30751 | ||
30752 | The result of expanding %headers_remove% must consist of a colon-separated | |
30753 | list of header names. This is confusing, because header names themselves are | |
30754 | often terminated by colons. In this case, the colons are the list separators, | |
30755 | not part of the names. For example: | |
30756 | ||
30757 | headers_remove = return-receipt-to:acknowledge-to | |
30758 | ||
30759 | When %headers_add% or %headers_remove% is specified on a router, its value is | |
30760 | expanded at routing time, and then associated with all addresses that are | |
30761 | accepted by that router, and also with any new addresses that it generates. If | |
30762 | an address passes through several routers as a result of aliasing or | |
30763 | forwarding, the changes are cumulative. | |
30764 | ||
30765 | cindex:[%unseen% option] | |
30766 | However, this does not apply to multiple routers that result from the use of | |
30767 | the %unseen% option. Any header modifications that were specified by the | |
30768 | ``unseen'' router or its predecessors apply only to the ``unseen'' delivery. | |
30769 | ||
30770 | Addresses that end up with different %headers_add% or %headers_remove% | |
30771 | settings cannot be delivered together in a batch, so a transport is always | |
30772 | dealing with a set of addresses that have the same header-processing | |
30773 | requirements. | |
30774 | ||
30775 | The transport starts by writing the original set of header lines that arrived | |
30776 | with the message, possibly modified by the system filter. As it writes out | |
30777 | these lines, it consults the list of header names that were attached to the | |
30778 | recipient address(es) by %headers_remove% options in routers, and it also | |
30779 | consults the transport's own %headers_remove% option. Header lines whose names | |
30780 | are on either of these lists are not written out. If there are multiple | |
30781 | instances of any listed header, they are all skipped. | |
30782 | ||
30783 | After the remaining original header lines have been written, new header | |
30784 | lines that were specified by routers' %headers_add% options are written, in | |
30785 | the order in which they were attached to the address. These are followed by any | |
30786 | header lines specified by the transport's %headers_add% option. | |
30787 | ||
30788 | This way of handling header line modifications in routers and transports has | |
30789 | the following consequences: | |
30790 | ||
30791 | - The original set of header lines, possibly modified by the system filter, | |
30792 | remains ``visible'', in the sense that the $header_$'xxx' variables refer to | |
30793 | it, at all times. | |
30794 | ||
30795 | - Header lines that are added by a router's | |
30796 | %headers_add% option are not accessible by means of the $header_$'xxx' | |
30797 | expansion syntax in subsequent routers or the transport. | |
30798 | ||
30799 | - Conversely, header lines that are specified for removal by %headers_remove% in | |
30800 | a router remain visible to subsequent routers and the transport. | |
30801 | ||
30802 | - Headers added to an address by %headers_add% in a router cannot be removed by | |
30803 | a later router or by a transport. | |
30804 | ||
30805 | - An added header can refer to the contents of an original header that is to be | |
30806 | removed, even it has the same name as the added header. For example: | |
30807 | ||
30808 | headers_remove = subject | |
30809 | headers_add = Subject: new subject (was: $h_subject:) | |
30810 | ||
30811 | ||
30812 | *Warning*: The %headers_add% and %headers_remove% options cannot be used | |
30813 | for a ^redirect^ router that has the %one_time% option set. | |
30814 | ||
30815 | ||
30816 | ||
30817 | ||
30818 | ||
30819 | [[SECTconstr]] | |
30820 | Constructed addresses | |
30821 | ~~~~~~~~~~~~~~~~~~~~~ | |
30822 | cindex:[address,constructed] | |
30823 | cindex:[constructed address] | |
30824 | When Exim constructs a sender address for a locally-generated message, it uses | |
30825 | the form | |
30826 | ||
30827 | <user name> <<login>@<qualify_domain>> | |
30828 | ||
30829 | For example: | |
30830 | ||
30831 | Zaphod Beeblebrox <zaphod@end.univ.example> | |
30832 | ||
30833 | The user name is obtained from the %-F% command line option if set, or | |
30834 | otherwise by looking up the calling user by 'getpwuid()' and extracting the | |
30835 | ``gecos'' field from the password entry. If the ``gecos'' field contains an | |
30836 | ampersand character, this is replaced by the login name with the first letter | |
30837 | upper cased, as is conventional in a number of operating systems. See the | |
30838 | %gecos_name% option for a way to tailor the handling of the ``gecos'' field. The | |
30839 | %unknown_username% option can be used to specify user names in cases when | |
30840 | there is no password file entry. | |
30841 | ||
d1e83bff | 30842 | cindex:[RFC 2047] |
168e428f PH |
30843 | In all cases, the user name is made to conform to RFC 2822 by quoting all or |
30844 | parts of it if necessary. In addition, if it contains any non-printing | |
30845 | characters, it is encoded as described in RFC 2047, which defines a way of | |
d1e83bff PH |
30846 | including non-ASCII characters in header lines. The value of the |
30847 | %headers_charset% option specifies the name of the encoding that is used (the | |
30848 | characters are assumed to be in this encoding). The setting of | |
30849 | %print_topbitchars% controls whether characters with the top bit set (that is, | |
30850 | with codes greater than 127) count as printing characters or not. | |
168e428f PH |
30851 | |
30852 | ||
30853 | ||
30854 | Case of local parts | |
30855 | ~~~~~~~~~~~~~~~~~~~ | |
30856 | cindex:[case of local parts] | |
30857 | cindex:[local part,case of] | |
30858 | RFC 2822 states that the case of letters in the local parts of addresses cannot | |
30859 | be assumed to be non-significant. Exim preserves the case of local parts of | |
30860 | addresses, but by default it uses a lower-cased form when it is routing, | |
30861 | because on most Unix systems, usernames are in lower case and case-insensitive | |
30862 | routing is required. However, any particular router can be made to use the | |
30863 | original case for local parts by setting the %caseful_local_part% generic | |
30864 | router option. | |
30865 | ||
30866 | cindex:[mixed-case login names] | |
30867 | If you must have mixed-case user names on your system, the best way to proceed, | |
30868 | assuming you want case-independent handling of incoming email, is to set up | |
30869 | your first router to convert incoming local parts in your domains to the | |
30870 | correct case by means of a file lookup. For example: | |
30871 | ||
30872 | .... | |
30873 | correct_case: | |
30874 | driver = redirect | |
30875 | domains = +local_domains | |
30876 | data = ${lookup{$local_part}cdb\ | |
30877 | {/etc/usercased.cdb}{$value}fail}\ | |
30878 | @$domain | |
30879 | .... | |
30880 | ||
30881 | For this router, the local part is forced to lower case by the default action | |
30882 | (%caseful_local_part% is not set). The lower-cased local part is used to look | |
30883 | up a new local part in the correct case. If you then set %caseful_local_part% | |
30884 | on any subsequent routers which process your domains, they will operate on | |
30885 | local parts with the correct case in a case-sensitive manner. | |
30886 | ||
30887 | ||
30888 | ||
30889 | Dots in local parts | |
30890 | ~~~~~~~~~~~~~~~~~~~ | |
30891 | cindex:[dot,in local part] | |
30892 | cindex:[local part,dots in] | |
30893 | RFC 2822 forbids empty components in local parts. That is, an unquoted local | |
30894 | part may not begin or end with a dot, nor have two consecutive dots in the | |
30895 | middle. However, it seems that many MTAs do not enforce this, so Exim permits | |
30896 | empty components for compatibility. | |
30897 | ||
30898 | ||
30899 | ||
30900 | Rewriting addresses | |
30901 | ~~~~~~~~~~~~~~~~~~~ | |
30902 | cindex:[rewriting,addresses] | |
30903 | Rewriting of sender and recipient addresses, and addresses in headers, can | |
30904 | happen automatically, or as the result of configuration options, as described | |
30905 | in chapter <<CHAPrewrite>>. The headers that may be affected by this are 'Bcc:', | |
30906 | 'Cc:', 'From:', 'Reply-To:', 'Sender:', and 'To:'. | |
30907 | ||
30908 | Automatic rewriting includes qualification, as mentioned above. The other case | |
30909 | in which it can happen is when an incomplete non-local domain is given. The | |
30910 | routing process may cause this to be expanded into the full domain name. For | |
30911 | example, a header such as | |
30912 | ||
30913 | To: hare@teaparty | |
30914 | ||
30915 | might get rewritten as | |
30916 | ||
30917 | To: hare@teaparty.wonderland.fict.example | |
30918 | ||
30919 | Rewriting as a result of routing is the one kind of message processing that | |
30920 | does not happen at input time, as it cannot be done until the address has | |
30921 | been routed. | |
30922 | ||
30923 | Strictly, one should not do 'any' deliveries of a message until all its | |
30924 | addresses have been routed, in case any of the headers get changed as a | |
30925 | result of routing. However, doing this in practice would hold up many | |
30926 | deliveries for unreasonable amounts of time, just because one address could not | |
30927 | immediately be routed. Exim therefore does not delay other deliveries when | |
30928 | routing of one or more addresses is deferred. | |
30929 | ||
30930 | ||
30931 | //////////////////////////////////////////////////////////////////////////// | |
30932 | //////////////////////////////////////////////////////////////////////////// | |
30933 | ||
30934 | [[CHAPSMTP]] | |
30935 | SMTP processing | |
30936 | --------------- | |
30937 | cindex:[SMTP,processing details] | |
30938 | cindex:[LMTP,processing details] | |
30939 | Exim supports a number of different ways of using the SMTP protocol, and its | |
30940 | LMTP variant, which is an interactive protocol for transferring messages into a | |
30941 | closed mail store application. This chapter contains details of how SMTP is | |
30942 | processed. For incoming mail, the following are available: | |
30943 | ||
30944 | - SMTP over TCP/IP (Exim daemon or 'inetd'); | |
30945 | ||
30946 | - SMTP over the standard input and output (the %-bs% option); | |
30947 | ||
30948 | - Batched SMTP on the standard input (the %-bS% option). | |
30949 | ||
30950 | For mail delivery, the following are available: | |
30951 | ||
30952 | - SMTP over TCP/IP (the ^smtp^ transport); | |
30953 | ||
30954 | - LMTP over TCP/IP (the ^smtp^ transport with the %protocol% option set to | |
30955 | ``lmtp''); | |
30956 | ||
30957 | - LMTP over a pipe to a process running in the local host (the ^lmtp^ | |
30958 | transport); | |
30959 | ||
30960 | - Batched SMTP to a file or pipe (the ^appendfile^ and ^pipe^ transports with | |
30961 | the %use_bsmtp% option set). | |
30962 | ||
30963 | 'Batched SMTP' is the name for a process in which batches of messages are | |
30964 | stored in or read from files (or pipes), in a format in which SMTP commands are | |
30965 | used to contain the envelope information. | |
30966 | ||
30967 | ||
30968 | ||
30969 | [[SECToutSMTPTCP]] | |
30970 | Outgoing SMTP and LMTP over TCP/IP | |
30971 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
30972 | cindex:[SMTP,outgoing over TCP/IP] | |
30973 | cindex:[outgoing SMTP over TCP/IP] | |
30974 | cindex:[LMTP,over TCP/IP] | |
30975 | cindex:[outgoing LMTP over TCP/IP] | |
30976 | cindex:[EHLO] | |
30977 | cindex:[HELO] | |
30978 | cindex:[SIZE option on MAIL command] | |
30979 | Outgoing SMTP and LMTP over TCP/IP is implemented by the ^smtp^ transport. | |
30980 | The %protocol% option selects which protocol is to be used, but the actual | |
30981 | processing is the same in both cases. | |
30982 | ||
30983 | If, in response to its EHLO command, Exim is told that the SIZE | |
30984 | parameter is supported, it adds SIZE=<'n'> to each subsequent MAIL | |
30985 | command. The value of <'n'> is the message size plus the value of the | |
30986 | %size_addition% option (default 1024) to allow for additions to the message | |
30987 | such as per-transport header lines, or changes made in a | |
30988 | cindex:[transport,filter] | |
30989 | cindex:[filter,transport filter] | |
30990 | transport filter. If %size_addition% is set negative, the use of SIZE is | |
30991 | suppressed. | |
30992 | ||
30993 | If the remote server advertises support for PIPELINING, Exim uses the | |
30994 | pipelining extension to SMTP (RFC 2197) to reduce the number of TCP/IP packets | |
30995 | required for the transaction. | |
30996 | ||
30997 | If the remote server advertises support for the STARTTLS command, and Exim | |
30998 | was built to support TLS encryption, it tries to start a TLS session unless the | |
30999 | server matches %hosts_avoid_tls%. See chapter <<CHAPTLS>> for more details. | |
31000 | ||
31001 | If the remote server advertises support for the AUTH command, Exim scans | |
31002 | the authenticators configuration for any suitable client settings, as described | |
31003 | in chapter <<CHAPSMTPAUTH>>. | |
31004 | ||
31005 | cindex:[carriage return] | |
31006 | cindex:[linefeed] | |
31007 | Responses from the remote host are supposed to be terminated by CR followed by | |
31008 | LF. However, there are known to be hosts that do not send CR characters, so in | |
31009 | order to be able to interwork with such hosts, Exim treats LF on its own as a | |
31010 | line terminator. | |
31011 | ||
31012 | If a message contains a number of different addresses, all those with the same | |
31013 | characteristics (for example, the same envelope sender) that resolve to the | |
31014 | same set of hosts, in the same order, are sent in a single SMTP transaction, | |
31015 | even if they are for different domains, unless there are more than the setting | |
31016 | of the %max_rcpts% option in the ^smtp^ transport allows, in which case they | |
31017 | are split into groups containing no more than %max_rcpts% addresses each. If | |
31018 | %remote_max_parallel% is greater than one, such groups may be sent in | |
31019 | parallel sessions. The order of hosts with identical MX values is not | |
31020 | significant when checking whether addresses can be batched in this way. | |
31021 | ||
31022 | When the ^smtp^ transport suffers a temporary failure that is not | |
31023 | message-related, Exim updates its transport-specific database, which contains | |
31024 | records indexed by host name that remember which messages are waiting for each | |
31025 | particular host. It also updates the retry database with new retry times. | |
31026 | ||
31027 | cindex:[hints database,retry keys] | |
31028 | Exim's retry hints are based on host name plus IP address, so if one address of | |
31029 | a multi-homed host is broken, it will soon be skipped most of the time. | |
31030 | See the next section for more detail about error handling. | |
31031 | ||
31032 | cindex:[SMTP,passed connection] | |
31033 | cindex:[SMTP,batching over TCP/IP] | |
31034 | When a message is successfully delivered over a TCP/IP SMTP connection, Exim | |
31035 | looks in the hints database for the transport to see if there are any queued | |
31036 | messages waiting for the host to which it is connected. If it finds one, it | |
31037 | creates a new Exim process using the %-MC% option (which can only be used by a | |
31038 | process running as root or the Exim user) and passes the TCP/IP socket to it so | |
31039 | that it can deliver another message using the same socket. The new process does | |
31040 | only those deliveries that are routed to the connected host, and may in turn | |
31041 | pass the socket on to a third process, and so on. | |
31042 | ||
31043 | The %connection_max_messages% option of the ^smtp^ transport can be used to | |
31044 | limit the number of messages sent down a single TCP/IP connection. | |
31045 | ||
31046 | cindex:[asterisk,after IP address] | |
31047 | The second and subsequent messages delivered down an existing connection are | |
31048 | identified in the main log by the addition of an asterisk after the closing | |
31049 | square bracket of the IP address. | |
31050 | ||
31051 | ||
31052 | ||
31053 | ||
31054 | [[SECToutSMTPerr]] | |
31055 | Errors in outgoing SMTP | |
31056 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
31057 | cindex:[error,in outgoing SMTP] | |
31058 | cindex:[SMTP,errors in outgoing] | |
31059 | cindex:[host,error] | |
31060 | Three different kinds of error are recognized for outgoing SMTP: host errors, | |
31061 | message errors, and recipient errors. | |
31062 | ||
31063 | . A host error is not associated with a particular message or with a | |
31064 | particular recipient of a message. The host errors are: | |
31065 | + | |
31066 | -- | |
31067 | - Connection refused or timed out, | |
31068 | ||
31069 | - Any error response code on connection, | |
31070 | ||
31071 | - Any error response code to EHLO or HELO, | |
31072 | ||
31073 | - Loss of connection at any time, except after ``.'', | |
31074 | ||
31075 | - I/O errors at any time, | |
31076 | ||
31077 | - Timeouts during the session, other than in response to MAIL, RCPT or | |
31078 | the ``.'' at the end of the data. | |
31079 | -- | |
31080 | + | |
31081 | For a host error, a permanent error response on connection, or in response to | |
31082 | EHLO, causes all addresses routed to the host to be failed. Any other host | |
31083 | error causes all addresses to be deferred, and retry data to be created for the | |
31084 | host. It is not tried again, for any message, until its retry time arrives. If | |
31085 | the current set of addresses are not all delivered in this run (to some | |
31086 | alternative host), the message is added to the list of those waiting for this | |
31087 | host, so if it is still undelivered when a subsequent successful delivery is | |
31088 | made to the host, it will be sent down the same SMTP connection. | |
31089 | ||
31090 | . cindex:[message,error] | |
31091 | A message error is associated with a particular message when sent to a | |
31092 | particular host, but not with a particular recipient of the message. The | |
31093 | message errors are: | |
31094 | + | |
31095 | -- | |
31096 | - Any error response code to MAIL, DATA, or the ``.'' that terminates | |
31097 | the data, | |
31098 | ||
31099 | - Timeout after MAIL, | |
31100 | ||
31101 | - Timeout or loss of connection after the ``.'' that terminates the data. A | |
31102 | timeout after the DATA command itself is treated as a host error, as is loss of | |
31103 | connection at any other time. | |
31104 | -- | |
31105 | + | |
31106 | For a message error, a permanent error response (5##'xx') causes all addresses | |
31107 | to be failed, and a delivery error report to be returned to the sender. A | |
31108 | temporary error response (4##'xx'), or one of the timeouts, causes all | |
31109 | addresses to be deferred. Retry data is not created for the host, but instead, | |
31110 | a retry record for the combination of host plus message id is created. The | |
31111 | message is not added to the list of those waiting for this host. This ensures | |
31112 | that the failing message will not be sent to this host again until the retry | |
31113 | time arrives. However, other messages that are routed to the host are not | |
31114 | affected, so if it is some property of the message that is causing the error, | |
31115 | it will not stop the delivery of other mail. | |
31116 | + | |
31117 | If the remote host specified support for the SIZE parameter in its response | |
31118 | to EHLO, Exim adds SIZE='nnn' to the MAIL command, so an | |
31119 | over-large message will cause a message error because the error arrives as a | |
31120 | response to MAIL. | |
31121 | ||
31122 | . cindex:[recipient,error] | |
31123 | A recipient error is associated with a particular recipient of a message. The | |
31124 | recipient errors are: | |
31125 | + | |
31126 | -- | |
31127 | - Any error response to RCPT, | |
31128 | ||
31129 | - Timeout after RCPT. | |
31130 | -- | |
31131 | + | |
31132 | For a recipient error, a permanent error response (5##'xx') causes the | |
31133 | recipient address to be failed, and a bounce message to be returned to the | |
31134 | sender. A temporary error response (4##'xx') or a timeout causes the failing | |
31135 | address to be deferred, and routing retry data to be created for it. This is | |
31136 | used to delay processing of the address in subsequent queue runs, until its | |
31137 | routing retry time arrives. This applies to all messages, but because it | |
31138 | operates only in queue runs, one attempt will be made to deliver a new message | |
31139 | to the failing address before the delay starts to operate. This ensures that, | |
31140 | if the failure is really related to the message rather than the recipient | |
31141 | (``message too big for this recipient'' is a possible example), other messages | |
31142 | have a chance of getting delivered. If a delivery to the address does succeed, | |
31143 | the retry information gets cleared, so all stuck messages get tried again, and | |
31144 | the retry clock is reset. | |
31145 | + | |
31146 | The message is not added to the list of those waiting for this host. Use of the | |
31147 | host for other messages is unaffected, and except in the case of a timeout, | |
31148 | other recipients are processed independently, and may be successfully delivered | |
31149 | in the current SMTP session. After a timeout it is of course impossible to | |
31150 | proceed with the session, so all addresses get deferred. However, those other | |
31151 | than the one that failed do not suffer any subsequent retry delays. Therefore, | |
31152 | if one recipient is causing trouble, the others have a chance of getting | |
31153 | through when a subsequent delivery attempt occurs before the failing | |
31154 | recipient's retry time. | |
31155 | ||
31156 | /// | |
31157 | End of list | |
31158 | /// | |
31159 | ||
31160 | In all cases, if there are other hosts (or IP addresses) available for the | |
31161 | current set of addresses (for example, from multiple MX records), they are | |
31162 | tried in this run for any undelivered addresses, subject of course to their | |
31163 | own retry data. In other words, recipient error retry data does not take effect | |
31164 | until the next delivery attempt. | |
31165 | ||
31166 | Some hosts have been observed to give temporary error responses to every | |
31167 | MAIL command at certain times (``insufficient space'' has been seen). It | |
31168 | would be nice if such circumstances could be recognized, and defer data for the | |
31169 | host itself created, but this is not possible within the current Exim design. | |
31170 | What actually happens is that retry data for every (host, message) combination | |
31171 | is created. | |
31172 | ||
31173 | The reason that timeouts after MAIL and RCPT are treated specially is that | |
31174 | these can sometimes arise as a result of the remote host's verification | |
31175 | procedures. Exim makes this assumption, and treats them as if a temporary error | |
31176 | response had been received. A timeout after ``.'' is treated specially because | |
31177 | it is known that some broken implementations fail to recognize the end of the | |
31178 | message if the last character of the last line is a binary zero. Thus, it is | |
31179 | helpful to treat this case as a message error. | |
31180 | ||
31181 | Timeouts at other times are treated as host errors, assuming a problem with the | |
31182 | host, or the connection to it. If a timeout after MAIL, RCPT, | |
31183 | or ``.'' is really a connection problem, the assumption is that at the next try | |
31184 | the timeout is likely to occur at some other point in the dialogue, causing it | |
31185 | then to be treated as a host error. | |
31186 | ||
31187 | There is experimental evidence that some MTAs drop the connection after the | |
31188 | terminating ``.'' if they do not like the contents of the message for some | |
31189 | reason, in contravention of the RFC, which indicates that a 5##'xx' response | |
31190 | should be given. That is why Exim treats this case as a message rather than a | |
31191 | host error, in order not to delay other messages to the same host. | |
31192 | ||
31193 | ||
31194 | ||
31195 | ||
31196 | ||
31197 | Variable Envelope Return Paths (VERP) | |
31198 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
31199 | cindex:[VERP] | |
31200 | cindex:[Variable Envelope Return Paths] | |
31201 | cindex:[envelope sender] | |
31202 | Variable Envelope Return Paths -- see | |
31203 | *ftp://koobera.math.uic.edu/www/proto/verp.txt[]* -- can be supported in Exim | |
31204 | by using the %return_path% generic transport option to rewrite the return path | |
31205 | at transport time. For example, the following could be used on an ^smtp^ | |
31206 | transport: | |
31207 | ||
31208 | .... | |
31209 | return_path = \ | |
31210 | ${if match {$return_path}{^(.+?)-request@your.dom.example\$}\ | |
31211 | {$1-request=$local_part%$domain@your.dom.example}fail} | |
31212 | .... | |
31213 | ||
31214 | This has the effect of rewriting the return path (envelope sender) on all | |
31215 | outgoing SMTP messages, if the local part of the original return path ends in | |
31216 | ``-request'', and the domain is 'your.dom.example'. The rewriting inserts the | |
31217 | local part and domain of the recipient into the return path. Suppose, for | |
31218 | example, that a message whose return path has been set to | |
31219 | 'somelist-request@your.dom.example' is sent to | |
31220 | 'subscriber@other.dom.example'. In the transport, the return path is | |
31221 | rewritten as | |
31222 | ||
31223 | somelist-request=subscriber%other.dom.example@your.dom.example | |
31224 | ||
31225 | For this to work, you must arrange for outgoing messages that have ``-request'' | |
31226 | in their return paths to have just a single recipient. This can be done by | |
31227 | setting | |
31228 | ||
31229 | max_rcpt = 1 | |
31230 | ||
068aaea8 | 31231 | cindex:[$local_part$] |
168e428f PH |
31232 | in the ^smtp^ transport. Otherwise a single copy of a message might be |
31233 | addressed to several different recipients in the same domain, in which case | |
31234 | $local_part$ is not available (because it is not unique). Of course, if you | |
31235 | do start sending out messages with this kind of return path, you must also | |
31236 | configure Exim to accept the bounce messages that come back to those paths. | |
31237 | Typically this would be done by setting an %local_part_suffix% option for a | |
31238 | suitable router. | |
31239 | ||
31240 | The overhead incurred in using VERP depends very much on the size of the | |
31241 | message, the number of recipient addresses that resolve to the same remote | |
31242 | host, and the speed of the connection over which the message is being sent. If | |
31243 | a lot of addresses resolve to the same host and the connection is slow, sending | |
31244 | a separate copy of the message for each address may take substantially longer | |
31245 | than sending a single copy with many recipients (for which VERP cannot be | |
31246 | used). | |
31247 | ||
31248 | ||
31249 | ||
31250 | Incoming SMTP messages over TCP/IP | |
31251 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
31252 | cindex:[SMTP,incoming over TCP/IP] | |
31253 | cindex:[incoming SMTP over TCP/IP] | |
31254 | cindex:[inetd] | |
31255 | cindex:[daemon] | |
31256 | Incoming SMTP messages can be accepted in one of two ways: by running a | |
31257 | listening daemon, or by using 'inetd'. In the latter case, the entry in | |
31258 | _/etc/inetd.conf_ should be like this: | |
31259 | ||
31260 | smtp stream tcp nowait exim /opt/exim/bin/exim in.exim -bs | |
31261 | ||
31262 | Exim distinguishes between this case and the case of a locally running user | |
31263 | agent using the %-bs% option by checking whether or not the standard input is | |
31264 | a socket. When it is, either the port must be privileged (less than 1024), or | |
31265 | the caller must be root or the Exim user. If any other user passes a socket | |
31266 | with an unprivileged port number, Exim prints a message on the standard error | |
31267 | stream and exits with an error code. | |
31268 | ||
31269 | By default, Exim does not make a log entry when a remote host connects or | |
31270 | disconnects (either via the daemon or 'inetd'), unless the disconnection is | |
31271 | unexpected. It can be made to write such log entries by setting the | |
31272 | %smtp_connection% log selector. | |
31273 | ||
31274 | cindex:[carriage return] | |
31275 | cindex:[linefeed] | |
31276 | Commands from the remote host are supposed to be terminated by CR followed by | |
31277 | LF. However, there are known to be hosts that do not send CR characters. In | |
31278 | order to be able to interwork with such hosts, Exim treats LF on its own as a | |
31279 | line terminator. | |
31280 | Furthermore, because common code is used for receiving messages from all | |
31281 | sources, a CR on its own is also interpreted as a line terminator. However, the | |
31282 | sequence ``CR, dot, CR'' does not terminate incoming SMTP data. | |
31283 | ||
31284 | cindex:[EHLO,invalid data] | |
31285 | cindex:[HELO,invalid data] | |
31286 | One area that sometimes gives rise to problems concerns the EHLO or | |
31287 | HELO commands. Some clients send syntactically invalid versions of these | |
31288 | commands, which Exim rejects by default. (This is nothing to do with verifying | |
31289 | the data that is sent, so %helo_verify_hosts% is not relevant.) You can tell | |
31290 | Exim not to apply a syntax check by setting %helo_accept_junk_hosts% to | |
31291 | match the broken hosts that send invalid commands. | |
31292 | ||
31293 | cindex:[SIZE option on MAIL command] | |
31294 | cindex:[MAIL,SIZE option] | |
31295 | The amount of disk space available is checked whenever SIZE is received on | |
31296 | a MAIL command, independently of whether %message_size_limit% or | |
31297 | %check_spool_space% is configured, unless %smtp_check_spool_space% is set | |
31298 | false. A temporary error is given if there is not enough space. If | |
31299 | %check_spool_space% is set, the check is for that amount of space plus the | |
31300 | value given with SIZE, that is, it checks that the addition of the incoming | |
31301 | message will not reduce the space below the threshold. | |
31302 | ||
31303 | When a message is successfully received, Exim includes the local message id in | |
31304 | its response to the final ``.'' that terminates the data. If the remote host logs | |
31305 | this text it can help with tracing what has happened to a message. | |
31306 | ||
31307 | The Exim daemon can limit the number of simultaneous incoming connections it is | |
31308 | prepared to handle (see the %smtp_accept_max% option). It can also limit the | |
31309 | number of simultaneous incoming connections from a single remote host (see the | |
31310 | %smtp_accept_max_per_host% option). Additional connection attempts are | |
31311 | rejected using the SMTP temporary error code 421. | |
31312 | ||
31313 | The Exim daemon does not rely on the SIGCHLD signal to detect when a | |
31314 | subprocess has finished, as this can get lost at busy times. Instead, it looks | |
31315 | for completed subprocesses every time it wakes up. Provided there are other | |
31316 | things happening (new incoming calls, starts of queue runs), completed | |
31317 | processes will be noticed and tidied away. On very quiet systems you may | |
31318 | sometimes see a ``defunct'' Exim process hanging about. This is not a problem; it | |
31319 | will be noticed when the daemon next wakes up. | |
31320 | ||
31321 | When running as a daemon, Exim can reserve some SMTP slots for specific hosts, | |
31322 | and can also be set up to reject SMTP calls from non-reserved hosts at times of | |
31323 | high system load -- for details see the %smtp_accept_reserve%, | |
31324 | %smtp_load_reserve%, and %smtp_reserve_hosts% options. The load check | |
31325 | applies in both the daemon and 'inetd' cases. | |
31326 | ||
31327 | Exim normally starts a delivery process for each message received, though this | |
31328 | can be varied by means of the %-odq% command line option and the | |
31329 | %queue_only%, %queue_only_file%, and %queue_only_load% options. The number | |
31330 | of simultaneously running delivery processes started in this way from SMTP | |
31331 | input can be limited by the %smtp_accept_queue% and | |
31332 | %smtp_accept_queue_per_connection% options. When either limit is reached, | |
31333 | subsequently received messages are just put on the input queue without starting | |
31334 | a delivery process. | |
31335 | ||
31336 | The controls that involve counts of incoming SMTP calls (%smtp_accept_max%, | |
31337 | %smtp_accept_queue%, %smtp_accept_reserve%) are not available when Exim is | |
31338 | started up from the 'inetd' daemon, because in that case each connection is | |
31339 | handled by an entirely independent Exim process. Control by load average is, | |
31340 | however, available with 'inetd'. | |
31341 | ||
31342 | Exim can be configured to verify addresses in incoming SMTP commands as they | |
31343 | are received. See chapter <<CHAPACL>> for details. It can also be configured to | |
31344 | rewrite addresses at this time -- before any syntax checking is done. See | |
31345 | section <<SECTrewriteS>>. | |
31346 | ||
31347 | Exim can also be configured to limit the rate at which a client host submits | |
31348 | MAIL and RCPT commands in a single SMTP session. See the | |
31349 | %smtp_ratelimit_hosts% option. | |
31350 | ||
31351 | ||
31352 | ||
31353 | Unrecognized SMTP commands | |
31354 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
31355 | cindex:[SMTP,unrecognized commands] | |
31356 | If Exim receives more than %smtp_max_unknown_commands% unrecognized SMTP | |
31357 | commands during a single SMTP connection, it drops the connection after sending | |
31358 | the error response to the last command. The default value for | |
31359 | %smtp_max_unknown_commands% is 3. This is a defence against some kinds of | |
31360 | abuse that subvert web servers into making connections to SMTP ports; in these | |
31361 | circumstances, a number of non-SMTP lines are sent first. | |
31362 | ||
31363 | ||
31364 | Syntax and protocol errors in SMTP commands | |
31365 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
31366 | cindex:[SMTP,syntax errors] | |
31367 | cindex:[SMTP,protocol errors] | |
31368 | A syntax error is detected if an SMTP command is recognized, but there is | |
31369 | something syntactically wrong with its data, for example, a malformed email | |
31370 | address in a RCPT command. Protocol errors include invalid command | |
31371 | sequencing such as RCPT before MAIL. If Exim receives more than | |
31372 | %smtp_max_synprot_errors% such commands during a single SMTP connection, it | |
31373 | drops the connection after sending the error response to the last command. The | |
31374 | default value for %smtp_max_synprot_errors% is 3. This is a defence against | |
31375 | broken clients that loop sending bad commands (yes, it has been seen). | |
31376 | ||
31377 | ||
31378 | ||
31379 | Use of non-mail SMTP commands | |
31380 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
31381 | cindex:[SMTP,non-mail commands] | |
31382 | The ``non-mail'' SMTP commands are those other than MAIL, RCPT, and | |
31383 | DATA. Exim counts such commands, and drops the connection if there are too | |
31384 | many of them in a single SMTP session. This action catches some | |
31385 | denial-of-service attempts and things like repeated failing AUTHs, or a mad | |
31386 | client looping sending EHLO. The global option %smtp_accept_max_nonmail% | |
31387 | defines what ``too many'' means. Its default value is 10. | |
31388 | ||
31389 | When a new message is expected, one occurrence of RSET is not counted. This | |
31390 | allows a client to send one RSET between messages (this is not necessary, | |
31391 | but some clients do it). Exim also allows one uncounted occurence of HELO | |
31392 | or EHLO, and one occurrence of STARTTLS between messages. After | |
31393 | starting up a TLS session, another EHLO is expected, and so it too is not | |
31394 | counted. | |
31395 | ||
31396 | The first occurrence of AUTH in a connection, or immediately following | |
31397 | STARTTLS is also not counted. Otherwise, all commands other than MAIL, | |
31398 | RCPT, DATA, and QUIT are counted. | |
31399 | ||
31400 | You can control which hosts are subject to the limit set by | |
31401 | %smtp_accept_max_nonmail% by setting | |
31402 | %smtp_accept_max_nonmail_hosts%. The default value is `\*`, which makes | |
31403 | the limit apply to all hosts. This option means that you can exclude any | |
31404 | specific badly-behaved hosts that you have to live with. | |
31405 | ||
31406 | ||
31407 | ||
31408 | ||
31409 | The VRFY and EXPN commands | |
31410 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
31411 | When Exim receives a VRFY or EXPN command on a TCP/IP connection, it | |
31412 | runs the ACL specified by %acl_smtp_vrfy% or %acl_smtp_expn% (as | |
31413 | appropriate) in order to decide whether the command should be accepted or not. | |
31414 | If no ACL is defined, the command is rejected. | |
31415 | ||
31416 | cindex:[VRFY,processing] | |
31417 | When VRFY is accepted, it runs exactly the same code as when Exim is | |
31418 | called with the %-bv% option. | |
31419 | ||
31420 | cindex:[EXPN,processing] | |
31421 | When EXPN is accepted, a single-level expansion of the address is done. | |
31422 | EXPN is treated as an ``address test'' (similar to the %-bt% option) rather | |
31423 | than a verification (the %-bv% option). If an unqualified local part is given | |
31424 | as the argument to EXPN, it is qualified with %qualify_domain%. Rejections | |
31425 | of VRFY and EXPN commands are logged on the main and reject logs, and | |
31426 | VRFY verification failures are logged on the main log for consistency with | |
31427 | RCPT failures. | |
31428 | ||
31429 | ||
31430 | ||
31431 | [[SECTETRN]] | |
31432 | The ETRN command | |
31433 | ~~~~~~~~~~~~~~~~ | |
31434 | cindex:[ETRN,processing] | |
31435 | RFC 1985 describes an SMTP command called ETRN that is designed to | |
31436 | overcome the security problems of the TURN command (which has fallen into | |
31437 | disuse). When Exim receives an ETRN command on a TCP/IP connection, it runs | |
31438 | the ACL specified by %acl_smtp_etrn% in order to decide whether the command | |
31439 | should be accepted or not. If no ACL is defined, the command is rejected. | |
31440 | ||
31441 | The ETRN command is concerned with ``releasing'' messages that are awaiting | |
31442 | delivery to certain hosts. As Exim does not organize its message queue by host, | |
31443 | the only form of ETRN that is supported by default is the one where the | |
31444 | text starts with the ``#'' prefix, in which case the remainder of the text is | |
31445 | specific to the SMTP server. A valid ETRN command causes a run of Exim with | |
31446 | the %-R% option to happen, with the remainder of the ETRN text as its | |
31447 | argument. For example, | |
31448 | ||
31449 | ETRN #brigadoon | |
31450 | ||
31451 | runs the command | |
31452 | ||
31453 | exim -R brigadoon | |
31454 | ||
31455 | which causes a delivery attempt on all messages with undelivered addresses | |
31456 | containing the text ``brigadoon''. When %smtp_etrn_serialize% is set (the | |
31457 | default), Exim prevents the simultaneous execution of more than one queue run | |
31458 | for the same argument string as a result of an ETRN command. This stops | |
31459 | a misbehaving client from starting more than one queue runner at once. | |
31460 | ||
31461 | cindex:[hints database,ETRN serialization] | |
31462 | Exim implements the serialization by means of a hints database in which a | |
31463 | record is written whenever a process is started by ETRN, and deleted when | |
31464 | the process completes. However, Exim does not keep the SMTP session waiting for | |
31465 | the ETRN process to complete. Once ETRN is accepted, the client is sent | |
31466 | a ``success'' return code. Obviously there is scope for hints records to get left | |
31467 | lying around if there is a system or program crash. To guard against this, Exim | |
31468 | ignores any records that are more than six hours old. | |
31469 | ||
31470 | cindex:[%smtp_etrn_command%] | |
31471 | For more control over what ETRN does, the %smtp_etrn_command% option can | |
31472 | used. This specifies a command that is run whenever ETRN is received, | |
31473 | whatever the form of its argument. For | |
31474 | example: | |
31475 | ||
31476 | smtp_etrn_command = /etc/etrn_command $domain $sender_host_address | |
31477 | ||
068aaea8 | 31478 | cindex:[$domain$] |
168e428f PH |
31479 | The string is split up into arguments which are independently expanded. The |
31480 | expansion variable $domain$ is set to the argument of the ETRN command, | |
31481 | and no syntax checking is done on the contents of this argument. Exim does not | |
31482 | wait for the command to complete, so its status code is not checked. Exim runs | |
31483 | under its own uid and gid when receiving incoming SMTP, so it is not possible | |
31484 | for it to change them before running the command. | |
31485 | ||
31486 | ||
31487 | ||
31488 | Incoming local SMTP | |
31489 | ~~~~~~~~~~~~~~~~~~~ | |
31490 | cindex:[SMTP,local incoming] | |
31491 | Some user agents use SMTP to pass messages to their local MTA using the | |
31492 | standard input and output, as opposed to passing the envelope on the command | |
31493 | line and writing the message to the standard input. This is supported by the | |
31494 | %-bs% option. This form of SMTP is handled in the same way as incoming | |
31495 | messages over TCP/IP (including the use of ACLs), except that the envelope | |
31496 | sender given in a MAIL command is ignored unless the caller is trusted. In | |
31497 | an ACL you can detect this form of SMTP input by testing for an empty host | |
31498 | identification. It is common to have this as the first line in the ACL that | |
31499 | runs for RCPT commands: | |
31500 | ||
31501 | accept hosts = : | |
31502 | ||
31503 | This accepts SMTP messages from local processes without doing any other tests. | |
31504 | ||
31505 | ||
31506 | ||
31507 | [[SECTbatchSMTP]] | |
31508 | Outgoing batched SMTP | |
31509 | ~~~~~~~~~~~~~~~~~~~~~ | |
31510 | cindex:[SMTP,batched outgoing] | |
31511 | cindex:[batched SMTP output] | |
31512 | Both the ^appendfile^ and ^pipe^ transports can be used for handling batched | |
31513 | SMTP. Each has an option called %use_bsmtp% which causes messages to be output | |
31514 | in BSMTP format. No SMTP responses are possible for this form of delivery. All | |
31515 | it is doing is using SMTP commands as a way of transmitting the envelope along | |
31516 | with the message. | |
31517 | ||
31518 | The message is written to the file or pipe preceded by the SMTP commands | |
31519 | MAIL and RCPT, and followed by a line containing a single dot. Lines in | |
31520 | the message that start with a dot have an extra dot added. The SMTP command | |
31521 | HELO is not normally used. If it is required, the %message_prefix% option | |
31522 | can be used to specify it. | |
31523 | ||
31524 | Because ^appendfile^ and ^pipe^ are both local transports, they accept only | |
31525 | one recipient address at a time by default. However, you can arrange for them | |
31526 | to handle several addresses at once by setting the %batch_max% option. When | |
31527 | this is done for BSMTP, messages may contain multiple RCPT commands. See | |
31528 | chapter <<CHAPbatching>> for more details. | |
31529 | ||
068aaea8 | 31530 | cindex:[$host$] |
168e428f PH |
31531 | When one or more addresses are routed to a BSMTP transport by a router that |
31532 | sets up a host list, the name of the first host on the list is available to the | |
31533 | transport in the variable $host$. Here is an example of such a transport and | |
31534 | router: | |
31535 | ||
31536 | begin routers | |
31537 | route_append: | |
31538 | driver = manualroute | |
31539 | transport = smtp_appendfile | |
31540 | route_list = domain.example batch.host.example | |
31541 | ||
31542 | begin transports | |
31543 | smtp_appendfile: | |
31544 | driver = appendfile | |
31545 | directory = /var/bsmtp/$host | |
31546 | batch_max = 1000 | |
31547 | use_bsmtp | |
31548 | user = exim | |
31549 | ||
31550 | This causes messages addressed to 'domain.example' to be written in BSMTP | |
31551 | format to _/var/bsmtp/batch.host.example_, with only a single copy of each | |
31552 | message (unless there are more than 1000 recipients). | |
31553 | ||
31554 | ||
31555 | ||
31556 | [[SECTincomingbatchedSMTP]] | |
31557 | Incoming batched SMTP | |
31558 | ~~~~~~~~~~~~~~~~~~~~~ | |
31559 | cindex:[SMTP,batched incoming] | |
31560 | cindex:[batched SMTP input] | |
31561 | The %-bS% command line option causes Exim to accept one or more messages by | |
31562 | reading SMTP on the standard input, but to generate no responses. If the caller | |
31563 | is trusted, the senders in the MAIL commands are believed; otherwise the | |
31564 | sender is always the caller of Exim. Unqualified senders and receivers are not | |
31565 | rejected (there seems little point) but instead just get qualified. HELO | |
31566 | and EHLO act as RSET; VRFY, EXPN, ETRN and HELP, act | |
31567 | as NOOP; QUIT quits. | |
31568 | ||
31569 | No policy checking is done for BSMTP input. That is, no ACL is run at anytime. | |
31570 | In this respect it is like non-SMTP local input. | |
31571 | ||
31572 | If an error is detected while reading a message, including a missing ``.'' at | |
31573 | the end, Exim gives up immediately. It writes details of the error to the | |
31574 | standard output in a stylized way that the calling program should be able to | |
31575 | make some use of automatically, for example: | |
31576 | ||
31577 | 554 Unexpected end of file | |
31578 | Transaction started in line 10 | |
31579 | Error detected in line 14 | |
31580 | ||
31581 | It writes a more verbose version, for human consumption, to the standard error | |
31582 | file, for example: | |
31583 | ||
31584 | An error was detected while processing a file of BSMTP input. | |
31585 | The error message was: | |
31586 | ||
31587 | 501 '>' missing at end of address | |
31588 | ||
31589 | The SMTP transaction started in line 10. | |
31590 | The error was detected in line 12. | |
31591 | The SMTP command at fault was: | |
31592 | ||
31593 | rcpt to:<malformed@in.com.plete | |
31594 | ||
31595 | 1 previous message was successfully processed. | |
31596 | The rest of the batch was abandoned. | |
31597 | ||
31598 | The return code from Exim is zero only if there were no errors. It is 1 if some | |
31599 | messages were accepted before an error was detected, and 2 if no messages were | |
31600 | accepted. | |
31601 | ||
31602 | ||
31603 | ||
31604 | //////////////////////////////////////////////////////////////////////////// | |
31605 | //////////////////////////////////////////////////////////////////////////// | |
31606 | ||
31607 | [[CHAPemsgcust]] | |
31608 | [titleabbrev="Customizing messages"] | |
31609 | Customizing bounce and warning messages | |
31610 | --------------------------------------- | |
31611 | When a message fails to be delivered, or remains on the queue for more than a | |
31612 | configured amount of time, Exim sends a message to the original sender, or | |
31613 | to an alternative configured address. The text of these messages is built into | |
31614 | the code of Exim, but it is possible to change it, either by adding a single | |
31615 | string, or by replacing each of the paragraphs by text supplied in a file. | |
31616 | ||
31617 | The 'From:' and 'To:' header lines are automatically generated; you can cause | |
31618 | a 'Reply-To:' line to be added by setting the %errors_reply_to% option. Exim | |
31619 | also adds the line | |
31620 | ||
31621 | Auto-Submitted: auto-generated | |
31622 | ||
31623 | to all warning and bounce messages, | |
31624 | ||
31625 | ||
31626 | Customizing bounce messages | |
31627 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
31628 | cindex:[customizing,bounce message] | |
31629 | cindex:[bounce message,customizing] | |
31630 | If %bounce_message_text% is set, its contents are included in the default | |
31631 | message immediately after ``This message was created automatically by mail | |
31632 | delivery software.'' The string is not expanded. It is not used if | |
31633 | %bounce_message_file% is set. | |
31634 | ||
31635 | When %bounce_message_file% is set, it must point to a template file for | |
31636 | constructing error messages. The file consists of a series of text items, | |
31637 | separated by lines consisting of exactly four asterisks. If the file cannot be | |
31638 | opened, default text is used and a message is written to the main and panic | |
31639 | logs. If any text item in the file is empty, default text is used for that | |
31640 | item. | |
31641 | ||
068aaea8 PH |
31642 | cindex:[$bounce_recipient$] |
31643 | cindex:[$bounce_return_size_limit$] | |
168e428f | 31644 | Each item of text that is read from the file is expanded, and there are two |
068aaea8 PH |
31645 | expansion variables which can be of use here: $bounce_recipient$ is set to the |
31646 | recipient of an error message while it is being created, and | |
31647 | $bounce_return_size_limit$ contains the value of the %return_size_limit% | |
31648 | option, rounded to a whole number. | |
168e428f PH |
31649 | |
31650 | The items must appear in the file in the following order: | |
31651 | ||
31652 | - The first item is included in the headers, and should include at least a | |
31653 | 'Subject:' header. Exim does not check the syntax of these headers. | |
31654 | ||
31655 | - The second item forms the start of the error message. After it, Exim lists the | |
31656 | failing addresses with their error messages. | |
31657 | ||
31658 | - The third item is used to introduce any text from pipe transports that is to be | |
31659 | returned to the sender. It is omitted if there is no such text. | |
31660 | ||
31661 | - The fourth item is used to introduce the copy of the message that is returned | |
31662 | as part of the error report. | |
31663 | ||
31664 | - The fifth item is added after the fourth one if the returned message is | |
31665 | truncated because it is bigger than %return_size_limit%. | |
31666 | ||
31667 | - The sixth item is added after the copy of the original message. | |
31668 | ||
31669 | The default state (%bounce_message_file% unset) is equivalent to the | |
31670 | following file, in which the sixth item is empty. The 'Subject:' line has been | |
31671 | split into two here in order to fit it on the page: | |
31672 | ||
31673 | Subject: Mail delivery failed | |
31674 | ${if eq{$sender_address}{$bounce_recipient}{: returning message to sender}} | |
31675 | **** | |
31676 | This message was created automatically by mail delivery software. | |
31677 | ||
31678 | A message ${if eq{$sender_address}{$bounce_recipient}{that you sent }{sent by | |
31679 | ||
31680 | <$sender_address> | |
31681 | ||
31682 | }}could not be delivered to all of its recipients. | |
31683 | The following address(es) failed: | |
31684 | **** | |
31685 | The following text was generated during the delivery attempt(s): | |
31686 | **** | |
31687 | ------ This is a copy of the message, including all the headers. ------ | |
31688 | **** | |
31689 | ------ The body of the message is $message_size characters long; only the first | |
068aaea8 | 31690 | ------ $bounce_return_size_limit or so are included here. |
168e428f PH |
31691 | **** |
31692 | ||
31693 | ||
31694 | [[SECTcustwarn]] | |
31695 | Customizing warning messages | |
31696 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
31697 | cindex:[customizing,warning message] | |
31698 | cindex:[warning of delay,customizing the message] | |
31699 | The option %warn_message_file% can be pointed at a template file for use when | |
31700 | warnings about message delays are created. In this case there are only three | |
31701 | text sections: | |
31702 | ||
31703 | - The first item is included in the headers, and should include at least a | |
31704 | 'Subject:' header. Exim does not check the syntax of these headers. | |
31705 | ||
31706 | - The second item forms the start of the warning message. After it, Exim lists | |
31707 | the delayed addresses. | |
31708 | ||
31709 | - The third item then ends the message. | |
31710 | ||
31711 | The default state is equivalent to the following file, except that the line | |
31712 | starting ``A message'' has been split here, in order to fit it on the page: | |
31713 | ||
068aaea8 | 31714 | Subject: Warning: message $message_exim_id delayed $warn_message_delay |
168e428f PH |
31715 | **** |
31716 | This message was created automatically by mail delivery software. | |
31717 | ||
31718 | A message ${if eq{$sender_address}{$warn_message_recipients} | |
31719 | {that you sent }{sent by | |
31720 | ||
31721 | <$sender_address> | |
31722 | ||
31723 | }}has not been delivered to all of its recipients after | |
31724 | more than $warn_message_delay on the queue on $primary_hostname. | |
31725 | ||
068aaea8 | 31726 | The message identifier is: $message_exim_id |
168e428f PH |
31727 | The subject of the message is: $h_subject |
31728 | The date of the message is: $h_date | |
31729 | ||
31730 | The following address(es) have not yet been delivered: | |
31731 | **** | |
31732 | No action is required on your part. Delivery attempts will continue for | |
31733 | some time, and this warning may be repeated at intervals if the message | |
31734 | remains undelivered. Eventually the mail delivery software will give up, | |
31735 | and when that happens, the message will be returned to you. | |
068aaea8 PH |
31736 | + |
31737 | cindex:[$warn_message_delay$] | |
31738 | cindex:[$warn_message_recipients$] | |
168e428f PH |
31739 | except that in the default state the subject and date lines are omitted if no |
31740 | appropriate headers exist. During the expansion of this file, | |
31741 | $warn_message_delay$ is set to the delay time in one of the forms ``<''n'> | |
31742 | minutes' or ``<''n'> hours', and $warn_message_recipients$ contains a list of | |
31743 | recipients for the warning message. There may be more than one if there are | |
31744 | multiple addresses with different %errors_to% settings on the routers that | |
31745 | handled them. | |
31746 | ||
31747 | ||
31748 | ||
31749 | ||
31750 | //////////////////////////////////////////////////////////////////////////// | |
31751 | //////////////////////////////////////////////////////////////////////////// | |
31752 | ||
31753 | [[CHAPcomconreq]] | |
31754 | [titleabbrev="Common configuration settings"] | |
31755 | Some common configuration settings | |
31756 | ---------------------------------- | |
31757 | This chapter discusses some configuration settings that seem to be fairly | |
31758 | common. More examples and discussion can be found in the Exim book. | |
31759 | ||
31760 | ||
31761 | ||
31762 | Sending mail to a smart host | |
31763 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
31764 | cindex:[smart host,example router] | |
31765 | If you want to send all mail for non-local domains to a ``smart host'', you | |
31766 | should replace the default ^dnslookup^ router with a router which does the | |
31767 | routing explicitly: | |
31768 | ||
31769 | send_to_smart_host: | |
31770 | driver = manualroute | |
31771 | route_list = !+local_domains smart.host.name | |
31772 | transport = remote_smtp | |
31773 | ||
31774 | You can use the smart host's IP address instead of the name if you wish. | |
31775 | ||
31776 | If you are using Exim only to submit messages to a smart host, and not for | |
31777 | receiving incoming messages, you can arrange for it to do the submission | |
31778 | synchronously by setting the %mua_wrapper% option (see chapter | |
31779 | <<CHAPnonqueueing>>). | |
31780 | ||
31781 | ||
31782 | ||
31783 | ||
31784 | [[SECTmailinglists]] | |
31785 | Using Exim to handle mailing lists | |
31786 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
31787 | cindex:[mailing lists] | |
31788 | Exim can be used to run simple mailing lists, but for large and/or complicated | |
31789 | requirements, the use of additional specialized mailing list software such as | |
31790 | Majordomo or Mailman is recommended. | |
31791 | ||
31792 | The ^redirect^ router can be used to handle mailing lists where each list | |
31793 | is maintained in a separate file, which can therefore be managed by an | |
31794 | independent manager. The %domains% router option can be used to run these | |
31795 | lists in a separate domain from normal mail. For example: | |
31796 | ||
31797 | lists: | |
31798 | driver = redirect | |
31799 | domains = lists.example | |
31800 | file = /usr/lists/$local_part | |
31801 | forbid_pipe | |
31802 | forbid_file | |
31803 | errors_to = $local_part-request@lists.example | |
31804 | no_more | |
31805 | ||
31806 | This router is skipped for domains other than 'lists.example'. For addresses | |
31807 | in that domain, it looks for a file that matches the local part. If there is no | |
31808 | such file, the router declines, but because %no_more% is set, no subsequent | |
31809 | routers are tried, and so the whole delivery fails. | |
31810 | ||
31811 | The %forbid_pipe% and %forbid_file% options prevent a local part from being | |
31812 | expanded into a file name or a pipe delivery, which is usually inappropriate in | |
31813 | a mailing list. | |
31814 | ||
31815 | cindex:[%errors_to%] | |
31816 | The %errors_to% option specifies that any delivery errors caused by addresses | |
31817 | taken from a mailing list are to be sent to the given address rather than the | |
31818 | original sender of the message. However, before acting on this, Exim verifies | |
31819 | the error address, and ignores it if verification fails. | |
31820 | ||
31821 | For example, using the configuration above, mail sent to | |
31822 | 'dicts@lists.example' is passed on to those addresses contained in | |
31823 | _/usr/lists/dicts_, with error reports directed to | |
31824 | 'dicts-request@lists.example', provided that this address can be verified. | |
31825 | There could be a file called _/usr/lists/dicts-request_ containing | |
31826 | the address(es) of this particular list's manager(s), but other approaches, | |
31827 | such as setting up an earlier router (possibly using the %local_part_prefix% | |
31828 | or %local_part_suffix% options) to handle addresses of the form %owner-xxx% | |
31829 | or %xxx-request%, are also possible. | |
31830 | ||
31831 | ||
31832 | ||
31833 | Syntax errors in mailing lists | |
31834 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
31835 | cindex:[mailing lists,syntax errors in] | |
31836 | If an entry in redirection data contains a syntax error, Exim normally defers | |
31837 | delivery of the original address. That means that a syntax error in a mailing | |
31838 | list holds up all deliveries to the list. This may not be appropriate when a | |
31839 | list is being maintained automatically from data supplied by users, and the | |
31840 | addresses are not rigorously checked. | |
31841 | ||
31842 | If the %skip_syntax_errors% option is set, the ^redirect^ router just skips | |
31843 | entries that fail to parse, noting the incident in the log. If in addition | |
31844 | %syntax_errors_to% is set to a verifiable address, a message is sent to it | |
31845 | whenever a broken address is skipped. It is usually appropriate to set | |
31846 | %syntax_errors_to% to the same address as %errors_to%. | |
31847 | ||
31848 | ||
31849 | ||
31850 | Re-expansion of mailing lists | |
31851 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
31852 | cindex:[mailing lists,re-expansion of] | |
31853 | Exim remembers every individual address to which a message has been delivered, | |
31854 | in order to avoid duplication, but it normally stores only the original | |
31855 | recipient addresses with a message. If all the deliveries to a mailing list | |
31856 | cannot be done at the first attempt, the mailing list is re-expanded when the | |
31857 | delivery is next tried. This means that alterations to the list are taken into | |
31858 | account at each delivery attempt, so addresses that have been added to | |
31859 | the list since the message arrived will therefore receive a copy of the | |
31860 | message, even though it pre-dates their subscription. | |
31861 | ||
31862 | If this behaviour is felt to be undesirable, the %one_time% option can be set | |
31863 | on the ^redirect^ router. If this is done, any addresses generated by the | |
31864 | router that fail to deliver at the first attempt are added to the message as | |
31865 | ``top level'' addresses, and the parent address that generated them is marked | |
31866 | ``delivered''. Thus, expansion of the mailing list does not happen again at the | |
31867 | subsequent delivery attempts. The disadvantage of this is that if any of the | |
31868 | failing addresses are incorrect, correcting them in the file has no effect on | |
31869 | pre-existing messages. | |
31870 | ||
31871 | The original top-level address is remembered with each of the generated | |
31872 | addresses, and is output in any log messages. However, any intermediate parent | |
31873 | addresses are not recorded. This makes a difference to the log only if the | |
31874 | %all_parents% selector is set, but for mailing lists there is normally only | |
31875 | one level of expansion anyway. | |
31876 | ||
31877 | ||
31878 | ||
31879 | Closed mailing lists | |
31880 | ~~~~~~~~~~~~~~~~~~~~ | |
31881 | cindex:[mailing lists,closed] | |
31882 | The examples so far have assumed open mailing lists, to which anybody may | |
31883 | send mail. It is also possible to set up closed lists, where mail is accepted | |
31884 | from specified senders only. This is done by making use of the generic | |
31885 | %senders% option to restrict the router that handles the list. | |
31886 | ||
31887 | The following example uses the same file as a list of recipients and as a list | |
31888 | of permitted senders. It requires three routers: | |
31889 | ||
31890 | .... | |
31891 | lists_request: | |
31892 | driver = redirect | |
31893 | domains = lists.example | |
31894 | local_part_suffix = -request | |
31895 | file = /usr/lists/$local_part$local_part_suffix | |
31896 | no_more | |
31897 | ||
31898 | lists_post: | |
31899 | driver = redirect | |
31900 | domains = lists.example | |
31901 | senders = ${if exists {/usr/lists/$local_part}\ | |
31902 | {lsearch;/usr/lists/$local_part}{*}} | |
31903 | file = /usr/lists/$local_part | |
31904 | forbid_pipe | |
31905 | forbid_file | |
31906 | errors_to = $local_part-request@lists.example | |
31907 | no_more | |
31908 | ||
31909 | lists_closed: | |
31910 | driver = redirect | |
31911 | domains = lists.example | |
31912 | allow_fail | |
31913 | data = :fail: $local_part@lists.example is a closed mailing list | |
31914 | .... | |
31915 | ||
31916 | All three routers have the same %domains% setting, so for any other domains, | |
31917 | they are all skipped. The first router runs only if the local part ends in | |
31918 | %-request%. It handles messages to the list manager(s) by means of an open | |
31919 | mailing list. | |
31920 | ||
31921 | The second router runs only if the %senders% precondition is satisfied. It | |
31922 | checks for the existence of a list that corresponds to the local part, and then | |
31923 | checks that the sender is on the list by means of a linear search. It is | |
31924 | necessary to check for the existence of the file before trying to search it, | |
31925 | because otherwise Exim thinks there is a configuration error. If the file does | |
31926 | not exist, the expansion of %senders% is \*, which matches all senders. This | |
31927 | means that the router runs, but because there is no list, declines, and | |
31928 | %no_more% ensures that no further routers are run. The address fails with an | |
31929 | ``unrouteable address'' error. | |
31930 | ||
31931 | The third router runs only if the second router is skipped, which happens when | |
31932 | a mailing list exists, but the sender is not on it. This router forcibly fails | |
31933 | the address, giving a suitable error message. | |
31934 | ||
31935 | ||
31936 | ||
31937 | ||
31938 | [[SECTvirtualdomains]] | |
31939 | Virtual domains | |
31940 | ~~~~~~~~~~~~~~~ | |
31941 | cindex:[virtual domains] | |
31942 | cindex:[domain,virtual] | |
31943 | The phrase 'virtual domain' is unfortunately used with two rather different | |
31944 | meanings: | |
31945 | ||
31946 | - A domain for which there are no real mailboxes; all valid local parts are | |
31947 | aliases for other email addresses. Common examples are organizational | |
31948 | top-level domains and ``vanity'' domains. | |
31949 | ||
31950 | - One of a number of independent domains that are all handled by the same host, | |
31951 | with mailboxes on that host, but where the mailbox owners do not necessarily | |
31952 | have login accounts on that host. | |
31953 | ||
31954 | The first usage is probably more common, and does seem more ``virtual'' than the | |
31955 | second. This kind of domain can be handled in Exim with a straightforward | |
31956 | aliasing router. One approach is to create a separate alias file for each | |
31957 | virtual domain. Exim can test for the existence of the alias file to determine | |
31958 | whether the domain exists. The ^dsearch^ lookup type is useful here, leading | |
31959 | to a router of this form: | |
31960 | ||
31961 | virtual: | |
31962 | driver = redirect | |
31963 | domains = dsearch;/etc/mail/virtual | |
31964 | data = ${lookup{$local_part}lsearch{/etc/mail/virtual/$domain}} | |
31965 | no_more | |
31966 | ||
31967 | The %domains% option specifies that the router is to be skipped, unless there | |
31968 | is a file in the _/etc/mail/virtual_ directory whose name is the same as the | |
31969 | domain that is being processed. When the router runs, it looks up the local | |
31970 | part in the file to find a new address (or list of addresses). The %no_more% | |
31971 | setting ensures that if the lookup fails (leading to %data% being an empty | |
31972 | string), Exim gives up on the address without trying any subsequent routers. | |
31973 | ||
31974 | This one router can handle all the virtual domains because the alias file names | |
31975 | follow a fixed pattern. Permissions can be arranged so that appropriate people | |
31976 | can edit the different alias files. A successful aliasing operation results in | |
31977 | a new envelope recipient address, which is then routed from scratch. | |
31978 | ||
31979 | The other kind of ``virtual'' domain can also be handled in a straightforward | |
31980 | way. One approach is to create a file for each domain containing a list of | |
31981 | valid local parts, and use it in a router like this: | |
31982 | ||
31983 | my_domains: | |
31984 | driver = accept | |
31985 | domains = dsearch;/etc/mail/domains | |
31986 | local_parts = lsearch;/etc/mail/domains/$domain | |
31987 | transport = my_mailboxes | |
31988 | ||
31989 | The address is accepted if there is a file for the domain, and the local part | |
31990 | can be found in the file. The %domains% option is used to check for the file's | |
31991 | existence because %domains% is tested before the %local_parts% option (see | |
31992 | section <<SECTrouprecon>>). You can't use %require_files%, because that option | |
31993 | is tested after %local_parts%. The transport is as follows: | |
31994 | ||
31995 | my_mailboxes: | |
31996 | driver = appendfile | |
31997 | file = /var/mail/$domain/$local_part | |
31998 | user = mail | |
31999 | ||
32000 | This uses a directory of mailboxes for each domain. The %user% setting is | |
32001 | required, to specify which uid is to be used for writing to the mailboxes. | |
32002 | ||
32003 | The configuration shown here is just one example of how you might support this | |
32004 | requirement. There are many other ways this kind of configuration can be set | |
32005 | up, for example, by using a database instead of separate files to hold all the | |
32006 | information about the domains. | |
32007 | ||
32008 | ||
32009 | ||
32010 | [[SECTmulbox]] | |
32011 | Multiple user mailboxes | |
32012 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
32013 | cindex:[multiple mailboxes] | |
32014 | cindex:[mailbox,multiple] | |
32015 | cindex:[local part,prefix] | |
32016 | cindex:[local part,suffix] | |
32017 | Heavy email users often want to operate with multiple mailboxes, into which | |
32018 | incoming mail is automatically sorted. A popular way of handling this is to | |
32019 | allow users to use multiple sender addresses, so that replies can easily be | |
32020 | identified. Users are permitted to add prefixes or suffixes to their local | |
32021 | parts for this purpose. The wildcard facility of the generic router options | |
32022 | %local_part_prefix% and %local_part_suffix% can be used for this. For | |
32023 | example, consider this router: | |
32024 | ||
32025 | userforward: | |
32026 | driver = redirect | |
32027 | check_local_user | |
32028 | file = $home/.forward | |
32029 | local_part_suffix = -* | |
32030 | local_part_suffix_optional | |
32031 | allow_filter | |
32032 | ||
068aaea8 | 32033 | cindex:[$local_part_suffix$] |
168e428f PH |
32034 | It runs a user's _.forward_ file for all local parts of the form |
32035 | 'username-\*'. Within the filter file the user can distinguish different | |
32036 | cases by testing the variable $local_part_suffix$. For example: | |
32037 | ||
32038 | if $local_part_suffix contains -special then | |
32039 | save /home/$local_part/Mail/special | |
32040 | endif | |
32041 | ||
32042 | If the filter file does not exist, or does not deal with such addresses, they | |
32043 | fall through to subsequent routers, and, assuming no subsequent use of the | |
32044 | %local_part_suffix% option is made, they presumably fail. Thus, users have | |
32045 | control over which suffixes are valid. | |
32046 | ||
32047 | Alternatively, a suffix can be used to trigger the use of a different | |
32048 | _.forward_ file -- which is the way a similar facility is implemented in | |
32049 | another MTA: | |
32050 | ||
32051 | userforward: | |
32052 | driver = redirect | |
32053 | check_local_user | |
32054 | file = $home/.forward$local_part_suffix | |
32055 | local_part_suffix = -* | |
32056 | local_part_suffix_optional | |
32057 | allow_filter | |
32058 | ||
32059 | If there is no suffix, _.forward_ is used; if the suffix is '-special', for | |
32060 | example, _.forward-special_ is used. Once again, if the appropriate file | |
32061 | does not exist, or does not deal with the address, it is passed on to | |
32062 | subsequent routers, which could, if required, look for an unqualified | |
32063 | _.forward_ file to use as a default. | |
32064 | ||
32065 | ||
32066 | ||
32067 | Simplified vacation processing | |
32068 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
32069 | cindex:[vacation processing] | |
32070 | The traditional way of running the 'vacation' program is for a user to set up | |
32071 | a pipe command in a _.forward_ file | |
32072 | (see section <<SECTspecitredli>> for syntax details). | |
32073 | This is prone to error by inexperienced users. There are two features of Exim | |
32074 | that can be used to make this process simpler for users: | |
32075 | ||
32076 | - A local part prefix such as ``vacation-'' can be specified on a router which | |
32077 | can cause the message to be delivered directly to the 'vacation' program, or | |
32078 | alternatively can use Exim's ^autoreply^ transport. The contents of a user's | |
32079 | _.forward_ file are then much simpler. For example: | |
32080 | ||
32081 | spqr, vacation-spqr | |
32082 | ||
32083 | - The %require_files% generic router option can be used to trigger a | |
32084 | vacation delivery by checking for the existence of a certain file in the | |
32085 | user's home directory. The %unseen% generic option should also be used, to | |
32086 | ensure that the original delivery also proceeds. In this case, all the user has | |
32087 | to do is to create a file called, say, _.vacation_, containing a vacation | |
32088 | message. | |
32089 | ||
32090 | Another advantage of both these methods is that they both work even when the | |
32091 | use of arbitrary pipes by users is locked out. | |
32092 | ||
32093 | ||
32094 | ||
32095 | Taking copies of mail | |
32096 | ~~~~~~~~~~~~~~~~~~~~~ | |
32097 | cindex:[message,copying every] | |
32098 | Some installations have policies that require archive copies of all messages to | |
32099 | be made. A single copy of each message can easily be taken by an appropriate | |
32100 | command in a system filter, which could, for example, use a different file for | |
32101 | each day's messages. | |
32102 | ||
32103 | There is also a shadow transport mechanism that can be used to take copies of | |
32104 | messages that are successfully delivered by local transports, one copy per | |
32105 | delivery. This could be used, 'inter alia', to implement automatic | |
32106 | notification of delivery by sites that insist on doing such things. | |
32107 | ||
32108 | ||
32109 | ||
32110 | Intermittently connected hosts | |
32111 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
32112 | cindex:[intermittently connected hosts] | |
32113 | It has become quite common (because it is cheaper) for hosts to connect to the | |
32114 | Internet periodically rather than remain connected all the time. The normal | |
32115 | arrangement is that mail for such hosts accumulates on a system that is | |
32116 | permanently connected. | |
32117 | ||
32118 | Exim was designed for use on permanently connected hosts, and so it is not | |
32119 | particularly well-suited to use in an intermittently connected environment. | |
32120 | Nevertheless there are some features that can be used. | |
32121 | ||
32122 | ||
32123 | Exim on the upstream server host | |
32124 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
32125 | It is tempting to arrange for incoming mail for the intermittently connected | |
32126 | host to remain on Exim's queue until the client connects. However, this | |
32127 | approach does not scale very well. Two different kinds of waiting message are | |
32128 | being mixed up in the same queue -- those that cannot be delivered because of | |
32129 | some temporary problem, and those that are waiting for their destination host | |
32130 | to connect. This makes it hard to manage the queue, as well as wasting | |
32131 | resources, because each queue runner scans the entire queue. | |
32132 | ||
32133 | A better approach is to separate off those messages that are waiting for an | |
32134 | intermittently connected host. This can be done by delivering these messages | |
32135 | into local files in batch SMTP, ``mailstore'', or other envelope-preserving | |
32136 | format, from where they are transmitted by other software when their | |
32137 | destination connects. This makes it easy to collect all the mail for one host | |
32138 | in a single directory, and to apply local timeout rules on a per-message basis | |
32139 | if required. | |
32140 | ||
32141 | On a very small scale, leaving the mail on Exim's queue can be made to work. If | |
32142 | you are doing this, you should configure Exim with a long retry period for the | |
32143 | intermittent host. For example: | |
32144 | ||
32145 | cheshire.wonderland.fict.example * F,5d,24h | |
32146 | ||
32147 | This stops a lot of failed delivery attempts from occurring, but Exim remembers | |
32148 | which messages it has queued up for that host. Once the intermittent host comes | |
32149 | online, forcing delivery of one message (either by using the %-M% or %-R% | |
32150 | options, or by using the ETRN SMTP command (see section <<SECTETRN>>) | |
32151 | causes all the queued up messages to be delivered, often down a single SMTP | |
32152 | connection. While the host remains connected, any new messages get delivered | |
32153 | immediately. | |
32154 | ||
32155 | If the connecting hosts do not have fixed IP addresses, that is, if a host is | |
32156 | issued with a different IP address each time it connects, Exim's retry | |
32157 | mechanisms on the holding host get confused, because the IP address is normally | |
32158 | used as part of the key string for holding retry information. This can be | |
32159 | avoided by unsetting %retry_include_ip_address% on the ^smtp^ transport. | |
32160 | Since this has disadvantages for permanently connected hosts, it is best to | |
32161 | arrange a separate transport for the intermittently connected ones. | |
32162 | ||
32163 | ||
32164 | ||
32165 | Exim on the intermittently connected client host | |
32166 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
32167 | The value of %smtp_accept_queue_per_connection% should probably be | |
32168 | increased, or even set to zero (that is, disabled) on the intermittently | |
32169 | connected host, so that all incoming messages down a single connection get | |
32170 | delivered immediately. | |
32171 | ||
32172 | cindex:[SMTP,passed connection] | |
32173 | cindex:[SMTP,multiple deliveries] | |
32174 | cindex:[multiple SMTP deliveries] | |
32175 | Mail waiting to be sent from an intermittently connected host will probably | |
32176 | not have been routed, because without a connection DNS lookups are not | |
32177 | possible. This means that if a normal queue run is done at connection time, | |
32178 | each message is likely to be sent in a separate SMTP session. This can be | |
32179 | avoided by starting the queue run with a command line option beginning with | |
32180 | %-qq% instead of %-q%. In this case, the queue is scanned twice. In the first | |
32181 | pass, routing is done but no deliveries take place. The second pass is a normal | |
32182 | queue run; since all the messages have been previously routed, those destined | |
32183 | for the same host are likely to get sent as multiple deliveries in a single | |
32184 | SMTP connection. | |
32185 | ||
32186 | ||
32187 | ||
32188 | //////////////////////////////////////////////////////////////////////////// | |
32189 | //////////////////////////////////////////////////////////////////////////// | |
32190 | ||
32191 | [[CHAPnonqueueing]] | |
32192 | [titleabbrev="Exim as a non-queueing client"] | |
32193 | Using Exim as a non-queueing client | |
32194 | ----------------------------------- | |
32195 | cindex:[client, non-queueing] | |
32196 | cindex:[smart host,queueing; suppressing] | |
32197 | On a personal computer, it is a common requirement for all | |
32198 | email to be sent to a ``smart host''. There are plenty of MUAs that can be | |
32199 | configured to operate that way, for all the popular operating systems. | |
32200 | However, there are some MUAs for Unix-like systems that cannot be so | |
32201 | configured: they submit messages using the command line interface of | |
32202 | _/usr/sbin/sendmail_. Furthermore, utility programs such as 'cron' submit | |
32203 | messages this way. | |
32204 | ||
32205 | If the personal computer runs continuously, there is no problem, because it can | |
32206 | run a conventional MTA that handles delivery to the smart host, and deal with | |
32207 | any delays via its queueing mechanism. However, if the computer does not run | |
32208 | continuously or runs different operating systems at different times, queueing | |
32209 | email is not desirable. | |
32210 | ||
32211 | There is therefore a requirement for something that can provide the | |
32212 | _/usr/sbin/sendmail_ interface but deliver messages to a smart host without | |
32213 | any queueing or retrying facilities. Furthermore, the delivery to the smart | |
32214 | host should be synchronous, so that if it fails, the sending MUA is immediately | |
32215 | informed. In other words, we want something that extends an MUA that submits | |
32216 | to a local MTA via the command line so that it behaves like one that submits | |
32217 | to a remote smart host using TCP/SMTP. | |
32218 | ||
32219 | There are a number of applications (for example, there is one called 'ssmtp') | |
32220 | that do this job. However, people have found them to be lacking in various | |
32221 | ways. For instance, you might want to allow aliasing and forwarding to be done | |
32222 | before sending a message to the smart host. | |
32223 | ||
32224 | Exim already had the necessary infrastructure for doing this job. Just a few | |
32225 | tweaks were needed to make it behave as required, though it is somewhat of an | |
32226 | overkill to use a fully-featured MTA for this purpose. | |
32227 | ||
32228 | cindex:[%mua_wrapper%] | |
32229 | There is a Boolean global option called %mua_wrapper%, defaulting false. | |
32230 | Setting %mua_wrapper% true causes Exim to run in a special mode where it | |
32231 | assumes that it is being used to ``wrap'' a command-line MUA in the manner | |
32232 | just described. As well as setting %mua_wrapper%, you also need to provide a | |
32233 | compatible router and transport configuration. Typically there will be just one | |
32234 | router and one transport, sending everything to a smart host. | |
32235 | ||
32236 | When run in MUA wrapping mode, the behaviour of Exim changes in the | |
32237 | following ways: | |
32238 | ||
32239 | - A daemon cannot be run, nor will Exim accept incoming messages from 'inetd'. | |
32240 | In other words, the only way to submit messages is via the command line. | |
32241 | ||
32242 | - Each message is synchonously delivered as soon as it is received (%-odi% is | |
32243 | assumed). All queueing options (%queue_only%, %queue_smtp_domains%, | |
32244 | %control% in an ACL, etc.) are quietly ignored. The Exim reception process does | |
32245 | not finish until the delivery attempt is complete. If the delivery is | |
32246 | successful, a zero return code is given. | |
32247 | ||
32248 | - Address redirection is permitted, but the final routing for all addresses must | |
32249 | be to the same remote transport, and to the same list of hosts. Furthermore, | |
32250 | the return address (envelope sender) must be the same for all recipients, as | |
32251 | must any added or deleted header lines. In other words, it must be possible to | |
32252 | deliver the message in a single SMTP transaction, however many recipients there | |
32253 | are. | |
32254 | ||
32255 | - If these conditions are not met, or if routing any address results in a | |
32256 | failure or defer status, or if Exim is unable to deliver all the recipients | |
32257 | successfully to one of the smart hosts, delivery of the entire message fails. | |
32258 | ||
32259 | - Because no queueing is allowed, all failures are treated as permanent; there | |
32260 | is no distinction between 4##'xx' and 5##'xx' SMTP response codes from the | |
32261 | smart host. Furthermore, because only a single yes/no response can be given to | |
32262 | the caller, it is not possible to deliver to some recipients and not others. If | |
32263 | there is an error (temporary or permanent) for any recipient, all are failed. | |
32264 | ||
32265 | - If more than one smart host is listed, Exim will try another host after a | |
32266 | connection failure or a timeout, in the normal way. However, if this kind of | |
32267 | failure happens for all the hosts, the delivery fails. | |
32268 | ||
32269 | - When delivery fails, an error message is written to the standard error stream | |
32270 | (as well as to Exim's log), and Exim exits to the caller with a return code | |
32271 | value 1. The message is expunged from Exim's spool files. No bounce messages | |
32272 | are ever generated. | |
32273 | ||
32274 | - No retry data is maintained, and any retry rules are ignored. | |
32275 | ||
32276 | - A number of Exim options are overridden: %deliver_drop_privilege% is forced | |
32277 | true, %max_rcpt% in the smtp transport is forced to ``unlimited'', | |
32278 | %remote_max_parallel% is forced to one, and fallback hosts are ignored. | |
32279 | ||
32280 | The overall effect is that Exim makes a single synchronous attempt to deliver | |
32281 | the message, failing if there is any kind of problem. Because no local | |
32282 | deliveries are done and no daemon can be run, Exim does not need root | |
32283 | privilege. It should be possible to run it setuid to 'exim' instead of setuid | |
32284 | to 'root'. See section <<SECTrunexiwitpri>> for a general discussion about the | |
32285 | advantages and disadvantages of running without root privilege. | |
32286 | ||
32287 | ||
32288 | ||
32289 | ||
32290 | //////////////////////////////////////////////////////////////////////////// | |
32291 | //////////////////////////////////////////////////////////////////////////// | |
32292 | ||
32293 | [[CHAPlog]] | |
32294 | Log files | |
32295 | --------- | |
32296 | cindex:[log,types of] | |
32297 | cindex:[log,general description] | |
32298 | Exim writes three different logs, referred to as the main log, the reject log, | |
32299 | and the panic log: | |
32300 | ||
32301 | - cindex:[main log] | |
32302 | The main log records the arrival of each message and each delivery in a single | |
32303 | line in each case. The format is as compact as possible, in an attempt to keep | |
32304 | down the size of log files. Two-character flag sequences make it easy to pick | |
32305 | out these lines. A number of other events are recorded in the main log. Some of | |
32306 | them are optional, in which case the %log_selector% option controls whether | |
32307 | they are included or not. A Perl script called 'eximstats', which does simple | |
32308 | analysis of main log files, is provided in the Exim distribution (see section | |
32309 | <<SECTmailstat>>). | |
32310 | ||
32311 | - cindex:[reject log] | |
32312 | The reject log records information from messages that are rejected as a result | |
32313 | of a configuration option (that is, for policy reasons). | |
32314 | The first line of each rejection is a copy of the line that is also written to | |
32315 | the main log. Then, if the message's header has been read at the time the log | |
32316 | is written, its contents are written to this log. Only the original header | |
32317 | lines are available; header lines added by ACLs are not logged. You can use the | |
32318 | reject log to check that your policy controls are working correctly; on a busy | |
32319 | host this may be easier than scanning the main log for rejection messages. You | |
32320 | can suppress the writing of the reject log by setting %write_rejectlog% false. | |
32321 | ||
32322 | - cindex:[panic log] | |
32323 | cindex:[system log] | |
32324 | When certain serious errors occur, Exim writes entries to its panic log. If the | |
32325 | error is sufficiently disastrous, Exim bombs out afterwards. Panic log entries | |
32326 | are usually written to the main log as well, but can get lost amid the mass of | |
32327 | other entries. The panic log should be empty under normal circumstances. It is | |
32328 | therefore a good idea to check it (or to have a 'cron' script check it) | |
32329 | regularly, in order to become aware of any problems. When Exim cannot open its | |
32330 | panic log, it tries as a last resort to write to the system log (syslog). This | |
32331 | is opened with LOG_PID+LOG_CONS and the facility code of LOG_MAIL. The | |
32332 | message itself is written at priority LOG_CRIT. | |
32333 | ||
32334 | Every log line starts with a timestamp, in the format shown in this example: | |
32335 | ||
32336 | 2001-09-16 16:09:47 SMTP connection from [127.0.0.1] closed by QUIT | |
32337 | ||
32338 | By default, the timestamps are in the local timezone. There are two | |
32339 | ways of changing this: | |
32340 | ||
32341 | - You can set the %timezone% option to a different time zone; in particular, if | |
32342 | you set | |
32343 | + | |
32344 | timezone = UTC | |
32345 | + | |
32346 | the timestamps will be in UTC (aka GMT). | |
32347 | ||
32348 | - If you set %log_timezone% true, the time zone is added to the timestamp, for | |
32349 | example: | |
32350 | + | |
32351 | 2003-04-25 11:17:07 +0100 Start queue run: pid=12762 | |
32352 | ||
32353 | ||
32354 | ||
32355 | ||
32356 | ||
32357 | [[SECTwhelogwri]] | |
32358 | Where the logs are written | |
32359 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
32360 | cindex:[log,destination] | |
32361 | cindex:[log,to file] | |
32362 | cindex:[log,to syslog] | |
32363 | cindex:[syslog] | |
32364 | The logs may be written to local files, or to syslog, or both. However, it | |
32365 | should be noted that many syslog implementations use UDP as a transport, and | |
32366 | are therefore unreliable in the sense that messages are not guaranteed to | |
32367 | arrive at the loghost, nor is the ordering of messages necessarily maintained. | |
32368 | It has also been reported that on large log files (tens of megabytes) you may | |
32369 | need to tweak syslog to prevent it syncing the file with each write -- on Linux | |
32370 | this has been seen to make syslog take 90% plus of CPU time. | |
32371 | ||
32372 | The destination for Exim's logs is configured by setting LOG_FILE_PATH in | |
32373 | _Local/Makefile_ or by setting %log_file_path% in the run time | |
32374 | configuration. This latter string is expanded, so it can contain, for example, | |
32375 | references to the host name: | |
32376 | ||
32377 | log_file_path = /var/log/$primary_hostname/exim_%slog | |
32378 | ||
32379 | It is generally advisable, however, to set the string in _Local/Makefile_ | |
32380 | rather than at run time, because then the setting is available right from the | |
32381 | start of Exim's execution. Otherwise, if there's something it wants to log | |
32382 | before it has read the configuration file (for example, an error in the | |
32383 | configuration file) it will not use the path you want, and may not be able to | |
32384 | log at all. | |
32385 | ||
32386 | The value of LOG_FILE_PATH or %log_file_path% is a colon-separated | |
32387 | list, currently limited to at most two items. This is one option where the | |
32388 | facility for changing a list separator may not be used. The list must always be | |
32389 | colon-separated. If an item in the list is ``syslog'' then syslog is used; | |
32390 | otherwise the item must either be an absolute path, containing `%s` at the | |
32391 | point where ``main'', ``reject'', or ``panic'' is to be inserted, or be empty, | |
32392 | implying the use of a default path. | |
32393 | ||
32394 | When Exim encounters an empty item in the list, it searches the list defined by | |
32395 | LOG_FILE_PATH, and uses the first item it finds that is neither empty nor | |
32396 | ``syslog''. This means that an empty item in %log_file_path% can be used to | |
32397 | mean ``use the path specified at build time''. It no such item exists, log files | |
32398 | are written in the _log_ subdirectory of the spool directory. This is | |
32399 | equivalent to the setting: | |
32400 | ||
32401 | log_file_path = $spool_directory/log/%slog | |
32402 | ||
32403 | If you do not specify anything at build time or run time, that is where the | |
32404 | logs are written. | |
32405 | ||
32406 | A log file path may also contain `%D` if datestamped log file names are in | |
32407 | use -- see section <<SECTdatlogfil>> below. | |
32408 | ||
32409 | Here are some examples of possible settings: | |
32410 | ||
32411 | &&& | |
32412 | `LOG_FILE_PATH=syslog ` syslog only | |
32413 | `LOG_FILE_PATH=:syslog ` syslog and default path | |
32414 | `LOG_FILE_PATH=syslog : /usr/log/exim_%s ` syslog and specified path | |
32415 | `LOG_FILE_PATH=/usr/log/exim_%s ` specified path only | |
32416 | &&& | |
32417 | ||
32418 | If there are more than two paths in the list, the first is used and a panic | |
32419 | error is logged. | |
32420 | ||
32421 | ||
32422 | ||
32423 | Logging to local files that are periodically ``cycled'' | |
32424 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
32425 | cindex:[log,cycling local files] | |
32426 | cindex:[cycling logs] | |
32427 | cindex:['exicyclog'] | |
32428 | cindex:[log,local files; writing to] | |
32429 | Some operating systems provide centralized and standardised methods for cycling | |
32430 | log files. For those that do not, a utility script called 'exicyclog' is | |
32431 | provided (see section <<SECTcyclogfil>>). This renames and compresses the main | |
32432 | and reject logs each time it is called. The maximum number of old logs to keep | |
32433 | can be set. It is suggested this script is run as a daily 'cron' job. | |
32434 | ||
32435 | An Exim delivery process opens the main log when it first needs to write to it, | |
32436 | and it keeps the file open in case subsequent entries are required -- for | |
32437 | example, if a number of different deliveries are being done for the same | |
32438 | message. However, remote SMTP deliveries can take a long time, and this means | |
32439 | that the file may be kept open long after it is renamed if 'exicyclog' or | |
32440 | something similar is being used to rename log files on a regular basis. To | |
32441 | ensure that a switch of log files is noticed as soon as possible, Exim calls | |
32442 | 'stat()' on the main log's name before reusing an open file, and if the file | |
32443 | does not exist, or its inode has changed, the old file is closed and Exim | |
32444 | tries to open the main log from scratch. Thus, an old log file may remain open | |
32445 | for quite some time, but no Exim processes should write to it once it has been | |
32446 | renamed. | |
32447 | ||
32448 | ||
32449 | ||
32450 | [[SECTdatlogfil]] | |
32451 | Datestamped log files | |
32452 | ~~~~~~~~~~~~~~~~~~~~~ | |
32453 | cindex:[log,datestamped files] | |
32454 | Instead of cycling the main and reject log files by renaming them | |
32455 | periodically, some sites like to use files whose names contain a datestamp, | |
32456 | for example, _mainlog-20031225_. The datestamp is in the form _yyyymmdd_. | |
32457 | Exim has support for this way of working. It is enabled by setting the | |
32458 | %log_file_path% option to a path that includes `%D` at the point where the | |
32459 | datestamp is required. For example: | |
32460 | ||
32461 | log_file_path = /var/spool/exim/log/%slog-%D | |
32462 | log_file_path = /var/log/exim-%s-%D.log | |
32463 | log_file_path = /var/spool/exim/log/%D-%slog | |
32464 | ||
32465 | As before, `%s` is replaced by ``main'' or ``reject''; the following are examples | |
32466 | of names generated by the above examples: | |
32467 | ||
32468 | /var/spool/exim/log/mainlog-20021225 | |
32469 | /var/log/exim-reject-20021225.log | |
32470 | /var/spool/exim/log/20021225-mainlog | |
32471 | ||
32472 | When this form of log file is specified, Exim automatically switches to new | |
32473 | files at midnight. It does not make any attempt to compress old logs; you | |
32474 | will need to write your own script if you require this. You should not | |
32475 | run 'exicyclog' with this form of logging. | |
32476 | ||
32477 | The location of the panic log is also determined by %log_file_path%, but it | |
32478 | is not datestamped, because rotation of the panic log does not make sense. | |
32479 | When generating the name of the panic log, `%D` is removed from the string. | |
32480 | In addition, if it immediately follows a slash, a following non-alphanumeric | |
32481 | character is removed; otherwise a preceding non-alphanumeric character is | |
32482 | removed. Thus, the three examples above would give these panic log names: | |
32483 | ||
32484 | /var/spool/exim/log/paniclog | |
32485 | /var/log/exim-panic.log | |
32486 | /var/spool/exim/log/paniclog | |
32487 | ||
32488 | ||
32489 | ||
32490 | ||
32491 | Logging to syslog | |
32492 | ~~~~~~~~~~~~~~~~~ | |
32493 | cindex:[log,syslog; writing to] | |
32494 | The use of syslog does not change what Exim logs or the format of its messages, | |
32495 | except in one respect. If %syslog_timestamp% is set false, the timestamps on | |
32496 | Exim's log lines are omitted when these lines are sent to syslog. Apart from | |
32497 | that, the same strings are written to syslog as to log files. The syslog | |
32498 | ``facility'' is set to LOG_MAIL, and the program name to ``exim'' | |
32499 | by default, but you can change these by setting the %syslog_facility% and | |
32500 | %syslog_processname% options, respectively. If Exim was compiled with | |
32501 | SYSLOG_LOG_PID set in _Local/Makefile_ (this is the default in | |
32502 | _src/EDITME_), then, on systems that permit it (all except ULTRIX), the | |
32503 | LOG_PID flag is set so that the 'syslog()' call adds the pid as well as | |
32504 | the time and host name to each line. | |
32505 | The three log streams are mapped onto syslog priorities as follows: | |
32506 | ||
32507 | - 'mainlog' is mapped to LOG_INFO | |
32508 | ||
32509 | - 'rejectlog' is mapped to LOG_NOTICE | |
32510 | ||
32511 | - 'paniclog' is mapped to LOG_ALERT | |
32512 | ||
32513 | Many log lines are written to both 'mainlog' and 'rejectlog', and some are | |
32514 | written to both 'mainlog' and 'paniclog', so there will be duplicates if | |
32515 | these are routed by syslog to the same place. You can suppress this duplication | |
32516 | by setting %syslog_duplication% false. | |
32517 | ||
32518 | Exim's log lines can sometimes be very long, and some of its 'rejectlog' | |
32519 | entries contain multiple lines when headers are included. To cope with both | |
32520 | these cases, entries written to syslog are split into separate 'syslog()' | |
32521 | calls at each internal newline, and also after a maximum of | |
32522 | 870 data characters. (This allows for a total syslog line length of 1024, when | |
32523 | additions such as timestamps are added.) If you are running a syslog | |
32524 | replacement that can handle lines longer than the 1024 characters allowed by | |
32525 | RFC 3164, you should set | |
32526 | ||
32527 | SYSLOG_LONG_LINES=yes | |
32528 | ||
32529 | in _Local/Makefile_ before building Exim. That stops Exim from splitting long | |
32530 | lines, but it still splits at internal newlines in 'reject' log entries. | |
32531 | ||
32532 | To make it easy to re-assemble split lines later, each component of a split | |
32533 | entry starts with a string of the form ``[<''n'>/<'m'>]' or ``[<''n'>\<'m'>]' | |
32534 | where <'n'> is the component number and <'m'> is the total number of components | |
32535 | in the entry. The / delimiter is used when the line was split because it was | |
32536 | too long; if it was split because of an internal newline, the \ delimiter is | |
32537 | used. For example, supposing the length limit to be 70 instead of 1000, the | |
32538 | following would be the result of a typical rejection message to 'mainlog' | |
32539 | (LOG_INFO), each line in addition being preceded by the time, host name, and | |
32540 | pid as added by syslog: | |
32541 | ||
32542 | $smc\{[1/3] 2002-09-16 16:09:43 16RdAL-0006pc-00 rejected from [127.0.0.1] (ph10): | |
32543 | [2/3] syntax error in 'From' header when scanning for sender: missing or ma | |
32544 | [3/3] lformed local part in "<>" (envelope sender is <ph10@cam.example>)\} | |
32545 | ||
32546 | The same error might cause the following lines to be written to ``rejectlog'' | |
32547 | (LOG_NOTICE): | |
32548 | ||
32549 | $smc\{[1/14] 2002-09-16 16:09:43 16RdAL-0006pc-00 rejected from [127.0.0.1] (ph10): | |
32550 | [2/14] syntax error in 'From' header when scanning for sender: missing or ma | |
32551 | [3\14] lformed local part in "<>" (envelope sender is <ph10@cam.example>) | |
32552 | [4\14] Recipients: ph10@some.domain.cam.example | |
32553 | [5\14] P Received: from [127.0.0.1] (ident=ph10) | |
32554 | [6\14] by xxxxx.cam.example with smtp (Exim 4.00) | |
32555 | [7\14] id 16RdAL-0006pc-00 | |
32556 | [8\14] for ph10@cam.example; Mon, 16 Sep 2002 16:09:43 +0100 | |
32557 | [9\14] F From: <> | |
32558 | [10\14] Subject: this is a test header | |
32559 | [11\14] X-something: this is another header | |
32560 | [12\14] I Message-Id: <E16RdAL-0006pc-00@xxxxx.cam.example> | |
32561 | [13\14] B Bcc: | |
32562 | [14/14] Date: Mon, 16 Sep 2002 16:09:43 +0100\} | |
32563 | ||
32564 | Log lines that are neither too long nor contain newlines are written to syslog | |
32565 | without modification. | |
32566 | ||
32567 | If only syslog is being used, the Exim monitor is unable to provide a log tail | |
32568 | display, unless syslog is routing 'mainlog' to a file on the local host and | |
32569 | the environment variable EXIMON_LOG_FILE_PATH is set to tell the monitor | |
32570 | where it is. | |
32571 | ||
32572 | ||
32573 | ||
32574 | Log line flags | |
32575 | ~~~~~~~~~~~~~~ | |
32576 | One line is written to the main log for each message received, and for each | |
32577 | successful, unsuccessful, and delayed delivery. These lines can readily be | |
32578 | picked out by the distinctive two-character flags that immediately follow the | |
32579 | timestamp. The flags are: | |
32580 | ||
32581 | &&& | |
32582 | `<=` message arrival | |
32583 | `=>` normal message delivery | |
32584 | `->` additional address in same delivery | |
32585 | `\*>` delivery suppressed by %-N% | |
32586 | `\*\*` delivery failed; address bounced | |
32587 | `==` delivery deferred; temporary problem | |
32588 | &&& | |
32589 | ||
32590 | ||
32591 | ||
32592 | Logging message reception | |
32593 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
32594 | cindex:[log,reception line] | |
32595 | The format of the single-line entry in the main log that is written for every | |
32596 | message received is shown in the basic example below, which is split over | |
32597 | several lines in order to fit it on the page: | |
32598 | ||
32599 | 2002-10-31 08:57:53 16ZCW1-0005MB-00 <= kryten@dwarf.fict.example | |
32600 | H=mailer.fict.example [192.168.123.123] U=exim | |
32601 | P=smtp S=5678 id=<incoming message id> | |
32602 | ||
32603 | The address immediately following ``<='' is the envelope sender address. A bounce | |
32604 | message is shown with the sender address ``<>'', and if it is locally generated, | |
32605 | this is followed by an item of the form | |
32606 | ||
32607 | R=<message id> | |
32608 | ||
32609 | which is a reference to the message that caused the bounce to be sent. | |
32610 | ||
32611 | cindex:[HELO] | |
32612 | cindex:[EHLO] | |
32613 | For messages from other hosts, the H and U fields identify the remote host and | |
32614 | record the RFC 1413 identity of the user that sent the message, if one was | |
32615 | received. The number given in square brackets is the IP address of the sending | |
32616 | host. If there is a single, unparenthesized host name in the H field, as | |
32617 | above, it has been verified to correspond to the IP address (see the | |
32618 | %host_lookup% option). If the name is in parentheses, it was the name quoted | |
32619 | by the remote host in the SMTP HELO or EHLO command, and has not been | |
32620 | verified. If verification yields a different name to that given for HELO or | |
32621 | EHLO, the verified name appears first, followed by the HELO or EHLO | |
32622 | name in parentheses. | |
32623 | ||
32624 | Misconfigured hosts (and mail forgers) sometimes put an IP address, with or | |
32625 | without brackets, in the HELO or EHLO command, leading to entries in | |
32626 | the log containing text like these examples: | |
32627 | ||
32628 | H=(10.21.32.43) [192.168.8.34] | |
32629 | H=([10.21.32.43]) [192.168.8.34] | |
32630 | ||
32631 | This can be confusing. Only the final address in square brackets can be relied | |
32632 | on. | |
32633 | ||
32634 | For locally generated messages (that is, messages not received over TCP/IP), | |
32635 | the H field is omitted, and the U field contains the login name of the caller | |
32636 | of Exim. | |
32637 | ||
068aaea8 | 32638 | [revisionflag="changed"] |
168e428f PH |
32639 | cindex:[authentication,logging] |
32640 | cindex:[AUTH,logging] | |
32641 | For all messages, the P field specifies the protocol used to receive the | |
068aaea8 PH |
32642 | message. This is the value that is stored in $received_protocol$. In the case |
32643 | of incoming SMTP messages, the value indicates whether or not any SMTP | |
32644 | extensions (ESMTP), encryption, or authentication were used. If the SMTP | |
32645 | session was encrypted, there is an additional X field that records the cipher | |
32646 | suite that was used. | |
32647 | ||
32648 | [revisionflag="changed"] | |
32649 | The protocol is set to ``esmptsa'' or ``esmtpa'' for messages received from | |
32650 | hosts that have authenticated themselves using the SMTP AUTH command. The first | |
32651 | value is used when the SMTP connection was encrypted (``secure''). In this case | |
32652 | there is an additional item A= followed by the name of the authenticator that | |
32653 | was used. If an authenticated identification was set up by the authenticator's | |
168e428f PH |
32654 | %server_set_id% option, this is logged too, separated by a colon from the |
32655 | authenticator name. | |
32656 | ||
068aaea8 | 32657 | |
168e428f | 32658 | cindex:[size,of message] |
068aaea8 PH |
32659 | The id field records the existing message id, if present. The size of the |
32660 | received message is given by the S field. When the message is delivered, | |
32661 | headers may be removed or added, so that the size of delivered copies of the | |
32662 | message may not correspond with this value (and indeed may be different to each | |
32663 | other). | |
168e428f PH |
32664 | |
32665 | The %log_selector% option can be used to request the logging of additional | |
32666 | data when a message is received. See section <<SECTlogselector>> below. | |
32667 | ||
32668 | ||
32669 | ||
32670 | Logging deliveries | |
32671 | ~~~~~~~~~~~~~~~~~~ | |
32672 | cindex:[log,delivery line] | |
32673 | The format of the single-line entry in the main log that is written for every | |
32674 | delivery is shown in one of the examples below, for local and remote deliveries, | |
32675 | respectively. Each example has been split into two lines in order to fit | |
32676 | it on the page: | |
32677 | ||
32678 | 2002-10-31 08:59:13 16ZCW1-0005MB-00 => marv <marv@hitch.fict.example> | |
32679 | R=localuser T=local_delivery | |
32680 | 2002-10-31 09:00:10 16ZCW1-0005MB-00 => monk@holistic.fict.example | |
32681 | R=dnslookup T=remote_smtp H=holistic.fict.example [192.168.234.234] | |
32682 | ||
32683 | For ordinary local deliveries, the original address is given in angle brackets | |
32684 | after the final delivery address, which might be a pipe or a file. If | |
32685 | intermediate address(es) exist between the original and the final address, the | |
32686 | last of these is given in parentheses after the final address. The R and T | |
32687 | fields record the router and transport that were used to process the address. | |
32688 | ||
32689 | If a shadow transport was run after a successful local delivery, the log line | |
32690 | for the successful delivery has an item added on the end, of the form | |
32691 | ||
32692 | ST=<shadow transport name> | |
32693 | ||
32694 | If the shadow transport did not succeed, the error message is put in | |
32695 | parentheses afterwards. | |
32696 | ||
068aaea8 | 32697 | cindex:[asterisk,after IP address] |
168e428f | 32698 | When more than one address is included in a single delivery (for example, two |
068aaea8 PH |
32699 | SMTP RCPT commands in one transaction) the second and subsequent addresses are |
32700 | flagged with `->` instead of `=>`. When two or more messages are delivered down | |
32701 | a single SMTP connection, an asterisk follows the IP address in the log lines | |
32702 | for the second and subsequent messages. | |
168e428f PH |
32703 | |
32704 | The generation of a reply message by a filter file gets logged as a ``delivery'' | |
32705 | to the addressee, preceded by ``>''. | |
32706 | ||
32707 | The %log_selector% option can be used to request the logging of additional | |
32708 | data when a message is delivered. See section <<SECTlogselector>> below. | |
32709 | ||
32710 | ||
168e428f PH |
32711 | Discarded deliveries |
32712 | ~~~~~~~~~~~~~~~~~~~~ | |
32713 | cindex:[discarded messages] | |
32714 | cindex:[message,discarded] | |
32715 | cindex:[delivery,discarded; logging] | |
32716 | When a message is discarded as a result of the command ``seen finish'' being | |
32717 | obeyed in a filter file which generates no deliveries, a log entry of the form | |
32718 | ||
32719 | 2002-12-10 00:50:49 16auJc-0001UB-00 => discarded | |
32720 | <low.club@bridge.example> R=userforward | |
32721 | ||
32722 | is written, to record why no deliveries are logged. When a message is discarded | |
32723 | because it is aliased to ``:blackhole:'' the log line is like this: | |
32724 | ||
32725 | 1999-03-02 09:44:33 10HmaX-0005vi-00 => :blackhole: | |
32726 | <hole@nowhere.example> R=blackhole_router | |
32727 | ||
32728 | ||
32729 | ||
32730 | ||
32731 | Deferred deliveries | |
32732 | ~~~~~~~~~~~~~~~~~~~ | |
32733 | When a delivery is deferred, a line of the following form is logged: | |
32734 | ||
32735 | 2002-12-19 16:20:23 16aiQz-0002Q5-00 == marvin@endrest.example | |
32736 | R=dnslookup T=smtp defer (146): Connection refused | |
32737 | ||
32738 | In the case of remote deliveries, the error is the one that was given for the | |
32739 | last IP address that was tried. Details of individual SMTP failures are also | |
32740 | written to the log, so the above line would be preceded by something like | |
32741 | ||
32742 | 2002-12-19 16:20:23 16aiQz-0002Q5-00 Failed to connect to | |
32743 | mail1.endrest.example [192.168.239.239]: Connection refused | |
32744 | ||
32745 | When a deferred address is skipped because its retry time has not been reached, | |
32746 | a message is written to the log, but this can be suppressed by setting an | |
32747 | appropriate value in %log_selector%. | |
32748 | ||
32749 | ||
32750 | ||
32751 | Delivery failures | |
32752 | ~~~~~~~~~~~~~~~~~ | |
32753 | cindex:[delivery,failure; logging] | |
32754 | If a delivery fails because an address cannot be routed, a line of the | |
32755 | following form is logged: | |
32756 | ||
32757 | 1995-12-19 16:20:23 0tRiQz-0002Q5-00 ** jim@trek99.example | |
32758 | <jim@trek99.example>: unknown mail domain | |
32759 | ||
32760 | If a delivery fails at transport time, the router and transport are shown, and | |
32761 | the response from the remote host is included, as in this example: | |
32762 | ||
32763 | 2002-07-11 07:14:17 17SXDU-000189-00 ** ace400@pb.example R=dnslookup | |
32764 | T=remote_smtp: SMTP error from remote mailer after pipelined | |
32765 | RCPT TO:<ace400@pb.example>: host pbmail3.py.example | |
32766 | [192.168.63.111]: 553 5.3.0 <ace400@pb.example>... | |
32767 | Addressee unknown | |
32768 | ||
32769 | The word ``pipelined'' indicates that the SMTP PIPELINING extension was being | |
32770 | used. See %hosts_avoid_esmtp% in the ^smtp^ transport for a way of | |
32771 | disabling PIPELINING. | |
32772 | ||
32773 | The log lines for all forms of delivery failure are flagged with `\*\*`. | |
32774 | ||
32775 | ||
32776 | ||
32777 | Fake deliveries | |
32778 | ~~~~~~~~~~~~~~~ | |
32779 | cindex:[delivery,fake; logging] | |
32780 | If a delivery does not actually take place because the %-N% option has been | |
32781 | used to suppress it, a normal delivery line is written to the log, except that | |
32782 | ``=>'' is replaced by ``\*>''. | |
32783 | ||
32784 | ||
32785 | ||
32786 | Completion | |
32787 | ~~~~~~~~~~ | |
32788 | A line of the form | |
32789 | ||
32790 | 2002-10-31 09:00:11 16ZCW1-0005MB-00 Completed | |
32791 | ||
32792 | is written to the main log when a message is about to be removed from the spool | |
32793 | at the end of its processing. | |
32794 | ||
32795 | ||
32796 | ||
32797 | ||
32798 | Summary of Fields in Log Lines | |
32799 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
32800 | cindex:[log,summary of fields] | |
32801 | A summary of the field identifiers that are used in log lines is shown in | |
32802 | the following table: | |
32803 | ||
32804 | &&& | |
32805 | `A ` authenticator name (and optional id) | |
32806 | `C ` SMTP confirmation on delivery | |
32807 | `CV ` certificate verification status | |
32808 | `DN ` distinguished name from peer certificate | |
32809 | `DT ` on `=>` lines: time taken for a delivery | |
32810 | `F ` sender address (on delivery lines) | |
32811 | `H ` host name and IP address | |
32812 | `I ` local interface used | |
32813 | `id ` message id for incoming message | |
32814 | `P ` on `<=` lines: protocol used | |
32815 | ` ` on `=>` and `\*\*` lines: return path | |
32816 | `QT ` on `=>` lines: time spent on queue so far | |
32817 | ` ` on ``Completed'' lines: time spent on queue | |
32818 | `R ` on `<=` lines: reference for local bounce | |
32819 | ` ` on `=>` `\*\*` and `==` lines: router name | |
32820 | `S ` size of message | |
32821 | `ST ` shadow transport name | |
32822 | `T ` on `<=` lines: message subject (topic) | |
32823 | ` ` on `=>` `\*\*` and `==` lines: transport name | |
32824 | `U ` local user or RFC 1413 identity | |
32825 | `X ` TLS cipher suite | |
32826 | &&& | |
32827 | ||
32828 | ||
32829 | ||
32830 | Other log entries | |
32831 | ~~~~~~~~~~~~~~~~~ | |
32832 | Various other types of log entry are written from time to time. Most should be | |
32833 | self-explanatory. Among the more common are: | |
32834 | ||
32835 | - cindex:[retry,time not reached] | |
32836 | 'retry time not reached'~~An address previously suffered a temporary error | |
32837 | during routing or local delivery, and the time to retry has not yet arrived. | |
32838 | This message is not written to an individual message log file unless it happens | |
32839 | during the first delivery attempt. | |
32840 | ||
32841 | - 'retry time not reached for any host'~~An address previously suffered | |
32842 | temporary errors during remote delivery, and the retry time has not yet arrived | |
32843 | for any of the hosts to which it is routed. | |
32844 | ||
32845 | - cindex:[spool directory,file locked] | |
32846 | 'spool file locked'~~An attempt to deliver a message cannot proceed because | |
32847 | some other Exim process is already working on the message. This can be quite | |
32848 | common if queue running processes are started at frequent intervals. The | |
32849 | 'exiwhat' utility script can be used to find out what Exim processes are | |
32850 | doing. | |
32851 | ||
32852 | - cindex:[error,ignored] | |
32853 | 'error ignored'~~There are several circumstances that give rise to this | |
32854 | message: | |
32855 | ||
32856 | . Exim failed to deliver a bounce message whose age was greater than | |
32857 | %ignore_bounce_errors_after%. The bounce was discarded. | |
32858 | ||
32859 | . A filter file set up a delivery using the ``noerror'' option, and the delivery | |
32860 | failed. The delivery was discarded. | |
32861 | ||
32862 | . A delivery set up by a router configured with | |
32863 | + | |
32864 | errors_to = <> | |
32865 | + | |
32866 | failed. The delivery was discarded. | |
32867 | ||
32868 | ||
32869 | ||
32870 | ||
32871 | ||
32872 | [[SECTlogselector]] | |
32873 | Reducing or increasing what is logged | |
32874 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
32875 | cindex:[log,selectors] | |
32876 | By setting the %log_selector% global option, you can disable some of Exim's | |
32877 | default logging, or you can request additional logging. The value of | |
32878 | %log_selector% is made up of names preceded by plus or minus characters. For | |
32879 | example: | |
32880 | ||
32881 | log_selector = +arguments -retry_defer | |
32882 | ||
32883 | The list of optional log items is in the following table, with the default | |
32884 | selection marked by asterisks: | |
32885 | ||
32886 | &&& | |
d1e83bff | 32887 | `\*acl_warn_skipped ` skipped %warn% statement in ACL |
168e428f PH |
32888 | ` address_rewrite ` address rewriting |
32889 | ` all_parents ` all parents in => lines | |
32890 | ` arguments ` command line arguments | |
32891 | `\*connection_reject ` connection rejections | |
32892 | `\*delay_delivery ` immediate delivery delayed | |
32893 | ` deliver_time ` time taken to perform delivery | |
32894 | ` delivery_size ` add S=nnn to => lines | |
32895 | `\*dnslist_defer ` defers of DNS list (aka RBL) lookups | |
32896 | `\*etrn ` ETRN commands | |
32897 | `\*host_lookup_failed ` as it says | |
32898 | ` ident_timeout ` timeout for ident connection | |
32899 | ` incoming_interface ` incoming interface on <= lines | |
32900 | ` incoming_port ` incoming port on <= lines | |
32901 | `\*lost_incoming_connection ` as it says (includes timeouts) | |
32902 | ` outgoing_port ` add remote port to => lines | |
32903 | `\*queue_run ` start and end queue runs | |
32904 | ` queue_time ` time on queue for one recipient | |
32905 | ` queue_time_overall ` time on queue for whole message | |
32906 | ` received_recipients ` recipients on <= lines | |
32907 | ` received_sender ` sender on <= lines | |
32908 | `\*rejected_header ` header contents on reject log | |
32909 | `\*retry_defer ` ``retry time not reached'' | |
32910 | ` return_path_on_delivery ` put return path on => and \*\ lines | |
32911 | ` sender_on_delivery ` add sender to => lines | |
32912 | `\*size_reject ` rejection because too big | |
32913 | `\*skip_delivery ` delivery skipped in a queue run | |
32914 | ` smtp_confirmation ` SMTP confirmation on => lines | |
32915 | ` smtp_connection ` SMTP connections | |
32916 | ` smtp_incomplete_transaction` incomplete SMTP transactions | |
32917 | ` smtp_protocol_error ` SMTP protocol errors | |
32918 | ` smtp_syntax_error ` SMTP syntax errors | |
32919 | ` subject ` contents of 'Subject:' on <= lines | |
32920 | ` tls_certificate_verified ` certificate verification status | |
32921 | `\*tls_cipher ` TLS cipher suite on <= and => lines | |
32922 | ` tls_peerdn ` TLS peer DN on <= and => lines | |
068aaea8 | 32923 | ` unknown_in_list ` DNS lookup failed in list match |
168e428f PH |
32924 | |
32925 | ` all ` all of the above | |
32926 | &&& | |
32927 | ||
32928 | More details on each of these items follows: | |
32929 | ||
d1e83bff PH |
32930 | [revisionflag="changed"] |
32931 | - cindex:[%warn% statement,log when skipping] | |
32932 | %acl_warn_skipped%: When an ACL %warn% statement is skipped because one of its | |
32933 | conditions cannot be evaluated, a log line to this effect is written if this | |
32934 | log selector is set. | |
32935 | ||
168e428f PH |
32936 | - cindex:[log,rewriting] |
32937 | cindex:[rewriting,logging] | |
32938 | %address_rewrite%: This applies both to global rewrites and per-transport | |
d1e83bff PH |
32939 | rewrites, but not to rewrites in filters run as an unprivileged user (because |
32940 | such users cannot access the log). | |
168e428f PH |
32941 | |
32942 | - cindex:[log,full parentage] | |
32943 | %all_parents%: Normally only the original and final addresses are logged on | |
32944 | delivery lines; with this selector, intermediate parents are given in | |
32945 | parentheses between them. | |
32946 | ||
32947 | - cindex:[log,Exim arguments] | |
32948 | cindex:[Exim arguments, logging] | |
32949 | %arguments%: This causes Exim to write the arguments with which it was called | |
32950 | to the main log, preceded by the current working directory. This is a debugging | |
32951 | feature, added to make it easier to find out how certain MUAs call | |
32952 | _/usr/sbin/sendmail_. The logging does not happen if Exim has given up root | |
32953 | privilege because it was called with the %-C% or %-D% options. Arguments that | |
068aaea8 | 32954 | are empty or that contain white space are quoted. Non-printing characters are |
168e428f PH |
32955 | shown as escape sequences. This facility cannot log unrecognized arguments, |
32956 | because the arguments are checked before the configuration file is read. The | |
32957 | only way to log such cases is to interpose a script such as _util/logargs.sh_ | |
32958 | between the caller and Exim. | |
32959 | ||
32960 | - cindex:[log,connection rejections] | |
32961 | %connection_reject%: A log entry is written whenever an incoming SMTP | |
32962 | connection is rejected, for whatever reason. | |
32963 | ||
32964 | - cindex:[log,delayed delivery] | |
32965 | cindex:[delayed delivery, logging] | |
32966 | %delay_delivery%: A log entry is written whenever a delivery process is not | |
32967 | started for an incoming message because the load is too high or too many | |
32968 | messages were received on one connection. Logging does not occur if no delivery | |
32969 | process is started because %queue_only% is set or %-odq% was used. | |
32970 | ||
32971 | - cindex:[log,delivery duration] | |
32972 | %deliver_time%: For each delivery, the amount of real time it has taken to | |
32973 | perform the actual delivery is logged as DT=<'time'>, for example, `DT=1s`. | |
32974 | ||
32975 | - cindex:[log,message size on delivery] | |
32976 | cindex:[size,of message] | |
32977 | %delivery_size%: For each delivery, the size of message delivered is added to | |
32978 | the ``=>'' line, tagged with S=. | |
32979 | ||
32980 | - cindex:[log,dnslist defer] | |
32981 | cindex:[DNS list,logging defer] | |
32982 | cindex:[black list (DNS)] | |
32983 | %dnslist_defer%: A log entry is written if an attempt to look up a host in a | |
32984 | DNS black list suffers a temporary error. | |
32985 | ||
32986 | - cindex:[log,ETRN commands] | |
32987 | cindex:[ETRN,logging] | |
32988 | %etrn%: Every legal ETRN command that is received is logged, before the ACL is | |
32989 | run to determine whether or not it is actually accepted. An invalid ETRN | |
32990 | command, or one received within a message transaction is not logged by this | |
32991 | selector (see %smtp_syntax_error% and %smtp_protocol_error%). | |
32992 | ||
32993 | - cindex:[log,host lookup failure] | |
32994 | %host_lookup_failed%: When a lookup of a host's IP addresses fails to find | |
32995 | any addresses, or when a lookup of an IP address fails to find a host name, a | |
32996 | log line is written. This logging does not apply to direct DNS lookups when | |
32997 | routing email addresses, but it does apply to ``byname'' lookups. | |
32998 | ||
32999 | - cindex:[log,ident timeout] | |
33000 | cindex:[RFC 1413,logging timeout] | |
33001 | %ident_timeout%: A log line is written whenever an attempt to connect to a | |
33002 | client's ident port times out. | |
33003 | ||
33004 | - cindex:[log,incoming interface] | |
33005 | cindex:[interface,logging] | |
33006 | %incoming_interface%: The interface on which a message was received is added to | |
33007 | the ``<='' line as an IP address in square brackets, tagged by I= and followed | |
33008 | by a colon and the port number. The local interface and port are also added to | |
33009 | other SMTP log lines, for example ``SMTP connection from'', and to rejection | |
33010 | lines. | |
33011 | ||
33012 | - cindex:[log,incoming remote port] | |
33013 | cindex:[port,logging remote] | |
33014 | cindex:[TCP/IP,logging incoming remote port] | |
068aaea8 PH |
33015 | cindex:[$sender_fullhost$] |
33016 | cindex:[$sender_rcvhost$] | |
168e428f PH |
33017 | %incoming_port%: The remote port number from which a message was received is |
33018 | added to log entries and 'Received:' header lines, following the IP address in | |
33019 | square brackets, and separated from it by a colon. This is implemented by | |
33020 | changing the value that is put in the $sender_fullhost$ and | |
33021 | $sender_rcvhost$ variables. Recording the remote port number has become more | |
33022 | important with the widening use of NAT (see RFC 2505). | |
33023 | ||
33024 | - cindex:[log,dropped connection] | |
33025 | %lost_incoming_connection%: A log line is written when an incoming SMTP | |
33026 | connection is unexpectedly dropped. | |
33027 | ||
33028 | - cindex:[log,outgoing remote port] | |
33029 | cindex:[port,logging outgoint remote] | |
33030 | cindex:[TCP/IP,logging ougtoing remote port] | |
33031 | %outgoing_port%: The remote port number is added to delivery log lines (those | |
33032 | containing => tags) following the IP address. This option is not included in | |
33033 | the default setting, because for most ordinary configurations, the remote port | |
33034 | number is always 25 (the SMTP port). | |
33035 | ||
33036 | - cindex:[log,queue run] | |
33037 | cindex:[queue runner,logging] | |
33038 | %queue_run%: The start and end of every queue run are logged. | |
33039 | ||
33040 | - cindex:[log,queue time] | |
33041 | %queue_time%: The amount of time the message has been in the queue on the local | |
33042 | host is logged as QT=<'time'> on delivery (`=>`) lines, for example, | |
33043 | `QT=3m45s`. The clock starts when Exim starts to receive the message, so it | |
33044 | includes reception time as well as the delivery time for the current address. | |
33045 | This means that it may be longer than the difference between the arrival and | |
33046 | delivery log line times, because the arrival log line is not written until the | |
33047 | message has been successfully received. | |
33048 | ||
33049 | - %queue_time_overall%: The amount of time the message has been in the queue on | |
33050 | the local host is logged as QT=<'time'> on ``Completed'' lines, for | |
33051 | example, `QT=3m45s`. The clock starts when Exim starts to receive the | |
33052 | message, so it includes reception time as well as the total delivery time. | |
33053 | ||
33054 | - cindex:[log,recipients] | |
33055 | %received_recipients%: The recipients of a message are listed in the main log | |
33056 | as soon as the message is received. The list appears at the end of the log line | |
33057 | that is written when a message is received, preceded by the word ``for''. The | |
33058 | addresses are listed after they have been qualified, but before any rewriting | |
33059 | has taken place. | |
33060 | Recipients that were discarded by an ACL for MAIL or RCPT do not appear | |
33061 | in the list. | |
33062 | ||
33063 | - cindex:[log,sender reception] | |
33064 | %received_sender%: The unrewritten original sender of a message is added to | |
33065 | the end of the log line that records the message's arrival, after the word | |
33066 | ``from'' (before the recipients if %received_recipients% is also set). | |
33067 | ||
33068 | - cindex:[log,header lines for rejection] | |
33069 | %rejected_header%: If a message's header has been received at the time a | |
33070 | rejection is written to the reject log, the complete header is added to the | |
33071 | log. Header logging can be turned off individually for messages that are | |
33072 | rejected by the 'local_scan()' function (see section <<SECTapiforloc>>). | |
33073 | ||
33074 | - cindex:[log,retry defer] | |
33075 | %retry_defer%: A log line is written if a delivery is deferred because a retry | |
33076 | time has not yet been reached. However, this ``retry time not reached'' message | |
33077 | is always omitted from individual message logs after the first delivery | |
33078 | attempt. | |
33079 | ||
33080 | - cindex:[log,return path] | |
33081 | %return_path_on_delivery%: The return path that is being transmitted with | |
33082 | the message is included in delivery and bounce lines, using the tag P=. | |
33083 | This is omitted if no delivery actually happens, for example, if routing fails, | |
33084 | or if delivery is to _/dev/null_ or to `:blackhole:`. | |
33085 | ||
33086 | - cindex:[log,sender on delivery] | |
33087 | %sender_on_delivery%: The message's sender address is added to every delivery | |
33088 | and bounce line, tagged by F= (for ``from''). | |
33089 | This is the original sender that was received with the message; it is not | |
33090 | necessarily the same as the outgoing return path. | |
33091 | ||
33092 | - cindex:[log,size rejection] | |
33093 | %size_reject%: A log line is written whenever a message is rejected because it | |
33094 | is too big. | |
33095 | ||
33096 | - cindex:[log,frozen messages; skipped] | |
33097 | cindex:[frozen messages,logging skipping] | |
33098 | %skip_delivery%: A log line is written whenever a message is skipped during a | |
33099 | queue run because it is frozen or because another process is already delivering | |
33100 | it. | |
33101 | cindex:[``spool file is locked''] | |
33102 | The message that is written is ``spool file is locked''. | |
33103 | ||
33104 | - cindex:[log,smtp confirmation] | |
33105 | cindex:[SMTP,logging confirmation] | |
33106 | %smtp_confirmation%: The response to the final ``.'' in the SMTP dialogue for | |
33107 | outgoing messages is added to delivery log lines in the form ``C="<''text'>"'. A | |
33108 | number of MTAs (including Exim) return an identifying string in this response. | |
33109 | ||
33110 | - cindex:[log,SMTP connections] | |
33111 | cindex:[SMTP,logging connections] | |
33112 | %smtp_connection%: A log line is written whenever an SMTP connection is | |
33113 | established or closed, unless the connection is from a host that matches | |
33114 | %hosts_connection_nolog%. (In contrast, %lost_incoming_connection% applies only | |
33115 | when the closure is unexpected.) This applies to connections from local | |
33116 | processes that use %-bs% as well as to TCP/IP connections. If a connection is | |
33117 | dropped in the middle of a message, a log line is always written, whether or | |
33118 | not this selector is set, but otherwise nothing is written at the start and end | |
33119 | of connections unless this selector is enabled. | |
33120 | + | |
33121 | For TCP/IP connections to an Exim daemon, the current number of connections is | |
33122 | included in the log message for each new connection, but note that the count is | |
33123 | reset if the daemon is restarted. | |
33124 | Also, because connections are closed (and the closure is logged) in | |
33125 | subprocesses, the count may not include connections that have been closed but | |
33126 | whose termination the daemon has not yet noticed. Thus, while it is possible to | |
33127 | match up the opening and closing of connections in the log, the value of the | |
33128 | logged counts may not be entirely accurate. | |
33129 | ||
33130 | - cindex:[log,SMTP transaction; incomplete] | |
33131 | cindex:[SMTP,logging incomplete transactions] | |
33132 | %smtp_incomplete_transaction%: When a mail transaction is aborted by | |
33133 | RSET, QUIT, loss of connection, or otherwise, the incident is logged, | |
33134 | and the message sender plus any accepted recipients are included in the log | |
33135 | line. This can provide evidence of dictionary attacks. | |
33136 | ||
33137 | - cindex:[log,SMTP protocol error] | |
33138 | cindex:[SMTP,logging protocol error] | |
33139 | %smtp_protocol_error%: A log line is written for every SMTP protocol error | |
33140 | encountered. Exim does not have perfect detection of all protocol errors | |
33141 | because of transmission delays and the use of pipelining. If PIPELINING has | |
33142 | been advertised to a client, an Exim server assumes that the client will use | |
33143 | it, and therefore it does not count ``expected'' errors (for example, RCPT | |
33144 | received after rejecting MAIL) as protocol errors. | |
33145 | ||
33146 | - cindex:[SMTP,logging syntax errors] | |
33147 | cindex:[SMTP,syntax errors; logging] | |
33148 | cindex:[SMTP,unknown command; logging] | |
33149 | cindex:[log,unknown SMTP command] | |
33150 | cindex:[log,SMTP syntax error] | |
33151 | %smtp_syntax_error%: A log line is written for every SMTP syntax error | |
33152 | encountered. An unrecognized command is treated as a syntax error. For an | |
33153 | external connection, the host identity is given; for an internal connection | |
33154 | using %-bs% the sender identification (normally the calling user) is given. | |
33155 | ||
33156 | - cindex:[log,subject] | |
33157 | cindex:[subject, logging] | |
33158 | %subject%: The subject of the message is added to the arrival log line, | |
33159 | preceded by ``T='' (T for ``topic'', since S is already used for ``size''). | |
33160 | Any MIME ``words'' in the subject are decoded. The %print_topbitchars% option | |
33161 | specifies whether characters with values greater than 127 should be logged | |
33162 | unchanged, or whether they should be rendered as escape sequences. | |
33163 | ||
33164 | - cindex:[log,certificate verification] | |
33165 | %tls_certificate_verified%: An extra item is added to <= and => log lines | |
33166 | when TLS is in use. The item is `CV=yes` if the peer's certificate was | |
33167 | verified, and `CV=no` if not. | |
33168 | ||
33169 | - cindex:[log,TLS cipher] | |
33170 | cindex:[TLS,logging cipher] | |
33171 | %tls_cipher%: When a message is sent or received over an encrypted connection, | |
33172 | the cipher suite used is added to the log line, preceded by X=. | |
33173 | ||
33174 | - cindex:[log,TLS peer DN] | |
33175 | cindex:[TLS,logging peer DN] | |
33176 | %tls_peerdn%: When a message is sent or received over an encrypted connection, | |
33177 | and a certificate is supplied by the remote host, the peer DN is added to the | |
33178 | log line, preceded by DN=. | |
33179 | ||
068aaea8 PH |
33180 | [revisionflag="changed"] |
33181 | - cindex:[log,DNS failure in list] | |
33182 | %unknown_in_list%: This setting causes a log entry to be written when the | |
33183 | result of a list match is failure because a DNS lookup failed. | |
168e428f PH |
33184 | |
33185 | ||
33186 | Message log | |
33187 | ~~~~~~~~~~~ | |
33188 | cindex:[message,log file for] | |
33189 | cindex:[log,message log; description of] | |
33190 | In addition to the general log files, Exim writes a log file for each message | |
33191 | that it handles. The names of these per-message logs are the message ids, and | |
33192 | ||
33193 | cindex:[_msglog_ directory] | |
33194 | they are kept in the _msglog_ sub-directory of the spool directory. Each | |
33195 | message log contains copies of the log lines that apply to the message. This | |
33196 | makes it easier to inspect the status of an individual message without having | |
33197 | to search the main log. A message log is deleted when processing of the message | |
33198 | is complete, | |
33199 | ||
33200 | cindex:[%preserve_message_logs%] | |
33201 | unless %preserve_message_logs% is set, but this should be used only with | |
33202 | great care because they can fill up your disk very quickly. | |
33203 | ||
33204 | On a heavily loaded system, it may be desirable to disable the use of | |
33205 | per-message logs, in order to reduce disk I/O. This can be done by setting the | |
33206 | %message_logs% option false. | |
33207 | ||
33208 | ||
33209 | ||
33210 | //////////////////////////////////////////////////////////////////////////// | |
33211 | //////////////////////////////////////////////////////////////////////////// | |
33212 | ||
33213 | [[CHAPutils]] | |
33214 | Exim utilities | |
33215 | -------------- | |
33216 | cindex:[utilities] | |
33217 | A number of utility scripts and programs are supplied with Exim and are | |
33218 | described in this chapter. There is also the Exim Monitor, which is covered in | |
33219 | the next chapter. The utilities described here are: | |
33220 | ||
33221 | [frame="none"] | |
33222 | `2`8`30`40~ | |
33223 | ,<<SECTfinoutwha>> , 'exiwhat' , list what Exim processes are doing | |
33224 | ,<<SECTgreptheque>> , 'exiqgrep' , grep the queue | |
33225 | ,<<SECTsumtheque>> , 'exiqsumm' , summarize the queue | |
33226 | ,<<SECTextspeinf>> , 'exigrep' , search the main log | |
33227 | ,<<SECTexipick>> , 'exipick' , select messages on various criteria | |
33228 | ,<<SECTcyclogfil>> , 'exicyclog' , cycle (rotate) log files | |
33229 | ,<<SECTmailstat>> , 'eximstats' , extract statistics from the log | |
33230 | ,<<SECTcheckaccess>> , 'exim_checkaccess', check address acceptance from given IP | |
33231 | ,<<SECTdbmbuild>> , 'exim_dbmbuild' , build a DBM file | |
33232 | ,<<SECTfinindret>> , 'exinext' , extract retry information | |
33233 | ,<<SECThindatmai>> , 'exim_dumpdb' , dump a hints database | |
33234 | ,<<SECThindatmai>> , 'exim_tidydb' , clean up a hints database | |
33235 | ,<<SECThindatmai>> , 'exim_fixdb' , patch a hints database | |
33236 | ,<<SECTmailboxmaint>>, 'exim_lock' , lock a mailbox file | |
33237 | ~~~~~ | |
33238 | ||
068aaea8 PH |
33239 | [revisionflag="changed"] |
33240 | Another utility that might be of use to sites with many MTAs is Tom Kistner's | |
33241 | 'exilog'. It provides log visualizations across multiple Exim servers. See | |
33242 | (*http://duncanthrax.net/exilog/[]*) for details. | |
33243 | ||
33244 | ||
33245 | ||
33246 | ||
168e428f PH |
33247 | |
33248 | [[SECTfinoutwha]] | |
33249 | Finding out what Exim processes are doing (exiwhat) | |
33250 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
33251 | cindex:['exiwhat'] | |
33252 | cindex:[process, querying] | |
33253 | cindex:[SIGUSR1] | |
33254 | On operating systems that can restart a system call after receiving a signal | |
33255 | (most modern OS), an Exim process responds to the SIGUSR1 signal by writing | |
33256 | a line describing what it is doing to the file _exim-process.info_ in the | |
33257 | Exim spool directory. The 'exiwhat' script sends the signal to all Exim | |
33258 | processes it can find, having first emptied the file. It then waits for one | |
33259 | second to allow the Exim processes to react before displaying the results. In | |
33260 | order to run 'exiwhat' successfully you have to have sufficient privilege to | |
33261 | send the signal to the Exim processes, so it is normally run as root. | |
33262 | ||
33263 | *Warning*: This is not an efficient process. It is intended for occasional | |
33264 | use by system administrators. It is not sensible, for example, to set up a | |
33265 | script that sends SIGUSR1 signals to Exim processes at short intervals. | |
33266 | ||
33267 | ||
33268 | Unfortunately, the 'ps' command that 'exiwhat' uses to find Exim processes | |
33269 | varies in different operating systems. Not only are different options used, | |
33270 | but the format of the output is different. For this reason, there are some | |
33271 | system configuration options that configure exactly how 'exiwhat' works. If it | |
33272 | doesn't seem to be working for you, check the following compile-time options: | |
33273 | ||
33274 | &&& | |
33275 | `EXIWHAT_PS_CMD ` the command for running 'ps' | |
33276 | `EXIWHAT_PS_ARG ` the argument for 'ps' | |
33277 | `EXIWHAT_EGREP_ARG ` the argument for 'egrep' to select from 'ps' output | |
33278 | `EXIWHAT_KILL_ARG ` the argument for the 'kill' command | |
33279 | &&& | |
33280 | ||
33281 | An example of typical output from 'exiwhat' is | |
33282 | ||
33283 | 164 daemon: -q1h, listening on port 25 | |
33284 | 10483 running queue: waiting for 0tAycK-0002ij-00 (10492) | |
33285 | 10492 delivering 0tAycK-0002ij-00 to mail.ref.example [10.19.42.42] | |
33286 | (editor@ref.example) | |
33287 | 10592 handling incoming call from [192.168.243.242] | |
33288 | 10628 accepting a local non-SMTP message | |
33289 | ||
33290 | The first number in the output line is the process number. The third line has | |
33291 | been split here, in order to fit it on the page. | |
33292 | ||
33293 | ||
33294 | ||
33295 | [[SECTgreptheque]] | |
33296 | Selective queue listing (exiqgrep) | |
33297 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
33298 | cindex:['exiqgrep'] | |
33299 | cindex:[queue,grepping] | |
33300 | This utility is a Perl script contributed by Matt Hubbard. It runs | |
33301 | ||
33302 | exim -bpu | |
33303 | ||
33304 | to obtain a queue listing with undelivered recipients only, and then greps the | |
33305 | output to select messages that match given criteria. The following selection | |
33306 | options are available: | |
33307 | ||
33308 | *-f*~<'regex'>:: | |
33309 | Match the sender address. The field that is tested is enclosed in angle | |
33310 | brackets, so you can test for bounce messages with | |
33311 | ||
33312 | exiqgrep -f '^<>$' | |
33313 | ||
33314 | *-r*~<'regex'>:: | |
33315 | Match a recipient address. The field that is tested is not enclosed in angle | |
33316 | brackets. | |
33317 | ||
33318 | *-s*~<'regex'>:: | |
33319 | Match against the size field. | |
33320 | ||
33321 | *-y*~<'seconds'>:: | |
33322 | Match messages that are younger than the given time. | |
33323 | ||
33324 | *-o*~<'seconds'>:: | |
33325 | Match messages that are older than the given time. | |
33326 | ||
33327 | *-z*:: | |
33328 | Match only frozen messages. | |
33329 | ||
33330 | *-x*:: | |
33331 | Match only non-frozen messages. | |
33332 | ||
33333 | /// | |
33334 | End of list | |
33335 | /// | |
33336 | ||
33337 | The following options control the format of the output: | |
33338 | ||
33339 | *-c*:: | |
33340 | Display only the count of matching messages. | |
33341 | ||
33342 | *-l*:: | |
33343 | Long format -- display the full message information as output by Exim. This is | |
33344 | the default. | |
33345 | ||
33346 | *-i*:: | |
33347 | Display message ids only. | |
33348 | ||
33349 | *-b*:: | |
33350 | Brief format -- one line per message. | |
33351 | ||
33352 | *-R*:: | |
33353 | Display messages in reverse order. | |
33354 | ||
33355 | /// | |
33356 | End of list | |
33357 | /// | |
33358 | ||
33359 | There is one more option, %-h%, which outputs a list of options. | |
33360 | ||
33361 | ||
33362 | ||
33363 | [[SECTsumtheque]] | |
33364 | Summarising the queue (exiqsumm) | |
33365 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
33366 | cindex:['exiqsumm'] | |
33367 | cindex:[queue,summary] | |
33368 | The 'exiqsumm' utility is a Perl script which reads the output of 'exim | |
33369 | -bp' and produces a summary of the messages on the queue. Thus, you use it by | |
33370 | running a command such as | |
33371 | ||
33372 | exim -bp | exiqsumm | |
33373 | ||
33374 | The output consists of one line for each domain that has messages waiting for | |
33375 | it, as in the following example: | |
33376 | ||
33377 | 3 2322 74m 66m msn.com.example | |
33378 | ||
33379 | Each line lists the number of | |
33380 | pending deliveries for a domain, their total volume, and the length of time | |
33381 | that the oldest and the newest messages have been waiting. Note that the number | |
33382 | of pending deliveries is greater than the number of messages when messages | |
33383 | have more than one recipient. | |
33384 | ||
33385 | A summary line is output at the end. By default the output is sorted on the | |
33386 | domain name, but 'exiqsumm' has the options %-a% and %-c%, which cause the | |
33387 | output to be sorted by oldest message and by count of messages, respectively. | |
33388 | ||
33389 | The output of 'exim -bp' contains the original addresses in the message, so | |
33390 | this also applies to the output from 'exiqsumm'. No domains from addresses | |
33391 | generated by aliasing or forwarding are included (unless the %one_time% option | |
33392 | of the ^redirect^ router has been used to convert them into ``top level'' | |
33393 | addresses). | |
33394 | ||
33395 | ||
33396 | ||
33397 | ||
33398 | [[SECTextspeinf]] | |
33399 | Extracting specific information from the log (exigrep) | |
33400 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
068aaea8 | 33401 | [revisionflag="changed"] |
168e428f PH |
33402 | cindex:['exigrep'] |
33403 | cindex:[log,extracts; grepping for] | |
33404 | The 'exigrep' utility is a Perl script that searches one or more main log | |
33405 | files for entries that match a given pattern. When it finds a match, it | |
33406 | extracts all the log entries for the relevant message, not just those that | |
33407 | match the pattern. Thus, 'exigrep' can extract complete log entries for a | |
33408 | given message, or all mail for a given user, or for a given host, for example. | |
068aaea8 | 33409 | The input files can be in Exim log format or syslog format. |
168e428f PH |
33410 | |
33411 | If a matching log line is not associated with a specific message, it is always | |
068aaea8 | 33412 | included in 'exigrep''s output. The usage is: |
168e428f PH |
33413 | |
33414 | exigrep [-l] [-t<n>] <pattern> [<log file>] ... | |
33415 | ||
33416 | The %-t% argument specifies a number of seconds. It adds an additional | |
33417 | condition for message selection. Messages that are complete are shown only if | |
33418 | they spent more than <'n'> seconds on the queue. | |
33419 | ||
33420 | The %-l% flag means ``literal'', that is, treat all characters in the | |
33421 | pattern as standing for themselves. Otherwise the pattern must be a Perl | |
33422 | regular expression. The pattern match is case-insensitive. If no file names are | |
33423 | given on the command line, the standard input is read. | |
33424 | ||
33425 | If the location of a 'zcat' command is known from the definition of | |
068aaea8 PH |
33426 | ZCAT_COMMAND in _Local/Makefile_, 'exigrep' automatically passes any file whose |
33427 | name ends in COMPRESS_SUFFIX through 'zcat' as it searches it. | |
168e428f PH |
33428 | |
33429 | ||
33430 | [[SECTexipick]] | |
33431 | Selecting messages by various criteria (exipick) | |
33432 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
33433 | cindex:['exipick'] | |
33434 | John Jetmore's 'exipick' utility is included in the Exim distribution. It | |
33435 | lists messages from the queue according to a variety of criteria. For details, | |
33436 | run: | |
33437 | ||
33438 | exipick --help | |
33439 | ||
33440 | ||
33441 | ||
33442 | ||
33443 | [[SECTcyclogfil]] | |
33444 | Cycling log files (exicyclog) | |
33445 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
33446 | cindex:[log,cycling local files] | |
33447 | cindex:[cycling logs] | |
33448 | cindex:['exicyclog'] | |
33449 | The 'exicyclog' script can be used to cycle (rotate) 'mainlog' and | |
33450 | 'rejectlog' files. This is not necessary if only syslog is being used, or if | |
33451 | you are using log files with datestamps in their names (see section | |
33452 | <<SECTdatlogfil>>). Some operating systems have their own standard mechanisms for | |
33453 | log cycling, and these can be used instead of 'exicyclog' if preferred. | |
33454 | ||
33455 | Each time 'exicyclog' is run the file names get ``shuffled down'' by one. If | |
33456 | the main log file name is _mainlog_ (the default) then when 'exicyclog' is | |
33457 | run _mainlog_ becomes _mainlog.01_, the previous _mainlog.01_ becomes | |
33458 | _mainlog.02_ and so on, up to a limit which is set in the script, and which | |
33459 | defaults to 10. Log files whose numbers exceed the limit are discarded. Reject | |
33460 | logs are handled similarly. | |
33461 | ||
33462 | If the limit is greater than 99, the script uses 3-digit numbers such as | |
33463 | _mainlog.001_, _mainlog.002_, etc. If you change from a number less than 99 | |
33464 | to one that is greater, or 'vice versa', you will have to fix the names of | |
33465 | any existing log files. | |
33466 | ||
33467 | ||
33468 | If no _mainlog_ file exists, the script does nothing. Files that ``drop off'' | |
33469 | the end are deleted. All files with numbers greater than 01 are compressed, | |
33470 | using a compression command which is configured by the COMPRESS_COMMAND | |
33471 | setting in _Local/Makefile_. It is usual to run 'exicyclog' daily from a | |
33472 | root %crontab% entry of the form | |
33473 | ||
33474 | 1 0 * * * su exim -c /usr/exim/bin/exicyclog | |
33475 | ||
33476 | assuming you have used the name ``exim'' for the Exim user. You can run | |
33477 | 'exicyclog' as root if you wish, but there is no need. | |
33478 | ||
33479 | ||
33480 | ||
33481 | [[SECTmailstat]] | |
33482 | Mail statistics (eximstats) | |
33483 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
33484 | cindex:[statistics] | |
33485 | cindex:['eximstats'] | |
33486 | A Perl script called 'eximstats' is provided for extracting statistical | |
33487 | information from log files. The output is either plain text, or HTML. | |
33488 | Exim log files are also suported by the 'Lire' system produced by the | |
33489 | LogReport Foundation (*http://www.logreport.org[]*). | |
33490 | ||
33491 | The 'eximstats' script has been hacked about quite a bit over time. The | |
33492 | latest version is the result of some extensive revision by Steve Campbell. A | |
33493 | lot of information is given by default, but there are options for suppressing | |
33494 | various parts of it. Following any options, the arguments to the script are a | |
33495 | list of files, which should be main log files. For example: | |
33496 | ||
33497 | eximstats -nr /var/spool/exim/log/mainlog.01 | |
33498 | ||
33499 | By default, 'eximstats' extracts information about the number and volume of | |
33500 | messages received from or delivered to various hosts. The information is sorted | |
33501 | both by message count and by volume, and the top fifty hosts in each category | |
33502 | are listed on the standard output. Similar information, based on email | |
33503 | addresses or domains instead of hosts can be requested by means of various | |
33504 | options. For messages delivered and received locally, similar statistics are | |
33505 | also produced per user. | |
33506 | ||
33507 | The output also includes total counts and statistics about delivery errors, and | |
33508 | histograms showing the number of messages received and deliveries made in each | |
33509 | hour of the day. A delivery with more than one address in its envelope (for | |
33510 | example, an SMTP transaction with more than one RCPT command) is counted | |
33511 | as a single delivery by 'eximstats'. | |
33512 | ||
33513 | Though normally more deliveries than receipts are reported (as messages may | |
33514 | have multiple recipients), it is possible for 'eximstats' to report more | |
33515 | messages received than delivered, even though the queue is empty at the start | |
33516 | and end of the period in question. If an incoming message contains no valid | |
33517 | recipients, no deliveries are recorded for it. A bounce message is handled as | |
33518 | an entirely separate message. | |
33519 | ||
33520 | 'eximstats' always outputs a grand total summary giving the volume and number | |
33521 | of messages received and deliveries made, and the number of hosts involved in | |
33522 | each case. It also outputs the number of messages that were delayed (that is, | |
33523 | not completely delivered at the first attempt), and the number that had at | |
33524 | least one address that failed. | |
33525 | ||
33526 | The remainder of the output is in sections that can be independently disabled | |
33527 | or modified by various options. It consists of a summary of deliveries by | |
33528 | transport, histograms of messages received and delivered per time interval | |
33529 | (default per hour), information about the time messages spent on the queue, | |
33530 | a list of relayed messages, lists of the top fifty sending hosts, local | |
33531 | senders, destination hosts, and destination local users by count and by volume, | |
33532 | and a list of delivery errors that occurred. | |
33533 | ||
33534 | The relay information lists messages that were actually relayed, that is, they | |
33535 | came from a remote host and were directly delivered to some other remote host, | |
33536 | without being processed (for example, for aliasing or forwarding) locally. | |
33537 | ||
33538 | There are quite a few options for 'eximstats' to control exactly what it | |
33539 | outputs. These are documented in the Perl script itself, and can be extracted | |
33540 | by running the command ^perldoc^ on the script. For example: | |
33541 | ||
33542 | perldoc /usr/exim/bin/eximstats | |
33543 | ||
33544 | ||
33545 | ||
33546 | [[SECTcheckaccess]] | |
33547 | Checking access policy (exim_checkaccess) | |
33548 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
33549 | cindex:['exim_checkaccess'] | |
33550 | cindex:[policy control,checking access] | |
33551 | cindex:[checking access] | |
33552 | The %-bh% command line argument allows you to run a fake SMTP session with | |
33553 | debugging output, in order to check what Exim is doing when it is applying | |
33554 | policy controls to incoming SMTP mail. However, not everybody is sufficiently | |
33555 | familiar with the SMTP protocol to be able to make full use of %-bh%, and | |
33556 | sometimes you just want to answer the question 'Does this address have | |
33557 | access?' without bothering with any further details. | |
33558 | ||
33559 | The 'exim_checkaccess' utility is a ``packaged'' version of %-bh%. It takes | |
33560 | two arguments, an IP address and an email address: | |
33561 | ||
33562 | exim_checkaccess 10.9.8.7 A.User@a.domain.example | |
33563 | ||
33564 | The utility runs a call to Exim with the %-bh% option, to test whether the | |
33565 | given email address would be accepted in a RCPT command in a TCP/IP | |
33566 | connection from the host with the given IP address. The output of the utility | |
33567 | is either the word ``accepted'', or the SMTP error response, for example: | |
33568 | ||
33569 | Rejected: | |
33570 | 550 Relay not permitted | |
33571 | ||
33572 | When running this test, the utility uses `<>` as the envelope sender address | |
33573 | for the MAIL command, but you can change this by providing additional | |
33574 | options. These are passed directly to the Exim command. For example, to specify | |
33575 | that the test is to be run with the sender address 'himself@there.example' | |
33576 | you can use: | |
33577 | ||
33578 | .... | |
33579 | exim_checkaccess 10.9.8.7 A.User@a.domain.example \ | |
33580 | -f himself@there.example | |
33581 | .... | |
33582 | ||
33583 | Note that these additional Exim command line items must be given after the two | |
33584 | mandatory arguments. | |
33585 | ||
33586 | Because the %exim_checkaccess% uses %-bh%, it does not perform callouts while | |
33587 | running its checks. You can run checks that include callouts by using %-bhc%, | |
33588 | but this is not yet available in a ``packaged'' form. | |
33589 | ||
33590 | ||
33591 | ||
33592 | [[SECTdbmbuild]] | |
33593 | Making DBM files (exim_dbmbuild) | |
33594 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
33595 | cindex:[DBM,building dbm files] | |
33596 | cindex:[building DBM files] | |
33597 | cindex:['exim_dbmbuild'] | |
33598 | cindex:[lower casing] | |
33599 | cindex:[binary zero,in lookup key] | |
33600 | The 'exim_dbmbuild' program reads an input file containing keys and data in | |
33601 | the format used by the ^lsearch^ lookup (see section <<SECTsinglekeylookups>>). | |
33602 | It writes a DBM file using the lower-cased alias names as keys and the | |
33603 | remainder of the information as data. The lower-casing can be prevented by | |
33604 | calling the program with the %-nolc% option. | |
33605 | ||
33606 | A terminating zero is included as part of the key string. This is expected by | |
33607 | the ^dbm^ lookup type. However, if the option %-nozero% is given, | |
33608 | 'exim_dbmbuild' creates files without terminating zeroes in either the key | |
33609 | strings or the data strings. The ^dbmnz^ lookup type can be used with such | |
33610 | files. | |
33611 | ||
33612 | The program requires two arguments: the name of the input file (which can be a | |
33613 | single hyphen to indicate the standard input), and the name of the output file. | |
33614 | It creates the output under a temporary name, and then renames it if all went | |
33615 | well. | |
33616 | ||
33617 | cindex:[USE_DB] | |
33618 | If the native DB interface is in use (USE_DB is set in a compile-time | |
33619 | configuration file -- this is common in free versions of Unix) the two file | |
33620 | names must be different, because in this mode the Berkeley DB functions create | |
33621 | a single output file using exactly the name given. For example, | |
33622 | ||
33623 | exim_dbmbuild /etc/aliases /etc/aliases.db | |
33624 | ||
33625 | reads the system alias file and creates a DBM version of it in | |
33626 | _/etc/aliases.db_. | |
33627 | ||
33628 | In systems that use the 'ndbm' routines (mostly proprietary versions of Unix), | |
33629 | two files are used, with the suffixes _.dir_ and _.pag_. In this | |
33630 | environment, the suffixes are added to the second argument of | |
33631 | 'exim_dbmbuild', so it can be the same as the first. This is also the case | |
33632 | when the Berkeley functions are used in compatibility mode (though this is not | |
33633 | recommended), because in that case it adds a _.db_ suffix to the file name. | |
33634 | ||
33635 | If a duplicate key is encountered, the program outputs a warning, and when it | |
33636 | finishes, its return code is 1 rather than zero, unless the %-noduperr% option | |
33637 | is used. By default, only the first of a set of duplicates is used -- this | |
33638 | makes it compatible with ^lsearch^ lookups. There is an option %-lastdup% | |
33639 | which causes it to use the data for the last duplicate instead. There is also | |
33640 | an option %-nowarn%, which stops it listing duplicate keys to %stderr%. For | |
33641 | other errors, where it doesn't actually make a new file, the return code is 2. | |
33642 | ||
33643 | ||
33644 | ||
33645 | ||
33646 | [[SECTfinindret]] | |
33647 | Finding individual retry times (exinext) | |
33648 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
33649 | cindex:[retry,times] | |
33650 | cindex:['exinext'] | |
33651 | A utility called 'exinext' (mostly a Perl script) provides the ability to fish | |
33652 | specific information out of the retry database. Given a mail domain (or a | |
33653 | complete address), it looks up the hosts for that domain, and outputs any retry | |
33654 | information for the hosts or for the domain. At present, the retry information | |
33655 | is obtained by running 'exim_dumpdb' (see below) and post-processing the | |
33656 | output. For example: | |
33657 | ||
33658 | $ exinext piglet@milne.fict.example | |
33659 | kanga.milne.fict.example:192.168.8.1 error 146: Connection refused | |
33660 | first failed: 21-Feb-1996 14:57:34 | |
33661 | last tried: 21-Feb-1996 14:57:34 | |
33662 | next try at: 21-Feb-1996 15:02:34 | |
33663 | roo.milne.fict.example:192.168.8.3 error 146: Connection refused | |
33664 | first failed: 20-Jan-1996 13:12:08 | |
33665 | last tried: 21-Feb-1996 11:42:03 | |
33666 | next try at: 21-Feb-1996 19:42:03 | |
33667 | past final cutoff time | |
33668 | ||
33669 | You can also give 'exinext' a local part, without a domain, and it | |
33670 | will give any retry information for that local part in your default domain. | |
33671 | A message id can be used to obtain retry information pertaining to a specific | |
33672 | message. This exists only when an attempt to deliver a message to a remote host | |
33673 | suffers a message-specific error (see section <<SECToutSMTPerr>>). 'exinext' is | |
33674 | not particularly efficient, but then it isn't expected to be run very often. | |
33675 | ||
33676 | The 'exinext' utility calls Exim to find out information such as the location | |
33677 | of the spool directory. The utility has %-C% and %-D% options, which are | |
33678 | passed on to the 'exim' commands. The first specifies an alternate Exim | |
33679 | configuration file, and the second sets macros for use within the configuration | |
33680 | file. These features are mainly to help in testing, but might also be useful in | |
33681 | environments where more than one configuration file is in use. | |
33682 | ||
33683 | ||
33684 | ||
33685 | ||
33686 | [[SECThindatmai]] | |
33687 | Hints database maintenance (exim_dumpdb, exim_fixdb, exim_tidydb) | |
33688 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
33689 | cindex:[hints database,maintenance] | |
33690 | cindex:[maintaining Exim's hints database] | |
33691 | Three utility programs are provided for maintaining the DBM files that Exim | |
33692 | uses to contain its delivery hint information. Each program requires two | |
33693 | arguments. The first specifies the name of Exim's spool directory, and the | |
068aaea8 | 33694 | second is the name of the database it is to operate on. These are as follows: |
168e428f PH |
33695 | |
33696 | - 'retry': the database of retry information | |
33697 | ||
33698 | - 'wait-'<'transport name'>: databases of information about messages waiting | |
33699 | for remote hosts | |
33700 | ||
33701 | - 'callout': the callout cache | |
33702 | ||
068aaea8 PH |
33703 | [revisionflag="changed"] |
33704 | - 'ratelimit': the data for implementing the ratelimit ACL condition | |
33705 | ||
168e428f PH |
33706 | - 'misc': other hints data |
33707 | ||
33708 | The 'misc' database is used for | |
33709 | ||
33710 | - Serializing ETRN runs (when %smtp_etrn_serialize% is set) | |
33711 | ||
33712 | - Serializing delivery to a specific host (when %serialize_hosts% is set in an | |
33713 | ^smtp^ transport) | |
33714 | ||
33715 | ||
33716 | ||
33717 | exim_dumpdb | |
33718 | ~~~~~~~~~~~ | |
33719 | cindex:['exim_dumpdb'] | |
33720 | The entire contents of a database are written to the standard output by the | |
33721 | 'exim_dumpdb' program, which has no options or arguments other than the | |
33722 | spool and database names. For example, to dump the retry database: | |
33723 | ||
33724 | exim_dumpdb /var/spool/exim retry | |
33725 | ||
33726 | Two lines of output are produced for each entry: | |
33727 | ||
33728 | T:mail.ref.example:192.168.242.242 146 77 Connection refused | |
33729 | 31-Oct-1995 12:00:12 02-Nov-1995 12:21:39 02-Nov-1995 20:21:39 * | |
33730 | ||
33731 | The first item on the first line is the key of the record. It starts with one | |
33732 | of the letters R, or T, depending on whether it refers to a routing or | |
33733 | transport retry. For a local delivery, the next part is the local address; for | |
33734 | a remote delivery it is the name of the remote host, followed by its failing IP | |
33735 | address (unless %no_retry_include_ip_address% is set on the ^smtp^ | |
33736 | transport). If the remote port is not the standard one (port 25), it is added | |
33737 | to the IP address. Then there follows an error code, an additional error code, | |
33738 | and a textual description of the error. | |
33739 | ||
33740 | The three times on the second line are the time of first failure, the time of | |
33741 | the last delivery attempt, and the computed time for the next attempt. The line | |
33742 | ends with an asterisk if the cutoff time for the last retry rule has been | |
33743 | exceeded. | |
33744 | ||
33745 | Each output line from 'exim_dumpdb' for the 'wait-''xxx' databases | |
33746 | consists of a host name followed by a list of ids for messages that are or were | |
33747 | waiting to be delivered to that host. If there are a very large number for any | |
33748 | one host, continuation records, with a sequence number added to the host name, | |
33749 | may be seen. The data in these records is often out of date, because a message | |
33750 | may be routed to several alternative hosts, and Exim makes no effort to keep | |
33751 | cross-references. | |
33752 | ||
33753 | ||
33754 | ||
33755 | exim_tidydb | |
33756 | ~~~~~~~~~~~ | |
068aaea8 | 33757 | [revisionflag="changed"] |
168e428f | 33758 | cindex:['exim_tidydb'] |
068aaea8 PH |
33759 | The 'exim_tidydb' utility program is used to tidy up the contents of a hints |
33760 | database. If run with no options, it removes all records that are more than 30 | |
33761 | days old. The age is calculated from the date and time that the record was last | |
33762 | updated. Note that, in the case of the retry database, it is 'not' the time | |
33763 | since the first delivery failure. Information about a host that has been down | |
33764 | for more than 30 days will remain in the database, provided that the record is | |
33765 | updated sufficiently often. | |
33766 | ||
33767 | The cutoff date can be altered by means of the %-t% option, which must be | |
33768 | followed by a time. For example, to remove all records older than a week from | |
33769 | the retry database: | |
168e428f PH |
33770 | |
33771 | exim_tidydb -t 7d /var/spool/exim retry | |
33772 | ||
33773 | Both the 'wait-''xxx' and 'retry' databases contain items that involve | |
33774 | message ids. In the former these appear as data in records keyed by host -- | |
33775 | they were messages that were waiting for that host -- and in the latter they | |
33776 | are the keys for retry information for messages that have suffered certain | |
33777 | types of error. When 'exim_tidydb' is run, a check is made to ensure that | |
33778 | message ids in database records are those of messages that are still on the | |
33779 | queue. Message ids for messages that no longer exist are removed from | |
33780 | 'wait-''xxx' records, and if this leaves any records empty, they are | |
33781 | deleted. For the 'retry' database, records whose keys are non-existent | |
33782 | message ids are removed. The 'exim_tidydb' utility outputs comments on the | |
33783 | standard output whenever it removes information from the database. | |
33784 | ||
33785 | Certain records are automatically removed by Exim when they are no longer | |
33786 | needed, but others are not. For example, if all the MX hosts for a domain are | |
33787 | down, a retry record is created for each one. If the primary MX host comes back | |
33788 | first, its record is removed when Exim successfully delivers to it, but the | |
33789 | records for the others remain because Exim has not tried to use those hosts. | |
33790 | ||
33791 | It is important, therefore, to run 'exim_tidydb' periodically on all the | |
33792 | hints databases. You should do this at a quiet time of day, because it requires | |
33793 | a database to be locked (and therefore inaccessible to Exim) while it does its | |
33794 | work. Removing records from a DBM file does not normally make the file smaller, | |
33795 | but all the common DBM libraries are able to re-use the space that is released. | |
33796 | After an initial phase of increasing in size, the databases normally reach a | |
33797 | point at which they no longer get any bigger, as long as they are regularly | |
33798 | tidied. | |
33799 | ||
33800 | *Warning*: If you never run 'exim_tidydb', the space used by the hints | |
33801 | databases is likely to keep on increasing. | |
33802 | ||
33803 | ||
33804 | ||
33805 | ||
33806 | exim_fixdb | |
33807 | ~~~~~~~~~~ | |
33808 | cindex:['exim_fixdb'] | |
33809 | The 'exim_fixdb' program is a utility for interactively modifying databases. | |
33810 | Its main use is for testing Exim, but it might also be occasionally useful for | |
33811 | getting round problems in a live system. It has no options, and its interface | |
33812 | is somewhat crude. On entry, it prompts for input with a right angle-bracket. A | |
33813 | key of a database record can then be entered, and the data for that record is | |
33814 | displayed. | |
33815 | ||
33816 | If ``d'' is typed at the next prompt, the entire record is deleted. For all | |
33817 | except the 'retry' database, that is the only operation that can be carried | |
33818 | out. For the 'retry' database, each field is output preceded by a number, and | |
33819 | data for individual fields can be changed by typing the field number followed | |
33820 | by new data, for example: | |
33821 | ||
33822 | > 4 951102:1000 | |
33823 | ||
33824 | resets the time of the next delivery attempt. Time values are given as a | |
33825 | sequence of digit pairs for year, month, day, hour, and minute. Colons can be | |
33826 | used as optional separators. | |
33827 | ||
33828 | ||
33829 | ||
33830 | ||
33831 | [[SECTmailboxmaint]] | |
33832 | Mailbox maintenance (exim_lock) | |
33833 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
33834 | cindex:[mailbox,maintenance] | |
33835 | cindex:['exim_lock'] | |
33836 | cindex:[locking mailboxes] | |
33837 | The 'exim_lock' utility locks a mailbox file using the same algorithm as | |
33838 | Exim. For a discussion of locking issues, see section <<SECTopappend>>. | |
33839 | 'Exim_lock' can be used to prevent any modification of a mailbox by Exim or | |
33840 | a user agent while investigating a problem. The utility requires the name of | |
33841 | the file as its first argument. If the locking is successful, the second | |
33842 | argument is run as a command (using C's 'system()' function); if there is no | |
33843 | second argument, the value of the SHELL environment variable is used; if this | |
33844 | is unset or empty, _/bin/sh_ is run. When the command finishes, the mailbox | |
33845 | is unlocked and the utility ends. The following options are available: | |
33846 | ||
33847 | *-fcntl*:: Use 'fcntl()' locking on the open mailbox. | |
33848 | ||
33849 | *-flock*:: Use 'flock()' locking on the open mailbox, provided the operating | |
33850 | system supports it. | |
33851 | ||
33852 | *-interval*:: This must be followed by a number, which is a number of seconds; | |
33853 | it sets the interval to sleep between retries (default 3). | |
33854 | ||
33855 | *-lockfile*:: Create a lock file before opening the mailbox. | |
33856 | ||
33857 | *-mbx*:: Lock the mailbox using MBX rules. | |
33858 | ||
33859 | *-q*:: Suppress verification output. | |
33860 | ||
33861 | *-retries*:: This must be followed by a number; it sets the number of times to | |
33862 | try to get the lock (default 10). | |
33863 | ||
33864 | *-restore_time*:: This option causes %exim_lock% to restore the modified and | |
33865 | read times to the locked file before exiting. This allows you to access a | |
33866 | locked mailbox (for example, to take a backup copy) without disturbing the | |
33867 | times that the user subsequently sees. | |
33868 | ||
33869 | *-timeout*:: This must be followed by a number, which is a number of seconds; | |
33870 | it sets a timeout to be used with a blocking 'fcntl()' lock. If it is not set | |
33871 | (the default), a non-blocking call is used. | |
33872 | ||
33873 | *-v*:: Generate verbose output. | |
33874 | ||
33875 | If none of %-fcntl%, %-flock%, %-lockfile% or %-mbx% are given, the default is | |
33876 | to create a lock file and also to use 'fcntl()' locking on the mailbox, which | |
33877 | is the same as Exim's default. The use of %-flock% or %-fcntl% requires that | |
33878 | the file be writeable; the use of %-lockfile% requires that the directory | |
33879 | containing the file be writeable. Locking by lock file does not last for ever; | |
33880 | Exim assumes that a lock file is expired if it is more than 30 minutes old. | |
33881 | ||
33882 | The %-mbx% option can be used with either or both of %-fcntl% or %-flock%. | |
33883 | It assumes %-fcntl% by default. | |
33884 | MBX locking causes a shared lock to be taken out on the open mailbox, and an | |
33885 | exclusive lock on the file _/tmp/._'n'.'m' where 'n' and 'm' are | |
33886 | the device number and inode number of the mailbox file. When the locking is | |
33887 | released, if an exclusive lock can be obtained for the mailbox, the file in | |
33888 | _/tmp_ is deleted. | |
33889 | ||
33890 | The default output contains verification of the locking that takes place. The | |
33891 | %-v% option causes some additional information to be given. The %-q% option | |
33892 | suppresses all output except error messages. | |
33893 | ||
33894 | A command such as | |
33895 | ||
33896 | exim_lock /var/spool/mail/spqr | |
33897 | ||
33898 | runs an interactive shell while the file is locked, whereas | |
33899 | ||
33900 | exim_lock -q /var/spool/mail/spqr <<End | |
33901 | <some commands> | |
33902 | End | |
33903 | ||
33904 | runs a specific non-interactive sequence of commands while the file is locked, | |
33905 | suppressing all verification output. A single command can be run by a command | |
33906 | such as | |
33907 | ||
33908 | .... | |
33909 | exim_lock -q /var/spool/mail/spqr \ | |
33910 | "cp /var/spool/mail/spqr /some/where" | |
33911 | .... | |
33912 | ||
33913 | Note that if a command is supplied, it must be entirely contained within the | |
33914 | second argument -- hence the quotes. | |
33915 | ||
33916 | ||
33917 | ||
33918 | //////////////////////////////////////////////////////////////////////////// | |
33919 | //////////////////////////////////////////////////////////////////////////// | |
33920 | ||
33921 | [[CHAPeximon]] | |
33922 | The Exim monitor | |
33923 | ---------------- | |
068aaea8 | 33924 | cindex:[Exim monitor,description] |
168e428f PH |
33925 | cindex:[X-windows] |
33926 | cindex:['eximon'] | |
33927 | cindex:[Local/eximon.conf] | |
33928 | cindex:[_exim_monitor/EDITME_] | |
33929 | The Exim monitor is an application which displays in an X window information | |
33930 | about the state of Exim's queue and what Exim is doing. An admin user can | |
33931 | perform certain operations on messages from this GUI interface; however all | |
33932 | such facilities are also available from the command line, and indeed, the | |
33933 | monitor itself makes use of the command line to perform any actions requested. | |
33934 | ||
33935 | ||
33936 | ||
33937 | Running the monitor | |
33938 | ~~~~~~~~~~~~~~~~~~~ | |
33939 | The monitor is started by running the script called 'eximon'. This is a shell | |
33940 | script that sets up a number of environment variables, and then runs the | |
33941 | binary called _eximon.bin_. The default appearance of the monitor window can | |
33942 | be changed by editing the _Local/eximon.conf_ file created by editing | |
33943 | _exim_monitor/EDITME_. Comments in that file describe what the various | |
33944 | parameters are for. | |
33945 | ||
33946 | The parameters that get built into the 'eximon' script can be overridden for a | |
33947 | particular invocation by setting up environment variables of the same names, | |
33948 | preceded by `EXIMON_`. For example, a shell command such as | |
33949 | ||
33950 | EXIMON_LOG_DEPTH=400 eximon | |
33951 | ||
33952 | (in a Bourne-compatible shell) runs 'eximon' with an overriding setting of the | |
33953 | LOG_DEPTH parameter. If EXIMON_LOG_FILE_PATH is set in the | |
33954 | environment, it overrides the Exim log file configuration. This makes it | |
33955 | possible to have 'eximon' tailing log data that is written to syslog, provided | |
33956 | that MAIL.INFO syslog messages are routed to a file on the local host. | |
33957 | ||
33958 | X resources can be used to change the appearance of the window in the normal | |
33959 | way. For example, a resource setting of the form | |
33960 | ||
33961 | Eximon*background: gray94 | |
33962 | ||
33963 | changes the colour of the background to light grey rather than white. The | |
33964 | stripcharts are drawn with both the data lines and the reference lines in | |
33965 | black. This means that the reference lines are not visible when on top of the | |
33966 | data. However, their colour can be changed by setting a resource called | |
33967 | ``highlight'' (an odd name, but that's what the Athena stripchart widget uses). | |
33968 | For example, if your X server is running Unix, you could set up lighter | |
33969 | reference lines in the stripcharts by obeying | |
33970 | ||
33971 | xrdb -merge <<End | |
33972 | Eximon*highlight: gray | |
33973 | End | |
33974 | ||
33975 | ||
33976 | cindex:[admin user] | |
33977 | In order to see the contents of messages on the queue, and to operate on them, | |
33978 | 'eximon' must either be run as root or by an admin user. | |
33979 | ||
33980 | The monitor's window is divided into three parts. The first contains one or | |
33981 | more stripcharts and two action buttons, the second contains a ``tail'' of the | |
33982 | main log file, and the third is a display of the queue of messages awaiting | |
33983 | delivery, with two more action buttons. The following sections describe these | |
33984 | different parts of the display. | |
33985 | ||
33986 | ||
33987 | ||
33988 | ||
33989 | The stripcharts | |
33990 | ~~~~~~~~~~~~~~~ | |
33991 | cindex:[stripchart] | |
33992 | The first stripchart is always a count of messages on the queue. Its name can | |
33993 | be configured by setting QUEUE_STRIPCHART_NAME in the | |
33994 | _Local/eximon.conf_ file. The remaining stripcharts are defined in the | |
33995 | configuration script by regular expression matches on log file entries, making | |
33996 | it possible to display, for example, counts of messages delivered to certain | |
33997 | hosts or using certain transports. The supplied defaults display counts of | |
33998 | received and delivered messages, and of local and SMTP deliveries. The default | |
33999 | period between stripchart updates is one minute; this can be adjusted by a | |
34000 | parameter in the _Local/eximon.conf_ file. | |
34001 | ||
34002 | The stripchart displays rescale themselves automatically as the value they are | |
34003 | displaying changes. There are always 10 horizontal lines in each chart; the | |
34004 | title string indicates the value of each division when it is greater than one. | |
34005 | For example, ``x2'' means that each division represents a value of 2. | |
34006 | ||
34007 | It is also possible to have a stripchart which shows the percentage fullness of | |
34008 | a particular disk partition, which is useful when local deliveries are confined | |
34009 | to a single partition. | |
34010 | ||
34011 | cindex:[%statvfs% function] | |
34012 | This relies on the availability of the 'statvfs()' function or equivalent in | |
34013 | the operating system. Most, but not all versions of Unix that support Exim have | |
34014 | this. For this particular stripchart, the top of the chart always represents | |
34015 | 100%, and the scale is given as ``x10%''. This chart is configured by setting | |
34016 | SIZE_STRIPCHART and (optionally) SIZE_STRIPCHART_NAME in the | |
34017 | _Local/eximon.conf_ file. | |
34018 | ||
34019 | ||
34020 | ||
34021 | ||
34022 | Main action buttons | |
34023 | ~~~~~~~~~~~~~~~~~~~ | |
34024 | cindex:[size,of monitor window] | |
068aaea8 | 34025 | cindex:[Exim monitor,window size] |
168e428f PH |
34026 | cindex:[window size] |
34027 | Below the stripcharts there is an action button for quitting the monitor. Next | |
34028 | to this is another button marked ``Size''. They are placed here so that shrinking | |
34029 | the window to its default minimum size leaves just the queue count stripchart | |
34030 | and these two buttons visible. Pressing the ``Size'' button causes the window to | |
34031 | expand to its maximum size, unless it is already at the maximum, in which case | |
34032 | it is reduced to its minimum. | |
34033 | ||
34034 | When expanding to the maximum, if the window cannot be fully seen where it | |
34035 | currently is, it is moved back to where it was the last time it was at full | |
34036 | size. When it is expanding from its minimum size, the old position is | |
34037 | remembered, and next time it is reduced to the minimum it is moved back there. | |
34038 | ||
34039 | The idea is that you can keep a reduced window just showing one or two | |
34040 | stripcharts at a convenient place on your screen, easily expand it to show | |
34041 | the full window when required, and just as easily put it back to what it was. | |
34042 | The idea is copied from what the 'twm' window manager does for its | |
34043 | 'f.fullzoom' action. The minimum size of the window can be changed by setting | |
34044 | the MIN_HEIGHT and MIN_WIDTH values in _Local/eximon.conf_. | |
34045 | ||
34046 | Normally, the monitor starts up with the window at its full size, but it can be | |
34047 | built so that it starts up with the window at its smallest size, by setting | |
34048 | START_SMALL=yes in _Local/eximon.conf_. | |
34049 | ||
34050 | ||
34051 | ||
34052 | The log display | |
34053 | ~~~~~~~~~~~~~~~ | |
34054 | cindex:[log,tail of; in monitor] | |
34055 | The second section of the window is an area in which a display of the tail of | |
34056 | the main log is maintained. | |
34057 | To save space on the screen, the timestamp on each log line is shortened by | |
34058 | removing the date and, if %log_timezone% is set, the timezone. | |
34059 | The log tail is not available when the only destination for logging data is | |
34060 | syslog, unless the syslog lines are routed to a local file whose name is passed | |
34061 | to 'eximon' via the EXIMON_LOG_FILE_PATH environment variable. | |
34062 | ||
34063 | The log sub-window has a scroll bar at its lefthand side which can be used to | |
34064 | move back to look at earlier text, and the up and down arrow keys also have a | |
34065 | scrolling effect. The amount of log that is kept depends on the setting of | |
34066 | LOG_BUFFER in _Local/eximon.conf_, which specifies the amount of memory | |
34067 | to use. When this is full, the earlier 50% of data is discarded -- this is much | |
34068 | more efficient than throwing it away line by line. The sub-window also has a | |
34069 | horizontal scroll bar for accessing the ends of long log lines. This is the | |
34070 | only means of horizontal scrolling; the right and left arrow keys are not | |
34071 | available. Text can be cut from this part of the window using the mouse in the | |
34072 | normal way. The size of this subwindow is controlled by parameters in the | |
34073 | configuration file _Local/eximon.conf_. | |
34074 | ||
34075 | Searches of the text in the log window can be carried out by means of the ^R | |
34076 | and ^S keystrokes, which default to a reverse and a forward search, | |
34077 | respectively. The search covers only the text that is displayed in the window. | |
34078 | It cannot go further back up the log. | |
34079 | ||
34080 | The point from which the search starts is indicated by a caret marker. This is | |
34081 | normally at the end of the text in the window, but can be positioned explicitly | |
34082 | by pointing and clicking with the left mouse button, and is moved automatically | |
34083 | by a successful search. If new text arrives in the window when it is scrolled | |
34084 | back, the caret remains where it is, but if the window is not scrolled back, | |
34085 | the caret is moved to the end of the new text. | |
34086 | ||
34087 | Pressing ^R or ^S pops up a window into which the search text can be typed. | |
34088 | There are buttons for selecting forward or reverse searching, for carrying out | |
34089 | the search, and for cancelling. If the ``Search'' button is pressed, the search | |
34090 | happens and the window remains so that further searches can be done. If the | |
34091 | ``Return'' key is pressed, a single search is done and the window is closed. If | |
34092 | ^C is typed the search is cancelled. | |
34093 | ||
34094 | The searching facility is implemented using the facilities of the Athena text | |
34095 | widget. By default this pops up a window containing both ``search'' and ``replace'' | |
34096 | options. In order to suppress the unwanted ``replace'' portion for eximon, a | |
34097 | modified version of the %TextPop% widget is distributed with Exim. However, the | |
34098 | linkers in BSDI and HP-UX seem unable to handle an externally provided version | |
34099 | of %TextPop% when the remaining parts of the text widget come from the standard | |
34100 | libraries. The compile-time option EXIMON_TEXTPOP can be unset to cut out | |
34101 | the modified %TextPop%, making it possible to build Eximon on these systems, at | |
34102 | the expense of having unwanted items in the search popup window. | |
34103 | ||
34104 | ||
34105 | ||
34106 | The queue display | |
34107 | ~~~~~~~~~~~~~~~~~ | |
34108 | cindex:[queue,display in monitor] | |
34109 | The bottom section of the monitor window contains a list of all messages that | |
34110 | are on the queue, which includes those currently being received or delivered, | |
34111 | as well as those awaiting delivery. The size of this subwindow is controlled by | |
34112 | parameters in the configuration file _Local/eximon.conf_, and the frequency | |
34113 | at which it is updated is controlled by another parameter in the same file -- | |
34114 | the default is 5 minutes, since queue scans can be quite expensive. However, | |
34115 | there is an ``Update'' action button just above the display which can be used to | |
34116 | force an update of the queue display at any time. | |
34117 | ||
34118 | When a host is down for some time, a lot of pending mail can build up for it, | |
34119 | and this can make it hard to deal with other messages on the queue. To help | |
34120 | with this situation there is a button next to ``Update'' called ``Hide''. If | |
34121 | pressed, a dialogue box called ``Hide addresses ending with'' is put up. If you | |
34122 | type anything in here and press ``Return'', the text is added to a chain of such | |
34123 | texts, and if every undelivered address in a message matches at least one | |
34124 | of the texts, the message is not displayed. | |
34125 | ||
34126 | If there is an address that does not match any of the texts, all the addresses | |
34127 | are displayed as normal. The matching happens on the ends of addresses so, for | |
34128 | example, 'cam.ac.uk' specifies all addresses in Cambridge, while | |
34129 | 'xxx@foo.com.example' specifies just one specific address. When any hiding | |
34130 | has been set up, a button called ``Unhide'' is displayed. If pressed, it cancels | |
34131 | all hiding. Also, to ensure that hidden messages do not get forgotten, a hide | |
34132 | request is automatically cancelled after one hour. | |
34133 | ||
34134 | While the dialogue box is displayed, you can't press any buttons or do anything | |
34135 | else to the monitor window. For this reason, if you want to cut text from the | |
34136 | queue display to use in the dialogue box, you have to do the cutting before | |
34137 | pressing the ``Hide'' button. | |
34138 | ||
34139 | The queue display contains, for each unhidden queued message, the length of | |
34140 | time it has been on the queue, the size of the message, the message id, the | |
34141 | message sender, and the first undelivered recipient, all on one line. If it is | |
34142 | a bounce message, the sender is shown as ``<>''. If there is more than one | |
34143 | recipient to which the message has not yet been delivered, subsequent ones are | |
34144 | listed on additional lines, up to a maximum configured number, following which | |
34145 | an ellipsis is displayed. Recipients that have already received the message are | |
34146 | not shown. | |
34147 | ||
34148 | cindex:[frozen messages,display] | |
34149 | If a message is frozen, an asterisk is displayed at the left-hand side. | |
34150 | ||
34151 | The queue display has a vertical scroll bar, and can also be scrolled by means | |
34152 | of the arrow keys. Text can be cut from it using the mouse in the normal way. | |
34153 | The text searching facilities, as described above for the log window, are also | |
34154 | available, but the caret is always moved to the end of the text when the queue | |
34155 | display is updated. | |
34156 | ||
34157 | ||
34158 | ||
34159 | The queue menu | |
34160 | ~~~~~~~~~~~~~~ | |
34161 | cindex:[queue,menu in monitor] | |
34162 | If the %shift% key is held down and the left button is clicked when the mouse | |
34163 | pointer is over the text for any message, an action menu pops up, and the first | |
34164 | line of the queue display for the message is highlighted. This does not affect | |
34165 | any selected text. | |
34166 | ||
34167 | If you want to use some other event for popping up the menu, you can set the | |
34168 | MENU_EVENT parameter in _Local/eximon.conf_ to change the default, or | |
34169 | set EXIMON_MENU_EVENT in the environment before starting the monitor. The | |
34170 | value set in this parameter is a standard X event description. For example, to | |
34171 | run eximon using %ctrl% rather than %shift% you could use | |
34172 | ||
34173 | EXIMON_MENU_EVENT='Ctrl<Btn1Down>' eximon | |
34174 | ||
34175 | The title of the menu is the message id, and it contains entries which act as | |
34176 | follows: | |
34177 | ||
34178 | - 'message log': The contents of the message log for the message are displayed in | |
34179 | a new text window. | |
34180 | ||
34181 | - 'headers': Information from the spool file that contains the envelope | |
34182 | information and headers is displayed in a new text window. See chapter | |
34183 | <<CHAPspool>> for a description of the format of spool files. | |
34184 | ||
34185 | - 'body': The contents of the spool file containing the body of the message are | |
34186 | displayed in a new text window. There is a default limit of 20,000 bytes to the | |
34187 | amount of data displayed. This can be changed by setting the BODY_MAX | |
34188 | option at compile time, or the EXIMON_BODY_MAX option at run time. | |
34189 | ||
34190 | - 'deliver message': A call to Exim is made using the %-M% option to request | |
34191 | delivery of the message. This causes an automatic thaw if the message is | |
34192 | frozen. The %-v% option is also set, and the output from Exim is displayed in | |
34193 | a new text window. The delivery is run in a separate process, to avoid holding | |
34194 | up the monitor while the delivery proceeds. | |
34195 | ||
34196 | - 'freeze message': A call to Exim is made using the %-Mf% option to request | |
34197 | that the message be frozen. | |
34198 | ||
34199 | - cindex:[thawing messages] | |
34200 | cindex:[unfreezing messages] | |
34201 | cindex:[frozen messages,thawing] | |
34202 | 'thaw message': A call to Exim is made using the %-Mt% option to request that | |
34203 | the message be thawed. | |
34204 | ||
34205 | - cindex:[delivery,forcing failure] | |
34206 | 'give up on msg': A call to Exim is made using the %-Mg% option to request | |
34207 | that Exim gives up trying to deliver the message. A bounce message is generated | |
34208 | for any remaining undelivered addresses. | |
34209 | ||
34210 | - 'remove message': A call to Exim is made using the %-Mrm% option to request | |
34211 | that the message be deleted from the system without generating a bounce | |
34212 | message. | |
34213 | ||
34214 | - 'add recipient': A dialog box is displayed into which a recipient address can | |
34215 | be typed. If the address is not qualified and the QUALIFY_DOMAIN parameter | |
34216 | is set in _Local/eximon.conf_, the address is qualified with that domain. | |
34217 | Otherwise it must be entered as a fully qualified address. Pressing RETURN | |
34218 | causes a call to Exim to be made using the %-Mar% option to request that an | |
34219 | additional recipient be added to the message, unless the entry box is empty, in | |
34220 | which case no action is taken. | |
34221 | ||
34222 | - 'mark delivered': A dialog box is displayed into which a recipient address can | |
34223 | be typed. If the address is not qualified and the QUALIFY_DOMAIN parameter | |
34224 | is set in _Local/eximon.conf_, the address is qualified with that domain. | |
34225 | Otherwise it must be entered as a fully qualified address. Pressing RETURN | |
34226 | causes a call to Exim to be made using the %-Mmd% option to mark the given | |
34227 | recipient address as already delivered, unless the entry box is empty, in which | |
34228 | case no action is taken. | |
34229 | ||
34230 | - 'mark all delivered': A call to Exim is made using the %-Mmad% option to mark | |
34231 | all recipient addresses as already delivered. | |
34232 | ||
34233 | - 'edit sender': A dialog box is displayed initialized with the current sender's | |
34234 | address. Pressing RETURN causes a call to Exim to be made using the %-Mes% | |
34235 | option to replace the sender address, unless the entry box is empty, in which | |
34236 | case no action is taken. If you want to set an empty sender (as in bounce | |
34237 | messages), you must specify it as ``<>''. Otherwise, if the address is not | |
34238 | qualified and the QUALIFY_DOMAIN parameter is set in | |
34239 | _Local/eximon.conf_, the address is qualified with that domain. | |
34240 | ||
34241 | When a delivery is forced, a window showing the %-v% output is displayed. In | |
34242 | other cases when a call to Exim is made, if there is any output from Exim (in | |
34243 | particular, if the command fails) a window containing the command and the | |
34244 | output is displayed. Otherwise, the results of the action are normally apparent | |
34245 | from the log and queue displays. However, if you set ACTION_OUTPUT=yes in | |
34246 | _Local/eximon.conf_, a window showing the Exim command is always opened, even | |
34247 | if no output is generated. | |
34248 | ||
34249 | The queue display is automatically updated for actions such as freezing and | |
34250 | thawing, unless ACTION_QUEUE_UPDATE=no has been set in | |
34251 | _Local/eximon.conf_. In this case the ``Update'' button has to be used to force | |
34252 | an update of the display after one of these actions. | |
34253 | ||
34254 | In any text window that is displayed as result of a menu action, the normal | |
34255 | cut-and-paste facility is available, and searching can be carried out using ^R | |
34256 | and ^S, as described above for the log tail window. | |
34257 | ||
34258 | ||
34259 | ||
34260 | ||
34261 | ||
34262 | ||
34263 | //////////////////////////////////////////////////////////////////////////// | |
34264 | //////////////////////////////////////////////////////////////////////////// | |
34265 | ||
34266 | [[CHAPsecurity]] | |
34267 | Security considerations | |
34268 | ----------------------- | |
34269 | cindex:[security] | |
34270 | This chapter discusses a number of issues concerned with security, some of | |
34271 | which are also covered in other parts of this manual. | |
34272 | ||
34273 | For reasons that this author does not understand, some people have promoted | |
34274 | Exim as a ``particularly secure'' mailer. Perhaps it is because of the existence | |
34275 | of this chapter in the documentation. However, the intent of the chapter is | |
34276 | simply to describe the way Exim works in relation to certain security concerns, | |
34277 | not to make any specific claims about the effectiveness of its security as | |
34278 | compared with other MTAs. | |
34279 | ||
34280 | What follows is a description of the way Exim is supposed to be. Best efforts | |
34281 | have been made to try to ensure that the code agrees with the theory, but an | |
34282 | absence of bugs can never be guaranteed. Any that are reported will get fixed | |
34283 | as soon as possible. | |
34284 | ||
34285 | ||
34286 | Building a more ``hardened'' Exim | |
34287 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
34288 | cindex:[security,build-time features] | |
34289 | There are a number of build-time options that can be set in _Local/Makefile_ | |
34290 | to create Exim binaries that are ``harder'' to attack, in particular by a rogue | |
34291 | Exim administrator who does not have the root password, or by someone who has | |
34292 | penetrated the Exim (but not the root) account. These options are as follows: | |
34293 | ||
34294 | - ALT_CONFIG_PREFIX can be set to a string that is required to match the | |
34295 | start of any file names used with the %-C% option. When it is set, these file | |
34296 | names are also not allowed to contain the sequence ``/../''. (However, if the | |
34297 | value of the %-C% option is identical to the value of CONFIGURE_FILE in | |
34298 | _Local/Makefile_, Exim ignores %-C% and proceeds as usual.) There is no | |
34299 | default setting for %ALT_CONFIG_PREFIX%. | |
34300 | + | |
34301 | If the permitted configuration files are confined to a directory to | |
34302 | which only root has access, this guards against someone who has broken | |
34303 | into the Exim account from running a privileged Exim with an arbitrary | |
34304 | configuration file, and using it to break into other accounts. | |
34305 | ||
34306 | - If ALT_CONFIG_ROOT_ONLY is defined, root privilege is retained for %-C% | |
34307 | and %-D% only if the caller of Exim is root. Without it, the Exim user may | |
34308 | also use %-C% and %-D% and retain privilege. Setting this option locks out | |
34309 | the possibility of testing a configuration using %-C% right through message | |
34310 | reception and delivery, even if the caller is root. The reception works, but by | |
34311 | that time, Exim is running as the Exim user, so when it re-execs to regain | |
34312 | privilege for the delivery, the use of %-C% causes privilege to be lost. | |
34313 | However, root can test reception and delivery using two separate commands. | |
34314 | ALT_CONFIG_ROOT_ONLY is not set by default. | |
34315 | ||
34316 | - If DISABLE_D_OPTION is defined, the use of the %-D% command line option | |
34317 | is disabled. | |
34318 | ||
34319 | - FIXED_NEVER_USERS can be set to a colon-separated list of users that are | |
34320 | never to be used for any deliveries. This is like the %never_users% runtime | |
34321 | option, but it cannot be overridden; the runtime option adds additional users | |
34322 | to the list. The default setting is ``root''; this prevents a non-root user who | |
34323 | is permitted to modify the runtime file from using Exim as a way to get root. | |
34324 | ||
34325 | ||
34326 | ||
34327 | ||
34328 | Root privilege | |
34329 | ~~~~~~~~~~~~~~ | |
34330 | cindex:[setuid] | |
34331 | cindex:[root privilege] | |
34332 | The Exim binary is normally setuid to root, which means that it gains root | |
34333 | privilege (runs as root) when it starts execution. In some special cases (for | |
34334 | example, when the daemon is not in use and there are no local deliveries), it | |
34335 | may be possible to run Exim setuid to some user other than root. This is | |
34336 | discussed in the next section. However, in most installations, root privilege | |
34337 | is required for two things: | |
34338 | ||
34339 | - To set up a socket connected to the standard SMTP port (25) when initialising | |
34340 | the listening daemon. If Exim is run from 'inetd', this privileged action is | |
34341 | not required. | |
34342 | ||
34343 | - To be able to change uid and gid in order to read users' _.forward_ files and | |
34344 | perform local deliveries as the receiving user or as specified in the | |
34345 | configuration. | |
34346 | ||
34347 | It is not necessary to be root to do any of the other things Exim does, such as | |
34348 | receiving messages and delivering them externally over SMTP, and it is | |
34349 | obviously more secure if Exim does not run as root except when necessary. | |
34350 | For this reason, a user and group for Exim to use must be defined in | |
34351 | _Local/Makefile_. These are known as ``the Exim user'' and ``the Exim group''. | |
34352 | Their values can be changed by the run time configuration, though this is not | |
34353 | recommended. Often a user called 'exim' is used, but some sites use 'mail' | |
34354 | or another user name altogether. | |
34355 | ||
34356 | Exim uses 'setuid()' whenever it gives up root privilege. This is a permanent | |
34357 | abdication; the process cannot regain root afterwards. Prior to release 4.00, | |
34358 | 'seteuid()' was used in some circumstances, but this is no longer the case. | |
34359 | ||
34360 | After a new Exim process has interpreted its command line options, it changes | |
34361 | uid and gid in the following cases: | |
34362 | ||
34363 | - cindex:[%-C% option] | |
34364 | cindex:[%-D% option] | |
34365 | If the %-C% option is used to specify an alternate configuration file, or if | |
34366 | the %-D% option is used to define macro values for the configuration, and the | |
34367 | calling process is not running as root or the Exim user, the uid and gid are | |
34368 | changed to those of the calling process. | |
34369 | However, if ALT_CONFIG_ROOT_ONLY is defined in _Local/Makefile_, only | |
34370 | root callers may use %-C% and %-D% without losing privilege, and if | |
34371 | DISABLE_D_OPTION is set, the %-D% option may not be used at all. | |
34372 | ||
34373 | - cindex:[%-be% option] | |
34374 | cindex:[%-bf% option] | |
34375 | cindex:[%-bF% option] | |
34376 | If the expansion test option (%-be%) or one of the filter testing options | |
34377 | (%-bf% or %-bF%) are used, the uid and gid are changed to those of the | |
34378 | calling process. | |
34379 | ||
34380 | - If the process is not a daemon process or a queue runner process or a delivery | |
34381 | process or a process for testing address routing (started with %-bt%), the uid | |
34382 | and gid are changed to the Exim user and group. This means that Exim always | |
34383 | runs under its own uid and gid when receiving messages. This also applies when | |
34384 | testing address verification | |
34385 | cindex:[%-bv% option] | |
34386 | cindex:[%-bh% option] | |
34387 | (the %-bv% option) and testing incoming message policy controls (the %-bh% | |
34388 | option). | |
34389 | ||
34390 | - For a daemon, queue runner, delivery, or address testing process, the uid | |
34391 | remains as root at this stage, but the gid is changed to the Exim group. | |
34392 | ||
34393 | /// | |
34394 | End of list | |
34395 | /// | |
34396 | ||
34397 | The processes that initially retain root privilege behave as follows: | |
34398 | ||
34399 | - A daemon process changes the gid to the Exim group and the uid to the Exim | |
34400 | user after setting up one or more listening sockets. The 'initgroups()' | |
34401 | function is called, so that if the Exim user is in any additional groups, they | |
34402 | will be used during message reception. | |
34403 | ||
34404 | - A queue runner process retains root privilege throughout its execution. Its | |
34405 | job is to fork a controlled sequence of delivery processes. | |
34406 | ||
34407 | - A delivery process retains root privilege throughout most of its execution, | |
34408 | but any actual deliveries (that is, the transports themselves) are run in | |
34409 | subprocesses which always change to a non-root uid and gid. For local | |
34410 | deliveries this is typically the uid and gid of the owner of the mailbox; for | |
34411 | remote deliveries, the Exim uid and gid are used. Once all the delivery | |
34412 | subprocesses have been run, a delivery process changes to the Exim uid and gid | |
34413 | while doing post-delivery tidying up such as updating the retry database and | |
34414 | generating bounce and warning messages. | |
34415 | + | |
34416 | While the recipient addresses in a message are being routed, the delivery | |
34417 | process runs as root. However, if a user's filter file has to be processed, | |
34418 | this is done in a subprocess that runs under the individual user's uid and | |
34419 | gid. A system filter is run as root unless %system_filter_user% is set. | |
34420 | ||
34421 | - A process that is testing addresses (the %-bt% option) runs as root so that | |
34422 | the routing is done in the same environment as a message delivery. | |
34423 | ||
34424 | ||
34425 | ||
34426 | ||
34427 | [[SECTrunexiwitpri]] | |
34428 | Running Exim without privilege | |
34429 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
34430 | cindex:[privilege, running without] | |
34431 | cindex:[unprivileged running] | |
34432 | cindex:[root privilege,running without] | |
34433 | Some installations like to run Exim in an unprivileged state for more of its | |
34434 | operation, for added security. Support for this mode of operation is provided | |
34435 | by the global option %deliver_drop_privilege%. When this is set, the uid and | |
34436 | gid are changed to the Exim user and group at the start of a delivery process | |
34437 | (and also queue runner and address testing processes). This means that address | |
34438 | routing is no longer run as root, and the deliveries themselves cannot change | |
34439 | to any other uid. | |
34440 | ||
34441 | Leaving the binary setuid to root, but setting %deliver_drop_privilege% means | |
34442 | that the daemon can still be started in the usual way, and it can respond | |
34443 | correctly to SIGHUP because the re-invocation regains root privilege. | |
34444 | ||
34445 | An alternative approach is to make Exim setuid to the Exim user and also setgid | |
34446 | to the Exim group. | |
34447 | If you do this, the daemon must be started from a root process. (Calling | |
34448 | Exim from a root process makes it behave in the way it does when it is setuid | |
34449 | root.) However, the daemon cannot restart itself after a SIGHUP signal because | |
34450 | it cannot regain privilege. | |
34451 | ||
34452 | It is still useful to set %deliver_drop_privilege% in this case, because it | |
34453 | stops Exim from trying to re-invoke itself to do a delivery after a message has | |
34454 | been received. Such a re-invocation is a waste of resources because it has no | |
34455 | effect. | |
34456 | ||
34457 | If restarting the daemon is not an issue (for example, if %mua_wrapper% is set, | |
34458 | or 'inetd' is being used instead of a daemon), having the binary setuid to the | |
34459 | Exim user seems a clean approach, but there is one complication: | |
34460 | ||
34461 | In this style of operation, Exim is running with the real uid and gid set to | |
34462 | those of the calling process, and the effective uid/gid set to Exim's values. | |
34463 | Ideally, any association with the calling process' uid/gid should be dropped, | |
34464 | that is, the real uid/gid should be reset to the effective values so as to | |
34465 | discard any privileges that the caller may have. While some operating systems | |
34466 | have a function that permits this action for a non-root effective uid, quite a | |
34467 | number of them do not. Because of this lack of standardization, Exim does not | |
34468 | address this problem at this time. | |
34469 | ||
34470 | For this reason, the recommended approach for ``mostly unprivileged'' running is | |
34471 | to keep the Exim binary setuid to root, and to set %deliver_drop_privilege%. | |
34472 | This also has the advantage of allowing a daemon to be used in the most | |
34473 | straightforward way. | |
34474 | ||
34475 | If you configure Exim not to run delivery processes as root, there are a | |
34476 | number of restrictions on what you can do: | |
34477 | ||
34478 | - You can deliver only as the Exim user/group. You should explicitly use the | |
34479 | %user% and %group% options to override routers or local transports that | |
34480 | normally deliver as the recipient. This makes sure that configurations that | |
34481 | work in this mode function the same way in normal mode. Any implicit or | |
34482 | explicit specification of another user causes an error. | |
34483 | ||
34484 | - Use of _.forward_ files is severely restricted, such that it is usually | |
34485 | not worthwhile to include them in the configuration. | |
34486 | ||
34487 | - Users who wish to use _.forward_ would have to make their home directory and | |
34488 | the file itself accessible to the Exim user. Pipe and append-to-file entries, | |
34489 | and their equivalents in Exim filters, cannot be used. While they could be | |
34490 | enabled in the Exim user's name, that would be insecure and not very useful. | |
34491 | ||
34492 | - Unless the local user mailboxes are all owned by the Exim user (possible in | |
34493 | some POP3 or IMAP-only environments): | |
34494 | ||
34495 | * They must be owned by the Exim group and be writable by that group. This | |
34496 | implies you must set %mode% in the appendfile configuration, as well as the | |
34497 | mode of the mailbox files themselves. | |
34498 | ||
34499 | * You must set %no_check_owner%, since most or all of the files will not be | |
34500 | owned by the Exim user. | |
34501 | ||
34502 | * You must set %file_must_exist%, because Exim cannot set the owner correctly | |
34503 | on a newly created mailbox when unprivileged. This also implies that new | |
34504 | mailboxes need to be created manually. | |
34505 | ||
34506 | These restrictions severely restrict what can be done in local deliveries. | |
34507 | However, there are no restrictions on remote deliveries. If you are running a | |
34508 | gateway host that does no local deliveries, setting %deliver_drop_privilege% | |
34509 | gives more security at essentially no cost. | |
34510 | ||
34511 | If you are using the %mua_wrapper% facility (see chapter <<CHAPnonqueueing>>), | |
34512 | %deliver_drop_privilege% is forced to be true. | |
34513 | ||
34514 | ||
34515 | ||
34516 | ||
34517 | Delivering to local files | |
34518 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
34519 | Full details of the checks applied by ^appendfile^ before it writes to a file | |
34520 | are given in chapter <<CHAPappendfile>>. | |
34521 | ||
34522 | ||
34523 | ||
34524 | IPv4 source routing | |
34525 | ~~~~~~~~~~~~~~~~~~~ | |
34526 | cindex:[source routing,in IP packets] | |
34527 | cindex:[IP source routing] | |
34528 | Many operating systems suppress IP source-routed packets in the kernel, but | |
34529 | some cannot be made to do this, so Exim does its own check. It logs incoming | |
34530 | IPv4 source-routed TCP calls, and then drops them. Things are all different in | |
34531 | IPv6. No special checking is currently done. | |
34532 | ||
34533 | ||
34534 | ||
34535 | The VRFY, EXPN, and ETRN commands in SMTP | |
34536 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
34537 | Support for these SMTP commands is disabled by default. If required, they can | |
34538 | be enabled by defining suitable ACLs. | |
34539 | ||
34540 | ||
34541 | ||
34542 | ||
34543 | Privileged users | |
34544 | ~~~~~~~~~~~~~~~~ | |
34545 | cindex:[trusted user] | |
34546 | cindex:[admin user] | |
34547 | cindex:[privileged user] | |
34548 | cindex:[user,trusted] | |
34549 | cindex:[user,admin] | |
34550 | Exim recognises two sets of users with special privileges. Trusted users are | |
34551 | able to submit new messages to Exim locally, but supply their own sender | |
34552 | addresses and information about a sending host. For other users submitting | |
34553 | local messages, Exim sets up the sender address from the uid, and doesn't | |
34554 | permit a remote host to be specified. | |
34555 | ||
34556 | cindex:[%-f% option] | |
34557 | However, an untrusted user is permitted to use the %-f% command line option in | |
34558 | the special form %-f <>% to indicate that a delivery failure for the message | |
34559 | should not cause an error report. This affects the message's envelope, but it | |
34560 | does not affect the 'Sender:' header. Untrusted users may also be permitted to | |
34561 | use specific forms of address with the %-f% option by setting the | |
34562 | %untrusted_set_sender% option. | |
34563 | ||
34564 | Trusted users are used to run processes that receive mail messages from some | |
34565 | other mail domain and pass them on to Exim for delivery either locally, or over | |
34566 | the Internet. Exim trusts a caller that is running as root, as the Exim user, | |
34567 | as any user listed in the %trusted_users% configuration option, or under any | |
34568 | group listed in the %trusted_groups% option. | |
34569 | ||
34570 | Admin users are permitted to do things to the messages on Exim's queue. They | |
34571 | can freeze or thaw messages, cause them to be returned to their senders, remove | |
34572 | them entirely, or modify them in various ways. In addition, admin users can run | |
34573 | the Exim monitor and see all the information it is capable of providing, which | |
34574 | includes the contents of files on the spool. | |
34575 | ||
34576 | cindex:[%-M% option] | |
34577 | cindex:[%-q% option] | |
34578 | By default, the use of the %-M% and %-q% options to cause Exim to attempt | |
34579 | delivery of messages on its queue is restricted to admin users. This | |
34580 | restriction can be relaxed by setting the %no_prod_requires_admin% option. | |
34581 | Similarly, the use of %-bp% (and its variants) to list the contents of the | |
34582 | queue is also restricted to admin users. This restriction can be relaxed by | |
34583 | setting %no_queue_list_requires_admin%. | |
34584 | ||
34585 | Exim recognises an admin user if the calling process is running as root or as | |
34586 | the Exim user or if any of the groups associated with the calling process is | |
34587 | the Exim group. It is not necessary actually to be running under the Exim | |
34588 | group. However, if admin users who are not root or the Exim user are to access | |
34589 | the contents of files on the spool via the Exim monitor (which runs | |
34590 | unprivileged), Exim must be built to allow group read access to its spool | |
34591 | files. | |
34592 | ||
34593 | ||
34594 | ||
34595 | Spool files | |
34596 | ~~~~~~~~~~~ | |
34597 | cindex:[spool directory,files] | |
34598 | Exim's spool directory and everything it contains is owned by the Exim user and | |
34599 | set to the Exim group. The mode for spool files is defined in the | |
34600 | _Local/Makefile_ configuration file, and defaults to 0640. This means that | |
34601 | any user who is a member of the Exim group can access these files. | |
34602 | ||
34603 | ||
34604 | ||
34605 | Use of argv[0] | |
34606 | ~~~~~~~~~~~~~~ | |
34607 | Exim examines the last component of %argv[0]%, and if it matches one of a set | |
34608 | of specific strings, Exim assumes certain options. For example, calling Exim | |
34609 | with the last component of %argv[0]% set to ``rsmtp'' is exactly equivalent to | |
34610 | calling it with the option %-bS%. There are no security implications in this. | |
34611 | ||
34612 | ||
34613 | ||
34614 | Use of %f formatting | |
34615 | ~~~~~~~~~~~~~~~~~~~~ | |
34616 | The only use made of ``%f'' by Exim is in formatting load average values. These | |
34617 | are actually stored in integer variables as 1000 times the load average. | |
34618 | Consequently, their range is limited and so therefore is the length of the | |
34619 | converted output. | |
34620 | ||
34621 | ||
34622 | ||
34623 | Embedded Exim path | |
34624 | ~~~~~~~~~~~~~~~~~~ | |
34625 | Exim uses its own path name, which is embedded in the code, only when it needs | |
34626 | to re-exec in order to regain root privilege. Therefore, it is not root when it | |
34627 | does so. If some bug allowed the path to get overwritten, it would lead to an | |
34628 | arbitrary program's being run as exim, not as root. | |
34629 | ||
34630 | ||
34631 | ||
34632 | Use of sprintf() | |
34633 | ~~~~~~~~~~~~~~~~ | |
34634 | cindex:['sprintf()'] | |
34635 | A large number of occurrences of ``sprintf'' in the code are actually calls to | |
34636 | 'string_sprintf()', a function that returns the result in malloc'd store. | |
34637 | The intermediate formatting is done into a large fixed buffer by a function | |
34638 | that runs through the format string itself, and checks the length of each | |
34639 | conversion before performing it, thus preventing buffer overruns. | |
34640 | ||
34641 | The remaining uses of 'sprintf()' happen in controlled circumstances where | |
34642 | the output buffer is known to be sufficiently long to contain the converted | |
34643 | string. | |
34644 | ||
34645 | ||
34646 | ||
34647 | Use of debug_printf() and log_write() | |
34648 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
34649 | Arbitrary strings are passed to both these functions, but they do their | |
34650 | formatting by calling the function 'string_vformat()', which runs through | |
34651 | the format string itself, and checks the length of each conversion. | |
34652 | ||
34653 | ||
34654 | ||
34655 | Use of strcat() and strcpy() | |
34656 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
34657 | These are used only in cases where the output buffer is known to be large | |
34658 | enough to hold the result. | |
34659 | ||
34660 | ||
34661 | ||
34662 | ||
34663 | //////////////////////////////////////////////////////////////////////////// | |
34664 | //////////////////////////////////////////////////////////////////////////// | |
34665 | ||
34666 | [[CHAPspool]] | |
34667 | Format of spool files | |
34668 | --------------------- | |
34669 | cindex:[format,spool files] | |
34670 | cindex:[spool directory,format of files] | |
34671 | cindex:[spool files, format of] | |
34672 | cindex:[spool files, editing] | |
34673 | A message on Exim's queue consists of two files, whose names are the message id | |
34674 | followed by -D and -H, respectively. The data portion of the message is kept in | |
34675 | the -D file on its own. The message's envelope, status, and headers are all | |
34676 | kept in the -H file, whose format is described in this chapter. Each of these | |
34677 | two files contains the final component of its own name as its first line. This | |
34678 | is insurance against disk crashes where the directory is lost but the files | |
34679 | themselves are recoverable. | |
34680 | ||
34681 | Some people are tempted into editing -D files in order to modify messages. You | |
34682 | need to be extremely careful if you do this; it is not recommended and you are | |
34683 | on your own if you do it. Here are some of the pitfalls: | |
34684 | ||
068aaea8 PH |
34685 | [revisionflag="changed"] |
34686 | - You must ensure that Exim does not try to deliver the message while you are | |
34687 | fiddling with it. The safest way is to take out a write lock on the -D file, | |
34688 | which is what Exim itself does, using ^^fcntl()^^. If you update the file in | |
34689 | place, the lock will be retained. If you write a new file and rename it, the | |
34690 | lock will be lost at the instant of rename. | |
168e428f | 34691 | |
068aaea8 PH |
34692 | [revisionflag="changed"] |
34693 | - cindex:[$body_linecount$] | |
34694 | If you change the number of lines in the file, the value of | |
34695 | $body_linecount$, which is stored in the -H file, will be incorrect. At | |
34696 | present, this value is not used by Exim, but there is no guarantee that this | |
34697 | will always be the case. | |
168e428f PH |
34698 | |
34699 | - If the message is in MIME format, you must take care not to break it. | |
34700 | ||
34701 | - If the message is cryptographically signed, any change will invalidate the | |
34702 | signature. | |
34703 | ||
34704 | ||
34705 | Files whose names end with -J may also be seen in the _input_ directory (or | |
34706 | its subdirectories when %split_spool_directory% is set). These are journal | |
34707 | files, used to record addresses to which the message has been delivered during | |
34708 | the course of a delivery run. At the end of the run, the -H file is updated, | |
34709 | and the -J file is deleted. | |
34710 | ||
34711 | ||
34712 | Format of the -H file | |
34713 | ~~~~~~~~~~~~~~~~~~~~~ | |
34714 | cindex:[uid (user id),in spool file] | |
34715 | cindex:[gid (group id),in spool file] | |
34716 | The second line of the -H file contains the login name for the uid of the | |
34717 | process that called Exim to read the message, followed by the numerical uid and | |
34718 | gid. For a locally generated message, this is normally the user who sent the | |
34719 | message. For a message received over TCP/IP, it is normally the Exim user. | |
34720 | ||
34721 | The third line of the file contains the address of the message's sender as | |
34722 | transmitted in the envelope, contained in angle brackets. The sender address is | |
34723 | empty for bounce messages. For incoming SMTP mail, the sender address is given | |
34724 | in the MAIL command. For locally generated mail, the sender address is | |
34725 | created by Exim from the login name of the current user and the configured | |
34726 | %qualify_domain%. However, this can be overridden by the %-f% option or a | |
34727 | leading ``From'' line if the caller is trusted, or if the supplied address is | |
34728 | ``<>'' or an address that matches %untrusted_set_senders%. | |
34729 | ||
34730 | The fourth line contains two numbers. The first is the time that the message | |
34731 | was received, in the conventional Unix form -- the number of seconds since the | |
34732 | start of the epoch. The second number is a count of the number of messages | |
34733 | warning of delayed delivery that have been sent to the sender. | |
34734 | ||
34735 | There follow a number of lines starting with a hyphen. These can appear in any | |
34736 | order, and are omitted when not relevant: | |
34737 | ||
34738 | %-acl% <'number'> <'length'>:: | |
34739 | A line of this form is present for every ACL variable that is not empty. The | |
34740 | number identifies the variable; the %acl_c%*x* variables are numbered 0--9 and | |
34741 | the %acl_m%*x* variables are numbered 10--19. The length is the length of the | |
34742 | data string for the variable. The string itself starts at the beginning of the | |
34743 | next line, and is followed by a newline character. It may contain internal | |
34744 | newlines. | |
34745 | ||
34746 | %-active_hostname% <'hostname'>:: | |
34747 | This is present if, when the message was received over SMTP, the value of | |
34748 | $smtp_active_hostname$ was different to the value of $primary_hostname$. | |
34749 | ||
34750 | %-allow_unqualified_recipient%:: | |
34751 | This is present if unqualified recipient addresses are permitted in header | |
34752 | lines (to stop such addresses from being qualified if rewriting occurs at | |
34753 | transport time). Local messages that were input using %-bnq% and remote | |
34754 | messages from hosts that match %recipient_unqualified_hosts% set this flag. | |
34755 | ||
34756 | %-allow_unqualified_sender%:: | |
34757 | This is present if unqualified sender addresses are permitted in header lines | |
34758 | (to stop such addresses from being qualified if rewriting occurs at transport | |
34759 | time). Local messages that were input using %-bnq% and remote messages from | |
34760 | hosts that match %sender_unqualified_hosts% set this flag. | |
34761 | ||
34762 | %-auth_id% <'text'>:: | |
34763 | The id information for a message received on an authenticated SMTP connection | |
34764 | -- the value of the $authenticated_id$ variable. | |
34765 | ||
34766 | %-auth_sender% <'address'>:: | |
34767 | The address of an authenticated sender -- the value of the | |
34768 | $authenticated_sender$ variable. | |
34769 | ||
34770 | %-body_linecount% <'number'>:: | |
34771 | This records the number of lines in the body of the message, and is always | |
34772 | present. | |
34773 | ||
34774 | %-body_zerocount% <'number'>:: | |
34775 | This records the number of binary zero bytes in the body of the message, and is | |
34776 | present if the number is greater than zero. | |
34777 | ||
34778 | %-deliver_firsttime%:: | |
34779 | This is written when a new message is first added to the spool. When the spool | |
34780 | file is updated after a deferral, it is omitted. | |
34781 | ||
34782 | %-frozen% <'time'>:: | |
34783 | cindex:[frozen messages,spool data] | |
34784 | The message is frozen, and the freezing happened at <'time'>. | |
34785 | ||
34786 | %-helo_name% <'text'>:: | |
34787 | This records the host name as specified by a remote host in a HELO or EHLO | |
34788 | command. | |
34789 | ||
34790 | %-host_address% <'address'>.<'port'>:: | |
34791 | This records the IP address of the host from which the message was received and | |
34792 | the remote port number that was used. It is omitted for locally generated | |
34793 | messages. | |
34794 | ||
34795 | %-host_auth% <'text'>:: | |
34796 | If the message was received on an authenticated SMTP connection, this records | |
34797 | the name of the authenticator -- the value of the $sender_host_authenticated$ | |
34798 | variable. | |
34799 | ||
34800 | %-host_lookup_failed%:: | |
34801 | This is present if an attempt to look up the sending host's name from its IP | |
34802 | address failed. It corresponds to the $host_lookup_failed$ variable. | |
34803 | ||
34804 | %-host_name% <'text'>:: | |
34805 | cindex:[reverse DNS lookup] | |
34806 | cindex:[DNS,reverse lookup] | |
34807 | This records the name of the remote host from which the message was received, | |
34808 | if the host name was looked up from the IP address when the message was being | |
34809 | received. It is not present if no reverse lookup was done. | |
34810 | ||
34811 | %-ident% <'text'>:: | |
34812 | For locally submitted messages, this records the login of the originating user, | |
34813 | unless it was a trusted user and the %-oMt% option was used to specify an ident | |
34814 | value. For messages received over TCP/IP, this records the ident string | |
34815 | supplied by the remote host, if any. | |
34816 | ||
34817 | %-interface_address% <'address'>.<'port'>:: | |
34818 | This records the IP address of the local interface and the port number through | |
34819 | which a message was received from a remote host. It is omitted for locally | |
34820 | generated messages. | |
34821 | ||
34822 | %-local%:: | |
34823 | The message is from a local sender. | |
34824 | ||
34825 | %-localerror%:: | |
34826 | The message is a locally-generated bounce message. | |
34827 | ||
34828 | %-local_scan% <'string'>:: | |
34829 | This records the data string that was returned by the 'local_scan()' function | |
34830 | when the message was received -- the value of the $local_scan_data$ variable. | |
34831 | It is omitted if no data was returned. | |
34832 | ||
34833 | %-manual_thaw%:: | |
34834 | The message was frozen but has been thawed manually, that is, by an explicit | |
34835 | Exim command rather than via the auto-thaw process. | |
34836 | ||
34837 | %-N%:: | |
34838 | A testing delivery process was started using the %-N% option to suppress any | |
34839 | actual deliveries, but delivery was deferred. At any further delivery attempts, | |
34840 | %-N% is assumed. | |
34841 | ||
34842 | %-received_protocol%:: | |
34843 | This records the value of the $received_protocol$ variable, which contains the | |
34844 | name of the protocol by which the message was received. | |
34845 | ||
34846 | %-sender_set_untrusted%:: | |
34847 | The envelope sender of this message was set by an untrusted local caller (used | |
34848 | to ensure that the caller is displayed in queue listings). | |
34849 | ||
34850 | %-spam_score_int% <'number'>:: | |
34851 | If a message was scanned by SpamAssassin, this is present. It records the value | |
34852 | of $spam_score_int$. | |
34853 | ||
34854 | %-tls_certificate_verified%:: | |
34855 | A TLS certificate was received from the client that sent this message, and the | |
34856 | certificate was verified by the server. | |
34857 | ||
34858 | %-tls_cipher% <'cipher name'>:: | |
34859 | When the message was received over an encrypted connection, this records the | |
34860 | name of the cipher suite that was used. | |
34861 | ||
34862 | %-tls_peerdn% <'peer DN'>:: | |
34863 | When the message was received over an encrypted connection, and a certificate | |
34864 | was received from the client, this records the Distinguished Name from that | |
34865 | certificate. | |
34866 | ||
34867 | /// | |
34868 | End of list | |
34869 | /// | |
34870 | ||
34871 | Following the options there is a list of those addresses to which the message | |
34872 | is not to be delivered. This set of addresses is initialized from the command | |
34873 | line when the %-t% option is used and %extract_addresses_remove_arguments% | |
34874 | is set; otherwise it starts out empty. Whenever a successful delivery is made, | |
34875 | the address is added to this set. The addresses are kept internally as a | |
34876 | balanced binary tree, and it is a representation of that tree which is written | |
34877 | to the spool file. If an address is expanded via an alias or forward file, the | |
34878 | original address is added to the tree when deliveries to all its child | |
34879 | addresses are complete. | |
34880 | ||
34881 | If the tree is empty, there is a single line in the spool file containing just | |
34882 | the text ``XX''. Otherwise, each line consists of two letters, which are either | |
34883 | Y or N, followed by an address. The address is the value for the node of the | |
34884 | tree, and the letters indicate whether the node has a left branch and/or a | |
34885 | right branch attached to it, respectively. If branches exist, they immediately | |
34886 | follow. Here is an example of a three-node tree: | |
34887 | ||
34888 | YY darcy@austen.fict.example | |
34889 | NN alice@wonderland.fict.example | |
34890 | NN editor@thesaurus.ref.example | |
34891 | ||
34892 | After the non-recipients tree, there is a list of the message's recipients. | |
34893 | This is a simple list, preceded by a count. It includes all the original | |
34894 | recipients of the message, including those to whom the message has already been | |
34895 | delivered. In the simplest case, the list contains one address per line. For | |
34896 | example: | |
34897 | ||
34898 | 4 | |
34899 | editor@thesaurus.ref.example | |
34900 | darcy@austen.fict.example | |
34901 | rdo@foundation | |
34902 | alice@wonderland.fict.example | |
34903 | ||
34904 | However, when a child address has been added to the top-level addresses as a | |
34905 | result of the use of the %one_time% option on a ^redirect^ router, each line | |
34906 | is of the following form: | |
34907 | ||
34908 | &&& | |
34909 | <'top-level address'> <'errors_to address'> <'length'>,<'parent number'>#<'flag bits'> | |
34910 | &&& | |
34911 | ||
34912 | The 01 flag bit indicates the presence of the three other fields that follow | |
34913 | the top-level address. Other bits may be used in future to support additional | |
34914 | fields. The <'parent number'> is the offset in the recipients list of the | |
34915 | original parent of the ``one time'' address. The first two fields are the | |
34916 | envelope sender that is associated with this address and its length. If the | |
34917 | length is zero, there is no special envelope sender (there are then two space | |
34918 | characters in the line). A non-empty field can arise from a ^redirect^ router | |
34919 | that has an %errors_to% setting. | |
34920 | ||
34921 | ||
34922 | A blank line separates the envelope and status information from the headers | |
34923 | which follow. A header may occupy several lines of the file, and to save effort | |
34924 | when reading it in, each header is preceded by a number and an identifying | |
34925 | character. The number is the number of characters in the header, including any | |
34926 | embedded newlines and the terminating newline. The character is one of the | |
34927 | following: | |
34928 | ||
34929 | [frame="none"] | |
34930 | `-`--------`---------------------------------------------- | |
34931 | <'blank'>header in which Exim has no special interest | |
34932 | `B` 'Bcc:' header | |
34933 | `C` 'Cc:' header | |
34934 | `F` 'From:' header | |
34935 | `I` 'Message-id:' header | |
34936 | `P` 'Received:' header -- P for ``postmark'' | |
34937 | `R` 'Reply-To:' header | |
34938 | `S` 'Sender:' header | |
34939 | `T` 'To:' header | |
34940 | `*` replaced or deleted header | |
34941 | ---------------------------------------------------------- | |
34942 | ||
34943 | Deleted or replaced (rewritten) headers remain in the spool file for debugging | |
34944 | purposes. They are not transmitted when the message is delivered. Here is a | |
34945 | typical set of headers: | |
34946 | ||
34947 | 111P Received: by hobbit.fict.example with local (Exim 4.00) | |
34948 | id 14y9EI-00026G-00; Fri, 11 May 2001 10:28:59 +0100 | |
34949 | 049 Message-Id: <E14y9EI-00026G-00@hobbit.fict.example> | |
34950 | 038* X-rewrote-sender: bb@hobbit.fict.example | |
34951 | 042* From: Bilbo Baggins <bb@hobbit.fict.example> | |
34952 | 049F From: Bilbo Baggins <B.Baggins@hobbit.fict.example> | |
34953 | 099* To: alice@wonderland.fict.example, rdo@foundation, | |
34954 | darcy@austen.fict.example, editor@thesaurus.ref.example | |
34955 | 109T To: alice@wonderland.fict.example, rdo@foundation.fict.example, | |
34956 | darcy@austen.fict.example, editor@thesaurus.ref.example | |
34957 | 038 Date: Fri, 11 May 2001 10:28:59 +0100 | |
34958 | ||
34959 | The asterisked headers indicate that the envelope sender, 'From:' header, and | |
34960 | 'To:' header have been rewritten, the last one because routing expanded the | |
34961 | unqualified domain 'foundation'. | |
34962 | ||
34963 | ||
34964 | ||
34965 | ||
34966 | //////////////////////////////////////////////////////////////////////////// | |
34967 | //////////////////////////////////////////////////////////////////////////// | |
34968 | ||
34969 | [titleabbrev="Adding drivers or lookups"] | |
34970 | Adding new drivers or lookup types | |
34971 | ---------------------------------- | |
34972 | cindex:[adding drivers] | |
34973 | cindex:[new drivers, adding] | |
34974 | cindex:[drivers,adding new] | |
34975 | The following actions have to be taken in order to add a new router, transport, | |
34976 | authenticator, or lookup type to Exim: | |
34977 | ||
34978 | . Choose a name for the driver or lookup type that does not conflict with any | |
34979 | existing name; I will use ``newdriver'' in what follows. | |
34980 | ||
34981 | . Add to _src/EDITME_ the line | |
34982 | + | |
34983 | <type>_NEWDRIVER=yes | |
34984 | + | |
34985 | where <'type'> is ROUTER, TRANSPORT, AUTH, or LOOKUP. If the | |
34986 | code is not to be included in the binary by default, comment this line out. You | |
34987 | should also add any relevant comments about the driver or lookup type. | |
34988 | ||
34989 | . Add to _src/config.h.defaults_ the line | |
34990 | + | |
34991 | #define <type>_NEWDRIVER | |
34992 | ||
34993 | . Edit _src/drtables.c_, adding conditional code to pull in the private header | |
34994 | and create a table entry as is done for all the other drivers and lookup types. | |
34995 | ||
34996 | . Edit _Makefile_ in the appropriate sub-directory (_src/routers_, | |
34997 | _src/transports_, _src/auths_, or _src/lookups_); add a line for the new | |
34998 | driver or lookup type and add it to the definition of OBJ. | |
34999 | ||
35000 | . Create _newdriver.h_ and _newdriver.c_ in the appropriate sub-directory of | |
35001 | _src_. | |
35002 | ||
35003 | . Edit _scripts/MakeLinks_ and add commands to link the _.h_ and _.c_ files | |
35004 | as for other drivers and lookups. | |
35005 | ||
35006 | Then all you need to do is write the code! A good way to start is to make a | |
35007 | proforma by copying an existing module of the same type, globally changing all | |
35008 | occurrences of the name, and cutting out most of the code. Note that any | |
35009 | options you create must be listed in alphabetical order, because the tables are | |
35010 | searched using a binary chop procedure. | |
35011 | ||
35012 | There is a _README_ file in each of the sub-directories of _src_ describing | |
35013 | the interface that is expected. | |
35014 | ||
35015 | ||
35016 | ||
35017 | ||
35018 | //////////////////////////////////////////////////////////////////////////// | |
35019 | //////////////////////////////////////////////////////////////////////////// | |
35020 | ||
35021 | [title="Option index",role="option"] | |
35022 | Index | |
35023 | ----- | |
35024 | ||
35025 | [title="Concept index",role="concept"] | |
35026 | Index | |
35027 | ----- | |
35028 | ||
35029 | /////////////////////////////////////////////////////////////////////////////// | |
35030 | Nothing needs to be included here except "Index" as pseudo chapter headings. | |
35031 | /////////////////////////////////////////////////////////////////////////////// |