Commit | Line | Data |
---|---|---|
a29e5231 | 1 | . $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.76 2010/06/05 10:04:43 pdp Exp $ |
9b371988 PH |
2 | . |
3 | . ///////////////////////////////////////////////////////////////////////////// | |
4 | . This is the primary source of the Exim Manual. It is an xfpt document that is | |
5 | . converted into DocBook XML for subsequent conversion into printing and online | |
6 | . formats. The markup used herein is "standard" xfpt markup, with some extras. | |
7 | . The markup is summarized in a file called Markup.txt. | |
595028e4 PH |
8 | . |
9 | . WARNING: When you use the .new macro, make sure it appears *before* any | |
10 | . adjacent index items; otherwise you get an empty "paragraph" which causes | |
11 | . unwanted vertical space. | |
9b371988 PH |
12 | . ///////////////////////////////////////////////////////////////////////////// |
13 | ||
14 | .include stdflags | |
15 | .include stdmacs | |
9b371988 PH |
16 | |
17 | . ///////////////////////////////////////////////////////////////////////////// | |
33393583 | 18 | . This outputs the standard DocBook boilerplate. |
9b371988 PH |
19 | . ///////////////////////////////////////////////////////////////////////////// |
20 | ||
33393583 | 21 | .docbook |
3cb1b51e PH |
22 | |
23 | . ///////////////////////////////////////////////////////////////////////////// | |
24 | . These lines are processing instructions for the Simple DocBook Processor that | |
f89d2485 PH |
25 | . Philip Hazel has developed as a less cumbersome way of making PostScript and |
26 | . PDFs than using xmlto and fop. They will be ignored by all other XML | |
27 | . processors. | |
3cb1b51e PH |
28 | . ///////////////////////////////////////////////////////////////////////////// |
29 | ||
30 | .literal xml | |
31 | <?sdop | |
f89d2485 PH |
32 | foot_right_recto="&chaptertitle; (&chapternumber;)" |
33 | foot_right_verso="&chaptertitle; (&chapternumber;)" | |
3cb1b51e | 34 | toc_chapter_blanks="yes,yes" |
595028e4 | 35 | table_warn_overflow="overprint" |
3cb1b51e PH |
36 | ?> |
37 | .literal off | |
9b371988 | 38 | |
33393583 PH |
39 | . ///////////////////////////////////////////////////////////////////////////// |
40 | . This generate the outermost <book> element that wraps then entire document. | |
41 | . ///////////////////////////////////////////////////////////////////////////// | |
42 | ||
43 | .book | |
44 | ||
45 | . ///////////////////////////////////////////////////////////////////////////// | |
46 | . These definitions set some parameters and save some typing. Remember that | |
47 | . the <bookinfo> element must also be updated for each new edition. | |
48 | . ///////////////////////////////////////////////////////////////////////////// | |
49 | ||
fdf795c0 NM |
50 | .set previousversion "4.71" |
51 | .set version "4.72" | |
f89d2485 | 52 | |
33393583 | 53 | .set ACL "access control lists (ACLs)" |
f89d2485 | 54 | .set I " " |
33393583 | 55 | |
9b371988 PH |
56 | |
57 | . ///////////////////////////////////////////////////////////////////////////// | |
58 | . Additional xfpt markup used by this document, over and above the default | |
59 | . provided in the xfpt library. | |
60 | . ///////////////////////////////////////////////////////////////////////////// | |
61 | ||
62 | . --- Override the &$ flag to automatically insert a $ with the variable name | |
63 | ||
64 | .flag &$ $& "<varname>$" "</varname>" | |
65 | ||
66 | . --- Short flags for daggers in option headings. They will always be inside | |
67 | . --- an italic string, but we want the daggers to be roman. | |
68 | ||
69 | .flag &!! "</emphasis>†<emphasis>" | |
70 | .flag &!? "</emphasis>‡<emphasis>" | |
71 | ||
72 | . --- A macro for an Exim option definition heading, generating a one-line | |
0a4e3112 PH |
73 | . --- table with four columns. For cases when the option name is given with |
74 | . --- a space, so that it can be split, a fifth argument is used for the | |
75 | . --- index entry. | |
9b371988 PH |
76 | |
77 | .macro option | |
0a4e3112 PH |
78 | .arg 5 |
79 | .oindex "&%$5%&" | |
80 | .endarg | |
81 | .arg -5 | |
3cb1b51e | 82 | .oindex "&%$1%&" |
0a4e3112 | 83 | .endarg |
f89d2485 | 84 | .itable all 0 0 4 8* left 6* center 6* center 6* right |
9b371988 PH |
85 | .row "&%$1%&" "Use: &'$2'&" "Type: &'$3'&" "Default: &'$4'&" |
86 | .endtable | |
87 | .endmacro | |
88 | ||
89 | . --- A macro for the common 2-column tables. The width of the first column | |
90 | . --- is suitable for the many tables at the start of the main options chapter; | |
91 | . --- the small number of other 2-column tables override it. | |
92 | ||
db9452a9 | 93 | .macro table2 196pt 254pt |
9b371988 PH |
94 | .itable none 0 0 2 $1 left $2 left |
95 | .endmacro | |
96 | ||
f89d2485 PH |
97 | . --- A macro that generates .row, but puts &I; at the start of the first |
98 | . --- argument, thus indenting it. Assume a minimum of two arguments, and | |
99 | . --- allow up to four arguments, which is as many as we'll ever need. | |
100 | ||
101 | .macro irow | |
102 | .arg 4 | |
103 | .row "&I;$1" "$2" "$3" "$4" | |
104 | .endarg | |
105 | .arg -4 | |
106 | .arg 3 | |
107 | .row "&I;$1" "$2" "$3" | |
108 | .endarg | |
109 | .arg -3 | |
110 | .row "&I;$1" "$2" | |
111 | .endarg | |
112 | .endarg | |
113 | .endmacro | |
114 | ||
115 | . --- Macros for option, variable, and concept index entries. For a "range" | |
116 | . --- style of entry, use .scindex for the start and .ecindex for the end. The | |
117 | . --- first argument of .scindex and the only argument of .ecindex must be the | |
118 | . --- ID that ties them together. | |
9b371988 PH |
119 | |
120 | .macro cindex | |
121 | &<indexterm role="concept">& | |
122 | &<primary>&$1&</primary>& | |
123 | .arg 2 | |
124 | &<secondary>&$2&</secondary>& | |
125 | .endarg | |
126 | &</indexterm>& | |
127 | .endmacro | |
128 | ||
4f578862 PH |
129 | .macro scindex |
130 | &<indexterm role="concept" id="$1" class="startofrange">& | |
131 | &<primary>&$2&</primary>& | |
132 | .arg 3 | |
133 | &<secondary>&$3&</secondary>& | |
134 | .endarg | |
135 | &</indexterm>& | |
136 | .endmacro | |
137 | ||
138 | .macro ecindex | |
139 | &<indexterm role="concept" startref="$1" class="endofrange"/>& | |
140 | .endmacro | |
141 | ||
9b371988 PH |
142 | .macro oindex |
143 | &<indexterm role="option">& | |
144 | &<primary>&$1&</primary>& | |
145 | .arg 2 | |
146 | &<secondary>&$2&</secondary>& | |
147 | .endarg | |
148 | &</indexterm>& | |
149 | .endmacro | |
150 | ||
f89d2485 PH |
151 | .macro vindex |
152 | &<indexterm role="variable">& | |
153 | &<primary>&$1&</primary>& | |
154 | .arg 2 | |
155 | &<secondary>&$2&</secondary>& | |
156 | .endarg | |
157 | &</indexterm>& | |
158 | .endmacro | |
159 | ||
9b371988 | 160 | .macro index |
f89d2485 | 161 | .echo "** Don't use .index; use .cindex or .oindex or .vindex" |
9b371988 PH |
162 | .endmacro |
163 | . //////////////////////////////////////////////////////////////////////////// | |
164 | ||
165 | ||
166 | . //////////////////////////////////////////////////////////////////////////// | |
167 | . The <bookinfo> element is removed from the XML before processing for Ascii | |
168 | . output formats. | |
169 | . //////////////////////////////////////////////////////////////////////////// | |
170 | ||
171 | .literal xml | |
172 | <bookinfo> | |
173 | <title>Specification of the Exim Mail Transfer Agent</title> | |
174 | <titleabbrev>The Exim MTA</titleabbrev> | |
fdf795c0 | 175 | <date>29 May 2010</date> |
7b4c60eb NM |
176 | <author><firstname>Exim</firstname><surname>Maintainers</surname></author> |
177 | <authorinitials>EM</authorinitials> | |
9b371988 | 178 | <revhistory><revision> |
fdf795c0 NM |
179 | <revnumber>4.72</revnumber> |
180 | <date>29 May 2010</date> | |
7b4c60eb | 181 | <authorinitials>EM</authorinitials> |
9b371988 | 182 | </revision></revhistory> |
68950195 | 183 | <copyright><year>2009</year><holder>University of Cambridge</holder></copyright> |
9b371988 PH |
184 | </bookinfo> |
185 | .literal off | |
186 | ||
187 | ||
188 | . ///////////////////////////////////////////////////////////////////////////// | |
189 | . This chunk of literal XML implements index entries of the form "x, see y" and | |
190 | . "x, see also y". However, the DocBook DTD doesn't allow <indexterm> entries | |
191 | . at the top level, so we have to put the .chapter directive first. | |
192 | . ///////////////////////////////////////////////////////////////////////////// | |
193 | ||
f89d2485 | 194 | .chapter "Introduction" "CHID1" |
9b371988 PH |
195 | .literal xml |
196 | ||
f89d2485 | 197 | <indexterm role="variable"> |
168e428f PH |
198 | <primary>$1, $2, etc.</primary> |
199 | <see><emphasis>numerical variables</emphasis></see> | |
200 | </indexterm> | |
201 | <indexterm role="concept"> | |
202 | <primary>address</primary> | |
203 | <secondary>rewriting</secondary> | |
204 | <see><emphasis>rewriting</emphasis></see> | |
205 | </indexterm> | |
068aaea8 PH |
206 | <indexterm role="concept"> |
207 | <primary>Bounce Address Tag Validation</primary> | |
208 | <see><emphasis>BATV</emphasis></see> | |
209 | </indexterm> | |
210 | <indexterm role="concept"> | |
211 | <primary>Client SMTP Authorization</primary> | |
212 | <see><emphasis>CSA</emphasis></see> | |
213 | </indexterm> | |
168e428f PH |
214 | <indexterm role="concept"> |
215 | <primary>CR character</primary> | |
216 | <see><emphasis>carriage return</emphasis></see> | |
217 | </indexterm> | |
218 | <indexterm role="concept"> | |
219 | <primary>CRL</primary> | |
220 | <see><emphasis>certificate revocation list</emphasis></see> | |
221 | </indexterm> | |
222 | <indexterm role="concept"> | |
223 | <primary>delivery</primary> | |
224 | <secondary>failure report</secondary> | |
225 | <see><emphasis>bounce message</emphasis></see> | |
226 | </indexterm> | |
227 | <indexterm role="concept"> | |
228 | <primary>dialup</primary> | |
229 | <see><emphasis>intermittently connected hosts</emphasis></see> | |
230 | </indexterm> | |
231 | <indexterm role="concept"> | |
232 | <primary>exiscan</primary> | |
233 | <see><emphasis>content scanning</emphasis></see> | |
234 | </indexterm> | |
235 | <indexterm role="concept"> | |
236 | <primary>failover</primary> | |
237 | <see><emphasis>fallback</emphasis></see> | |
238 | </indexterm> | |
239 | <indexterm role="concept"> | |
240 | <primary>fallover</primary> | |
241 | <see><emphasis>fallback</emphasis></see> | |
242 | </indexterm> | |
243 | <indexterm role="concept"> | |
244 | <primary>filter</primary> | |
245 | <secondary>Sieve</secondary> | |
246 | <see><emphasis>Sieve filter</emphasis></see> | |
247 | </indexterm> | |
248 | <indexterm role="concept"> | |
249 | <primary>ident</primary> | |
250 | <see><emphasis>RFC 1413</emphasis></see> | |
251 | </indexterm> | |
252 | <indexterm role="concept"> | |
253 | <primary>LF character</primary> | |
254 | <see><emphasis>linefeed</emphasis></see> | |
255 | </indexterm> | |
256 | <indexterm role="concept"> | |
257 | <primary>maximum</primary> | |
595028e4 | 258 | <seealso><emphasis>limit</emphasis></seealso> |
168e428f | 259 | </indexterm> |
068aaea8 PH |
260 | <indexterm role="concept"> |
261 | <primary>monitor</primary> | |
262 | <see><emphasis>Exim monitor</emphasis></see> | |
263 | </indexterm> | |
168e428f PH |
264 | <indexterm role="concept"> |
265 | <primary>no_<emphasis>xxx</emphasis></primary> | |
266 | <see>entry for xxx</see> | |
267 | </indexterm> | |
268 | <indexterm role="concept"> | |
269 | <primary>NUL</primary> | |
270 | <see><emphasis>binary zero</emphasis></see> | |
271 | </indexterm> | |
272 | <indexterm role="concept"> | |
273 | <primary>passwd file</primary> | |
274 | <see><emphasis>/etc/passwd</emphasis></see> | |
275 | </indexterm> | |
276 | <indexterm role="concept"> | |
277 | <primary>process id</primary> | |
278 | <see><emphasis>pid</emphasis></see> | |
279 | </indexterm> | |
280 | <indexterm role="concept"> | |
281 | <primary>RBL</primary> | |
282 | <see><emphasis>DNS list</emphasis></see> | |
283 | </indexterm> | |
284 | <indexterm role="concept"> | |
285 | <primary>redirection</primary> | |
286 | <see><emphasis>address redirection</emphasis></see> | |
287 | </indexterm> | |
288 | <indexterm role="concept"> | |
289 | <primary>return path</primary> | |
290 | <seealso><emphasis>envelope sender</emphasis></seealso> | |
291 | </indexterm> | |
292 | <indexterm role="concept"> | |
293 | <primary>scanning</primary> | |
294 | <see><emphasis>content scanning</emphasis></see> | |
295 | </indexterm> | |
296 | <indexterm role="concept"> | |
297 | <primary>SSL</primary> | |
298 | <see><emphasis>TLS</emphasis></see> | |
299 | </indexterm> | |
300 | <indexterm role="concept"> | |
301 | <primary>string</primary> | |
302 | <secondary>expansion</secondary> | |
303 | <see><emphasis>expansion</emphasis></see> | |
304 | </indexterm> | |
305 | <indexterm role="concept"> | |
306 | <primary>top bit</primary> | |
307 | <see><emphasis>8-bit characters</emphasis></see> | |
308 | </indexterm> | |
309 | <indexterm role="concept"> | |
310 | <primary>variables</primary> | |
311 | <see><emphasis>expansion, variables</emphasis></see> | |
312 | </indexterm> | |
313 | <indexterm role="concept"> | |
314 | <primary>zero, binary</primary> | |
315 | <see><emphasis>binary zero</emphasis></see> | |
316 | </indexterm> | |
9b371988 PH |
317 | |
318 | .literal off | |
168e428f PH |
319 | |
320 | ||
9b371988 PH |
321 | . ///////////////////////////////////////////////////////////////////////////// |
322 | . This is the real start of the first chapter. See the comment above as to why | |
323 | . we can't have the .chapter line here. | |
324 | . chapter "Introduction" | |
325 | . ///////////////////////////////////////////////////////////////////////////// | |
168e428f PH |
326 | |
327 | Exim is a mail transfer agent (MTA) for hosts that are running Unix or | |
328 | Unix-like operating systems. It was designed on the assumption that it would be | |
329 | run on hosts that are permanently connected to the Internet. However, it can be | |
330 | used on intermittently connected hosts with suitable configuration adjustments. | |
331 | ||
332 | Configuration files currently exist for the following operating systems: AIX, | |
068aaea8 PH |
333 | BSD/OS (aka BSDI), Darwin (Mac OS X), DGUX, Dragonfly, FreeBSD, GNU/Hurd, |
334 | GNU/Linux, HI-OSF (Hitachi), HI-UX, HP-UX, IRIX, MIPS RISCOS, NetBSD, OpenBSD, | |
335 | OpenUNIX, QNX, SCO, SCO SVR4.2 (aka UNIX-SV), Solaris (aka SunOS5), SunOS4, | |
336 | Tru64-Unix (formerly Digital UNIX, formerly DEC-OSF1), Ultrix, and Unixware. | |
337 | Some of these operating systems are no longer current and cannot easily be | |
338 | tested, so the configuration files may no longer work in practice. | |
168e428f PH |
339 | |
340 | There are also configuration files for compiling Exim in the Cygwin environment | |
341 | that can be installed on systems running Windows. However, this document does | |
342 | not contain any information about running Exim in the Cygwin environment. | |
343 | ||
344 | The terms and conditions for the use and distribution of Exim are contained in | |
9b371988 PH |
345 | the file &_NOTICE_&. Exim is distributed under the terms of the GNU General |
346 | Public Licence, a copy of which may be found in the file &_LICENCE_&. | |
168e428f PH |
347 | |
348 | The use, supply or promotion of Exim for the purpose of sending bulk, | |
349 | unsolicited electronic mail is incompatible with the basic aims of the program, | |
350 | which revolve around the free provision of a service that enhances the quality | |
351 | of personal communications. The author of Exim regards indiscriminate | |
352 | mass-mailing as an antisocial, irresponsible abuse of the Internet. | |
353 | ||
354 | Exim owes a great deal to Smail 3 and its author, Ron Karr. Without the | |
355 | experience of running and working on the Smail 3 code, I could never have | |
356 | contemplated starting to write a new MTA. Many of the ideas and user interfaces | |
357 | were originally taken from Smail 3, though the actual code of Exim is entirely | |
358 | new, and has developed far beyond the initial concept. | |
359 | ||
360 | Many people, both in Cambridge and around the world, have contributed to the | |
361 | development and the testing of Exim, and to porting it to various operating | |
362 | systems. I am grateful to them all. The distribution now contains a file called | |
9b371988 | 363 | &_ACKNOWLEDGMENTS_&, in which I have started recording the names of |
168e428f PH |
364 | contributors. |
365 | ||
366 | ||
f89d2485 | 367 | .section "Exim documentation" "SECID1" |
800d5176 TF |
368 | . Keep this example change bar when updating the documentation! |
369 | .new | |
9b371988 PH |
370 | .cindex "documentation" |
371 | This edition of the Exim specification applies to version &version; of Exim. | |
372 | Substantive changes from the &previousversion; edition are marked in some | |
168e428f PH |
373 | renditions of the document; this paragraph is so marked if the rendition is |
374 | capable of showing a change indicator. | |
800d5176 | 375 | .wen |
168e428f PH |
376 | |
377 | This document is very much a reference manual; it is not a tutorial. The reader | |
378 | is expected to have some familiarity with the SMTP mail transfer protocol and | |
379 | with general Unix system administration. Although there are some discussions | |
380 | and examples in places, the information is mostly organized in a way that makes | |
381 | it easy to look up, rather than in a natural order for sequential reading. | |
382 | Furthermore, the manual aims to cover every aspect of Exim in detail, including | |
383 | a number of rarely-used, special-purpose features that are unlikely to be of | |
384 | very wide interest. | |
385 | ||
9b371988 PH |
386 | .cindex "books about Exim" |
387 | An &"easier"& discussion of Exim which provides more in-depth explanatory, | |
388 | introductory, and tutorial material can be found in a book entitled &'The Exim | |
595028e4 | 389 | SMTP Mail Server'& (second edition, 2007), published by UIT Cambridge |
9b371988 | 390 | (&url(http://www.uit.co.uk/exim-book/)). |
168e428f PH |
391 | |
392 | This book also contains a chapter that gives a general introduction to SMTP and | |
393 | Internet mail. Inevitably, however, the book is unlikely to be fully up-to-date | |
394 | with the latest release of Exim. (Note that the earlier book about Exim, | |
395 | published by O'Reilly, covers Exim 3, and many things have changed in Exim 4.) | |
396 | ||
9b371988 | 397 | .cindex "Debian" "information sources" |
068aaea8 PH |
398 | If you are using a Debian distribution of Exim, you will find information about |
399 | Debian-specific features in the file | |
f89d2485 | 400 | &_/usr/share/doc/exim4-base/README.Debian_&. |
9b371988 | 401 | The command &(man update-exim.conf)& is another source of Debian-specific |
068aaea8 PH |
402 | information. |
403 | ||
9b371988 PH |
404 | .cindex "&_doc/NewStuff_&" |
405 | .cindex "&_doc/ChangeLog_&" | |
406 | .cindex "change log" | |
168e428f PH |
407 | As the program develops, there may be features in newer versions that have not |
408 | yet made it into this document, which is updated only when the most significant | |
409 | digit of the fractional part of the version number changes. Specifications of | |
410 | new features that are not yet in this manual are placed in the file | |
9b371988 | 411 | &_doc/NewStuff_& in the Exim distribution. |
168e428f | 412 | |
9b371988 | 413 | Some features may be classified as &"experimental"&. These may change |
168e428f PH |
414 | incompatibly while they are developing, or even be withdrawn. For this reason, |
415 | they are not documented in this manual. Information about experimental features | |
9b371988 | 416 | can be found in the file &_doc/experimental.txt_&. |
168e428f PH |
417 | |
418 | All changes to the program (whether new features, bug fixes, or other kinds of | |
9b371988 | 419 | change) are noted briefly in the file called &_doc/ChangeLog_&. |
168e428f | 420 | |
9b371988 PH |
421 | .cindex "&_doc/spec.txt_&" |
422 | This specification itself is available as an ASCII file in &_doc/spec.txt_& so | |
423 | that it can easily be searched with a text editor. Other files in the &_doc_& | |
168e428f PH |
424 | directory are: |
425 | ||
9b371988 PH |
426 | .table2 100pt |
427 | .row &_OptionLists.txt_& "list of all options in alphabetical order" | |
428 | .row &_dbm.discuss.txt_& "discussion about DBM libraries" | |
429 | .row &_exim.8_& "a man page of Exim's command line options" | |
430 | .row &_experimental.txt_& "documentation of experimental features" | |
431 | .row &_filter.txt_& "specification of the filter language" | |
9b371988 PH |
432 | .row &_Exim3.upgrade_& "upgrade notes from release 2 to release 3" |
433 | .row &_Exim4.upgrade_& "upgrade notes from release 3 to release 4" | |
434 | .endtable | |
168e428f PH |
435 | |
436 | The main specification and the specification of the filtering language are also | |
437 | available in other formats (HTML, PostScript, PDF, and Texinfo). Section | |
9b371988 | 438 | &<<SECTavail>>& below tells you how to get hold of these. |
168e428f PH |
439 | |
440 | ||
441 | ||
f89d2485 | 442 | .section "FTP and web sites" "SECID2" |
9b371988 PH |
443 | .cindex "web site" |
444 | .cindex "FTP site" | |
068aaea8 | 445 | The primary site for Exim source distributions is currently the University of |
9b371988 PH |
446 | Cambridge's FTP site, whose contents are described in &'Where to find the Exim |
447 | distribution'& below. In addition, there is a web site and an FTP site at | |
448 | &%exim.org%&. These are now also hosted at the University of Cambridge. The | |
449 | &%exim.org%& site was previously hosted for a number of years by Energis | |
450 | Squared, formerly Planet Online Ltd, whose support I gratefully acknowledge. | |
451 | ||
452 | .cindex "wiki" | |
453 | .cindex "FAQ" | |
168e428f | 454 | As well as Exim distribution tar files, the Exim web site contains a number of |
f89d2485 | 455 | differently formatted versions of the documentation. A recent addition to the |
7d0ab55c | 456 | online information is the Exim wiki (&url(http://wiki.exim.org)), |
f89d2485 PH |
457 | which contains what used to be a separate FAQ, as well as various other |
458 | examples, tips, and know-how that have been contributed by Exim users. | |
459 | ||
460 | .cindex Bugzilla | |
7d0ab55c | 461 | An Exim Bugzilla exists at &url(http://bugs.exim.org). You can use |
f89d2485 PH |
462 | this to report bugs, and also to add items to the wish list. Please search |
463 | first to check that you are not duplicating a previous entry. | |
168e428f PH |
464 | |
465 | ||
466 | ||
f89d2485 | 467 | .section "Mailing lists" "SECID3" |
9b371988 | 468 | .cindex "mailing lists" "for Exim users" |
f89d2485 | 469 | The following Exim mailing lists exist: |
168e428f | 470 | |
9b371988 | 471 | .table2 140pt |
f89d2485 PH |
472 | .row &'exim-users@exim.org'& "General discussion list" |
473 | .row &'exim-dev@exim.org'& "Discussion of bugs, enhancements, etc." | |
474 | .row &'exim-announce@exim.org'& "Moderated, low volume announcements list" | |
475 | .row &'exim-future@exim.org'& "Discussion of long-term development" | |
9b371988 | 476 | .endtable |
168e428f PH |
477 | |
478 | You can subscribe to these lists, change your existing subscriptions, and view | |
9b371988 PH |
479 | or search the archives via the mailing lists link on the Exim home page. |
480 | .cindex "Debian" "mailing list for" | |
4f578862 | 481 | If you are using a Debian distribution of Exim, you may wish to subscribe to |
db9452a9 PH |
482 | the Debian-specific mailing list &'pkg-exim4-users@lists.alioth.debian.org'& |
483 | via this web page: | |
484 | .display | |
485 | &url(http://lists.alioth.debian.org/mailman/listinfo/pkg-exim4-users) | |
486 | .endd | |
487 | Please ask Debian-specific questions on this list and not on the general Exim | |
488 | lists. | |
9b371988 | 489 | |
f89d2485 | 490 | .section "Exim training" "SECID4" |
9b371988 | 491 | .cindex "training courses" |
595028e4 PH |
492 | Training courses in Cambridge (UK) used to be run annually by the author of |
493 | Exim, before he retired. At the time of writing, there are no plans to run | |
494 | further Exim courses in Cambridge. However, if that changes, relevant | |
495 | information will be posted at &url(http://www-tus.csx.cam.ac.uk/courses/exim/). | |
168e428f | 496 | |
f89d2485 | 497 | .section "Bug reports" "SECID5" |
9b371988 PH |
498 | .cindex "bug reports" |
499 | .cindex "reporting bugs" | |
7d0ab55c TF |
500 | Reports of obvious bugs can be emailed to &'bugs@exim.org'& or reported |
501 | via the Bugzilla (&url(http://bugs.exim.org)). However, if you are unsure | |
595028e4 PH |
502 | whether some behaviour is a bug or not, the best thing to do is to post a |
503 | message to the &'exim-dev'& mailing list and have it discussed. | |
168e428f PH |
504 | |
505 | ||
506 | ||
9b371988 PH |
507 | .section "Where to find the Exim distribution" "SECTavail" |
508 | .cindex "FTP site" | |
509 | .cindex "distribution" "ftp site" | |
168e428f | 510 | The master ftp site for the Exim distribution is |
9b371988 PH |
511 | .display |
512 | &*ftp://ftp.csx.cam.ac.uk/pub/software/email/exim*& | |
513 | .endd | |
168e428f | 514 | This is mirrored by |
9b371988 PH |
515 | .display |
516 | &*ftp://ftp.exim.org/pub/exim*& | |
517 | .endd | |
518 | The file references that follow are relative to the &_exim_& directories at | |
519 | these sites. There are now quite a number of independent mirror sites around | |
520 | the world. Those that I know about are listed in the file called &_Mirrors_&. | |
521 | ||
522 | Within the &_exim_& directory there are subdirectories called &_exim3_& (for | |
523 | previous Exim 3 distributions), &_exim4_& (for the latest Exim 4 | |
524 | distributions), and &_Testing_& for testing versions. In the &_exim4_& | |
168e428f | 525 | subdirectory, the current release can always be found in files called |
9b371988 PH |
526 | .display |
527 | &_exim-n.nn.tar.gz_& | |
528 | &_exim-n.nn.tar.bz2_& | |
529 | .endd | |
530 | where &'n.nn'& is the highest such version number in the directory. The two | |
168e428f | 531 | files contain identical data; the only difference is the type of compression. |
9b371988 | 532 | The &_.bz2_& file is usually a lot smaller than the &_.gz_& file. |
168e428f | 533 | |
9b371988 PH |
534 | .cindex "distribution" "signing details" |
535 | .cindex "distribution" "public key" | |
536 | .cindex "public key for signed distribution" | |
210f147e | 537 | The distributions are currently signed with Nigel Metheringham's GPG key. The |
168e428f | 538 | corresponding public key is available from a number of keyservers, and there is |
210f147e | 539 | also a copy in the file &_nigel-pubkey.asc_&. The signatures for the tar bundles are |
168e428f | 540 | in: |
9b371988 | 541 | .display |
210f147e NM |
542 | &_exim-n.nn.tar.gz.asc_& |
543 | &_exim-n.nn.tar.bz2.asc_& | |
9b371988 | 544 | .endd |
168e428f | 545 | For each released version, the log of changes is made separately available in a |
9b371988 | 546 | separate file in the directory &_ChangeLogs_& so that it is possible to |
168e428f PH |
547 | find out what has changed without having to download the entire distribution. |
548 | ||
9b371988 | 549 | .cindex "documentation" "available formats" |
168e428f PH |
550 | The main distribution contains ASCII versions of this specification and other |
551 | documentation; other formats of the documents are available in separate files | |
9b371988 PH |
552 | inside the &_exim4_& directory of the FTP site: |
553 | .display | |
554 | &_exim-html-n.nn.tar.gz_& | |
555 | &_exim-pdf-n.nn.tar.gz_& | |
556 | &_exim-postscript-n.nn.tar.gz_& | |
557 | &_exim-texinfo-n.nn.tar.gz_& | |
558 | .endd | |
559 | These tar files contain only the &_doc_& directory, not the complete | |
560 | distribution, and are also available in &_.bz2_& as well as &_.gz_& forms. | |
168e428f | 561 | |
168e428f | 562 | |
f89d2485 | 563 | .section "Limitations" "SECID6" |
9b371988 PH |
564 | .ilist |
565 | .cindex "limitations of Exim" | |
566 | .cindex "bang paths" "not handled by Exim" | |
567 | Exim is designed for use as an Internet MTA, and therefore handles addresses in | |
568 | RFC 2822 domain format only. It cannot handle UUCP &"bang paths"&, though | |
569 | simple two-component bang paths can be converted by a straightforward rewriting | |
570 | configuration. This restriction does not prevent Exim from being interfaced to | |
571 | UUCP as a transport mechanism, provided that domain addresses are used. | |
572 | .next | |
573 | .cindex "domainless addresses" | |
574 | .cindex "address" "without domain" | |
168e428f PH |
575 | Exim insists that every address it handles has a domain attached. For incoming |
576 | local messages, domainless addresses are automatically qualified with a | |
577 | configured domain value. Configuration options specify from which remote | |
578 | systems unqualified addresses are acceptable. These are then qualified on | |
579 | arrival. | |
9b371988 PH |
580 | .next |
581 | .cindex "transport" "external" | |
582 | .cindex "external transports" | |
583 | The only external transport mechanisms that are currently implemented are SMTP | |
584 | and LMTP over a TCP/IP network (including support for IPv6). However, a pipe | |
168e428f | 585 | transport is available, and there are facilities for writing messages to files |
9b371988 PH |
586 | and pipes, optionally in &'batched SMTP'& format; these facilities can be used |
587 | to send messages to other transport mechanisms such as UUCP, provided they can | |
588 | handle domain-style addresses. Batched SMTP input is also catered for. | |
589 | .next | |
590 | Exim is not designed for storing mail for dial-in hosts. When the volumes of | |
591 | such mail are large, it is better to get the messages &"delivered"& into files | |
168e428f PH |
592 | (that is, off Exim's queue) and subsequently passed on to the dial-in hosts by |
593 | other means. | |
9b371988 PH |
594 | .next |
595 | Although Exim does have basic facilities for scanning incoming messages, these | |
168e428f PH |
596 | are not comprehensive enough to do full virus or spam scanning. Such operations |
597 | are best carried out using additional specialized software packages. If you | |
598 | compile Exim with the content-scanning extension, straightforward interfaces to | |
599 | a number of common scanners are provided. | |
9b371988 | 600 | .endlist |
168e428f PH |
601 | |
602 | ||
f89d2485 | 603 | .section "Run time configuration" "SECID7" |
168e428f PH |
604 | Exim's run time configuration is held in a single text file that is divided |
605 | into a number of sections. The entries in this file consist of keywords and | |
606 | values, in the style of Smail 3 configuration files. A default configuration | |
607 | file which is suitable for simple online installations is provided in the | |
9b371988 | 608 | distribution, and is described in chapter &<<CHAPdefconfil>>& below. |
168e428f PH |
609 | |
610 | ||
f89d2485 | 611 | .section "Calling interface" "SECID8" |
9b371988 | 612 | .cindex "Sendmail compatibility" "command line interface" |
168e428f | 613 | Like many MTAs, Exim has adopted the Sendmail command line interface so that it |
9b371988 PH |
614 | can be a straight replacement for &_/usr/lib/sendmail_& or |
615 | &_/usr/sbin/sendmail_& when sending mail, but you do not need to know anything | |
168e428f PH |
616 | about Sendmail in order to run Exim. For actions other than sending messages, |
617 | Sendmail-compatible options also exist, but those that produce output (for | |
9b371988 | 618 | example, &%-bp%&, which lists the messages on the queue) do so in Exim's own |
168e428f | 619 | format. There are also some additional options that are compatible with Smail |
9b371988 | 620 | 3, and some further options that are new to Exim. Chapter &<<CHAPcommandline>>& |
168e428f PH |
621 | documents all Exim's command line options. This information is automatically |
622 | made into the man page that forms part of the Exim distribution. | |
623 | ||
624 | Control of messages on the queue can be done via certain privileged command | |
9b371988 PH |
625 | line options. There is also an optional monitor program called &'eximon'&, |
626 | which displays current information in an X window, and which contains a menu | |
168e428f PH |
627 | interface to Exim's command line administration options. |
628 | ||
629 | ||
630 | ||
f89d2485 | 631 | .section "Terminology" "SECID9" |
9b371988 PH |
632 | .cindex "terminology definitions" |
633 | .cindex "body of message" "definition of" | |
634 | The &'body'& of a message is the actual data that the sender wants to transmit. | |
635 | It is the last part of a message, and is separated from the &'header'& (see | |
168e428f PH |
636 | below) by a blank line. |
637 | ||
9b371988 | 638 | .cindex "bounce message" "definition of" |
168e428f | 639 | When a message cannot be delivered, it is normally returned to the sender in a |
9b371988 PH |
640 | delivery failure message or a &"non-delivery report"& (NDR). The term |
641 | &'bounce'& is commonly used for this action, and the error reports are often | |
642 | called &'bounce messages'&. This is a convenient shorthand for &"delivery | |
643 | failure error report"&. Such messages have an empty sender address in the | |
644 | message's &'envelope'& (see below) to ensure that they cannot themselves give | |
645 | rise to further bounce messages. | |
646 | ||
647 | The term &'default'& appears frequently in this manual. It is used to qualify a | |
168e428f PH |
648 | value which is used in the absence of any setting in the configuration. It may |
649 | also qualify an action which is taken unless a configuration setting specifies | |
650 | otherwise. | |
651 | ||
9b371988 | 652 | The term &'defer'& is used when the delivery of a message to a specific |
168e428f | 653 | destination cannot immediately take place for some reason (a remote host may be |
9b371988 | 654 | down, or a user's local mailbox may be full). Such deliveries are &'deferred'& |
168e428f PH |
655 | until a later time. |
656 | ||
9b371988 PH |
657 | The word &'domain'& is sometimes used to mean all but the first component of a |
658 | host's name. It is &'not'& used in that sense here, where it normally refers to | |
659 | the part of an email address following the @ sign. | |
168e428f | 660 | |
f89d2485 | 661 | .cindex "envelope, definition of" |
9b371988 PH |
662 | .cindex "sender" "definition of" |
663 | A message in transit has an associated &'envelope'&, as well as a header and a | |
168e428f PH |
664 | body. The envelope contains a sender address (to which bounce messages should |
665 | be delivered), and any number of recipient addresses. References to the | |
666 | sender or the recipients of a message usually mean the addresses in the | |
667 | envelope. An MTA uses these addresses for delivery, and for returning bounce | |
668 | messages, not the addresses that appear in the header lines. | |
669 | ||
f89d2485 | 670 | .cindex "message" "header, definition of" |
9b371988 PH |
671 | .cindex "header section" "definition of" |
672 | The &'header'& of a message is the first part of a message's text, consisting | |
673 | of a number of lines, each of which has a name such as &'From:'&, &'To:'&, | |
674 | &'Subject:'&, etc. Long header lines can be split over several text lines by | |
168e428f PH |
675 | indenting the continuations. The header is separated from the body by a blank |
676 | line. | |
677 | ||
9b371988 PH |
678 | .cindex "local part" "definition of" |
679 | .cindex "domain" "definition of" | |
680 | The term &'local part'&, which is taken from RFC 2822, is used to refer to that | |
168e428f | 681 | part of an email address that precedes the @ sign. The part that follows the |
9b371988 | 682 | @ sign is called the &'domain'& or &'mail domain'&. |
168e428f | 683 | |
9b371988 | 684 | .cindex "local delivery" "definition of" |
f89d2485 | 685 | .cindex "remote delivery, definition of" |
9b371988 | 686 | The terms &'local delivery'& and &'remote delivery'& are used to distinguish |
168e428f | 687 | delivery to a file or a pipe on the local host from delivery by SMTP over |
068aaea8 | 688 | TCP/IP to another host. As far as Exim is concerned, all hosts other than the |
9b371988 | 689 | host it is running on are &'remote'&. |
168e428f | 690 | |
9b371988 PH |
691 | .cindex "return path" "definition of" |
692 | &'Return path'& is another name that is used for the sender address in a | |
168e428f PH |
693 | message's envelope. |
694 | ||
9b371988 PH |
695 | .cindex "queue" "definition of" |
696 | The term &'queue'& is used to refer to the set of messages awaiting delivery, | |
168e428f PH |
697 | because this term is in widespread use in the context of MTAs. However, in |
698 | Exim's case the reality is more like a pool than a queue, because there is | |
699 | normally no ordering of waiting messages. | |
700 | ||
9b371988 PH |
701 | .cindex "queue runner" "definition of" |
702 | The term &'queue runner'& is used to describe a process that scans the queue | |
168e428f | 703 | and attempts to deliver those messages whose retry times have come. This term |
9b371988 | 704 | is used by other MTAs, and also relates to the command &%runq%&, but in Exim |
168e428f PH |
705 | the waiting messages are normally processed in an unpredictable order. |
706 | ||
9b371988 PH |
707 | .cindex "spool directory" "definition of" |
708 | The term &'spool directory'& is used for a directory in which Exim keeps the | |
709 | messages on its queue &-- that is, those that it is in the process of | |
168e428f | 710 | delivering. This should not be confused with the directory in which local |
9b371988 PH |
711 | mailboxes are stored, which is called a &"spool directory"& by some people. In |
712 | the Exim documentation, &"spool"& is always used in the first sense. | |
168e428f PH |
713 | |
714 | ||
715 | ||
716 | ||
717 | ||
718 | ||
9b371988 PH |
719 | . //////////////////////////////////////////////////////////////////////////// |
720 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 721 | |
f89d2485 | 722 | .chapter "Incorporated code" "CHID2" |
9b371988 PH |
723 | .cindex "incorporated code" |
724 | .cindex "regular expressions" "library" | |
725 | .cindex "PCRE" | |
168e428f PH |
726 | A number of pieces of external code are included in the Exim distribution. |
727 | ||
9b371988 | 728 | .ilist |
210f147e NM |
729 | Regular expressions are supported in the main Exim program and in the |
730 | Exim monitor using the freely-distributable PCRE library, copyright | |
40df1be3 TF |
731 | © University of Cambridge. The source to PCRE is no longer shipped with |
732 | Exim, so you will need to use the version of PCRE shipped with your system, | |
733 | or obtain and install the full version of the library from | |
f89d2485 | 734 | &url(ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre). |
9b371988 | 735 | .next |
f89d2485 | 736 | .cindex "cdb" "acknowledgment" |
168e428f PH |
737 | Support for the cdb (Constant DataBase) lookup method is provided by code |
738 | contributed by Nigel Metheringham of (at the time he contributed it) Planet | |
9b371988 PH |
739 | Online Ltd. The implementation is completely contained within the code of Exim. |
740 | It does not link against an external cdb library. The code contains the | |
741 | following statements: | |
742 | ||
743 | .blockquote | |
744 | Copyright © 1998 Nigel Metheringham, Planet Online Ltd | |
745 | ||
168e428f PH |
746 | This program is free software; you can redistribute it and/or modify it under |
747 | the terms of the GNU General Public License as published by the Free Software | |
748 | Foundation; either version 2 of the License, or (at your option) any later | |
749 | version. | |
168e428f PH |
750 | This code implements Dan Bernstein's Constant DataBase (cdb) spec. Information, |
751 | the spec and sample code for cdb can be obtained from | |
f89d2485 PH |
752 | &url(http://www.pobox.com/~djb/cdb.html). This implementation borrows |
753 | some code from Dan Bernstein's implementation (which has no license | |
754 | restrictions applied to it). | |
9b371988 PH |
755 | .endblockquote |
756 | .next | |
757 | .cindex "SPA authentication" | |
758 | .cindex "Samba project" | |
759 | .cindex "Microsoft Secure Password Authentication" | |
760 | Client support for Microsoft's &'Secure Password Authentication'& is provided | |
168e428f PH |
761 | by code contributed by Marc Prud'hommeaux. Server support was contributed by |
762 | Tom Kistner. This includes code taken from the Samba project, which is released | |
763 | under the Gnu GPL. | |
9b371988 PH |
764 | .next |
765 | .cindex "Cyrus" | |
766 | .cindex "&'pwcheck'& daemon" | |
767 | .cindex "&'pwauthd'& daemon" | |
768 | Support for calling the Cyrus &'pwcheck'& and &'saslauthd'& daemons is provided | |
168e428f PH |
769 | by code taken from the Cyrus-SASL library and adapted by Alexander S. |
770 | Sabourenkov. The permission notice appears below, in accordance with the | |
771 | conditions expressed therein. | |
9b371988 PH |
772 | |
773 | .blockquote | |
774 | Copyright © 2001 Carnegie Mellon University. All rights reserved. | |
775 | ||
168e428f PH |
776 | Redistribution and use in source and binary forms, with or without |
777 | modification, are permitted provided that the following conditions | |
778 | are met: | |
168e428f | 779 | |
9b371988 PH |
780 | .olist |
781 | Redistributions of source code must retain the above copyright | |
782 | notice, this list of conditions and the following disclaimer. | |
783 | .next | |
784 | Redistributions in binary form must reproduce the above copyright | |
168e428f PH |
785 | notice, this list of conditions and the following disclaimer in |
786 | the documentation and/or other materials provided with the | |
787 | distribution. | |
9b371988 PH |
788 | .next |
789 | The name &"Carnegie Mellon University"& must not be used to | |
168e428f PH |
790 | endorse or promote products derived from this software without |
791 | prior written permission. For permission or any other legal | |
792 | details, please contact | |
9b371988 | 793 | .display |
068aaea8 PH |
794 | Office of Technology Transfer |
795 | Carnegie Mellon University | |
796 | 5000 Forbes Avenue | |
797 | Pittsburgh, PA 15213-3890 | |
798 | (412) 268-4387, fax: (412) 268-7395 | |
799 | tech-transfer@andrew.cmu.edu | |
9b371988 PH |
800 | .endd |
801 | .next | |
802 | Redistributions of any form whatsoever must retain the following | |
168e428f | 803 | acknowledgment: |
9b371988 PH |
804 | |
805 | &"This product includes software developed by Computing Services | |
806 | at Carnegie Mellon University (&url(http://www.cmu.edu/computing/)."& | |
807 | ||
168e428f PH |
808 | CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO |
809 | THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY | |
810 | AND FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE | |
811 | FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | |
812 | WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN | |
813 | AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING | |
814 | OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | |
9b371988 PH |
815 | .endlist |
816 | .endblockquote | |
168e428f | 817 | |
9b371988 | 818 | .next |
f89d2485 | 819 | .cindex "Exim monitor" "acknowledgment" |
9b371988 PH |
820 | .cindex "X-windows" |
821 | .cindex "Athena" | |
168e428f PH |
822 | The Exim Monitor program, which is an X-Window application, includes |
823 | modified versions of the Athena StripChart and TextPop widgets. | |
824 | This code is copyright by DEC and MIT, and their permission notice appears | |
825 | below, in accordance with the conditions expressed therein. | |
9b371988 PH |
826 | |
827 | .blockquote | |
168e428f PH |
828 | Copyright 1987, 1988 by Digital Equipment Corporation, Maynard, Massachusetts, |
829 | and the Massachusetts Institute of Technology, Cambridge, Massachusetts. | |
9b371988 | 830 | |
168e428f | 831 | All Rights Reserved |
9b371988 | 832 | |
168e428f PH |
833 | Permission to use, copy, modify, and distribute this software and its |
834 | documentation for any purpose and without fee is hereby granted, | |
835 | provided that the above copyright notice appear in all copies and that | |
836 | both that copyright notice and this permission notice appear in | |
837 | supporting documentation, and that the names of Digital or MIT not be | |
838 | used in advertising or publicity pertaining to distribution of the | |
839 | software without specific, written prior permission. | |
9b371988 | 840 | |
168e428f PH |
841 | DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING |
842 | ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL | |
843 | DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR | |
844 | ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, | |
845 | WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, | |
846 | ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS | |
847 | SOFTWARE. | |
9b371988 | 848 | .endblockquote |
168e428f | 849 | |
9b371988 PH |
850 | .next |
851 | Many people have contributed code fragments, some large, some small, that were | |
168e428f | 852 | not covered by any specific licence requirements. It is assumed that the |
f89d2485 | 853 | contributors are happy to see their code incorporated into Exim under the GPL. |
9b371988 | 854 | .endlist |
168e428f PH |
855 | |
856 | ||
857 | ||
858 | ||
859 | ||
9b371988 PH |
860 | . //////////////////////////////////////////////////////////////////////////// |
861 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 862 | |
f89d2485 | 863 | .chapter "How Exim receives and delivers mail" "CHID11" &&& |
9b371988 | 864 | "Receiving and delivering mail" |
168e428f PH |
865 | |
866 | ||
f89d2485 | 867 | .section "Overall philosophy" "SECID10" |
9b371988 | 868 | .cindex "design philosophy" |
168e428f PH |
869 | Exim is designed to work efficiently on systems that are permanently connected |
870 | to the Internet and are handling a general mix of mail. In such circumstances, | |
871 | most messages can be delivered immediately. Consequently, Exim does not | |
872 | maintain independent queues of messages for specific domains or hosts, though | |
873 | it does try to send several messages in a single SMTP connection after a host | |
874 | has been down, and it also maintains per-host retry information. | |
875 | ||
876 | ||
f89d2485 | 877 | .section "Policy control" "SECID11" |
9b371988 | 878 | .cindex "policy control" "overview" |
168e428f PH |
879 | Policy controls are now an important feature of MTAs that are connected to the |
880 | Internet. Perhaps their most important job is to stop MTAs being abused as | |
9b371988 PH |
881 | &"open relays"& by misguided individuals who send out vast amounts of |
882 | unsolicited junk, and want to disguise its source. Exim provides flexible | |
883 | facilities for specifying policy controls on incoming mail: | |
168e428f | 884 | |
9b371988 PH |
885 | .ilist |
886 | .cindex "&ACL;" "introduction" | |
168e428f | 887 | Exim 4 (unlike previous versions of Exim) implements policy controls on |
9b371988 | 888 | incoming mail by means of &'Access Control Lists'& (ACLs). Each list is a |
168e428f PH |
889 | series of statements that may either grant or deny access. ACLs can be used at |
890 | several places in the SMTP dialogue while receiving a message from a remote | |
9b371988 PH |
891 | host. However, the most common places are after each RCPT command, and at the |
892 | very end of the message. The sysadmin can specify conditions for accepting or | |
893 | rejecting individual recipients or the entire message, respectively, at these | |
894 | two points (see chapter &<<CHAPACL>>&). Denial of access results in an SMTP | |
168e428f | 895 | error code. |
9b371988 PH |
896 | .next |
897 | An ACL is also available for locally generated, non-SMTP messages. In this | |
168e428f | 898 | case, the only available actions are to accept or deny the entire message. |
9b371988 PH |
899 | .next |
900 | When Exim is compiled with the content-scanning extension, facilities are | |
168e428f PH |
901 | provided in the ACL mechanism for passing the message to external virus and/or |
902 | spam scanning software. The result of such a scan is passed back to the ACL, | |
903 | which can then use it to decide what to do with the message. | |
9b371988 PH |
904 | .next |
905 | When a message has been received, either from a remote host or from the local | |
f89d2485 | 906 | host, but before the final acknowledgment has been sent, a locally supplied C |
9b371988 PH |
907 | function called &[local_scan()]& can be run to inspect the message and decide |
908 | whether to accept it or not (see chapter &<<CHAPlocalscan>>&). If the message | |
909 | is accepted, the list of recipients can be modified by the function. | |
910 | .next | |
911 | Using the &[local_scan()]& mechanism is another way of calling external scanner | |
912 | software. The &%SA-Exim%& add-on package works this way. It does not require | |
913 | Exim to be compiled with the content-scanning extension. | |
914 | .next | |
915 | After a message has been accepted, a further checking mechanism is available in | |
916 | the form of the &'system filter'& (see chapter &<<CHAPsystemfilter>>&). This | |
917 | runs at the start of every delivery process. | |
918 | .endlist | |
919 | ||
920 | ||
921 | ||
f89d2485 | 922 | .section "User filters" "SECID12" |
9b371988 PH |
923 | .cindex "filter" "introduction" |
924 | .cindex "Sieve filter" | |
168e428f | 925 | In a conventional Exim configuration, users are able to run private filters by |
9b371988 PH |
926 | setting up appropriate &_.forward_& files in their home directories. See |
927 | chapter &<<CHAPredirect>>& (about the &(redirect)& router) for the | |
928 | configuration needed to support this, and the separate document entitled | |
929 | &'Exim's interfaces to mail filtering'& for user details. Two different kinds | |
930 | of filtering are available: | |
931 | ||
932 | .ilist | |
933 | Sieve filters are written in the standard filtering language that is defined | |
168e428f | 934 | by RFC 3028. |
9b371988 PH |
935 | .next |
936 | Exim filters are written in a syntax that is unique to Exim, but which is more | |
168e428f | 937 | powerful than Sieve, which it pre-dates. |
9b371988 | 938 | .endlist |
168e428f PH |
939 | |
940 | User filters are run as part of the routing process, described below. | |
941 | ||
942 | ||
943 | ||
9b371988 PH |
944 | .section "Message identification" "SECTmessiden" |
945 | .cindex "message ids" "details of format" | |
946 | .cindex "format" "of message id" | |
947 | .cindex "id of message" | |
948 | .cindex "base62" | |
949 | .cindex "base36" | |
950 | .cindex "Darwin" | |
951 | .cindex "Cygwin" | |
952 | Every message handled by Exim is given a &'message id'& which is sixteen | |
168e428f | 953 | characters long. It is divided into three parts, separated by hyphens, for |
9b371988 | 954 | example &`16VDhn-0001bo-D3`&. Each part is a sequence of letters and digits, |
168e428f PH |
955 | normally encoding numbers in base 62. However, in the Darwin operating |
956 | system (Mac OS X) and when Exim is compiled to run under Cygwin, base 36 | |
957 | (avoiding the use of lower case letters) is used instead, because the message | |
958 | id is used to construct file names, and the names of files in those systems are | |
068aaea8 | 959 | not always case-sensitive. |
168e428f | 960 | |
9b371988 | 961 | .cindex "pid (process id)" "re-use of" |
168e428f PH |
962 | The detail of the contents of the message id have changed as Exim has evolved. |
963 | Earlier versions relied on the operating system not re-using a process id (pid) | |
964 | within one second. On modern operating systems, this assumption can no longer | |
965 | be made, so the algorithm had to be changed. To retain backward compatibility, | |
966 | the format of the message id was retained, which is why the following rules are | |
967 | somewhat eccentric: | |
968 | ||
9b371988 PH |
969 | .ilist |
970 | The first six characters of the message id are the time at which the message | |
168e428f PH |
971 | started to be received, to a granularity of one second. That is, this field |
972 | contains the number of seconds since the start of the epoch (the normal Unix | |
973 | way of representing the date and time of day). | |
9b371988 PH |
974 | .next |
975 | After the first hyphen, the next six characters are the id of the process that | |
168e428f | 976 | received the message. |
9b371988 PH |
977 | .next |
978 | There are two different possibilities for the final two characters: | |
979 | .olist | |
0a4e3112 | 980 | .oindex "&%localhost_number%&" |
9b371988 | 981 | If &%localhost_number%& is not set, this value is the fractional part of the |
168e428f PH |
982 | time of reception, normally in units of 1/2000 of a second, but for systems |
983 | that must use base 36 instead of base 62 (because of case-insensitive file | |
984 | systems), the units are 1/1000 of a second. | |
9b371988 PH |
985 | .next |
986 | If &%localhost_number%& is set, it is multiplied by 200 (100) and added to | |
168e428f PH |
987 | the fractional part of the time, which in this case is in units of 1/200 |
988 | (1/100) of a second. | |
9b371988 PH |
989 | .endlist |
990 | .endlist | |
168e428f PH |
991 | |
992 | After a message has been received, Exim waits for the clock to tick at the | |
993 | appropriate resolution before proceeding, so that if another message is | |
994 | received by the same process, or by another process with the same (re-used) | |
995 | pid, it is guaranteed that the time will be different. In most cases, the clock | |
996 | will already have ticked while the message was being received. | |
997 | ||
998 | ||
f89d2485 | 999 | .section "Receiving mail" "SECID13" |
9b371988 PH |
1000 | .cindex "receiving mail" |
1001 | .cindex "message" "reception" | |
068aaea8 PH |
1002 | The only way Exim can receive mail from another host is using SMTP over |
1003 | TCP/IP, in which case the sender and recipient addresses are transferred using | |
168e428f PH |
1004 | SMTP commands. However, from a locally running process (such as a user's MUA), |
1005 | there are several possibilities: | |
1006 | ||
9b371988 PH |
1007 | .ilist |
1008 | If the process runs Exim with the &%-bm%& option, the message is read | |
168e428f | 1009 | non-interactively (usually via a pipe), with the recipients taken from the |
9b371988 PH |
1010 | command line, or from the body of the message if &%-t%& is also used. |
1011 | .next | |
1012 | If the process runs Exim with the &%-bS%& option, the message is also read | |
168e428f PH |
1013 | non-interactively, but in this case the recipients are listed at the start of |
1014 | the message in a series of SMTP RCPT commands, terminated by a DATA | |
9b371988 | 1015 | command. This is so-called &"batch SMTP"& format, |
168e428f PH |
1016 | but it isn't really SMTP. The SMTP commands are just another way of passing |
1017 | envelope addresses in a non-interactive submission. | |
9b371988 PH |
1018 | .next |
1019 | If the process runs Exim with the &%-bs%& option, the message is read | |
168e428f PH |
1020 | interactively, using the SMTP protocol. A two-way pipe is normally used for |
1021 | passing data between the local process and the Exim process. | |
9b371988 | 1022 | This is &"real"& SMTP and is handled in the same way as SMTP over TCP/IP. For |
168e428f | 1023 | example, the ACLs for SMTP commands are used for this form of submission. |
9b371988 PH |
1024 | .next |
1025 | A local process may also make a TCP/IP call to the host's loopback address | |
168e428f PH |
1026 | (127.0.0.1) or any other of its IP addresses. When receiving messages, Exim |
1027 | does not treat the loopback address specially. It treats all such connections | |
1028 | in the same way as connections from other hosts. | |
9b371988 | 1029 | .endlist |
168e428f PH |
1030 | |
1031 | ||
f89d2485 | 1032 | .cindex "message sender, constructed by Exim" |
9b371988 | 1033 | .cindex "sender" "constructed by Exim" |
168e428f PH |
1034 | In the three cases that do not involve TCP/IP, the sender address is |
1035 | constructed from the login name of the user that called Exim and a default | |
9b371988 | 1036 | qualification domain (which can be set by the &%qualify_domain%& configuration |
168e428f PH |
1037 | option). For local or batch SMTP, a sender address that is passed using the |
1038 | SMTP MAIL command is ignored. However, the system administrator may allow | |
9b371988 | 1039 | certain users (&"trusted users"&) to specify a different sender address |
168e428f | 1040 | unconditionally, or all users to specify certain forms of different sender |
9b371988 PH |
1041 | address. The &%-f%& option or the SMTP MAIL command is used to specify these |
1042 | different addresses. See section &<<SECTtrustedadmin>>& for details of trusted | |
1043 | users, and the &%untrusted_set_sender%& option for a way of allowing untrusted | |
168e428f PH |
1044 | users to change sender addresses. |
1045 | ||
1046 | Messages received by either of the non-interactive mechanisms are subject to | |
1047 | checking by the non-SMTP ACL, if one is defined. Messages received using SMTP | |
1048 | (either over TCP/IP, or interacting with a local process) can be checked by a | |
1049 | number of ACLs that operate at different times during the SMTP session. Either | |
1050 | individual recipients, or the entire message, can be rejected if local policy | |
9b371988 PH |
1051 | requirements are not met. The &[local_scan()]& function (see chapter |
1052 | &<<CHAPlocalscan>>&) is run for all incoming messages. | |
168e428f PH |
1053 | |
1054 | Exim can be configured not to start a delivery process when a message is | |
1055 | received; this can be unconditional, or depend on the number of incoming SMTP | |
1056 | connections or the system load. In these situations, new messages wait on the | |
1057 | queue until a queue runner process picks them up. However, in standard | |
1058 | configurations under normal conditions, delivery is started as soon as a | |
1059 | message is received. | |
1060 | ||
1061 | ||
1062 | ||
1063 | ||
1064 | ||
f89d2485 | 1065 | .section "Handling an incoming message" "SECID14" |
9b371988 PH |
1066 | .cindex "spool directory" "files that hold a message" |
1067 | .cindex "file" "how a message is held" | |
168e428f PH |
1068 | When Exim accepts a message, it writes two files in its spool directory. The |
1069 | first contains the envelope information, the current status of the message, and | |
1070 | the header lines, and the second contains the body of the message. The names of | |
9b371988 PH |
1071 | the two spool files consist of the message id, followed by &`-H`& for the |
1072 | file containing the envelope and header, and &`-D`& for the data file. | |
168e428f | 1073 | |
9b371988 | 1074 | .cindex "spool directory" "&_input_& sub-directory" |
168e428f | 1075 | By default all these message files are held in a single directory called |
9b371988 | 1076 | &_input_& inside the general Exim spool directory. Some operating systems do |
c0712871 | 1077 | not perform very well if the number of files in a directory gets large; to |
9b371988 | 1078 | improve performance in such cases, the &%split_spool_directory%& option can be |
168e428f | 1079 | used. This causes Exim to split up the input files into 62 sub-directories |
db9452a9 | 1080 | whose names are single letters or digits. When this is done, the queue is |
c0712871 PH |
1081 | processed one sub-directory at a time instead of all at once, which can improve |
1082 | overall performance even when there are not enough files in each directory to | |
db9452a9 | 1083 | affect file system performance. |
168e428f PH |
1084 | |
1085 | The envelope information consists of the address of the message's sender and | |
1086 | the addresses of the recipients. This information is entirely separate from | |
1087 | any addresses contained in the header lines. The status of the message includes | |
1088 | a list of recipients who have already received the message. The format of the | |
9b371988 | 1089 | first spool file is described in chapter &<<CHAPspool>>&. |
168e428f | 1090 | |
9b371988 | 1091 | .cindex "rewriting" "addresses" |
168e428f | 1092 | Address rewriting that is specified in the rewrite section of the configuration |
9b371988 | 1093 | (see chapter &<<CHAPrewrite>>&) is done once and for all on incoming addresses, |
168e428f PH |
1094 | both in the header lines and the envelope, at the time the message is accepted. |
1095 | If during the course of delivery additional addresses are generated (for | |
1096 | example, via aliasing), these new addresses are rewritten as soon as they are | |
1097 | generated. At the time a message is actually delivered (transported) further | |
1098 | rewriting can take place; because this is a transport option, it can be | |
1099 | different for different forms of delivery. It is also possible to specify the | |
1100 | addition or removal of certain header lines at the time the message is | |
9b371988 PH |
1101 | delivered (see chapters &<<CHAProutergeneric>>& and |
1102 | &<<CHAPtransportgeneric>>&). | |
168e428f PH |
1103 | |
1104 | ||
1105 | ||
f89d2485 | 1106 | .section "Life of a message" "SECID15" |
9b371988 PH |
1107 | .cindex "message" "life of" |
1108 | .cindex "message" "frozen" | |
168e428f PH |
1109 | A message remains in the spool directory until it is completely delivered to |
1110 | its recipients or to an error address, or until it is deleted by an | |
1111 | administrator or by the user who originally created it. In cases when delivery | |
9b371988 PH |
1112 | cannot proceed &-- for example, when a message can neither be delivered to its |
1113 | recipients nor returned to its sender, the message is marked &"frozen"& on the | |
168e428f PH |
1114 | spool, and no more deliveries are attempted. |
1115 | ||
9b371988 PH |
1116 | .cindex "frozen messages" "thawing" |
1117 | .cindex "message" "thawing frozen" | |
1118 | An administrator can &"thaw"& such messages when the problem has been | |
1119 | corrected, and can also freeze individual messages by hand if necessary. In | |
1120 | addition, an administrator can force a delivery error, causing a bounce message | |
1121 | to be sent. | |
1122 | ||
0a4e3112 PH |
1123 | .oindex "&%timeout_frozen_after%&" |
1124 | .oindex "&%ignore_bounce_errors_after%&" | |
9b371988 PH |
1125 | There are options called &%ignore_bounce_errors_after%& and |
1126 | &%timeout_frozen_after%&, which discard frozen messages after a certain time. | |
068aaea8 | 1127 | The first applies only to frozen bounces, the second to any frozen messages. |
168e428f | 1128 | |
9b371988 PH |
1129 | .cindex "message" "log file for" |
1130 | .cindex "log" "file for each message" | |
168e428f | 1131 | While Exim is working on a message, it writes information about each delivery |
068aaea8 | 1132 | attempt to its main log file. This includes successful, unsuccessful, and |
9b371988 PH |
1133 | delayed deliveries for each recipient (see chapter &<<CHAPlog>>&). The log |
1134 | lines are also written to a separate &'message log'& file for each message. | |
1135 | These logs are solely for the benefit of the administrator, and are normally | |
1136 | deleted along with the spool files when processing of a message is complete. | |
168e428f | 1137 | The use of individual message logs can be disabled by setting |
9b371988 PH |
1138 | &%no_message_logs%&; this might give an improvement in performance on very busy |
1139 | systems. | |
168e428f | 1140 | |
9b371988 PH |
1141 | .cindex "journal file" |
1142 | .cindex "file" "journal" | |
168e428f PH |
1143 | All the information Exim itself needs to set up a delivery is kept in the first |
1144 | spool file, along with the header lines. When a successful delivery occurs, the | |
1145 | address is immediately written at the end of a journal file, whose name is the | |
9b371988 PH |
1146 | message id followed by &`-J`&. At the end of a delivery run, if there are some |
1147 | addresses left to be tried again later, the first spool file (the &`-H`& file) | |
168e428f PH |
1148 | is updated to indicate which these are, and the journal file is then deleted. |
1149 | Updating the spool file is done by writing a new file and renaming it, to | |
1150 | minimize the possibility of data loss. | |
1151 | ||
1152 | Should the system or the program crash after a successful delivery but before | |
1153 | the spool file has been updated, the journal is left lying around. The next | |
1154 | time Exim attempts to deliver the message, it reads the journal file and | |
1155 | updates the spool file before proceeding. This minimizes the chances of double | |
1156 | deliveries caused by crashes. | |
1157 | ||
1158 | ||
1159 | ||
9b371988 PH |
1160 | .section "Processing an address for delivery" "SECTprocaddress" |
1161 | .cindex "drivers" "definition of" | |
1162 | .cindex "router" "definition of" | |
1163 | .cindex "transport" "definition of" | |
1164 | The main delivery processing elements of Exim are called &'routers'& and | |
1165 | &'transports'&, and collectively these are known as &'drivers'&. Code for a | |
168e428f PH |
1166 | number of them is provided in the source distribution, and compile-time options |
1167 | specify which ones are included in the binary. Run time options specify which | |
1168 | ones are actually used for delivering messages. | |
1169 | ||
9b371988 PH |
1170 | .cindex "drivers" "instance definition" |
1171 | Each driver that is specified in the run time configuration is an &'instance'& | |
168e428f | 1172 | of that particular driver type. Multiple instances are allowed; for example, |
9b371988 | 1173 | you can set up several different &(smtp)& transports, each with different |
168e428f PH |
1174 | option values that might specify different ports or different timeouts. Each |
1175 | instance has its own identifying name. In what follows we will normally use the | |
1176 | instance name when discussing one particular instance (that is, one specific | |
1177 | configuration of the driver), and the generic driver name when discussing | |
1178 | the driver's features in general. | |
1179 | ||
9b371988 | 1180 | A &'router'& is a driver that operates on an address, either determining how |
068aaea8 | 1181 | its delivery should happen, by assigning it to a specific transport, or |
168e428f PH |
1182 | converting the address into one or more new addresses (for example, via an |
1183 | alias file). A router may also explicitly choose to fail an address, causing it | |
1184 | to be bounced. | |
1185 | ||
9b371988 PH |
1186 | A &'transport'& is a driver that transmits a copy of the message from Exim's |
1187 | spool to some destination. There are two kinds of transport: for a &'local'& | |
168e428f | 1188 | transport, the destination is a file or a pipe on the local host, whereas for a |
9b371988 | 1189 | &'remote'& transport the destination is some other host. A message is passed |
168e428f PH |
1190 | to a specific transport as a result of successful routing. If a message has |
1191 | several recipients, it may be passed to a number of different transports. | |
1192 | ||
9b371988 | 1193 | .cindex "preconditions" "definition of" |
168e428f PH |
1194 | An address is processed by passing it to each configured router instance in |
1195 | turn, subject to certain preconditions, until a router accepts the address or | |
1196 | specifies that it should be bounced. We will describe this process in more | |
068aaea8 PH |
1197 | detail shortly. First, as a simple example, we consider how each recipient |
1198 | address in a message is processed in a small configuration of three routers. | |
168e428f | 1199 | |
068aaea8 | 1200 | To make this a more concrete example, it is described in terms of some actual |
168e428f PH |
1201 | routers, but remember, this is only an example. You can configure Exim's |
1202 | routers in many different ways, and there may be any number of routers in a | |
1203 | configuration. | |
1204 | ||
1205 | The first router that is specified in a configuration is often one that handles | |
1206 | addresses in domains that are not recognized specially by the local host. These | |
1207 | are typically addresses for arbitrary domains on the Internet. A precondition | |
1208 | is set up which looks for the special domains known to the host (for example, | |
9b371988 | 1209 | its own domain name), and the router is run for addresses that do &'not'& |
168e428f PH |
1210 | match. Typically, this is a router that looks up domains in the DNS in order to |
1211 | find the hosts to which this address routes. If it succeeds, the address is | |
068aaea8 | 1212 | assigned to a suitable SMTP transport; if it does not succeed, the router is |
168e428f PH |
1213 | configured to fail the address. |
1214 | ||
068aaea8 | 1215 | The second router is reached only when the domain is recognized as one that |
9b371988 | 1216 | &"belongs"& to the local host. This router does redirection &-- also known as |
068aaea8 PH |
1217 | aliasing and forwarding. When it generates one or more new addresses from the |
1218 | original, each of them is routed independently from the start. Otherwise, the | |
1219 | router may cause an address to fail, or it may simply decline to handle the | |
1220 | address, in which case the address is passed to the next router. | |
168e428f PH |
1221 | |
1222 | The final router in many configurations is one that checks to see if the | |
1223 | address belongs to a local mailbox. The precondition may involve a check to | |
1224 | see if the local part is the name of a login account, or it may look up the | |
1225 | local part in a file or a database. If its preconditions are not met, or if | |
1226 | the router declines, we have reached the end of the routers. When this happens, | |
1227 | the address is bounced. | |
1228 | ||
1229 | ||
1230 | ||
f89d2485 | 1231 | .section "Processing an address for verification" "SECID16" |
9b371988 PH |
1232 | .cindex "router" "for verification" |
1233 | .cindex "verifying address" "overview" | |
168e428f | 1234 | As well as being used to decide how to deliver to an address, Exim's routers |
9b371988 | 1235 | are also used for &'address verification'&. Verification can be requested as |
168e428f | 1236 | one of the checks to be performed in an ACL for incoming messages, on both |
9b371988 PH |
1237 | sender and recipient addresses, and it can be tested using the &%-bv%& and |
1238 | &%-bvs%& command line options. | |
168e428f | 1239 | |
9b371988 | 1240 | When an address is being verified, the routers are run in &"verify mode"&. This |
168e428f PH |
1241 | does not affect the way the routers work, but it is a state that can be |
1242 | detected. By this means, a router can be skipped or made to behave differently | |
1243 | when verifying. A common example is a configuration in which the first router | |
1244 | sends all messages to a message-scanning program, unless they have been | |
1245 | previously scanned. Thus, the first router accepts all addresses without any | |
9b371988 | 1246 | checking, making it useless for verifying. Normally, the &%no_verify%& option |
168e428f PH |
1247 | would be set for such a router, causing it to be skipped in verify mode. |
1248 | ||
1249 | ||
1250 | ||
1251 | ||
9b371988 PH |
1252 | .section "Running an individual router" "SECTrunindrou" |
1253 | .cindex "router" "running details" | |
1254 | .cindex "preconditions" "checking" | |
1255 | .cindex "router" "result of running" | |
168e428f PH |
1256 | As explained in the example above, a number of preconditions are checked before |
1257 | running a router. If any are not met, the router is skipped, and the address is | |
9b371988 | 1258 | passed to the next router. When all the preconditions on a router &'are'& met, |
168e428f PH |
1259 | the router is run. What happens next depends on the outcome, which is one of |
1260 | the following: | |
1261 | ||
9b371988 PH |
1262 | .ilist |
1263 | &'accept'&: The router accepts the address, and either assigns it to a | |
1264 | transport, or generates one or more &"child"& addresses. Processing the | |
1265 | original address ceases, | |
0a4e3112 | 1266 | .oindex "&%unseen%&" |
9b371988 | 1267 | unless the &%unseen%& option is set on the router. This option |
168e428f | 1268 | can be used to set up multiple deliveries with different routing (for example, |
9b371988 PH |
1269 | for keeping archive copies of messages). When &%unseen%& is set, the address is |
1270 | passed to the next router. Normally, however, an &'accept'& return marks the | |
168e428f | 1271 | end of routing. |
9b371988 | 1272 | |
068aaea8 PH |
1273 | Any child addresses generated by the router are processed independently, |
1274 | starting with the first router by default. It is possible to change this by | |
9b371988 PH |
1275 | setting the &%redirect_router%& option to specify which router to start at for |
1276 | child addresses. Unlike &%pass_router%& (see below) the router specified by | |
1277 | &%redirect_router%& may be anywhere in the router configuration. | |
1278 | .next | |
1279 | &'pass'&: The router recognizes the address, but cannot handle it itself. It | |
168e428f PH |
1280 | requests that the address be passed to another router. By default the address |
1281 | is passed to the next router, but this can be changed by setting the | |
9b371988 | 1282 | &%pass_router%& option. However, (unlike &%redirect_router%&) the named router |
168e428f | 1283 | must be below the current router (to avoid loops). |
9b371988 PH |
1284 | .next |
1285 | &'decline'&: The router declines to accept the address because it does not | |
168e428f | 1286 | recognize it at all. By default, the address is passed to the next router, but |
9b371988 PH |
1287 | this can be prevented by setting the &%no_more%& option. When &%no_more%& is |
1288 | set, all the remaining routers are skipped. In effect, &%no_more%& converts | |
1289 | &'decline'& into &'fail'&. | |
1290 | .next | |
1291 | &'fail'&: The router determines that the address should fail, and queues it for | |
168e428f | 1292 | the generation of a bounce message. There is no further processing of the |
9b371988 PH |
1293 | original address unless &%unseen%& is set on the router. |
1294 | .next | |
1295 | &'defer'&: The router cannot handle the address at the present time. (A | |
068aaea8 PH |
1296 | database may be offline, or a DNS lookup may have timed out.) No further |
1297 | processing of the address happens in this delivery attempt. It is tried again | |
1298 | next time the message is considered for delivery. | |
9b371988 PH |
1299 | .next |
1300 | &'error'&: There is some error in the router (for example, a syntax error in | |
168e428f | 1301 | its configuration). The action is as for defer. |
9b371988 | 1302 | .endlist |
168e428f PH |
1303 | |
1304 | If an address reaches the end of the routers without having been accepted by | |
068aaea8 | 1305 | any of them, it is bounced as unrouteable. The default error message in this |
9b371988 PH |
1306 | situation is &"unrouteable address"&, but you can set your own message by |
1307 | making use of the &%cannot_route_message%& option. This can be set for any | |
1308 | router; the value from the last router that &"saw"& the address is used. | |
168e428f PH |
1309 | |
1310 | Sometimes while routing you want to fail a delivery when some conditions are | |
1311 | met but others are not, instead of passing the address on for further routing. | |
1312 | You can do this by having a second router that explicitly fails the delivery | |
9b371988 | 1313 | when the relevant conditions are met. The &(redirect)& router has a &"fail"& |
168e428f PH |
1314 | facility for this purpose. |
1315 | ||
1316 | ||
f89d2485 | 1317 | .section "Duplicate addresses" "SECID17" |
9b371988 | 1318 | .cindex "case of local parts" |
f89d2485 | 1319 | .cindex "address duplicate, discarding" |
db9452a9 | 1320 | .cindex "duplicate addresses" |
068aaea8 PH |
1321 | Once routing is complete, Exim scans the addresses that are assigned to local |
1322 | and remote transports, and discards any duplicates that it finds. During this | |
3cb1b51e | 1323 | check, local parts are treated as case-sensitive. This happens only when |
db9452a9 | 1324 | actually delivering a message; when testing routers with &%-bt%&, all the |
3cb1b51e | 1325 | routed addresses are shown. |
db9452a9 | 1326 | |
068aaea8 | 1327 | |
168e428f | 1328 | |
9b371988 | 1329 | .section "Router preconditions" "SECTrouprecon" |
f89d2485 | 1330 | .cindex "router" "preconditions, order of processing" |
9b371988 | 1331 | .cindex "preconditions" "order of processing" |
168e428f PH |
1332 | The preconditions that are tested for each router are listed below, in the |
1333 | order in which they are tested. The individual configuration options are | |
9b371988 | 1334 | described in more detail in chapter &<<CHAProutergeneric>>&. |
168e428f | 1335 | |
9b371988 PH |
1336 | .ilist |
1337 | The &%local_part_prefix%& and &%local_part_suffix%& options can specify that | |
168e428f PH |
1338 | the local parts handled by the router may or must have certain prefixes and/or |
1339 | suffixes. If a mandatory affix (prefix or suffix) is not present, the router is | |
1340 | skipped. These conditions are tested first. When an affix is present, it is | |
1341 | removed from the local part before further processing, including the evaluation | |
1342 | of any other conditions. | |
9b371988 PH |
1343 | .next |
1344 | Routers can be designated for use only when not verifying an address, that is, | |
168e428f | 1345 | only when routing it for delivery (or testing its delivery routing). If the |
9b371988 | 1346 | &%verify%& option is set false, the router is skipped when Exim is verifying an |
168e428f | 1347 | address. |
9b371988 PH |
1348 | Setting the &%verify%& option actually sets two options, &%verify_sender%& and |
1349 | &%verify_recipient%&, which independently control the use of the router for | |
168e428f PH |
1350 | sender and recipient verification. You can set these options directly if |
1351 | you want a router to be used for only one type of verification. | |
9b371988 PH |
1352 | .next |
1353 | If the &%address_test%& option is set false, the router is skipped when Exim is | |
1354 | run with the &%-bt%& option to test an address routing. This can be helpful | |
1355 | when the first router sends all new messages to a scanner of some sort; it | |
1356 | makes it possible to use &%-bt%& to test subsequent delivery routing without | |
1357 | having to simulate the effect of the scanner. | |
1358 | .next | |
1359 | Routers can be designated for use only when verifying an address, as | |
1360 | opposed to routing it for delivery. The &%verify_only%& option controls this. | |
1361 | .next | |
1362 | Individual routers can be explicitly skipped when running the routers to | |
1363 | check an address given in the SMTP EXPN command (see the &%expn%& option). | |
1364 | .next | |
1365 | If the &%domains%& option is set, the domain of the address must be in the set | |
068aaea8 | 1366 | of domains that it defines. |
9b371988 | 1367 | .next |
f89d2485 PH |
1368 | .vindex "&$local_part_prefix$&" |
1369 | .vindex "&$local_part$&" | |
1370 | .vindex "&$local_part_suffix$&" | |
9b371988 PH |
1371 | If the &%local_parts%& option is set, the local part of the address must be in |
1372 | the set of local parts that it defines. If &%local_part_prefix%& or | |
1373 | &%local_part_suffix%& is in use, the prefix or suffix is removed from the local | |
168e428f | 1374 | part before this check. If you want to do precondition tests on local parts |
9b371988 PH |
1375 | that include affixes, you can do so by using a &%condition%& option (see below) |
1376 | that uses the variables &$local_part$&, &$local_part_prefix$&, and | |
1377 | &$local_part_suffix$& as necessary. | |
1378 | .next | |
f89d2485 PH |
1379 | .vindex "&$local_user_uid$&" |
1380 | .vindex "&$local_user_gid$&" | |
1381 | .vindex "&$home$&" | |
9b371988 | 1382 | If the &%check_local_user%& option is set, the local part must be the name of |
068aaea8 | 1383 | an account on the local host. If this check succeeds, the uid and gid of the |
9b371988 PH |
1384 | local user are placed in &$local_user_uid$& and &$local_user_gid$& and the |
1385 | user's home directory is placed in &$home$&; these values can be used in the | |
1386 | remaining preconditions. | |
1387 | .next | |
1388 | If the &%router_home_directory%& option is set, it is expanded at this point, | |
1389 | because it overrides the value of &$home$&. If this expansion were left till | |
1390 | later, the value of &$home$& as set by &%check_local_user%& would be used in | |
1391 | subsequent tests. Having two different values of &$home$& in the same router | |
168e428f | 1392 | could lead to confusion. |
9b371988 PH |
1393 | .next |
1394 | If the &%senders%& option is set, the envelope sender address must be in the | |
1395 | set of addresses that it defines. | |
1396 | .next | |
1397 | If the &%require_files%& option is set, the existence or non-existence of | |
168e428f | 1398 | specified files is tested. |
9b371988 PH |
1399 | .next |
1400 | .cindex "customizing" "precondition" | |
1401 | If the &%condition%& option is set, it is evaluated and tested. This option | |
1402 | uses an expanded string to allow you to set up your own custom preconditions. | |
1403 | Expanded strings are described in chapter &<<CHAPexpand>>&. | |
1404 | .endlist | |
168e428f | 1405 | |
168e428f | 1406 | |
9b371988 PH |
1407 | Note that &%require_files%& comes near the end of the list, so you cannot use |
1408 | it to check for the existence of a file in which to lookup up a domain, local | |
168e428f | 1409 | part, or sender. However, as these options are all expanded, you can use the |
9b371988 PH |
1410 | &%exists%& expansion condition to make such tests within each condition. The |
1411 | &%require_files%& option is intended for checking files that the router may be | |
168e428f | 1412 | going to use internally, or which are needed by a specific transport (for |
9b371988 | 1413 | example, &_.procmailrc_&). |
168e428f PH |
1414 | |
1415 | ||
1416 | ||
f89d2485 | 1417 | .section "Delivery in detail" "SECID18" |
9b371988 | 1418 | .cindex "delivery" "in detail" |
168e428f PH |
1419 | When a message is to be delivered, the sequence of events is as follows: |
1420 | ||
9b371988 PH |
1421 | .ilist |
1422 | If a system-wide filter file is specified, the message is passed to it. The | |
168e428f PH |
1423 | filter may add recipients to the message, replace the recipients, discard the |
1424 | message, cause a new message to be generated, or cause the message delivery to | |
1425 | fail. The format of the system filter file is the same as for Exim user filter | |
9b371988 PH |
1426 | files, described in the separate document entitled &'Exim's interfaces to mail |
1427 | filtering'&. | |
1428 | .cindex "Sieve filter" "not available for system filter" | |
1429 | (&*Note*&: Sieve cannot be used for system filter files.) | |
1430 | ||
1431 | Some additional features are available in system filters &-- see chapter | |
1432 | &<<CHAPsystemfilter>>& for details. Note that a message is passed to the system | |
168e428f PH |
1433 | filter only once per delivery attempt, however many recipients it has. However, |
1434 | if there are several delivery attempts because one or more addresses could not | |
1435 | be immediately delivered, the system filter is run each time. The filter | |
9b371988 | 1436 | condition &%first_delivery%& can be used to detect the first run of the system |
168e428f | 1437 | filter. |
9b371988 PH |
1438 | .next |
1439 | Each recipient address is offered to each configured router in turn, subject to | |
1440 | its preconditions, until one is able to handle it. If no router can handle the | |
1441 | address, that is, if they all decline, the address is failed. Because routers | |
1442 | can be targeted at particular domains, several locally handled domains can be | |
1443 | processed entirely independently of each other. | |
1444 | .next | |
1445 | .cindex "routing" "loops in" | |
1446 | .cindex "loop" "while routing" | |
1447 | A router that accepts an address may assign it to a local or a remote | |
1448 | transport. However, the transport is not run at this time. Instead, the address | |
1449 | is placed on a list for the particular transport, which will be run later. | |
068aaea8 PH |
1450 | Alternatively, the router may generate one or more new addresses (typically |
1451 | from alias, forward, or filter files). New addresses are fed back into this | |
1452 | process from the top, but in order to avoid loops, a router ignores any address | |
1453 | which has an identically-named ancestor that was processed by itself. | |
9b371988 PH |
1454 | .next |
1455 | When all the routing has been done, addresses that have been successfully | |
168e428f PH |
1456 | handled are passed to their assigned transports. When local transports are |
1457 | doing real local deliveries, they handle only one address at a time, but if a | |
1458 | local transport is being used as a pseudo-remote transport (for example, to | |
1459 | collect batched SMTP messages for transmission by some other means) multiple | |
1460 | addresses can be handled. Remote transports can always handle more than one | |
1461 | address at a time, but can be configured not to do so, or to restrict multiple | |
1462 | addresses to the same domain. | |
9b371988 PH |
1463 | .next |
1464 | Each local delivery to a file or a pipe runs in a separate process under a | |
168e428f PH |
1465 | non-privileged uid, and these deliveries are run one at a time. Remote |
1466 | deliveries also run in separate processes, normally under a uid that is private | |
9b371988 | 1467 | to Exim (&"the Exim user"&), but in this case, several remote deliveries can be |
168e428f | 1468 | run in parallel. The maximum number of simultaneous remote deliveries for any |
9b371988 | 1469 | one message is set by the &%remote_max_parallel%& option. |
168e428f PH |
1470 | The order in which deliveries are done is not defined, except that all local |
1471 | deliveries happen before any remote deliveries. | |
9b371988 PH |
1472 | .next |
1473 | .cindex "queue runner" | |
168e428f PH |
1474 | When it encounters a local delivery during a queue run, Exim checks its retry |
1475 | database to see if there has been a previous temporary delivery failure for the | |
1476 | address before running the local transport. If there was a previous failure, | |
1477 | Exim does not attempt a new delivery until the retry time for the address is | |
1478 | reached. However, this happens only for delivery attempts that are part of a | |
1479 | queue run. Local deliveries are always attempted when delivery immediately | |
1480 | follows message reception, even if retry times are set for them. This makes for | |
1481 | better behaviour if one particular message is causing problems (for example, | |
1482 | causing quota overflow, or provoking an error in a filter file). | |
9b371988 PH |
1483 | .next |
1484 | .cindex "delivery" "retry in remote transports" | |
168e428f PH |
1485 | Remote transports do their own retry handling, since an address may be |
1486 | deliverable to one of a number of hosts, each of which may have a different | |
1487 | retry time. If there have been previous temporary failures and no host has | |
1488 | reached its retry time, no delivery is attempted, whether in a queue run or | |
9b371988 PH |
1489 | not. See chapter &<<CHAPretry>>& for details of retry strategies. |
1490 | .next | |
1491 | If there were any permanent errors, a bounce message is returned to an | |
168e428f PH |
1492 | appropriate address (the sender in the common case), with details of the error |
1493 | for each failing address. Exim can be configured to send copies of bounce | |
1494 | messages to other addresses. | |
9b371988 PH |
1495 | .next |
1496 | .cindex "delivery" "deferral" | |
168e428f PH |
1497 | If one or more addresses suffered a temporary failure, the message is left on |
1498 | the queue, to be tried again later. Delivery of these addresses is said to be | |
9b371988 PH |
1499 | &'deferred'&. |
1500 | .next | |
1501 | When all the recipient addresses have either been delivered or bounced, | |
168e428f PH |
1502 | handling of the message is complete. The spool files and message log are |
1503 | deleted, though the message log can optionally be preserved if required. | |
9b371988 | 1504 | .endlist |
168e428f PH |
1505 | |
1506 | ||
1507 | ||
1508 | ||
f89d2485 | 1509 | .section "Retry mechanism" "SECID19" |
9b371988 PH |
1510 | .cindex "delivery" "retry mechanism" |
1511 | .cindex "retry" "description of mechanism" | |
1512 | .cindex "queue runner" | |
168e428f PH |
1513 | Exim's mechanism for retrying messages that fail to get delivered at the first |
1514 | attempt is the queue runner process. You must either run an Exim daemon that | |
9b371988 PH |
1515 | uses the &%-q%& option with a time interval to start queue runners at regular |
1516 | intervals, or use some other means (such as &'cron'&) to start them. If you do | |
168e428f PH |
1517 | not arrange for queue runners to be run, messages that fail temporarily at the |
1518 | first attempt will remain on your queue for ever. A queue runner process works | |
068aaea8 | 1519 | its way through the queue, one message at a time, trying each delivery that has |
168e428f PH |
1520 | passed its retry time. |
1521 | You can run several queue runners at once. | |
1522 | ||
1523 | Exim uses a set of configured rules to determine when next to retry the failing | |
9b371988 PH |
1524 | address (see chapter &<<CHAPretry>>&). These rules also specify when Exim |
1525 | should give up trying to deliver to the address, at which point it generates a | |
1526 | bounce message. If no retry rules are set for a particular host, address, and | |
1527 | error combination, no retries are attempted, and temporary errors are treated | |
1528 | as permanent. | |
168e428f PH |
1529 | |
1530 | ||
1531 | ||
f89d2485 | 1532 | .section "Temporary delivery failure" "SECID20" |
9b371988 | 1533 | .cindex "delivery" "temporary failure" |
168e428f PH |
1534 | There are many reasons why a message may not be immediately deliverable to a |
1535 | particular address. Failure to connect to a remote machine (because it, or the | |
1536 | connection to it, is down) is one of the most common. Temporary failures may be | |
1537 | detected during routing as well as during the transport stage of delivery. | |
1538 | Local deliveries may be delayed if NFS files are unavailable, or if a mailbox | |
1539 | is on a file system where the user is over quota. Exim can be configured to | |
1540 | impose its own quotas on local mailboxes; where system quotas are set they will | |
1541 | also apply. | |
1542 | ||
1543 | If a host is unreachable for a period of time, a number of messages may be | |
1544 | waiting for it by the time it recovers, and sending them in a single SMTP | |
1545 | connection is clearly beneficial. Whenever a delivery to a remote host is | |
1546 | deferred, | |
1547 | ||
9b371988 | 1548 | .cindex "hints database" |
168e428f PH |
1549 | Exim makes a note in its hints database, and whenever a successful |
1550 | SMTP delivery has happened, it looks to see if any other messages are waiting | |
1551 | for the same host. If any are found, they are sent over the same SMTP | |
1552 | connection, subject to a configuration limit as to the maximum number in any | |
1553 | one connection. | |
1554 | ||
1555 | ||
1556 | ||
1557 | ||
f89d2485 | 1558 | .section "Permanent delivery failure" "SECID21" |
9b371988 PH |
1559 | .cindex "delivery" "permanent failure" |
1560 | .cindex "bounce message" "when generated" | |
168e428f PH |
1561 | When a message cannot be delivered to some or all of its intended recipients, a |
1562 | bounce message is generated. Temporary delivery failures turn into permanent | |
1563 | errors when their timeout expires. All the addresses that fail in a given | |
1564 | delivery attempt are listed in a single message. If the original message has | |
1565 | many recipients, it is possible for some addresses to fail in one delivery | |
1566 | attempt and others to fail subsequently, giving rise to more than one bounce | |
1567 | message. The wording of bounce messages can be customized by the administrator. | |
9b371988 | 1568 | See chapter &<<CHAPemsgcust>>& for details. |
168e428f | 1569 | |
9b371988 PH |
1570 | .cindex "&'X-Failed-Recipients:'& header line" |
1571 | Bounce messages contain an &'X-Failed-Recipients:'& header line that lists the | |
168e428f PH |
1572 | failed addresses, for the benefit of programs that try to analyse such messages |
1573 | automatically. | |
1574 | ||
9b371988 | 1575 | .cindex "bounce message" "recipient of" |
168e428f PH |
1576 | A bounce message is normally sent to the sender of the original message, as |
1577 | obtained from the message's envelope. For incoming SMTP messages, this is the | |
9b371988 PH |
1578 | address given in the MAIL command. However, when an address is expanded via a |
1579 | forward or alias file, an alternative address can be specified for delivery | |
1580 | failures of the generated addresses. For a mailing list expansion (see section | |
1581 | &<<SECTmailinglists>>&) it is common to direct bounce messages to the manager | |
1582 | of the list. | |
168e428f PH |
1583 | |
1584 | ||
1585 | ||
f89d2485 | 1586 | .section "Failures to deliver bounce messages" "SECID22" |
9b371988 | 1587 | .cindex "bounce message" "failure to deliver" |
168e428f PH |
1588 | If a bounce message (either locally generated or received from a remote host) |
1589 | itself suffers a permanent delivery failure, the message is left on the queue, | |
1590 | but it is frozen, awaiting the attention of an administrator. There are options | |
068aaea8 | 1591 | that can be used to make Exim discard such failed messages, or to keep them |
9b371988 PH |
1592 | for only a short time (see &%timeout_frozen_after%& and |
1593 | &%ignore_bounce_errors_after%&). | |
168e428f PH |
1594 | |
1595 | ||
1596 | ||
1597 | ||
1598 | ||
9b371988 PH |
1599 | . //////////////////////////////////////////////////////////////////////////// |
1600 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 1601 | |
f89d2485 | 1602 | .chapter "Building and installing Exim" "CHID3" |
4f578862 | 1603 | .scindex IIDbuex "building Exim" |
168e428f | 1604 | |
f89d2485 PH |
1605 | .section "Unpacking" "SECID23" |
1606 | Exim is distributed as a gzipped or bzipped tar file which, when unpacked, | |
168e428f | 1607 | creates a directory with the name of the current release (for example, |
9b371988 PH |
1608 | &_exim-&version;_&) into which the following files are placed: |
1609 | ||
1610 | .table2 140pt | |
f89d2485 PH |
1611 | .irow &_ACKNOWLEDGMENTS_& "contains some acknowledgments" |
1612 | .irow &_CHANGES_& "contains a reference to where changes are &&& | |
1613 | documented" | |
1614 | .irow &_LICENCE_& "the GNU General Public Licence" | |
1615 | .irow &_Makefile_& "top-level make file" | |
1616 | .irow &_NOTICE_& "conditions for the use of Exim" | |
1617 | .irow &_README_& "list of files, directories and simple build &&& | |
1618 | instructions" | |
9b371988 PH |
1619 | .endtable |
1620 | ||
1621 | Other files whose names begin with &_README_& may also be present. The | |
168e428f PH |
1622 | following subdirectories are created: |
1623 | ||
9b371988 | 1624 | .table2 140pt |
f89d2485 PH |
1625 | .irow &_Local_& "an empty directory for local configuration files" |
1626 | .irow &_OS_& "OS-specific files" | |
1627 | .irow &_doc_& "documentation files" | |
1628 | .irow &_exim_monitor_& "source files for the Exim monitor" | |
1629 | .irow &_scripts_& "scripts used in the build process" | |
1630 | .irow &_src_& "remaining source files" | |
1631 | .irow &_util_& "independent utilities" | |
9b371988 PH |
1632 | .endtable |
1633 | ||
1634 | The main utility programs are contained in the &_src_& directory, and are built | |
1635 | with the Exim binary. The &_util_& directory contains a few optional scripts | |
168e428f PH |
1636 | that may be useful to some sites. |
1637 | ||
1638 | ||
f89d2485 | 1639 | .section "Multiple machine architectures and operating systems" "SECID24" |
9b371988 | 1640 | .cindex "building Exim" "multiple OS/architectures" |
168e428f PH |
1641 | The building process for Exim is arranged to make it easy to build binaries for |
1642 | a number of different architectures and operating systems from the same set of | |
9b371988 PH |
1643 | source files. Compilation does not take place in the &_src_& directory. |
1644 | Instead, a &'build directory'& is created for each architecture and operating | |
1645 | system. | |
1646 | .cindex "symbolic link" "to build directory" | |
168e428f | 1647 | Symbolic links to the sources are installed in this directory, which is where |
9b371988 PH |
1648 | the actual building takes place. In most cases, Exim can discover the machine |
1649 | architecture and operating system for itself, but the defaults can be | |
1650 | overridden if necessary. | |
168e428f | 1651 | |
168e428f | 1652 | |
8473d4ee | 1653 | .section "PCRE library" "SECTpcre" |
210f147e NM |
1654 | .cindex "PCRE library" |
1655 | Exim no longer has an embedded PCRE library as the vast majority of | |
1656 | modern systems include PCRE as a system library, although you may need | |
1657 | to install the PCRE or PCRE development package for your operating | |
1658 | system. If your system has a normal PCRE installation the Exim build | |
1659 | process will need no further configuration. If the library or the | |
1660 | headers are in an unusual location you will need to set the PCRE_LIBS | |
1661 | and INCLUDE directives appropriately. If your operating system has no | |
1662 | PCRE support then you will need to obtain and build the current PCRE | |
1663 | from &url(ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/). | |
1664 | ||
9b371988 PH |
1665 | .section "DBM libraries" "SECTdb" |
1666 | .cindex "DBM libraries" "discussion of" | |
1667 | .cindex "hints database" "DBM files used for" | |
168e428f PH |
1668 | Even if you do not use any DBM files in your configuration, Exim still needs a |
1669 | DBM library in order to operate, because it uses indexed files for its hints | |
1670 | databases. Unfortunately, there are a number of DBM libraries in existence, and | |
1671 | different operating systems often have different ones installed. | |
1672 | ||
9b371988 | 1673 | .cindex "Solaris" "DBM library for" |
f89d2485 PH |
1674 | .cindex "IRIX, DBM library for" |
1675 | .cindex "BSD, DBM library for" | |
1676 | .cindex "Linux, DBM library for" | |
168e428f PH |
1677 | If you are using Solaris, IRIX, one of the modern BSD systems, or a modern |
1678 | Linux distribution, the DBM configuration should happen automatically, and you | |
1679 | may be able to ignore this section. Otherwise, you may have to learn more than | |
1680 | you would like about DBM libraries from what follows. | |
1681 | ||
9b371988 | 1682 | .cindex "&'ndbm'& DBM library" |
168e428f | 1683 | Licensed versions of Unix normally contain a library of DBM functions operating |
9b371988 | 1684 | via the &'ndbm'& interface, and this is what Exim expects by default. Free |
168e428f PH |
1685 | versions of Unix seem to vary in what they contain as standard. In particular, |
1686 | some early versions of Linux have no default DBM library, and different | |
1687 | distributors have chosen to bundle different libraries with their packaged | |
f89d2485 | 1688 | versions. However, the more recent releases seem to have standardized on the |
168e428f PH |
1689 | Berkeley DB library. |
1690 | ||
1691 | Different DBM libraries have different conventions for naming the files they | |
9b371988 | 1692 | use. When a program opens a file called &_dbmfile_&, there are several |
168e428f PH |
1693 | possibilities: |
1694 | ||
9b371988 PH |
1695 | .olist |
1696 | A traditional &'ndbm'& implementation, such as that supplied as part of | |
1697 | Solaris, operates on two files called &_dbmfile.dir_& and &_dbmfile.pag_&. | |
1698 | .next | |
1699 | .cindex "&'gdbm'& DBM library" | |
1700 | The GNU library, &'gdbm'&, operates on a single file. If used via its &'ndbm'& | |
168e428f | 1701 | compatibility interface it makes two different hard links to it with names |
9b371988 | 1702 | &_dbmfile.dir_& and &_dbmfile.pag_&, but if used via its native interface, the |
168e428f | 1703 | file name is used unmodified. |
9b371988 PH |
1704 | .next |
1705 | .cindex "Berkeley DB library" | |
1706 | The Berkeley DB package, if called via its &'ndbm'& compatibility interface, | |
1707 | operates on a single file called &_dbmfile.db_&, but otherwise looks to the | |
1708 | programmer exactly the same as the traditional &'ndbm'& implementation. | |
1709 | .next | |
1710 | If the Berkeley package is used in its native mode, it operates on a single | |
1711 | file called &_dbmfile_&; the programmer's interface is somewhat different to | |
1712 | the traditional &'ndbm'& interface. | |
1713 | .next | |
1714 | To complicate things further, there are several very different versions of the | |
168e428f | 1715 | Berkeley DB package. Version 1.85 was stable for a very long time, releases |
9b371988 PH |
1716 | 2.&'x'& and 3.&'x'& were current for a while, but the latest versions are now |
1717 | numbered 4.&'x'&. Maintenance of some of the earlier releases has ceased. All | |
168e428f | 1718 | versions of Berkeley DB can be obtained from |
9b371988 PH |
1719 | &url(http://www.sleepycat.com/). |
1720 | .next | |
1721 | .cindex "&'tdb'& DBM library" | |
1722 | Yet another DBM library, called &'tdb'&, is available from | |
1723 | &url(http://download.sourceforge.net/tdb). It has its own interface, and also | |
1724 | operates on a single file. | |
1725 | .endlist | |
1726 | ||
1727 | .cindex "USE_DB" | |
1728 | .cindex "DBM libraries" "configuration for building" | |
168e428f PH |
1729 | Exim and its utilities can be compiled to use any of these interfaces. In order |
1730 | to use any version of the Berkeley DB package in native mode, you must set | |
1731 | USE_DB in an appropriate configuration file (typically | |
9b371988 PH |
1732 | &_Local/Makefile_&). For example: |
1733 | .code | |
1734 | USE_DB=yes | |
1735 | .endd | |
168e428f PH |
1736 | Similarly, for gdbm you set USE_GDBM, and for tdb you set USE_TDB. An |
1737 | error is diagnosed if you set more than one of these. | |
1738 | ||
1739 | At the lowest level, the build-time configuration sets none of these options, | |
1740 | thereby assuming an interface of type (1). However, some operating system | |
1741 | configuration files (for example, those for the BSD operating systems and | |
1742 | Linux) assume type (4) by setting USE_DB as their default, and the | |
1743 | configuration files for Cygwin set USE_GDBM. Anything you set in | |
9b371988 | 1744 | &_Local/Makefile_&, however, overrides these system defaults. |
168e428f PH |
1745 | |
1746 | As well as setting USE_DB, USE_GDBM, or USE_TDB, it may also be | |
1747 | necessary to set DBMLIB, to cause inclusion of the appropriate library, as | |
1748 | in one of these lines: | |
9b371988 PH |
1749 | .code |
1750 | DBMLIB = -ldb | |
1751 | DBMLIB = -ltdb | |
1752 | .endd | |
168e428f PH |
1753 | Settings like that will work if the DBM library is installed in the standard |
1754 | place. Sometimes it is not, and the library's header file may also not be in | |
1755 | the default path. You may need to set INCLUDE to specify where the header | |
1756 | file is, and to specify the path to the library more fully in DBMLIB, as in | |
1757 | this example: | |
9b371988 PH |
1758 | .code |
1759 | INCLUDE=-I/usr/local/include/db-4.1 | |
1760 | DBMLIB=/usr/local/lib/db-4.1/libdb.a | |
1761 | .endd | |
168e428f | 1762 | There is further detailed discussion about the various DBM libraries in the |
9b371988 | 1763 | file &_doc/dbm.discuss.txt_& in the Exim distribution. |
168e428f PH |
1764 | |
1765 | ||
1766 | ||
f89d2485 | 1767 | .section "Pre-building configuration" "SECID25" |
9b371988 PH |
1768 | .cindex "building Exim" "pre-building configuration" |
1769 | .cindex "configuration for building Exim" | |
1770 | .cindex "&_Local/Makefile_&" | |
1771 | .cindex "&_src/EDITME_&" | |
168e428f PH |
1772 | Before building Exim, a local configuration file that specifies options |
1773 | independent of any operating system has to be created with the name | |
9b371988 PH |
1774 | &_Local/Makefile_&. A template for this file is supplied as the file |
1775 | &_src/EDITME_&, and it contains full descriptions of all the option settings | |
168e428f PH |
1776 | therein. These descriptions are therefore not repeated here. If you are |
1777 | building Exim for the first time, the simplest thing to do is to copy | |
9b371988 | 1778 | &_src/EDITME_& to &_Local/Makefile_&, then read it and edit it appropriately. |
168e428f PH |
1779 | |
1780 | There are three settings that you must supply, because Exim will not build | |
1781 | without them. They are the location of the run time configuration file | |
1782 | (CONFIGURE_FILE), the directory in which Exim binaries will be installed | |
1783 | (BIN_DIRECTORY), and the identity of the Exim user (EXIM_USER and | |
1784 | maybe EXIM_GROUP as well). The value of CONFIGURE_FILE can in fact be | |
1785 | a colon-separated list of file names; Exim uses the first of them that exists. | |
1786 | ||
1787 | There are a few other parameters that can be specified either at build time or | |
1788 | at run time, to enable the same binary to be used on a number of different | |
1789 | machines. However, if the locations of Exim's spool directory and log file | |
1790 | directory (if not within the spool directory) are fixed, it is recommended that | |
9b371988 | 1791 | you specify them in &_Local/Makefile_& instead of at run time, so that errors |
168e428f PH |
1792 | detected early in Exim's execution (such as a malformed configuration file) can |
1793 | be logged. | |
1794 | ||
9b371988 | 1795 | .cindex "content scanning" "specifying at build time" |
068aaea8 | 1796 | Exim's interfaces for calling virus and spam scanning software directly from |
168e428f PH |
1797 | access control lists are not compiled by default. If you want to include these |
1798 | facilities, you need to set | |
9b371988 PH |
1799 | .code |
1800 | WITH_CONTENT_SCAN=yes | |
1801 | .endd | |
1802 | in your &_Local/Makefile_&. For details of the facilities themselves, see | |
1803 | chapter &<<CHAPexiscan>>&. | |
168e428f PH |
1804 | |
1805 | ||
9b371988 | 1806 | .cindex "&_Local/eximon.conf_&" |
3cb1b51e | 1807 | .cindex "&_exim_monitor/EDITME_&" |
168e428f | 1808 | If you are going to build the Exim monitor, a similar configuration process is |
9b371988 PH |
1809 | required. The file &_exim_monitor/EDITME_& must be edited appropriately for |
1810 | your installation and saved under the name &_Local/eximon.conf_&. If you are | |
1811 | happy with the default settings described in &_exim_monitor/EDITME_&, | |
1812 | &_Local/eximon.conf_& can be empty, but it must exist. | |
168e428f PH |
1813 | |
1814 | This is all the configuration that is needed in straightforward cases for known | |
1815 | operating systems. However, the building process is set up so that it is easy | |
1816 | to override options that are set by default or by operating-system-specific | |
1817 | configuration files, for example to change the name of the C compiler, which | |
9b371988 PH |
1818 | defaults to &%gcc%&. See section &<<SECToverride>>& below for details of how to |
1819 | do this. | |
168e428f PH |
1820 | |
1821 | ||
1822 | ||
f89d2485 | 1823 | .section "Support for iconv()" "SECID26" |
9b371988 PH |
1824 | .cindex "&[iconv()]& support" |
1825 | .cindex "RFC 2047" | |
168e428f PH |
1826 | The contents of header lines in messages may be encoded according to the rules |
1827 | described RFC 2047. This makes it possible to transmit characters that are not | |
1828 | in the ASCII character set, and to label them as being in a particular | |
9b371988 | 1829 | character set. When Exim is inspecting header lines by means of the &%$h_%& |
168e428f PH |
1830 | mechanism, it decodes them, and translates them into a specified character set |
1831 | (default ISO-8859-1). The translation is possible only if the operating system | |
9b371988 PH |
1832 | supports the &[iconv()]& function. |
1833 | ||
1834 | However, some of the operating systems that supply &[iconv()]& do not support | |
1835 | very many conversions. The GNU &%libiconv%& library (available from | |
1836 | &url(http://www.gnu.org/software/libiconv/)) can be installed on such | |
1837 | systems to remedy this deficiency, as well as on systems that do not supply | |
1838 | &[iconv()]& at all. After installing &%libiconv%&, you should add | |
1839 | .code | |
1840 | HAVE_ICONV=yes | |
1841 | .endd | |
1842 | to your &_Local/Makefile_& and rebuild Exim. | |
1843 | ||
1844 | ||
1845 | ||
1846 | .section "Including TLS/SSL encryption support" "SECTinctlsssl" | |
1847 | .cindex "TLS" "including support for TLS" | |
1848 | .cindex "encryption" "including support for" | |
1849 | .cindex "SUPPORT_TLS" | |
1850 | .cindex "OpenSSL" "building Exim with" | |
1851 | .cindex "GnuTLS" "building Exim with" | |
168e428f PH |
1852 | Exim can be built to support encrypted SMTP connections, using the STARTTLS |
1853 | command as per RFC 2487. It can also support legacy clients that expect to | |
1854 | start a TLS session immediately on connection to a non-standard port (see the | |
9b371988 | 1855 | &%tls_on_connect_ports%& runtime option and the &%-tls-on-connect%& command |
168e428f PH |
1856 | line option). |
1857 | ||
1858 | If you want to build Exim with TLS support, you must first install either the | |
1859 | OpenSSL or GnuTLS library. There is no cryptographic code in Exim itself for | |
1860 | implementing SSL. | |
1861 | ||
1862 | If OpenSSL is installed, you should set | |
9b371988 PH |
1863 | .code |
1864 | SUPPORT_TLS=yes | |
1865 | TLS_LIBS=-lssl -lcrypto | |
1866 | .endd | |
1867 | in &_Local/Makefile_&. You may also need to specify the locations of the | |
168e428f | 1868 | OpenSSL library and include files. For example: |
9b371988 PH |
1869 | .code |
1870 | SUPPORT_TLS=yes | |
1871 | TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto | |
1872 | TLS_INCLUDE=-I/usr/local/openssl/include/ | |
1873 | .endd | |
1874 | .cindex "USE_GNUTLS" | |
168e428f | 1875 | If GnuTLS is installed, you should set |
9b371988 PH |
1876 | .code |
1877 | SUPPORT_TLS=yes | |
1878 | USE_GNUTLS=yes | |
1879 | TLS_LIBS=-lgnutls -ltasn1 -lgcrypt | |
1880 | .endd | |
1881 | in &_Local/Makefile_&, and again you may need to specify the locations of the | |
168e428f | 1882 | library and include files. For example: |
9b371988 PH |
1883 | .code |
1884 | SUPPORT_TLS=yes | |
1885 | USE_GNUTLS=yes | |
1886 | TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt | |
1887 | TLS_INCLUDE=-I/usr/gnu/include | |
1888 | .endd | |
168e428f | 1889 | You do not need to set TLS_INCLUDE if the relevant directory is already |
9b371988 PH |
1890 | specified in INCLUDE. Details of how to configure Exim to make use of TLS are |
1891 | given in chapter &<<CHAPTLS>>&. | |
168e428f PH |
1892 | |
1893 | ||
1894 | ||
1895 | ||
f89d2485 PH |
1896 | .section "Use of tcpwrappers" "SECID27" |
1897 | .cindex "tcpwrappers, building Exim to support" | |
9b371988 PH |
1898 | .cindex "USE_TCP_WRAPPERS" |
1899 | Exim can be linked with the &'tcpwrappers'& library in order to check incoming | |
1900 | SMTP calls using the &'tcpwrappers'& control files. This may be a convenient | |
168e428f | 1901 | alternative to Exim's own checking facilities for installations that are |
9b371988 PH |
1902 | already making use of &'tcpwrappers'& for other purposes. To do this, you |
1903 | should set USE_TCP_WRAPPERS in &_Local/Makefile_&, arrange for the file | |
1904 | &_tcpd.h_& to be available at compile time, and also ensure that the library | |
1905 | &_libwrap.a_& is available at link time, typically by including &%-lwrap%& in | |
1906 | EXTRALIBS_EXIM. For example, if &'tcpwrappers'& is installed in &_/usr/local_&, | |
1907 | you might have | |
1908 | .code | |
1909 | USE_TCP_WRAPPERS=yes | |
1910 | CFLAGS=-O -I/usr/local/include | |
1911 | EXTRALIBS_EXIM=-L/usr/local/lib -lwrap | |
1912 | .endd | |
1913 | in &_Local/Makefile_&. The name to use in the &'tcpwrappers'& control files is | |
1914 | &"exim"&. For example, the line | |
1915 | .code | |
1916 | exim : LOCAL 192.168.1. .friendly.domain.example | |
1917 | .endd | |
1918 | in your &_/etc/hosts.allow_& file allows connections from the local host, from | |
1919 | the subnet 192.168.1.0/24, and from all hosts in &'friendly.domain.example'&. | |
1920 | All other connections are denied. Consult the &'tcpwrappers'& documentation for | |
168e428f PH |
1921 | further details. |
1922 | ||
1923 | ||
1924 | ||
f89d2485 | 1925 | .section "Including support for IPv6" "SECID28" |
9b371988 | 1926 | .cindex "IPv6" "including support for" |
168e428f | 1927 | Exim contains code for use on systems that have IPv6 support. Setting |
9b371988 | 1928 | &`HAVE_IPV6=YES`& in &_Local/Makefile_& causes the IPv6 code to be included; |
168e428f PH |
1929 | it may also be necessary to set IPV6_INCLUDE and IPV6_LIBS on systems |
1930 | where the IPv6 support is not fully integrated into the normal include and | |
1931 | library files. | |
1932 | ||
1933 | Two different types of DNS record for handling IPv6 addresses have been | |
f89d2485 | 1934 | defined. AAAA records (analogous to A records for IPv4) are in use, and are |
168e428f PH |
1935 | currently seen as the mainstream. Another record type called A6 was proposed |
1936 | as better than AAAA because it had more flexibility. However, it was felt to be | |
9b371988 | 1937 | over-complex, and its status was reduced to &"experimental"&. It is not known |
168e428f | 1938 | if anyone is actually using A6 records. Exim has support for A6 records, but |
9b371988 | 1939 | this is included only if you set &`SUPPORT_A6=YES`& in &_Local/Makefile_&. The |
168e428f PH |
1940 | support has not been tested for some time. |
1941 | ||
1942 | ||
1943 | ||
f89d2485 | 1944 | .section "The building process" "SECID29" |
9b371988 PH |
1945 | .cindex "build directory" |
1946 | Once &_Local/Makefile_& (and &_Local/eximon.conf_&, if required) have been | |
1947 | created, run &'make'& at the top level. It determines the architecture and | |
168e428f PH |
1948 | operating system types, and creates a build directory if one does not exist. |
1949 | For example, on a Sun system running Solaris 8, the directory | |
9b371988 PH |
1950 | &_build-SunOS5-5.8-sparc_& is created. |
1951 | .cindex "symbolic link" "to source files" | |
168e428f PH |
1952 | Symbolic links to relevant source files are installed in the build directory. |
1953 | ||
9b371988 | 1954 | &*Warning*&: The &%-j%& (parallel) flag must not be used with &'make'&; the |
168e428f PH |
1955 | building process fails if it is set. |
1956 | ||
9b371988 | 1957 | If this is the first time &'make'& has been run, it calls a script that builds |
168e428f | 1958 | a make file inside the build directory, using the configuration files from the |
9b371988 PH |
1959 | &_Local_& directory. The new make file is then passed to another instance of |
1960 | &'make'&. This does the real work, building a number of utility scripts, and | |
168e428f | 1961 | then compiling and linking the binaries for the Exim monitor (if configured), a |
9b371988 PH |
1962 | number of utility programs, and finally Exim itself. The command &`make |
1963 | makefile`& can be used to force a rebuild of the make file in the build | |
168e428f PH |
1964 | directory, should this ever be necessary. |
1965 | ||
1966 | If you have problems building Exim, check for any comments there may be in the | |
9b371988 | 1967 | &_README_& file concerning your operating system, and also take a look at the |
168e428f PH |
1968 | FAQ, where some common problems are covered. |
1969 | ||
1970 | ||
1971 | ||
f89d2485 | 1972 | .section 'Output from &"make"&' "SECID283" |
9b371988 | 1973 | The output produced by the &'make'& process for compile lines is often very |
068aaea8 PH |
1974 | unreadable, because these lines can be very long. For this reason, the normal |
1975 | output is suppressed by default, and instead output similar to that which | |
1976 | appears when compiling the 2.6 Linux kernel is generated: just a short line for | |
1977 | each module that is being compiled or linked. However, it is still possible to | |
9b371988 PH |
1978 | get the full output, by calling &'make'& like this: |
1979 | .code | |
1980 | FULLECHO='' make -e | |
1981 | .endd | |
1982 | The value of FULLECHO defaults to &"@"&, the flag character that suppresses | |
1983 | command reflection in &'make'&. When you ask for the full output, it is | |
3cb1b51e | 1984 | given in addition to the short output. |
068aaea8 PH |
1985 | |
1986 | ||
1987 | ||
9b371988 | 1988 | .section "Overriding build-time options for Exim" "SECToverride" |
f89d2485 | 1989 | .cindex "build-time options, overriding" |
168e428f PH |
1990 | The main make file that is created at the beginning of the building process |
1991 | consists of the concatenation of a number of files which set configuration | |
9b371988 | 1992 | values, followed by a fixed set of &'make'& instructions. If a value is set |
168e428f PH |
1993 | more than once, the last setting overrides any previous ones. This provides a |
1994 | convenient way of overriding defaults. The files that are concatenated are, in | |
1995 | order: | |
9b371988 PH |
1996 | .display |
1997 | &_OS/Makefile-Default_& | |
1998 | &_OS/Makefile-_&<&'ostype'&> | |
1999 | &_Local/Makefile_& | |
2000 | &_Local/Makefile-_&<&'ostype'&> | |
2001 | &_Local/Makefile-_&<&'archtype'&> | |
2002 | &_Local/Makefile-_&<&'ostype'&>-<&'archtype'&> | |
2003 | &_OS/Makefile-Base_& | |
2004 | .endd | |
2005 | .cindex "&_Local/Makefile_&" | |
2006 | .cindex "building Exim" "operating system type" | |
2007 | .cindex "building Exim" "architecture type" | |
2008 | where <&'ostype'&> is the operating system type and <&'archtype'&> is the | |
2009 | architecture type. &_Local/Makefile_& is required to exist, and the building | |
2010 | process fails if it is absent. The other three &_Local_& files are optional, | |
168e428f PH |
2011 | and are often not needed. |
2012 | ||
9b371988 PH |
2013 | The values used for <&'ostype'&> and <&'archtype'&> are obtained from scripts |
2014 | called &_scripts/os-type_& and &_scripts/arch-type_& respectively. If either of | |
168e428f PH |
2015 | the environment variables EXIM_OSTYPE or EXIM_ARCHTYPE is set, their |
2016 | values are used, thereby providing a means of forcing particular settings. | |
9b371988 | 2017 | Otherwise, the scripts try to get values from the &%uname%& command. If this |
168e428f | 2018 | fails, the shell variables OSTYPE and ARCHTYPE are inspected. A number |
9b371988 | 2019 | of &'ad hoc'& transformations are then applied, to produce the standard names |
168e428f PH |
2020 | that Exim expects. You can run these scripts directly from the shell in order |
2021 | to find out what values are being used on your system. | |
2022 | ||
2023 | ||
9b371988 | 2024 | &_OS/Makefile-Default_& contains comments about the variables that are set |
168e428f PH |
2025 | therein. Some (but not all) are mentioned below. If there is something that |
2026 | needs changing, review the contents of this file and the contents of the make | |
9b371988 | 2027 | file for your operating system (&_OS/Makefile-<ostype>_&) to see what the |
168e428f PH |
2028 | default values are. |
2029 | ||
2030 | ||
9b371988 PH |
2031 | .cindex "building Exim" "overriding default settings" |
2032 | If you need to change any of the values that are set in &_OS/Makefile-Default_& | |
2033 | or in &_OS/Makefile-<ostype>_&, or to add any new definitions, you do not | |
168e428f | 2034 | need to change the original files. Instead, you should make the changes by |
9b371988 PH |
2035 | putting the new values in an appropriate &_Local_& file. For example, |
2036 | .cindex "Tru64-Unix build-time settings" | |
168e428f PH |
2037 | when building Exim in many releases of the Tru64-Unix (formerly Digital UNIX, |
2038 | formerly DEC-OSF1) operating system, it is necessary to specify that the C | |
9b371988 PH |
2039 | compiler is called &'cc'& rather than &'gcc'&. Also, the compiler must be |
2040 | called with the option &%-std1%&, to make it recognize some of the features of | |
168e428f | 2041 | Standard C that Exim uses. (Most other compilers recognize Standard C by |
9b371988 | 2042 | default.) To do this, you should create a file called &_Local/Makefile-OSF1_& |
168e428f | 2043 | containing the lines |
9b371988 PH |
2044 | .code |
2045 | CC=cc | |
2046 | CFLAGS=-std1 | |
2047 | .endd | |
168e428f | 2048 | If you are compiling for just one operating system, it may be easier to put |
9b371988 | 2049 | these lines directly into &_Local/Makefile_&. |
168e428f PH |
2050 | |
2051 | Keeping all your local configuration settings separate from the distributed | |
2052 | files makes it easy to transfer them to new versions of Exim simply by copying | |
9b371988 | 2053 | the contents of the &_Local_& directory. |
168e428f PH |
2054 | |
2055 | ||
9b371988 PH |
2056 | .cindex "NIS lookup type" "including support for" |
2057 | .cindex "NIS+ lookup type" "including support for" | |
2058 | .cindex "LDAP" "including support for" | |
2059 | .cindex "lookup" "inclusion in binary" | |
168e428f PH |
2060 | Exim contains support for doing LDAP, NIS, NIS+, and other kinds of file |
2061 | lookup, but not all systems have these components installed, so the default is | |
2062 | not to include the relevant code in the binary. All the different kinds of file | |
2063 | and database lookup that Exim supports are implemented as separate code modules | |
2064 | which are included only if the relevant compile-time options are set. In the | |
9b371988 PH |
2065 | case of LDAP, NIS, and NIS+, the settings for &_Local/Makefile_& are: |
2066 | .code | |
2067 | LOOKUP_LDAP=yes | |
2068 | LOOKUP_NIS=yes | |
2069 | LOOKUP_NISPLUS=yes | |
2070 | .endd | |
168e428f | 2071 | and similar settings apply to the other lookup types. They are all listed in |
9b371988 | 2072 | &_src/EDITME_&. In many cases the relevant include files and interface |
168e428f | 2073 | libraries need to be installed before compiling Exim. |
9b371988 | 2074 | .cindex "cdb" "including support for" |
068aaea8 PH |
2075 | However, there are some optional lookup types (such as cdb) for which |
2076 | the code is entirely contained within Exim, and no external include | |
168e428f PH |
2077 | files or libraries are required. When a lookup type is not included in the |
2078 | binary, attempts to configure Exim to use it cause run time configuration | |
2079 | errors. | |
2080 | ||
9b371988 | 2081 | .cindex "Perl" "including support for" |
168e428f PH |
2082 | Exim can be linked with an embedded Perl interpreter, allowing Perl |
2083 | subroutines to be called during string expansion. To enable this facility, | |
9b371988 PH |
2084 | .code |
2085 | EXIM_PERL=perl.o | |
2086 | .endd | |
2087 | must be defined in &_Local/Makefile_&. Details of this facility are given in | |
2088 | chapter &<<CHAPperl>>&. | |
168e428f | 2089 | |
f89d2485 | 2090 | .cindex "X11 libraries, location of" |
168e428f | 2091 | The location of the X11 libraries is something that varies a lot between |
068aaea8 | 2092 | operating systems, and there may be different versions of X11 to cope |
168e428f PH |
2093 | with. Exim itself makes no use of X11, but if you are compiling the Exim |
2094 | monitor, the X11 libraries must be available. | |
9b371988 PH |
2095 | The following three variables are set in &_OS/Makefile-Default_&: |
2096 | .code | |
2097 | X11=/usr/X11R6 | |
2098 | XINCLUDE=-I$(X11)/include | |
2099 | XLFLAGS=-L$(X11)/lib | |
2100 | .endd | |
168e428f | 2101 | These are overridden in some of the operating-system configuration files. For |
9b371988 PH |
2102 | example, in &_OS/Makefile-SunOS5_& there is |
2103 | .code | |
2104 | X11=/usr/openwin | |
2105 | XINCLUDE=-I$(X11)/include | |
2106 | XLFLAGS=-L$(X11)/lib -R$(X11)/lib | |
2107 | .endd | |
168e428f PH |
2108 | If you need to override the default setting for your operating system, place a |
2109 | definition of all three of these variables into your | |
9b371988 | 2110 | &_Local/Makefile-<ostype>_& file. |
168e428f | 2111 | |
9b371988 | 2112 | .cindex "EXTRALIBS" |
168e428f PH |
2113 | If you need to add any extra libraries to the link steps, these can be put in a |
2114 | variable called EXTRALIBS, which appears in all the link commands, but by | |
2115 | default is not defined. In contrast, EXTRALIBS_EXIM is used only on the | |
2116 | command for linking the main Exim binary, and not for any associated utilities. | |
2117 | ||
9b371988 | 2118 | .cindex "DBM libraries" "configuration for building" |
168e428f | 2119 | There is also DBMLIB, which appears in the link commands for binaries that |
9b371988 | 2120 | use DBM functions (see also section &<<SECTdb>>&). Finally, there is |
168e428f PH |
2121 | EXTRALIBS_EXIMON, which appears only in the link step for the Exim monitor |
2122 | binary, and which can be used, for example, to include additional X11 | |
2123 | libraries. | |
2124 | ||
9b371988 | 2125 | .cindex "configuration file" "editing" |
168e428f PH |
2126 | The make file copes with rebuilding Exim correctly if any of the configuration |
2127 | files are edited. However, if an optional configuration file is deleted, it is | |
9b371988 PH |
2128 | necessary to touch the associated non-optional file (that is, |
2129 | &_Local/Makefile_& or &_Local/eximon.conf_&) before rebuilding. | |
168e428f PH |
2130 | |
2131 | ||
f89d2485 | 2132 | .section "OS-specific header files" "SECID30" |
9b371988 PH |
2133 | .cindex "&_os.h_&" |
2134 | .cindex "building Exim" "OS-specific C header files" | |
2135 | The &_OS_& directory contains a number of files with names of the form | |
2136 | &_os.h-<ostype>_&. These are system-specific C header files that should not | |
168e428f | 2137 | normally need to be changed. There is a list of macro settings that are |
9b371988 | 2138 | recognized in the file &_OS/os.configuring_&, which should be consulted if you |
168e428f PH |
2139 | are porting Exim to a new operating system. |
2140 | ||
2141 | ||
2142 | ||
f89d2485 PH |
2143 | .section "Overriding build-time options for the monitor" "SECID31" |
2144 | .cindex "building Eximon" | |
168e428f PH |
2145 | A similar process is used for overriding things when building the Exim monitor, |
2146 | where the files that are involved are | |
9b371988 PH |
2147 | .display |
2148 | &_OS/eximon.conf-Default_& | |
2149 | &_OS/eximon.conf-_&<&'ostype'&> | |
2150 | &_Local/eximon.conf_& | |
2151 | &_Local/eximon.conf-_&<&'ostype'&> | |
2152 | &_Local/eximon.conf-_&<&'archtype'&> | |
2153 | &_Local/eximon.conf-_&<&'ostype'&>-<&'archtype'&> | |
2154 | .endd | |
2155 | .cindex "&_Local/eximon.conf_&" | |
168e428f | 2156 | As with Exim itself, the final three files need not exist, and in this case the |
9b371988 PH |
2157 | &_OS/eximon.conf-<ostype>_& file is also optional. The default values in |
2158 | &_OS/eximon.conf-Default_& can be overridden dynamically by setting environment | |
168e428f PH |
2159 | variables of the same name, preceded by EXIMON_. For example, setting |
2160 | EXIMON_LOG_DEPTH in the environment overrides the value of | |
2161 | LOG_DEPTH at run time. | |
4f578862 | 2162 | .ecindex IIDbuex |
168e428f PH |
2163 | |
2164 | ||
f89d2485 | 2165 | .section "Installing Exim binaries and scripts" "SECID32" |
9b371988 PH |
2166 | .cindex "installing Exim" |
2167 | .cindex "BIN_DIRECTORY" | |
2168 | The command &`make install`& runs the &(exim_install)& script with no | |
2169 | arguments. The script copies binaries and utility scripts into the directory | |
2170 | whose name is specified by the BIN_DIRECTORY setting in &_Local/Makefile_&. | |
2171 | .cindex "setuid" "installing Exim with" | |
068aaea8 PH |
2172 | The install script copies files only if they are newer than the files they are |
2173 | going to replace. The Exim binary is required to be owned by root and have the | |
9b371988 PH |
2174 | &'setuid'& bit set, for normal configurations. Therefore, you must run &`make |
2175 | install`& as root so that it can set up the Exim binary in this way. However, in | |
068aaea8 PH |
2176 | some special situations (for example, if a host is doing no local deliveries) |
2177 | it may be possible to run Exim without making the binary setuid root (see | |
9b371988 | 2178 | chapter &<<CHAPsecurity>>& for details). |
168e428f | 2179 | |
9b371988 | 2180 | .cindex "CONFIGURE_FILE" |
168e428f | 2181 | Exim's run time configuration file is named by the CONFIGURE_FILE setting |
9b371988 PH |
2182 | in &_Local/Makefile_&. If this names a single file, and the file does not |
2183 | exist, the default configuration file &_src/configure.default_& is copied there | |
168e428f PH |
2184 | by the installation script. If a run time configuration file already exists, it |
2185 | is left alone. If CONFIGURE_FILE is a colon-separated list, naming several | |
2186 | alternative files, no default is installed. | |
2187 | ||
9b371988 PH |
2188 | .cindex "system aliases file" |
2189 | .cindex "&_/etc/aliases_&" | |
168e428f PH |
2190 | One change is made to the default configuration file when it is installed: the |
2191 | default configuration contains a router that references a system aliases file. | |
2192 | The path to this file is set to the value specified by | |
9b371988 | 2193 | SYSTEM_ALIASES_FILE in &_Local/Makefile_& (&_/etc/aliases_& by default). |
168e428f PH |
2194 | If the system aliases file does not exist, the installation script creates it, |
2195 | and outputs a comment to the user. | |
2196 | ||
2197 | The created file contains no aliases, but it does contain comments about the | |
2198 | aliases a site should normally have. Mail aliases have traditionally been | |
9b371988 PH |
2199 | kept in &_/etc/aliases_&. However, some operating systems are now using |
2200 | &_/etc/mail/aliases_&. You should check if yours is one of these, and change | |
168e428f PH |
2201 | Exim's configuration if necessary. |
2202 | ||
2203 | The default configuration uses the local host's name as the only local domain, | |
9b371988 PH |
2204 | and is set up to do local deliveries into the shared directory &_/var/mail_&, |
2205 | running as the local user. System aliases and &_.forward_& files in users' home | |
168e428f PH |
2206 | directories are supported, but no NIS or NIS+ support is configured. Domains |
2207 | other than the name of the local host are routed using the DNS, with delivery | |
2208 | over SMTP. | |
2209 | ||
168e428f PH |
2210 | It is possible to install Exim for special purposes (such as building a binary |
2211 | distribution) in a private part of the file system. You can do this by a | |
2212 | command such as | |
9b371988 PH |
2213 | .code |
2214 | make DESTDIR=/some/directory/ install | |
2215 | .endd | |
168e428f PH |
2216 | This has the effect of pre-pending the specified directory to all the file |
2217 | paths, except the name of the system aliases file that appears in the default | |
9b371988 | 2218 | configuration. (If a default alias file is created, its name &'is'& modified.) |
168e428f PH |
2219 | For backwards compatibility, ROOT is used if DESTDIR is not set, |
2220 | but this usage is deprecated. | |
2221 | ||
9b371988 PH |
2222 | .cindex "installing Exim" "what is not installed" |
2223 | Running &'make install'& does not copy the Exim 4 conversion script | |
40df1be3 TF |
2224 | &'convert4r4'&. You will probably run this only once if you are |
2225 | upgrading from Exim 3. None of the documentation files in the &_doc_& | |
168e428f | 2226 | directory are copied, except for the info files when you have set |
9b371988 | 2227 | INFO_DIRECTORY, as described in section &<<SECTinsinfdoc>>& below. |
168e428f | 2228 | |
9b371988 | 2229 | For the utility programs, old versions are renamed by adding the suffix &_.O_& |
168e428f PH |
2230 | to their names. The Exim binary itself, however, is handled differently. It is |
2231 | installed under a name that includes the version number and the compile number, | |
9b371988 PH |
2232 | for example &_exim-&version;-1_&. The script then arranges for a symbolic link |
2233 | called &_exim_& to point to the binary. If you are updating a previous version | |
2234 | of Exim, the script takes care to ensure that the name &_exim_& is never absent | |
168e428f PH |
2235 | from the directory (as seen by other processes). |
2236 | ||
9b371988 PH |
2237 | .cindex "installing Exim" "testing the script" |
2238 | If you want to see what the &'make install'& will do before running it for | |
2239 | real, you can pass the &%-n%& option to the installation script by this | |
2240 | command: | |
2241 | .code | |
2242 | make INSTALL_ARG=-n install | |
2243 | .endd | |
168e428f PH |
2244 | The contents of the variable INSTALL_ARG are passed to the installation |
2245 | script. You do not need to be root to run this test. Alternatively, you can run | |
2246 | the installation script directly, but this must be from within the build | |
2247 | directory. For example, from the top-level Exim directory you could use this | |
2248 | command: | |
9b371988 PH |
2249 | .code |
2250 | (cd build-SunOS5-5.5.1-sparc; ../scripts/exim_install -n) | |
2251 | .endd | |
2252 | .cindex "installing Exim" "install script options" | |
168e428f PH |
2253 | There are two other options that can be supplied to the installation script. |
2254 | ||
9b371988 PH |
2255 | .ilist |
2256 | &%-no_chown%& bypasses the call to change the owner of the installed binary | |
168e428f | 2257 | to root, and the call to make it a setuid binary. |
9b371988 PH |
2258 | .next |
2259 | &%-no_symlink%& bypasses the setting up of the symbolic link &_exim_& to the | |
168e428f | 2260 | installed binary. |
9b371988 | 2261 | .endlist |
168e428f PH |
2262 | |
2263 | INSTALL_ARG can be used to pass these options to the script. For example: | |
9b371988 PH |
2264 | .code |
2265 | make INSTALL_ARG=-no_symlink install | |
2266 | .endd | |
168e428f PH |
2267 | The installation script can also be given arguments specifying which files are |
2268 | to be copied. For example, to install just the Exim binary, and nothing else, | |
2269 | without creating the symbolic link, you could use: | |
9b371988 PH |
2270 | .code |
2271 | make INSTALL_ARG='-no_symlink exim' install | |
2272 | .endd | |
168e428f PH |
2273 | |
2274 | ||
2275 | ||
9b371988 PH |
2276 | .section "Installing info documentation" "SECTinsinfdoc" |
2277 | .cindex "installing Exim" "&'info'& documentation" | |
2278 | Not all systems use the GNU &'info'& system for documentation, and for this | |
168e428f PH |
2279 | reason, the Texinfo source of Exim's documentation is not included in the main |
2280 | distribution. Instead it is available separately from the ftp site (see section | |
9b371988 | 2281 | &<<SECTavail>>&). |
168e428f | 2282 | |
9b371988 PH |
2283 | If you have defined INFO_DIRECTORY in &_Local/Makefile_& and the Texinfo |
2284 | source of the documentation is found in the source tree, running &`make | |
2285 | install`& automatically builds the info files and installs them. | |
168e428f PH |
2286 | |
2287 | ||
2288 | ||
f89d2485 | 2289 | .section "Setting up the spool directory" "SECID33" |
9b371988 | 2290 | .cindex "spool directory" "creating" |
168e428f PH |
2291 | When it starts up, Exim tries to create its spool directory if it does not |
2292 | exist. The Exim uid and gid are used for the owner and group of the spool | |
2293 | directory. Sub-directories are automatically created in the spool directory as | |
2294 | necessary. | |
2295 | ||
2296 | ||
2297 | ||
2298 | ||
f89d2485 | 2299 | .section "Testing" "SECID34" |
9b371988 | 2300 | .cindex "testing" "installation" |
168e428f PH |
2301 | Having installed Exim, you can check that the run time configuration file is |
2302 | syntactically valid by running the following command, which assumes that the | |
2303 | Exim binary directory is within your PATH environment variable: | |
9b371988 PH |
2304 | .code |
2305 | exim -bV | |
2306 | .endd | |
168e428f PH |
2307 | If there are any errors in the configuration file, Exim outputs error messages. |
2308 | Otherwise it outputs the version number and build date, | |
2309 | the DBM library that is being used, and information about which drivers and | |
2310 | other optional code modules are included in the binary. | |
2311 | Some simple routing tests can be done by using the address testing option. For | |
2312 | example, | |
9b371988 PH |
2313 | .display |
2314 | &`exim -bt`& <&'local username'&> | |
2315 | .endd | |
168e428f | 2316 | should verify that it recognizes a local mailbox, and |
9b371988 PH |
2317 | .display |
2318 | &`exim -bt`& <&'remote address'&> | |
2319 | .endd | |
168e428f PH |
2320 | a remote one. Then try getting it to deliver mail, both locally and remotely. |
2321 | This can be done by passing messages directly to Exim, without going through a | |
2322 | user agent. For example: | |
9b371988 | 2323 | .code |
068aaea8 PH |
2324 | exim -v postmaster@your.domain.example |
2325 | From: user@your.domain.example | |
2326 | To: postmaster@your.domain.example | |
2327 | Subject: Testing Exim | |
168e428f | 2328 | |
068aaea8 PH |
2329 | This is a test message. |
2330 | ^D | |
9b371988 PH |
2331 | .endd |
2332 | The &%-v%& option causes Exim to output some verification of what it is doing. | |
168e428f | 2333 | In this case you should see copies of three log lines, one for the message's |
9b371988 | 2334 | arrival, one for its delivery, and one containing &"Completed"&. |
168e428f | 2335 | |
9b371988 PH |
2336 | .cindex "delivery" "problems with" |
2337 | If you encounter problems, look at Exim's log files (&'mainlog'& and | |
2338 | &'paniclog'&) to see if there is any relevant information there. Another source | |
168e428f | 2339 | of information is running Exim with debugging turned on, by specifying the |
9b371988 | 2340 | &%-d%& option. If a message is stuck on Exim's spool, you can force a delivery |
168e428f | 2341 | with debugging turned on by a command of the form |
9b371988 PH |
2342 | .display |
2343 | &`exim -d -M`& <&'exim-message-id'&> | |
2344 | .endd | |
2345 | You must be root or an &"admin user"& in order to do this. The &%-d%& option | |
168e428f | 2346 | produces rather a lot of output, but you can cut this down to specific areas. |
9b371988 PH |
2347 | For example, if you use &%-d-all+route%& only the debugging information |
2348 | relevant to routing is included. (See the &%-d%& option in chapter | |
2349 | &<<CHAPcommandline>>& for more details.) | |
168e428f | 2350 | |
9b371988 PH |
2351 | .cindex '&"sticky"& bit' |
2352 | .cindex "lock files" | |
168e428f PH |
2353 | One specific problem that has shown up on some sites is the inability to do |
2354 | local deliveries into a shared mailbox directory, because it does not have the | |
9b371988 | 2355 | &"sticky bit"& set on it. By default, Exim tries to create a lock file before |
168e428f | 2356 | writing to a mailbox file, and if it cannot create the lock file, the delivery |
9b371988 | 2357 | is deferred. You can get round this either by setting the &"sticky bit"& on the |
168e428f PH |
2358 | directory, or by setting a specific group for local deliveries and allowing |
2359 | that group to create files in the directory (see the comments above the | |
9b371988 | 2360 | &(local_delivery)& transport in the default configuration file). Another |
168e428f | 2361 | approach is to configure Exim not to use lock files, but just to rely on |
9b371988 PH |
2362 | &[fcntl()]& locking instead. However, you should do this only if all user |
2363 | agents also use &[fcntl()]& locking. For further discussion of locking issues, | |
2364 | see chapter &<<CHAPappendfile>>&. | |
168e428f PH |
2365 | |
2366 | One thing that cannot be tested on a system that is already running an MTA is | |
2367 | the receipt of incoming SMTP mail on the standard SMTP port. However, the | |
9b371988 PH |
2368 | &%-oX%& option can be used to run an Exim daemon that listens on some other |
2369 | port, or &'inetd'& can be used to do this. The &%-bh%& option and the | |
2370 | &'exim_checkaccess'& utility can be used to check out policy controls on | |
168e428f PH |
2371 | incoming SMTP mail. |
2372 | ||
2373 | Testing a new version on a system that is already running Exim can most easily | |
2374 | be done by building a binary with a different CONFIGURE_FILE setting. From | |
2375 | within the run time configuration, all other file and directory names | |
2376 | that Exim uses can be altered, in order to keep it entirely clear of the | |
2377 | production version. | |
2378 | ||
2379 | ||
f89d2485 | 2380 | .section "Replacing another MTA with Exim" "SECID35" |
9b371988 | 2381 | .cindex "replacing another MTA" |
168e428f PH |
2382 | Building and installing Exim for the first time does not of itself put it in |
2383 | general use. The name by which the system's MTA is called by mail user agents | |
9b371988 PH |
2384 | is either &_/usr/sbin/sendmail_&, or &_/usr/lib/sendmail_& (depending on the |
2385 | operating system), and it is necessary to make this name point to the &'exim'& | |
168e428f | 2386 | binary in order to get the user agents to pass messages to Exim. This is |
9b371988 PH |
2387 | normally done by renaming any existing file and making &_/usr/sbin/sendmail_& |
2388 | or &_/usr/lib/sendmail_& | |
2389 | .cindex "symbolic link" "to &'exim'& binary" | |
2390 | a symbolic link to the &'exim'& binary. It is a good idea to remove any setuid | |
168e428f PH |
2391 | privilege and executable status from the old MTA. It is then necessary to stop |
2392 | and restart the mailer daemon, if one is running. | |
2393 | ||
f89d2485 | 2394 | .cindex "FreeBSD, MTA indirection" |
9b371988 | 2395 | .cindex "&_/etc/mail/mailer.conf_&" |
168e428f PH |
2396 | Some operating systems have introduced alternative ways of switching MTAs. For |
2397 | example, if you are running FreeBSD, you need to edit the file | |
9b371988 | 2398 | &_/etc/mail/mailer.conf_& instead of setting up a symbolic link as just |
168e428f PH |
2399 | described. A typical example of the contents of this file for running Exim is |
2400 | as follows: | |
9b371988 PH |
2401 | .code |
2402 | sendmail /usr/exim/bin/exim | |
2403 | send-mail /usr/exim/bin/exim | |
2404 | mailq /usr/exim/bin/exim -bp | |
2405 | newaliases /usr/bin/true | |
2406 | .endd | |
2407 | Once you have set up the symbolic link, or edited &_/etc/mail/mailer.conf_&, | |
2408 | your Exim installation is &"live"&. Check it by sending a message from your | |
168e428f PH |
2409 | favourite user agent. |
2410 | ||
2411 | You should consider what to tell your users about the change of MTA. Exim may | |
2412 | have different capabilities to what was previously running, and there are | |
2413 | various operational differences such as the text of messages produced by | |
2414 | command line options and in bounce messages. If you allow your users to make | |
2415 | use of Exim's filtering capabilities, you should make the document entitled | |
9b371988 | 2416 | &'Exim's interface to mail filtering'& available to them. |
168e428f PH |
2417 | |
2418 | ||
2419 | ||
f89d2485 | 2420 | .section "Upgrading Exim" "SECID36" |
9b371988 | 2421 | .cindex "upgrading Exim" |
168e428f PH |
2422 | If you are already running Exim on your host, building and installing a new |
2423 | version automatically makes it available to MUAs, or any other programs that | |
2424 | call the MTA directly. However, if you are running an Exim daemon, you do need | |
9b371988 PH |
2425 | to send it a HUP signal, to make it re-execute itself, and thereby pick up the |
2426 | new binary. You do not need to stop processing mail in order to install a new | |
068aaea8 PH |
2427 | version of Exim. The install script does not modify an existing runtime |
2428 | configuration file. | |
2429 | ||
168e428f PH |
2430 | |
2431 | ||
2432 | ||
f89d2485 | 2433 | .section "Stopping the Exim daemon on Solaris" "SECID37" |
9b371988 | 2434 | .cindex "Solaris" "stopping Exim on" |
168e428f | 2435 | The standard command for stopping the mailer daemon on Solaris is |
9b371988 PH |
2436 | .code |
2437 | /etc/init.d/sendmail stop | |
2438 | .endd | |
2439 | If &_/usr/lib/sendmail_& has been turned into a symbolic link, this script | |
2440 | fails to stop Exim because it uses the command &'ps -e'& and greps the output | |
2441 | for the text &"sendmail"&; this is not present because the actual program name | |
2442 | (that is, &"exim"&) is given by the &'ps'& command with these options. A | |
2443 | solution is to replace the line that finds the process id with something like | |
2444 | .code | |
2445 | pid=`cat /var/spool/exim/exim-daemon.pid` | |
2446 | .endd | |
168e428f PH |
2447 | to obtain the daemon's pid directly from the file that Exim saves it in. |
2448 | ||
9b371988 | 2449 | Note, however, that stopping the daemon does not &"stop Exim"&. Messages can |
168e428f PH |
2450 | still be received from local processes, and if automatic delivery is configured |
2451 | (the normal case), deliveries will still occur. | |
2452 | ||
2453 | ||
2454 | ||
2455 | ||
9b371988 PH |
2456 | . //////////////////////////////////////////////////////////////////////////// |
2457 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 2458 | |
9b371988 | 2459 | .chapter "The Exim command line" "CHAPcommandline" |
4f578862 PH |
2460 | .scindex IIDclo1 "command line" "options" |
2461 | .scindex IIDclo2 "options" "command line" | |
168e428f PH |
2462 | Exim's command line takes the standard Unix form of a sequence of options, |
2463 | each starting with a hyphen character, followed by a number of arguments. The | |
2464 | options are compatible with the main options of Sendmail, and there are also | |
2465 | some additional options, some of which are compatible with Smail 3. Certain | |
2466 | combinations of options do not make sense, and provoke an error if used. | |
2467 | The form of the arguments depends on which options are set. | |
2468 | ||
2469 | ||
f89d2485 | 2470 | .section "Setting options by program name" "SECID38" |
9b371988 PH |
2471 | .cindex "&'mailq'&" |
2472 | If Exim is called under the name &'mailq'&, it behaves as if the option &%-bp%& | |
168e428f | 2473 | were present before any other options. |
9b371988 | 2474 | The &%-bp%& option requests a listing of the contents of the mail queue on the |
168e428f PH |
2475 | standard output. |
2476 | This feature is for compatibility with some systems that contain a command of | |
2477 | that name in one of the standard libraries, symbolically linked to | |
9b371988 PH |
2478 | &_/usr/sbin/sendmail_& or &_/usr/lib/sendmail_&. |
2479 | ||
2480 | .cindex "&'rsmtp'&" | |
2481 | If Exim is called under the name &'rsmtp'& it behaves as if the option &%-bS%& | |
2482 | were present before any other options, for compatibility with Smail. The | |
2483 | &%-bS%& option is used for reading in a number of messages in batched SMTP | |
2484 | format. | |
2485 | ||
2486 | .cindex "&'rmail'&" | |
2487 | If Exim is called under the name &'rmail'& it behaves as if the &%-i%& and | |
2488 | &%-oee%& options were present before any other options, for compatibility with | |
2489 | Smail. The name &'rmail'& is used as an interface by some UUCP systems. | |
2490 | ||
2491 | .cindex "&'runq'&" | |
2492 | .cindex "queue runner" | |
2493 | If Exim is called under the name &'runq'& it behaves as if the option &%-q%& | |
2494 | were present before any other options, for compatibility with Smail. The &%-q%& | |
168e428f PH |
2495 | option causes a single queue runner process to be started. |
2496 | ||
9b371988 PH |
2497 | .cindex "&'newaliases'&" |
2498 | .cindex "alias file" "building" | |
2499 | .cindex "Sendmail compatibility" "calling Exim as &'newaliases'&" | |
2500 | If Exim is called under the name &'newaliases'& it behaves as if the option | |
2501 | &%-bi%& were present before any other options, for compatibility with Sendmail. | |
168e428f PH |
2502 | This option is used for rebuilding Sendmail's alias file. Exim does not have |
2503 | the concept of a single alias file, but can be configured to run a given | |
9b371988 | 2504 | command if called with the &%-bi%& option. |
168e428f PH |
2505 | |
2506 | ||
9b371988 PH |
2507 | .section "Trusted and admin users" "SECTtrustedadmin" |
2508 | Some Exim options are available only to &'trusted users'& and others are | |
2509 | available only to &'admin users'&. In the description below, the phrases &"Exim | |
2510 | user"& and &"Exim group"& mean the user and group defined by EXIM_USER and | |
2511 | EXIM_GROUP in &_Local/Makefile_& or set by the &%exim_user%& and | |
2512 | &%exim_group%& options. These do not necessarily have to use the name &"exim"&. | |
168e428f | 2513 | |
9b371988 | 2514 | .ilist |
f89d2485 | 2515 | .cindex "trusted users" "definition of" |
9b371988 | 2516 | .cindex "user" "trusted definition of" |
168e428f | 2517 | The trusted users are root, the Exim user, any user listed in the |
9b371988 PH |
2518 | &%trusted_users%& configuration option, and any user whose current group or any |
2519 | supplementary group is one of those listed in the &%trusted_groups%& | |
168e428f | 2520 | configuration option. Note that the Exim group is not automatically trusted. |
9b371988 PH |
2521 | |
2522 | .cindex '&"From"& line' | |
2523 | .cindex "envelope sender" | |
2524 | Trusted users are always permitted to use the &%-f%& option or a leading | |
2525 | &"From&~"& line to specify the envelope sender of a message that is passed to | |
2526 | Exim through the local interface (see the &%-bm%& and &%-f%& options below). | |
2527 | See the &%untrusted_set_sender%& option for a way of permitting non-trusted | |
2528 | users to set envelope senders. | |
2529 | ||
2530 | .cindex "&'From:'& header line" | |
2531 | .cindex "&'Sender:'& header line" | |
2532 | For a trusted user, there is never any check on the contents of the &'From:'& | |
2533 | header line, and a &'Sender:'& line is never added. Furthermore, any existing | |
2534 | &'Sender:'& line in incoming local (non-TCP/IP) messages is not removed. | |
2535 | ||
168e428f PH |
2536 | Trusted users may also specify a host name, host address, interface address, |
2537 | protocol name, ident value, and authentication data when submitting a message | |
2538 | locally. Thus, they are able to insert messages into Exim's queue locally that | |
2539 | have the characteristics of messages received from a remote host. Untrusted | |
9b371988 | 2540 | users may in some circumstances use &%-f%&, but can never set the other values |
168e428f | 2541 | that are available to trusted users. |
9b371988 PH |
2542 | .next |
2543 | .cindex "user" "admin definition of" | |
2544 | .cindex "admin user" "definition of" | |
168e428f | 2545 | The admin users are root, the Exim user, and any user that is a member of the |
9b371988 | 2546 | Exim group or of any group listed in the &%admin_groups%& configuration option. |
168e428f | 2547 | The current group does not have to be one of these groups. |
9b371988 | 2548 | |
168e428f PH |
2549 | Admin users are permitted to list the queue, and to carry out certain |
2550 | operations on messages, for example, to force delivery failures. It is also | |
2551 | necessary to be an admin user in order to see the full information provided by | |
2552 | the Exim monitor, and full debugging output. | |
9b371988 PH |
2553 | |
2554 | By default, the use of the &%-M%&, &%-q%&, &%-R%&, and &%-S%& options to cause | |
2555 | Exim to attempt delivery of messages on its queue is restricted to admin users. | |
2556 | However, this restriction can be relaxed by setting the &%prod_requires_admin%& | |
2557 | option false (that is, specifying &%no_prod_requires_admin%&). | |
2558 | ||
2559 | Similarly, the use of the &%-bp%& option to list all the messages in the queue | |
2560 | is restricted to admin users unless &%queue_list_requires_admin%& is set | |
168e428f | 2561 | false. |
9b371988 | 2562 | .endlist |
168e428f PH |
2563 | |
2564 | ||
9b371988 | 2565 | &*Warning*&: If you configure your system so that admin users are able to |
168e428f PH |
2566 | edit Exim's configuration file, you are giving those users an easy way of |
2567 | getting root. There is further discussion of this issue at the start of chapter | |
9b371988 | 2568 | &<<CHAPconf>>&. |
168e428f PH |
2569 | |
2570 | ||
2571 | ||
2572 | ||
f89d2485 | 2573 | .section "Command line options" "SECID39" |
db9452a9 PH |
2574 | Exim's command line options are described in alphabetical order below. If none |
2575 | of the options that specifies a specific action (such as starting the daemon or | |
2576 | a queue runner, or testing an address, or receiving a message in a specific | |
2577 | format, or listing the queue) are present, and there is at least one argument | |
2578 | on the command line, &%-bm%& (accept a local message on the standard input, | |
2579 | with the arguments specifying the recipients) is assumed. Otherwise, Exim | |
2580 | outputs a brief message about itself and exits. | |
168e428f | 2581 | |
9b371988 PH |
2582 | . //////////////////////////////////////////////////////////////////////////// |
2583 | . Insert a stylized XML comment here, to identify the start of the command line | |
2584 | . options. This is for the benefit of the Perl script that automatically | |
2585 | . creates a man page for the options. | |
2586 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 2587 | |
9b371988 | 2588 | .literal xml |
168e428f | 2589 | <!-- === Start of command line options === --> |
9b371988 | 2590 | .literal off |
168e428f PH |
2591 | |
2592 | ||
9b371988 PH |
2593 | .vlist |
2594 | .vitem &%--%& | |
2595 | .oindex "--" | |
2596 | .cindex "options" "command line; terminating" | |
168e428f PH |
2597 | This is a pseudo-option whose only purpose is to terminate the options and |
2598 | therefore to cause subsequent command line items to be treated as arguments | |
2599 | rather than options, even if they begin with hyphens. | |
2600 | ||
9b371988 PH |
2601 | .vitem &%--help%& |
2602 | .oindex "&%--help%&" | |
168e428f PH |
2603 | This option causes Exim to output a few sentences stating what it is. |
2604 | The same output is generated if the Exim binary is called with no options and | |
2605 | no arguments. | |
2606 | ||
9b371988 PH |
2607 | .vitem &%-B%&<&'type'&> |
2608 | .oindex "&%-B%&" | |
2609 | .cindex "8-bit characters" | |
2610 | .cindex "Sendmail compatibility" "8-bit characters" | |
168e428f PH |
2611 | This is a Sendmail option for selecting 7 or 8 bit processing. Exim is 8-bit |
2612 | clean; it ignores this option. | |
2613 | ||
9b371988 PH |
2614 | .vitem &%-bd%& |
2615 | .oindex "&%-bd%&" | |
2616 | .cindex "daemon" | |
f89d2485 | 2617 | .cindex "SMTP" "listener" |
9b371988 | 2618 | .cindex "queue runner" |
168e428f | 2619 | This option runs Exim as a daemon, awaiting incoming SMTP connections. Usually |
9b371988 PH |
2620 | the &%-bd%& option is combined with the &%-q%&<&'time'&> option, to specify |
2621 | that the daemon should also initiate periodic queue runs. | |
2622 | ||
2623 | The &%-bd%& option can be used only by an admin user. If either of the &%-d%& | |
2624 | (debugging) or &%-v%& (verifying) options are set, the daemon does not | |
168e428f PH |
2625 | disconnect from the controlling terminal. When running this way, it can be |
2626 | stopped by pressing ctrl-C. | |
9b371988 | 2627 | |
168e428f PH |
2628 | By default, Exim listens for incoming connections to the standard SMTP port on |
2629 | all the host's running interfaces. However, it is possible to listen on other | |
2630 | ports, on multiple ports, and only on specific interfaces. Chapter | |
9b371988 PH |
2631 | &<<CHAPinterfaces>>& contains a description of the options that control this. |
2632 | ||
168e428f | 2633 | When a listening daemon |
9b371988 PH |
2634 | .cindex "daemon" "process id (pid)" |
2635 | .cindex "pid (process id)" "of daemon" | |
2636 | is started without the use of &%-oX%& (that is, without overriding the normal | |
2637 | configuration), it writes its process id to a file called &_exim-daemon.pid_& | |
2638 | in Exim's spool directory. This location can be overridden by setting | |
2639 | PID_FILE_PATH in &_Local/Makefile_&. The file is written while Exim is still | |
168e428f | 2640 | running as root. |
9b371988 PH |
2641 | |
2642 | When &%-oX%& is used on the command line to start a listening daemon, the | |
2643 | process id is not written to the normal pid file path. However, &%-oP%& can be | |
168e428f | 2644 | used to specify a path on the command line if a pid file is required. |
9b371988 | 2645 | |
168e428f | 2646 | The SIGHUP signal |
9b371988 | 2647 | .cindex "SIGHUP" |
3cb1b51e PH |
2648 | .cindex "daemon" "restarting" |
2649 | can be used to cause the daemon to re-execute itself. This should be done | |
2650 | whenever Exim's configuration file, or any file that is incorporated into it by | |
2651 | means of the &%.include%& facility, is changed, and also whenever a new version | |
2652 | of Exim is installed. It is not necessary to do this when other files that are | |
9b371988 PH |
2653 | referenced from the configuration (for example, alias files) are changed, |
2654 | because these are reread each time they are used. | |
2655 | ||
2656 | .vitem &%-bdf%& | |
2657 | .oindex "&%-bdf%&" | |
2658 | This option has the same effect as &%-bd%& except that it never disconnects | |
2659 | from the controlling terminal, even when no debugging is specified. | |
2660 | ||
2661 | .vitem &%-be%& | |
2662 | .oindex "&%-be%&" | |
2663 | .cindex "testing" "string expansion" | |
2664 | .cindex "expansion" "testing" | |
168e428f PH |
2665 | Run Exim in expansion testing mode. Exim discards its root privilege, to |
2666 | prevent ordinary users from using this mode to read otherwise inaccessible | |
2667 | files. If no arguments are given, Exim runs interactively, prompting for lines | |
4f578862 | 2668 | of data. Otherwise, it processes each argument in turn. |
9b371988 PH |
2669 | |
2670 | If Exim was built with USE_READLINE=yes in &_Local/Makefile_&, it tries | |
2671 | to load the &%libreadline%& library dynamically whenever the &%-be%& option is | |
2672 | used without command line arguments. If successful, it uses the &[readline()]& | |
168e428f PH |
2673 | function, which provides extensive line-editing facilities, for reading the |
2674 | test data. A line history is supported. | |
9b371988 | 2675 | |
168e428f | 2676 | Long expansion expressions can be split over several lines by using backslash |
068aaea8 | 2677 | continuations. As in Exim's run time configuration, white space at the start of |
168e428f PH |
2678 | continuation lines is ignored. Each argument or data line is passed through the |
2679 | string expansion mechanism, and the result is output. Variable values from the | |
9b371988 | 2680 | configuration file (for example, &$qualify_domain$&) are available, but no |
3cb1b51e | 2681 | message-specific values (such as &$sender_domain$&) are set, because no message |
f89d2485 | 2682 | is being processed (but see &%-bem%& and &%-Mset%&). |
168e428f | 2683 | |
9b371988 PH |
2684 | &*Note*&: If you use this mechanism to test lookups, and you change the data |
2685 | files or databases you are using, you must exit and restart Exim before trying | |
2686 | the same lookup again. Otherwise, because each Exim process caches the results | |
2687 | of lookups, you will just get the same result as before. | |
9b371988 | 2688 | |
3cb1b51e PH |
2689 | .vitem &%-bem%&&~<&'filename'&> |
2690 | .oindex "&%-bem%&" | |
2691 | .cindex "testing" "string expansion" | |
2692 | .cindex "expansion" "testing" | |
2693 | This option operates like &%-be%& except that it must be followed by the name | |
2694 | of a file. For example: | |
2695 | .code | |
2696 | exim -bem /tmp/testmessage | |
2697 | .endd | |
2698 | The file is read as a message (as if receiving a locally-submitted non-SMTP | |
2699 | message) before any of the test expansions are done. Thus, message-specific | |
2700 | variables such as &$message_size$& and &$header_from:$& are available. However, | |
2701 | no &'Received:'& header is added to the message. If the &%-t%& option is set, | |
2702 | recipients are read from the headers in the normal way, and are shown in the | |
2703 | &$recipients$& variable. Note that recipients cannot be given on the command | |
2704 | line, because further arguments are taken as strings to expand (just like | |
2705 | &%-be%&). | |
3cb1b51e | 2706 | |
9b371988 PH |
2707 | .vitem &%-bF%&&~<&'filename'&> |
2708 | .oindex "&%-bF%&" | |
2709 | .cindex "system filter" "testing" | |
2710 | .cindex "testing" "system filter" | |
2711 | This option is the same as &%-bf%& except that it assumes that the filter being | |
168e428f PH |
2712 | tested is a system filter. The additional commands that are available only in |
2713 | system filters are recognized. | |
2714 | ||
9b371988 PH |
2715 | .vitem &%-bf%&&~<&'filename'&> |
2716 | .oindex "&%-bf%&" | |
2717 | .cindex "filter" "testing" | |
2718 | .cindex "testing" "filter file" | |
2719 | .cindex "forward file" "testing" | |
2720 | .cindex "testing" "forward file" | |
2721 | .cindex "Sieve filter" "testing" | |
168e428f PH |
2722 | This option runs Exim in user filter testing mode; the file is the filter file |
2723 | to be tested, and a test message must be supplied on the standard input. If | |
2724 | there are no message-dependent tests in the filter, an empty file can be | |
2725 | supplied. | |
168e428f | 2726 | |
9b371988 PH |
2727 | If you want to test a system filter file, use &%-bF%& instead of &%-bf%&. You |
2728 | can use both &%-bF%& and &%-bf%& on the same command, in order to test a system | |
2729 | filter and a user filter in the same run. For example: | |
2730 | .code | |
2731 | exim -bF /system/filter -bf /user/filter </test/message | |
2732 | .endd | |
168e428f PH |
2733 | This is helpful when the system filter adds header lines or sets filter |
2734 | variables that are used by the user filter. | |
168e428f | 2735 | |
9b371988 PH |
2736 | If the test filter file does not begin with one of the special lines |
2737 | .code | |
2738 | # Exim filter | |
2739 | # Sieve filter | |
2740 | .endd | |
2741 | it is taken to be a normal &_.forward_& file, and is tested for validity under | |
2742 | that interpretation. See sections &<<SECTitenonfilred>>& to | |
2743 | &<<SECTspecitredli>>& for a description of the possible contents of non-filter | |
2744 | redirection lists. | |
2745 | ||
2746 | The result of an Exim command that uses &%-bf%&, provided no errors are | |
168e428f PH |
2747 | detected, is a list of the actions that Exim would try to take if presented |
2748 | with the message for real. More details of filter testing are given in the | |
9b371988 PH |
2749 | separate document entitled &'Exim's interfaces to mail filtering'&. |
2750 | ||
168e428f | 2751 | When testing a filter file, |
9b371988 PH |
2752 | .cindex "&""From""& line" |
2753 | .cindex "envelope sender" | |
f89d2485 | 2754 | .oindex "&%-f%&" "for filter testing" |
9b371988 PH |
2755 | the envelope sender can be set by the &%-f%& option, |
2756 | or by a &"From&~"& line at the start of the test message. Various parameters | |
2757 | that would normally be taken from the envelope recipient address of the message | |
2758 | can be set by means of additional command line options (see the next four | |
2759 | options). | |
2760 | ||
2761 | .vitem &%-bfd%&&~<&'domain'&> | |
2762 | .oindex "&%-bfd%&" | |
f89d2485 | 2763 | .vindex "&$qualify_domain$&" |
168e428f | 2764 | This sets the domain of the recipient address when a filter file is being |
9b371988 PH |
2765 | tested by means of the &%-bf%& option. The default is the value of |
2766 | &$qualify_domain$&. | |
168e428f | 2767 | |
9b371988 PH |
2768 | .vitem &%-bfl%&&~<&'local&~part'&> |
2769 | .oindex "&%-bfl%&" | |
168e428f | 2770 | This sets the local part of the recipient address when a filter file is being |
9b371988 | 2771 | tested by means of the &%-bf%& option. The default is the username of the |
168e428f PH |
2772 | process that calls Exim. A local part should be specified with any prefix or |
2773 | suffix stripped, because that is how it appears to the filter when a message is | |
2774 | actually being delivered. | |
2775 | ||
9b371988 PH |
2776 | .vitem &%-bfp%&&~<&'prefix'&> |
2777 | .oindex "&%-bfp%&" | |
168e428f | 2778 | This sets the prefix of the local part of the recipient address when a filter |
9b371988 | 2779 | file is being tested by means of the &%-bf%& option. The default is an empty |
168e428f PH |
2780 | prefix. |
2781 | ||
9b371988 PH |
2782 | .vitem &%-bfs%&&~<&'suffix'&> |
2783 | .oindex "&%-bfs%&" | |
168e428f | 2784 | This sets the suffix of the local part of the recipient address when a filter |
9b371988 | 2785 | file is being tested by means of the &%-bf%& option. The default is an empty |
168e428f PH |
2786 | suffix. |
2787 | ||
9b371988 PH |
2788 | .vitem &%-bh%&&~<&'IP&~address'&> |
2789 | .oindex "&%-bh%&" | |
2790 | .cindex "testing" "incoming SMTP" | |
2791 | .cindex "SMTP" "testing incoming" | |
2792 | .cindex "testing" "relay control" | |
2793 | .cindex "relaying" "testing configuration" | |
2794 | .cindex "policy control" "testing" | |
2795 | .cindex "debugging" "&%-bh%& option" | |
168e428f PH |
2796 | This option runs a fake SMTP session as if from the given IP address, using the |
2797 | standard input and output. The IP address may include a port number at the end, | |
2798 | after a full stop. For example: | |
9b371988 PH |
2799 | .code |
2800 | exim -bh 10.9.8.7.1234 | |
2801 | exim -bh fe80::a00:20ff:fe86:a061.5678 | |
2802 | .endd | |
168e428f | 2803 | When an IPv6 address is given, it is converted into canonical form. In the case |
9b371988 PH |
2804 | of the second example above, the value of &$sender_host_address$& after |
2805 | conversion to the canonical form is | |
2806 | &`fe80:0000:0000:0a00:20ff:fe86:a061.5678`&. | |
2807 | ||
168e428f | 2808 | Comments as to what is going on are written to the standard error file. These |
9b371988 | 2809 | include lines beginning with &"LOG"& for anything that would have been logged. |
168e428f PH |
2810 | This facility is provided for testing configuration options for incoming |
2811 | messages, to make sure they implement the required policy. For example, you can | |
9b371988 PH |
2812 | test your relay controls using &%-bh%&. |
2813 | ||
2814 | &*Warning 1*&: | |
2815 | .cindex "RFC 1413" | |
db9452a9 PH |
2816 | You can test features of the configuration that rely on ident (RFC 1413) |
2817 | information by using the &%-oMt%& option. However, Exim cannot actually perform | |
2818 | an ident callout when testing using &%-bh%& because there is no incoming SMTP | |
2819 | connection. | |
9b371988 PH |
2820 | |
2821 | &*Warning 2*&: Address verification callouts (see section &<<SECTcallver>>&) | |
2822 | are also skipped when testing using &%-bh%&. If you want these callouts to | |
2823 | occur, use &%-bhc%& instead. | |
2824 | ||
168e428f PH |
2825 | Messages supplied during the testing session are discarded, and nothing is |
2826 | written to any of the real log files. There may be pauses when DNS (and other) | |
9b371988 | 2827 | lookups are taking place, and of course these may time out. The &%-oMi%& option |
db9452a9 PH |
2828 | can be used to specify a specific IP interface and port if this is important, |
2829 | and &%-oMaa%& and &%-oMai%& can be used to set parameters as if the SMTP | |
2830 | session were authenticated. | |
9b371988 PH |
2831 | |
2832 | The &'exim_checkaccess'& utility is a &"packaged"& version of &%-bh%& whose | |
168e428f | 2833 | output just states whether a given recipient address from a given host is |
9b371988 | 2834 | acceptable or not. See section &<<SECTcheckaccess>>&. |
168e428f | 2835 | |
3cb1b51e | 2836 | Features such as authentication and encryption, where the client input is not |
f89d2485 PH |
2837 | plain text, cannot easily be tested with &%-bh%&. Instead, you should use a |
2838 | specialized SMTP test program such as | |
3cb1b51e | 2839 | &url(http://jetmore.org/john/code/#swaks,swaks). |
3cb1b51e | 2840 | |
9b371988 PH |
2841 | .vitem &%-bhc%&&~<&'IP&~address'&> |
2842 | .oindex "&%-bhc%&" | |
2843 | This option operates in the same way as &%-bh%&, except that address | |
168e428f PH |
2844 | verification callouts are performed if required. This includes consulting and |
2845 | updating the callout cache database. | |
2846 | ||
9b371988 PH |
2847 | .vitem &%-bi%& |
2848 | .oindex "&%-bi%&" | |
2849 | .cindex "alias file" "building" | |
2850 | .cindex "building alias file" | |
2851 | .cindex "Sendmail compatibility" "&%-bi%& option" | |
2852 | Sendmail interprets the &%-bi%& option as a request to rebuild its alias file. | |
168e428f | 2853 | Exim does not have the concept of a single alias file, and so it cannot mimic |
9b371988 | 2854 | this behaviour. However, calls to &_/usr/lib/sendmail_& with the &%-bi%& option |
168e428f PH |
2855 | tend to appear in various scripts such as NIS make files, so the option must be |
2856 | recognized. | |
9b371988 PH |
2857 | |
2858 | If &%-bi%& is encountered, the command specified by the &%bi_command%& | |
168e428f | 2859 | configuration option is run, under the uid and gid of the caller of Exim. If |
9b371988 PH |
2860 | the &%-oA%& option is used, its value is passed to the command as an argument. |
2861 | The command set by &%bi_command%& may not contain arguments. The command can | |
2862 | use the &'exim_dbmbuild'& utility, or some other means, to rebuild alias files | |
2863 | if this is required. If the &%bi_command%& option is not set, calling Exim with | |
2864 | &%-bi%& is a no-op. | |
2865 | ||
2866 | .vitem &%-bm%& | |
2867 | .oindex "&%-bm%&" | |
2868 | .cindex "local message reception" | |
168e428f PH |
2869 | This option runs an Exim receiving process that accepts an incoming, |
2870 | locally-generated message on the current input. The recipients are given as the | |
9b371988 | 2871 | command arguments (except when &%-t%& is also present &-- see below). Each |
168e428f PH |
2872 | argument can be a comma-separated list of RFC 2822 addresses. This is the |
2873 | default option for selecting the overall action of an Exim call; it is assumed | |
2874 | if no other conflicting option is present. | |
9b371988 | 2875 | |
168e428f | 2876 | If any addresses in the message are unqualified (have no domain), they are |
9b371988 PH |
2877 | qualified by the values of the &%qualify_domain%& or &%qualify_recipient%& |
2878 | options, as appropriate. The &%-bnq%& option (see below) provides a way of | |
168e428f | 2879 | suppressing this for special cases. |
9b371988 | 2880 | |
168e428f | 2881 | Policy checks on the contents of local messages can be enforced by means of |
9b371988 PH |
2882 | the non-SMTP ACL. See chapter &<<CHAPACL>>& for details. |
2883 | ||
2884 | .cindex "return code" "for &%-bm%&" | |
2885 | The return code is zero if the message is successfully accepted. Otherwise, the | |
2886 | action is controlled by the &%-oe%&&'x'& option setting &-- see below. | |
2887 | ||
168e428f | 2888 | The format |
9b371988 PH |
2889 | .cindex "message" "format" |
2890 | .cindex "format" "message" | |
2891 | .cindex "&""From""& line" | |
2892 | .cindex "UUCP" "&""From""& line" | |
2893 | .cindex "Sendmail compatibility" "&""From""& line" | |
168e428f PH |
2894 | of the message must be as defined in RFC 2822, except that, for |
2895 | compatibility with Sendmail and Smail, a line in one of the forms | |
9b371988 PH |
2896 | .code |
2897 | From sender Fri Jan 5 12:55 GMT 1997 | |
2898 | From sender Fri, 5 Jan 97 12:55:01 | |
2899 | .endd | |
168e428f PH |
2900 | (with the weekday optional, and possibly with additional text after the date) |
2901 | is permitted to appear at the start of the message. There appears to be no | |
2902 | authoritative specification of the format of this line. Exim recognizes it by | |
9b371988 | 2903 | matching against the regular expression defined by the &%uucp_from_pattern%& |
168e428f | 2904 | option, which can be changed if necessary. |
9b371988 | 2905 | |
f89d2485 PH |
2906 | .oindex "&%-f%&" "overriding &""From""& line" |
2907 | The specified sender is treated as if it were given as the argument to the | |
9b371988 | 2908 | &%-f%& option, but if a &%-f%& option is also present, its argument is used in |
168e428f PH |
2909 | preference to the address taken from the message. The caller of Exim must be a |
2910 | trusted user for the sender of a message to be set in this way. | |
2911 | ||
9b371988 PH |
2912 | .vitem &%-bnq%& |
2913 | .oindex "&%-bnq%&" | |
f89d2485 | 2914 | .cindex "address qualification, suppressing" |
168e428f PH |
2915 | By default, Exim automatically qualifies unqualified addresses (those |
2916 | without domains) that appear in messages that are submitted locally (that | |
2917 | is, not over TCP/IP). This qualification applies both to addresses in | |
2918 | envelopes, and addresses in header lines. Sender addresses are qualified using | |
9b371988 PH |
2919 | &%qualify_domain%&, and recipient addresses using &%qualify_recipient%& (which |
2920 | defaults to the value of &%qualify_domain%&). | |
2921 | ||
2922 | Sometimes, qualification is not wanted. For example, if &%-bS%& (batch SMTP) is | |
168e428f PH |
2923 | being used to re-submit messages that originally came from remote hosts after |
2924 | content scanning, you probably do not want to qualify unqualified addresses in | |
2925 | header lines. (Such lines will be present only if you have not enabled a header | |
2926 | syntax check in the appropriate ACL.) | |
9b371988 PH |
2927 | |
2928 | The &%-bnq%& option suppresses all qualification of unqualified addresses in | |
168e428f PH |
2929 | messages that originate on the local host. When this is used, unqualified |
2930 | addresses in the envelope provoke errors (causing message rejection) and | |
2931 | unqualified addresses in header lines are left alone. | |
2932 | ||
2933 | ||
9b371988 PH |
2934 | .vitem &%-bP%& |
2935 | .oindex "&%-bP%&" | |
595028e4 | 2936 | .cindex "configuration options" "extracting" |
9b371988 | 2937 | .cindex "options" "configuration &-- extracting" |
168e428f PH |
2938 | If this option is given with no arguments, it causes the values of all Exim's |
2939 | main configuration options to be written to the standard output. The values | |
2940 | of one or more specific options can be requested by giving their names as | |
2941 | arguments, for example: | |
9b371988 PH |
2942 | .code |
2943 | exim -bP qualify_domain hold_domains | |
2944 | .endd | |
595028e4 PH |
2945 | .cindex "hiding configuration option values" |
2946 | .cindex "configuration options" "hiding value of" | |
2947 | .cindex "options" "hiding value of" | |
9b371988 | 2948 | However, any option setting that is preceded by the word &"hide"& in the |
168e428f PH |
2949 | configuration file is not shown in full, except to an admin user. For other |
2950 | users, the output is as in this example: | |
9b371988 PH |
2951 | .code |
2952 | mysql_servers = <value not displayable> | |
2953 | .endd | |
2954 | If &%configure_file%& is given as an argument, the name of the run time | |
168e428f PH |
2955 | configuration file is output. |
2956 | If a list of configuration files was supplied, the value that is output here | |
2957 | is the name of the file that was actually used. | |
168e428f | 2958 | |
9b371988 PH |
2959 | .cindex "daemon" "process id (pid)" |
2960 | .cindex "pid (process id)" "of daemon" | |
2961 | If &%log_file_path%& or &%pid_file_path%& are given, the names of the | |
2962 | directories where log files and daemon pid files are written are output, | |
2963 | respectively. If these values are unset, log files are written in a | |
2964 | sub-directory of the spool directory called &%log%&, and the pid file is | |
2965 | written directly into the spool directory. | |
2966 | ||
2967 | If &%-bP%& is followed by a name preceded by &`+`&, for example, | |
2968 | .code | |
2969 | exim -bP +local_domains | |
2970 | .endd | |
168e428f PH |
2971 | it searches for a matching named list of any type (domain, host, address, or |
2972 | local part) and outputs what it finds. | |
9b371988 PH |
2973 | |
2974 | .cindex "options" "router &-- extracting" | |
2975 | .cindex "options" "transport &-- extracting" | |
5d9c27ec | 2976 | .cindex "options" "authenticator &-- extracting" |
9b371988 | 2977 | If one of the words &%router%&, &%transport%&, or &%authenticator%& is given, |
168e428f PH |
2978 | followed by the name of an appropriate driver instance, the option settings for |
2979 | that driver are output. For example: | |
9b371988 PH |
2980 | .code |
2981 | exim -bP transport local_delivery | |
2982 | .endd | |
168e428f PH |
2983 | The generic driver options are output first, followed by the driver's private |
2984 | options. A list of the names of drivers of a particular type can be obtained by | |
9b371988 PH |
2985 | using one of the words &%router_list%&, &%transport_list%&, or |
2986 | &%authenticator_list%&, and a complete list of all drivers with their option | |
2987 | settings can be obtained by using &%routers%&, &%transports%&, or | |
2988 | &%authenticators%&. | |
168e428f | 2989 | |
5d9c27ec TK |
2990 | .cindex "options" "macro &-- extracting" |
2991 | If invoked by an admin user, then &%macro%&, &%macro_list%& and &%macros%& | |
2992 | are available, similarly to the drivers. Because macros are sometimes used | |
2993 | for storing passwords, this option is restricted. | |
2994 | The output format is one item per line. | |
168e428f | 2995 | |
9b371988 PH |
2996 | .vitem &%-bp%& |
2997 | .oindex "&%-bp%&" | |
2998 | .cindex "queue" "listing messages on" | |
2999 | .cindex "listing" "messages on the queue" | |
168e428f | 3000 | This option requests a listing of the contents of the mail queue on the |
9b371988 | 3001 | standard output. If the &%-bp%& option is followed by a list of message ids, |
168e428f | 3002 | just those messages are listed. By default, this option can be used only by an |
9b371988 | 3003 | admin user. However, the &%queue_list_requires_admin%& option can be set false |
168e428f | 3004 | to allow any user to see the queue. |
168e428f | 3005 | |
9b371988 PH |
3006 | Each message on the queue is displayed as in the following example: |
3007 | .code | |
3008 | 25m 2.9K 0t5C6f-0000c8-00 <alice@wonderland.fict.example> | |
3009 | red.king@looking-glass.fict.example | |
3010 | <other addresses> | |
3011 | .endd | |
3012 | .cindex "message" "size in queue listing" | |
3013 | .cindex "size" "of message" | |
3014 | The first line contains the length of time the message has been on the queue | |
168e428f PH |
3015 | (in this case 25 minutes), the size of the message (2.9K), the unique local |
3016 | identifier for the message, and the message sender, as contained in the | |
3017 | envelope. For bounce messages, the sender address is empty, and appears as | |
9b371988 | 3018 | &"<>"&. If the message was submitted locally by an untrusted user who overrode |
168e428f PH |
3019 | the default sender address, the user's login name is shown in parentheses |
3020 | before the sender address. | |
9b371988 PH |
3021 | |
3022 | .cindex "frozen messages" "in queue listing" | |
3023 | If the message is frozen (attempts to deliver it are suspended) then the text | |
3024 | &"*** frozen ***"& is displayed at the end of this line. | |
3025 | ||
168e428f PH |
3026 | The recipients of the message (taken from the envelope, not the headers) are |
3027 | displayed on subsequent lines. Those addresses to which the message has already | |
3028 | been delivered are marked with the letter D. If an original address gets | |
3029 | expanded into several addresses via an alias or forward file, the original is | |
3030 | displayed with a D only when deliveries for all of its child addresses are | |
3031 | complete. | |
3032 | ||
3033 | ||
9b371988 PH |
3034 | .vitem &%-bpa%& |
3035 | .oindex "&%-bpa%&" | |
3036 | This option operates like &%-bp%&, but in addition it shows delivered addresses | |
168e428f | 3037 | that were generated from the original top level address(es) in each message by |
9b371988 PH |
3038 | alias or forwarding operations. These addresses are flagged with &"+D"& instead |
3039 | of just &"D"&. | |
168e428f PH |
3040 | |
3041 | ||
9b371988 PH |
3042 | .vitem &%-bpc%& |
3043 | .oindex "&%-bpc%&" | |
3044 | .cindex "queue" "count of messages on" | |
168e428f PH |
3045 | This option counts the number of messages on the queue, and writes the total |
3046 | to the standard output. It is restricted to admin users, unless | |
9b371988 | 3047 | &%queue_list_requires_admin%& is set false. |
168e428f PH |
3048 | |
3049 | ||
9b371988 PH |
3050 | .vitem &%-bpr%& |
3051 | .oindex "&%-bpr%&" | |
3052 | This option operates like &%-bp%&, but the output is not sorted into | |
168e428f PH |
3053 | chronological order of message arrival. This can speed it up when there are |
3054 | lots of messages on the queue, and is particularly useful if the output is | |
3055 | going to be post-processed in a way that doesn't need the sorting. | |
3056 | ||
9b371988 PH |
3057 | .vitem &%-bpra%& |
3058 | .oindex "&%-bpra%&" | |
3059 | This option is a combination of &%-bpr%& and &%-bpa%&. | |
168e428f | 3060 | |
9b371988 PH |
3061 | .vitem &%-bpru%& |
3062 | .oindex "&%-bpru%&" | |
3063 | This option is a combination of &%-bpr%& and &%-bpu%&. | |
168e428f PH |
3064 | |
3065 | ||
9b371988 PH |
3066 | .vitem &%-bpu%& |
3067 | .oindex "&%-bpu%&" | |
3068 | This option operates like &%-bp%& but shows only undelivered top-level | |
3069 | addresses for each message displayed. Addresses generated by aliasing or | |
3070 | forwarding are not shown, unless the message was deferred after processing by a | |
3071 | router with the &%one_time%& option set. | |
168e428f PH |
3072 | |
3073 | ||
9b371988 PH |
3074 | .vitem &%-brt%& |
3075 | .oindex "&%-brt%&" | |
3076 | .cindex "testing" "retry configuration" | |
3077 | .cindex "retry" "configuration testing" | |
168e428f PH |
3078 | This option is for testing retry rules, and it must be followed by up to three |
3079 | arguments. It causes Exim to look for a retry rule that matches the values | |
3080 | and to write it to the standard output. For example: | |
9b371988 PH |
3081 | .code |
3082 | exim -brt bach.comp.mus.example | |
3083 | Retry rule: *.comp.mus.example F,2h,15m; F,4d,30m; | |
3084 | .endd | |
3085 | See chapter &<<CHAPretry>>& for a description of Exim's retry rules. The first | |
168e428f | 3086 | argument, which is required, can be a complete address in the form |
4f578862 PH |
3087 | &'local_part@domain'&, or it can be just a domain name. If the second argument |
3088 | contains a dot, it is interpreted as an optional second domain name; if no | |
3089 | retry rule is found for the first argument, the second is tried. This ties in | |
3090 | with Exim's behaviour when looking for retry rules for remote hosts &-- if no | |
3091 | rule is found that matches the host, one that matches the mail domain is | |
3092 | sought. Finally, an argument that is the name of a specific delivery error, as | |
3093 | used in setting up retry rules, can be given. For example: | |
3094 | .code | |
3095 | exim -brt haydn.comp.mus.example quota_3d | |
3096 | Retry rule: *@haydn.comp.mus.example quota_3d F,1h,15m | |
3097 | .endd | |
168e428f | 3098 | |
9b371988 PH |
3099 | .vitem &%-brw%& |
3100 | .oindex "&%-brw%&" | |
3101 | .cindex "testing" "rewriting" | |
3102 | .cindex "rewriting" "testing" | |
168e428f PH |
3103 | This option is for testing address rewriting rules, and it must be followed by |
3104 | a single argument, consisting of either a local part without a domain, or a | |
3105 | complete address with a fully qualified domain. Exim outputs how this address | |
3106 | would be rewritten for each possible place it might appear. See chapter | |
9b371988 | 3107 | &<<CHAPrewrite>>& for further details. |
168e428f | 3108 | |
9b371988 PH |
3109 | .vitem &%-bS%& |
3110 | .oindex "&%-bS%&" | |
3111 | .cindex "SMTP" "batched incoming" | |
3112 | .cindex "batched SMTP input" | |
168e428f PH |
3113 | This option is used for batched SMTP input, which is an alternative interface |
3114 | for non-interactive local message submission. A number of messages can be | |
3115 | submitted in a single run. However, despite its name, this is not really SMTP | |
3116 | input. Exim reads each message's envelope from SMTP commands on the standard | |
3117 | input, but generates no responses. If the caller is trusted, or | |
9b371988 | 3118 | &%untrusted_set_sender%& is set, the senders in the SMTP MAIL commands are |
168e428f | 3119 | believed; otherwise the sender is always the caller of Exim. |
9b371988 | 3120 | |
168e428f PH |
3121 | The message itself is read from the standard input, in SMTP format (leading |
3122 | dots doubled), terminated by a line containing just a single dot. An error is | |
3123 | provoked if the terminating dot is missing. A further message may then follow. | |
9b371988 | 3124 | |
168e428f | 3125 | As for other local message submissions, the contents of incoming batch SMTP |
9b371988 PH |
3126 | messages can be checked using the non-SMTP ACL (see chapter &<<CHAPACL>>&). |
3127 | Unqualified addresses are automatically qualified using &%qualify_domain%& and | |
3128 | &%qualify_recipient%&, as appropriate, unless the &%-bnq%& option is used. | |
3129 | ||
168e428f PH |
3130 | Some other SMTP commands are recognized in the input. HELO and EHLO act |
3131 | as RSET; VRFY, EXPN, ETRN, and HELP act as NOOP; | |
3132 | QUIT quits, ignoring the rest of the standard input. | |
9b371988 PH |
3133 | |
3134 | .cindex "return code" "for &%-bS%&" | |
168e428f PH |
3135 | If any error is encountered, reports are written to the standard output and |
3136 | error streams, and Exim gives up immediately. The return code is 0 if no error | |
3137 | was detected; it is 1 if one or more messages were accepted before the error | |
3138 | was detected; otherwise it is 2. | |
9b371988 | 3139 | |
168e428f | 3140 | More details of input using batched SMTP are given in section |
9b371988 | 3141 | &<<SECTincomingbatchedSMTP>>&. |
168e428f | 3142 | |
9b371988 PH |
3143 | .vitem &%-bs%& |
3144 | .oindex "&%-bs%&" | |
3145 | .cindex "SMTP" "local input" | |
3146 | .cindex "local SMTP input" | |
168e428f PH |
3147 | This option causes Exim to accept one or more messages by reading SMTP commands |
3148 | on the standard input, and producing SMTP replies on the standard output. SMTP | |
9b371988 | 3149 | policy controls, as defined in ACLs (see chapter &<<CHAPACL>>&) are applied. |
168e428f PH |
3150 | Some user agents use this interface as a way of passing locally-generated |
3151 | messages to the MTA. | |
9b371988 | 3152 | |
168e428f | 3153 | In |
9b371988 PH |
3154 | .cindex "sender" "source of" |
3155 | this usage, if the caller of Exim is trusted, or &%untrusted_set_sender%& is | |
168e428f PH |
3156 | set, the senders of messages are taken from the SMTP MAIL commands. |
3157 | Otherwise the content of these commands is ignored and the sender is set up as | |
3158 | the calling user. Unqualified addresses are automatically qualified using | |
9b371988 PH |
3159 | &%qualify_domain%& and &%qualify_recipient%&, as appropriate, unless the |
3160 | &%-bnq%& option is used. | |
3161 | ||
3162 | .cindex "inetd" | |
168e428f | 3163 | The |
9b371988 PH |
3164 | &%-bs%& option is also used to run Exim from &'inetd'&, as an alternative to |
3165 | using a listening daemon. Exim can distinguish the two cases by checking | |
3166 | whether the standard input is a TCP/IP socket. When Exim is called from | |
3167 | &'inetd'&, the source of the mail is assumed to be remote, and the comments | |
3168 | above concerning senders and qualification do not apply. In this situation, | |
3169 | Exim behaves in exactly the same way as it does when receiving a message via | |
3170 | the listening daemon. | |
3171 | ||
3172 | .vitem &%-bt%& | |
3173 | .oindex "&%-bt%&" | |
3174 | .cindex "testing" "addresses" | |
3175 | .cindex "address" "testing" | |
168e428f | 3176 | This option runs Exim in address testing mode, in which each argument is taken |
595028e4 | 3177 | as a recipient address to be tested for deliverability. The results are |
f89d2485 PH |
3178 | written to the standard output. If a test fails, and the caller is not an admin |
3179 | user, no details of the failure are output, because these might contain | |
3180 | sensitive information such as usernames and passwords for database lookups. | |
9b371988 | 3181 | |
168e428f PH |
3182 | If no arguments are given, Exim runs in an interactive manner, prompting with a |
3183 | right angle bracket for addresses to be tested. | |
9b371988 PH |
3184 | |
3185 | Unlike the &%-be%& test option, you cannot arrange for Exim to use the | |
3186 | &[readline()]& function, because it is running as &'root'& and there are | |
168e428f | 3187 | security issues. |
9b371988 | 3188 | |
168e428f | 3189 | Each address is handled as if it were the recipient address of a message |
9b371988 | 3190 | (compare the &%-bv%& option). It is passed to the routers and the result is |
168e428f | 3191 | written to the standard output. However, any router that has |
9b371988 | 3192 | &%no_address_test%& set is bypassed. This can make &%-bt%& easier to use for |
168e428f PH |
3193 | genuine routing tests if your first router passes everything to a scanner |
3194 | program. | |
9b371988 | 3195 | |
9b371988 | 3196 | .cindex "return code" "for &%-bt%&" |
f89d2485 | 3197 | The return code is 2 if any address failed outright; it is 1 if no address |
168e428f PH |
3198 | failed outright but at least one could not be resolved for some reason. Return |
3199 | code 0 is given only when all addresses succeed. | |
9b371988 | 3200 | |
db9452a9 PH |
3201 | .cindex "duplicate addresses" |
3202 | &*Note*&: When actually delivering a message, Exim removes duplicate recipient | |
3203 | addresses after routing is complete, so that only one delivery takes place. | |
3204 | This does not happen when testing with &%-bt%&; the full results of routing are | |
3205 | always shown. | |
db9452a9 | 3206 | |
9b371988 | 3207 | &*Warning*&: &%-bt%& can only do relatively simple testing. If any of the |
168e428f PH |
3208 | routers in the configuration makes any tests on the sender address of a |
3209 | message, | |
f89d2485 | 3210 | .oindex "&%-f%&" "for address testing" |
9b371988 PH |
3211 | you can use the &%-f%& option to set an appropriate sender when running |
3212 | &%-bt%& tests. Without it, the sender is assumed to be the calling user at the | |
168e428f PH |
3213 | default qualifying domain. However, if you have set up (for example) routers |
3214 | whose behaviour depends on the contents of an incoming message, you cannot test | |
9b371988 | 3215 | those conditions using &%-bt%&. The &%-N%& option provides a possible way of |
168e428f PH |
3216 | doing such tests. |
3217 | ||
9b371988 PH |
3218 | .vitem &%-bV%& |
3219 | .oindex "&%-bV%&" | |
f89d2485 | 3220 | .cindex "version number of Exim" |
168e428f | 3221 | This option causes Exim to write the current version number, compilation |
9b371988 | 3222 | number, and compilation date of the &'exim'& binary to the standard output. |
168e428f PH |
3223 | It also lists the DBM library this is being used, the optional modules (such as |
3224 | specific lookup types), the drivers that are included in the binary, and the | |
3225 | name of the run time configuration file that is in use. | |
9b371988 PH |
3226 | |
3227 | As part of its operation, &%-bV%& causes Exim to read and syntax check its | |
168e428f PH |
3228 | configuration file. However, this is a static check only. It cannot check |
3229 | values that are to be expanded. For example, although a misspelt ACL verb is | |
9b371988 | 3230 | detected, an error in the verb's arguments is not. You cannot rely on &%-bV%& |
168e428f | 3231 | alone to discover (for example) all the typos in the configuration; some |
9b371988 PH |
3232 | realistic testing is needed. The &%-bh%& and &%-N%& options provide more |
3233 | dynamic testing facilities. | |
168e428f | 3234 | |
9b371988 PH |
3235 | .vitem &%-bv%& |
3236 | .oindex "&%-bv%&" | |
3237 | .cindex "verifying address" "using &%-bv%&" | |
3238 | .cindex "address" "verification" | |
168e428f | 3239 | This option runs Exim in address verification mode, in which each argument is |
595028e4 | 3240 | taken as a recipient address to be verified by the routers. (This does |
f89d2485 PH |
3241 | not involve any verification callouts). During normal operation, verification |
3242 | happens mostly as a consequence processing a &%verify%& condition in an ACL | |
3243 | (see chapter &<<CHAPACL>>&). If you want to test an entire ACL, possibly | |
3244 | including callouts, see the &%-bh%& and &%-bhc%& options. | |
9b371988 | 3245 | |
168e428f PH |
3246 | If verification fails, and the caller is not an admin user, no details of the |
3247 | failure are output, because these might contain sensitive information such as | |
3248 | usernames and passwords for database lookups. | |
9b371988 | 3249 | |
168e428f PH |
3250 | If no arguments are given, Exim runs in an interactive manner, prompting with a |
3251 | right angle bracket for addresses to be verified. | |
9b371988 PH |
3252 | |
3253 | Unlike the &%-be%& test option, you cannot arrange for Exim to use the | |
3254 | &[readline()]& function, because it is running as &'exim'& and there are | |
168e428f | 3255 | security issues. |
9b371988 PH |
3256 | |
3257 | Verification differs from address testing (the &%-bt%& option) in that routers | |
3258 | that have &%no_verify%& set are skipped, and if the address is accepted by a | |
3259 | router that has &%fail_verify%& set, verification fails. The address is | |
3260 | verified as a recipient if &%-bv%& is used; to test verification for a sender | |
3261 | address, &%-bvs%& should be used. | |
3262 | ||
3263 | If the &%-v%& option is not set, the output consists of a single line for each | |
168e428f | 3264 | address, stating whether it was verified or not, and giving a reason in the |
3cb1b51e PH |
3265 | latter case. Without &%-v%&, generating more than one address by redirection |
3266 | causes verification to end successfully, without considering the generated | |
3267 | addresses. However, if just one address is generated, processing continues, | |
3268 | and the generated address must verify successfully for the overall verification | |
3269 | to succeed. | |
3270 | ||
3271 | When &%-v%& is set, more details are given of how the address has been handled, | |
3272 | and in the case of address redirection, all the generated addresses are also | |
3273 | considered. Verification may succeed for some and fail for others. | |
9b371988 | 3274 | |
168e428f | 3275 | The |
9b371988 | 3276 | .cindex "return code" "for &%-bv%&" |
168e428f PH |
3277 | return code is 2 if any address failed outright; it is 1 if no address |
3278 | failed outright but at least one could not be resolved for some reason. Return | |
3279 | code 0 is given only when all addresses succeed. | |
9b371988 | 3280 | |
168e428f | 3281 | If any of the routers in the configuration makes any tests on the sender |
9b371988 PH |
3282 | address of a message, you should use the &%-f%& option to set an appropriate |
3283 | sender when running &%-bv%& tests. Without it, the sender is assumed to be the | |
168e428f PH |
3284 | calling user at the default qualifying domain. |
3285 | ||
9b371988 PH |
3286 | .vitem &%-bvs%& |
3287 | .oindex "&%-bvs%&" | |
3288 | This option acts like &%-bv%&, but verifies the address as a sender rather | |
168e428f PH |
3289 | than a recipient address. This affects any rewriting and qualification that |
3290 | might happen. | |
3291 | ||
9b371988 PH |
3292 | .vitem &%-C%&&~<&'filelist'&> |
3293 | .oindex "&%-C%&" | |
3294 | .cindex "configuration file" "alternate" | |
3295 | .cindex "CONFIGURE_FILE" | |
3296 | .cindex "alternate configuration file" | |
168e428f PH |
3297 | This option causes Exim to find the run time configuration file from the given |
3298 | list instead of from the list specified by the CONFIGURE_FILE | |
3299 | compile-time setting. Usually, the list will consist of just a single file | |
3300 | name, but it can be a colon-separated list of names. In this case, the first | |
3301 | file that exists is used. Failure to open an existing file stops Exim from | |
3302 | proceeding any further along the list, and an error is generated. | |
9b371988 | 3303 | |
168e428f PH |
3304 | When this option is used by a caller other than root or the Exim user, and the |
3305 | list is different from the compiled-in list, Exim gives up its root privilege | |
3306 | immediately, and runs with the real and effective uid and gid set to those of | |
3307 | the caller. However, if ALT_CONFIG_ROOT_ONLY is defined in | |
9b371988 | 3308 | &_Local/Makefile_&, root privilege is retained for &%-C%& only if the caller of |
168e428f | 3309 | Exim is root. |
9b371988 | 3310 | |
168e428f PH |
3311 | That is, the Exim user is no longer privileged in this regard. This build-time |
3312 | option is not set by default in the Exim source distribution tarbundle. | |
9b371988 PH |
3313 | However, if you are using a &"packaged"& version of Exim (source or binary), |
3314 | the packagers might have enabled it. | |
3315 | ||
168e428f | 3316 | Setting ALT_CONFIG_ROOT_ONLY locks out the possibility of testing a |
9b371988 PH |
3317 | configuration using &%-C%& right through message reception and delivery, even |
3318 | if the caller is root. The reception works, but by that time, Exim is running | |
3319 | as the Exim user, so when it re-executes to regain privilege for the delivery, | |
3320 | the use of &%-C%& causes privilege to be lost. However, root can test reception | |
3321 | and delivery using two separate commands (one to put a message on the queue, | |
3322 | using &%-odq%&, and another to do the delivery, using &%-M%&). | |
3323 | ||
3324 | If ALT_CONFIG_PREFIX is defined &_in Local/Makefile_&, it specifies a | |
3325 | prefix string with which any file named in a &%-C%& command line option | |
3326 | must start. In addition, the file name must not contain the sequence &`/../`&. | |
3327 | However, if the value of the &%-C%& option is identical to the value of | |
3328 | CONFIGURE_FILE in &_Local/Makefile_&, Exim ignores &%-C%& and proceeds as | |
168e428f | 3329 | usual. There is no default setting for ALT_CONFIG_PREFIX; when it is |
9b371988 PH |
3330 | unset, any file name can be used with &%-C%&. |
3331 | ||
168e428f PH |
3332 | ALT_CONFIG_PREFIX can be used to confine alternative configuration files |
3333 | to a directory to which only root has access. This prevents someone who has | |
3334 | broken into the Exim account from running a privileged Exim with an arbitrary | |
3335 | configuration file. | |
9b371988 PH |
3336 | |
3337 | The &%-C%& facility is useful for ensuring that configuration files are | |
168e428f PH |
3338 | syntactically correct, but cannot be used for test deliveries, unless the |
3339 | caller is privileged, or unless it is an exotic configuration that does not | |
3340 | require privilege. No check is made on the owner or group of the files | |
3341 | specified by this option. | |
3342 | ||
9b371988 PH |
3343 | .vitem &%-D%&<&'macro'&>=<&'value'&> |
3344 | .oindex "&%-D%&" | |
3345 | .cindex "macro" "setting on command line" | |
168e428f | 3346 | This option can be used to override macro definitions in the configuration file |
9b371988 | 3347 | (see section &<<SECTmacrodefs>>&). However, like &%-C%&, if it is used by an |
168e428f | 3348 | unprivileged caller, it causes Exim to give up its root privilege. |
9b371988 | 3349 | If DISABLE_D_OPTION is defined in &_Local/Makefile_&, the use of &%-D%& is |
168e428f | 3350 | completely disabled, and its use causes an immediate error exit. |
9b371988 | 3351 | |
168e428f | 3352 | The entire option (including equals sign if present) must all be within one |
9b371988 | 3353 | command line item. &%-D%& can be used to set the value of a macro to the empty |
168e428f PH |
3354 | string, in which case the equals sign is optional. These two commands are |
3355 | synonymous: | |
9b371988 PH |
3356 | .code |
3357 | exim -DABC ... | |
3358 | exim -DABC= ... | |
3359 | .endd | |
168e428f PH |
3360 | To include spaces in a macro definition item, quotes must be used. If you use |
3361 | quotes, spaces are permitted around the macro name and the equals sign. For | |
3362 | example: | |
9b371988 PH |
3363 | .code |
3364 | exim '-D ABC = something' ... | |
3365 | .endd | |
3366 | &%-D%& may be repeated up to 10 times on a command line. | |
3367 | ||
3368 | .vitem &%-d%&<&'debug&~options'&> | |
3369 | .oindex "&%-d%&" | |
3370 | .cindex "debugging" "list of selectors" | |
3371 | .cindex "debugging" "&%-d%& option" | |
168e428f PH |
3372 | This option causes debugging information to be written to the standard |
3373 | error stream. It is restricted to admin users because debugging output may show | |
3374 | database queries that contain password information. Also, the details of users' | |
f89d2485 | 3375 | filter files should be protected. If a non-admin user uses &%-d%&, Exim |
3cb1b51e | 3376 | writes an error message to the standard error stream and exits with a non-zero |
f89d2485 | 3377 | return code. |
3cb1b51e PH |
3378 | |
3379 | When &%-d%& is used, &%-v%& is assumed. If &%-d%& is given on its own, a lot of | |
3380 | standard debugging data is output. This can be reduced, or increased to include | |
3381 | some more rarely needed information, by directly following &%-d%& with a string | |
3382 | made up of names preceded by plus or minus characters. These add or remove sets | |
3383 | of debugging data, respectively. For example, &%-d+filter%& adds filter | |
3384 | debugging, whereas &%-d-all+filter%& selects only filter debugging. Note that | |
3385 | no spaces are allowed in the debug setting. The available debugging categories | |
3386 | are: | |
9b371988 PH |
3387 | .display |
3388 | &`acl `& ACL interpretation | |
3389 | &`auth `& authenticators | |
3390 | &`deliver `& general delivery logic | |
3391 | &`dns `& DNS lookups (see also resolver) | |
3392 | &`dnsbl `& DNS black list (aka RBL) code | |
3393 | &`exec `& arguments for &[execv()]& calls | |
3394 | &`expand `& detailed debugging for string expansions | |
3395 | &`filter `& filter handling | |
3396 | &`hints_lookup `& hints data lookups | |
3397 | &`host_lookup `& all types of name-to-IP address handling | |
3398 | &`ident `& ident lookup | |
3399 | &`interface `& lists of local interfaces | |
3400 | &`lists `& matching things in lists | |
3401 | &`load `& system load checks | |
3402 | &`local_scan `& can be used by &[local_scan()]& (see chapter &&& | |
3403 | &<<CHAPlocalscan>>&) | |
3404 | &`lookup `& general lookup code and all lookups | |
3405 | &`memory `& memory handling | |
3406 | &`pid `& add pid to debug output lines | |
3407 | &`process_info `& setting info for the process log | |
3408 | &`queue_run `& queue runs | |
3409 | &`receive `& general message reception logic | |
3410 | &`resolver `& turn on the DNS resolver's debugging output | |
3411 | &`retry `& retry handling | |
3412 | &`rewrite `& address rewriting | |
3413 | &`route `& address routing | |
3414 | &`timestamp `& add timestamp to debug output lines | |
3415 | &`tls `& TLS logic | |
3416 | &`transport `& transports | |
3417 | &`uid `& changes of uid/gid and looking up uid/gid | |
3418 | &`verify `& address verification logic | |
3419 | &`all `& almost all of the above (see below), and also &%-v%& | |
3420 | .endd | |
9b371988 PH |
3421 | The &`all`& option excludes &`memory`& when used as &`+all`&, but includes it |
3422 | for &`-all`&. The reason for this is that &`+all`& is something that people | |
3423 | tend to use when generating debug output for Exim maintainers. If &`+memory`& | |
3424 | is included, an awful lot of output that is very rarely of interest is | |
3425 | generated, so it now has to be explicitly requested. However, &`-all`& does | |
3426 | turn everything off. | |
9b371988 | 3427 | |
f89d2485 PH |
3428 | .cindex "resolver, debugging output" |
3429 | .cindex "DNS resolver, debugging output" | |
9b371988 | 3430 | The &`resolver`& option produces output only if the DNS resolver was compiled |
168e428f PH |
3431 | with DEBUG enabled. This is not the case in some operating systems. Also, |
3432 | unfortunately, debugging output from the DNS resolver is written to stdout | |
3433 | rather than stderr. | |
9b371988 PH |
3434 | |
3435 | The default (&%-d%& with no argument) omits &`expand`&, &`filter`&, | |
3436 | &`interface`&, &`load`&, &`memory`&, &`pid`&, &`resolver`&, and &`timestamp`&. | |
3437 | However, the &`pid`& selector is forced when debugging is turned on for a | |
168e428f PH |
3438 | daemon, which then passes it on to any re-executed Exims. Exim also |
3439 | automatically adds the pid to debug lines when several remote deliveries are | |
3440 | run in parallel. | |
9b371988 PH |
3441 | |
3442 | The &`timestamp`& selector causes the current time to be inserted at the start | |
168e428f PH |
3443 | of all debug output lines. This can be useful when trying to track down delays |
3444 | in processing. | |
168e428f | 3445 | |
9b371988 PH |
3446 | If the &%debug_print%& option is set in any driver, it produces output whenever |
3447 | any debugging is selected, or if &%-v%& is used. | |
3448 | ||
3449 | .vitem &%-dd%&<&'debug&~options'&> | |
3450 | .oindex "&%-dd%&" | |
3451 | This option behaves exactly like &%-d%& except when used on a command that | |
168e428f PH |
3452 | starts a daemon process. In that case, debugging is turned off for the |
3453 | subprocesses that the daemon creates. Thus, it is useful for monitoring the | |
3454 | behaviour of the daemon without creating as much output as full debugging does. | |
3455 | ||
9b371988 PH |
3456 | .vitem &%-dropcr%& |
3457 | .oindex "&%-dropcr%&" | |
168e428f PH |
3458 | This is an obsolete option that is now a no-op. It used to affect the way Exim |
3459 | handled CR and LF characters in incoming messages. What happens now is | |
9b371988 | 3460 | described in section &<<SECTlineendings>>&. |
168e428f | 3461 | |
9b371988 PH |
3462 | .vitem &%-E%& |
3463 | .oindex "&%-E%&" | |
3464 | .cindex "bounce message" "generating" | |
168e428f PH |
3465 | This option specifies that an incoming message is a locally-generated delivery |
3466 | failure report. It is used internally by Exim when handling delivery failures | |
3467 | and is not intended for external use. Its only effect is to stop Exim | |
3468 | generating certain messages to the postmaster, as otherwise message cascades | |
3469 | could occur in some situations. As part of the same option, a message id may | |
9b371988 PH |
3470 | follow the characters &%-E%&. If it does, the log entry for the receipt of the |
3471 | new message contains the id, following &"R="&, as a cross-reference. | |
3472 | ||
3473 | .vitem &%-e%&&'x'& | |
3474 | .oindex "&%-e%&&'x'&" | |
3475 | There are a number of Sendmail options starting with &%-oe%& which seem to be | |
3476 | called by various programs without the leading &%o%& in the option. For | |
3477 | example, the &%vacation%& program uses &%-eq%&. Exim treats all options of the | |
3478 | form &%-e%&&'x'& as synonymous with the corresponding &%-oe%&&'x'& options. | |
3479 | ||
3480 | .vitem &%-F%&&~<&'string'&> | |
3481 | .oindex "&%-F%&" | |
3482 | .cindex "sender" "name" | |
3483 | .cindex "name" "of sender" | |
168e428f | 3484 | This option sets the sender's full name for use when a locally-generated |
9b371988 | 3485 | message is being accepted. In the absence of this option, the user's &'gecos'& |
168e428f | 3486 | entry from the password data is used. As users are generally permitted to alter |
9b371988 PH |
3487 | their &'gecos'& entries, no security considerations are involved. White space |
3488 | between &%-F%& and the <&'string'&> is optional. | |
3489 | ||
3490 | .vitem &%-f%&&~<&'address'&> | |
3491 | .oindex "&%-f%&" | |
3492 | .cindex "sender" "address" | |
3493 | .cindex "address" "sender" | |
f89d2485 | 3494 | .cindex "trusted users" |
9b371988 PH |
3495 | .cindex "envelope sender" |
3496 | .cindex "user" "trusted" | |
168e428f PH |
3497 | This option sets the address of the envelope sender of a locally-generated |
3498 | message (also known as the return path). The option can normally be used only | |
9b371988 | 3499 | by a trusted user, but &%untrusted_set_sender%& can be set to allow untrusted |
168e428f | 3500 | users to use it. |
9b371988 | 3501 | |
168e428f | 3502 | Processes running as root or the Exim user are always trusted. Other |
9b371988 PH |
3503 | trusted users are defined by the &%trusted_users%& or &%trusted_groups%& |
3504 | options. In the absence of &%-f%&, or if the caller is not trusted, the sender | |
3505 | of a local message is set to the caller's login name at the default qualify | |
3506 | domain. | |
3507 | ||
3508 | There is one exception to the restriction on the use of &%-f%&: an empty sender | |
168e428f PH |
3509 | can be specified by any user, trusted or not, to create a message that can |
3510 | never provoke a bounce. An empty sender can be specified either as an empty | |
3511 | string, or as a pair of angle brackets with nothing between them, as in these | |
3512 | examples of shell commands: | |
9b371988 PH |
3513 | .code |
3514 | exim -f '<>' user@domain | |
3515 | exim -f "" user@domain | |
3516 | .endd | |
3517 | In addition, the use of &%-f%& is not restricted when testing a filter file | |
3518 | with &%-bf%& or when testing or verifying addresses using the &%-bt%& or | |
3519 | &%-bv%& options. | |
168e428f | 3520 | |
168e428f | 3521 | Allowing untrusted users to change the sender address does not of itself make |
9b371988 PH |
3522 | it possible to send anonymous mail. Exim still checks that the &'From:'& header |
3523 | refers to the local user, and if it does not, it adds a &'Sender:'& header, | |
3524 | though this can be overridden by setting &%no_local_from_check%&. | |
3525 | ||
168e428f | 3526 | White |
9b371988 PH |
3527 | .cindex "&""From""& line" |
3528 | space between &%-f%& and the <&'address'&> is optional (that is, they can be | |
3529 | given as two arguments or one combined argument). The sender of a | |
3530 | locally-generated message can also be set (when permitted) by an initial | |
3531 | &"From&~"& line in the message &-- see the description of &%-bm%& above &-- but | |
3532 | if &%-f%& is also present, it overrides &"From&~"&. | |
3533 | ||
3534 | .vitem &%-G%& | |
3535 | .oindex "&%-G%&" | |
3536 | .cindex "Sendmail compatibility" "&%-G%& option ignored" | |
168e428f PH |
3537 | This is a Sendmail option which is ignored by Exim. |
3538 | ||
9b371988 PH |
3539 | .vitem &%-h%&&~<&'number'&> |
3540 | .oindex "&%-h%&" | |
3541 | .cindex "Sendmail compatibility" "&%-h%& option ignored" | |
168e428f | 3542 | This option is accepted for compatibility with Sendmail, but has no effect. (In |
9b371988 | 3543 | Sendmail it overrides the &"hop count"& obtained by counting &'Received:'& |
168e428f PH |
3544 | headers.) |
3545 | ||
9b371988 PH |
3546 | .vitem &%-i%& |
3547 | .oindex "&%-i%&" | |
3548 | .cindex "Solaris" "&'mail'& command" | |
f89d2485 | 3549 | .cindex "dot" "in incoming non-SMTP message" |
9b371988 PH |
3550 | This option, which has the same effect as &%-oi%&, specifies that a dot on a |
3551 | line by itself should not terminate an incoming, non-SMTP message. I can find | |
3552 | no documentation for this option in Solaris 2.4 Sendmail, but the &'mailx'& | |
3553 | command in Solaris 2.4 uses it. See also &%-ti%&. | |
3554 | ||
3555 | .vitem &%-M%&&~<&'message&~id'&>&~<&'message&~id'&>&~... | |
3556 | .oindex "&%-M%&" | |
3557 | .cindex "forcing delivery" | |
3558 | .cindex "delivery" "forcing attempt" | |
3559 | .cindex "frozen messages" "forcing delivery" | |
168e428f PH |
3560 | This option requests Exim to run a delivery attempt on each message in turn. If |
3561 | any of the messages are frozen, they are automatically thawed before the | |
9b371988 PH |
3562 | delivery attempt. The settings of &%queue_domains%&, &%queue_smtp_domains%&, |
3563 | and &%hold_domains%& are ignored. | |
3564 | ||
168e428f | 3565 | Retry |
9b371988 PH |
3566 | .cindex "hints database" "overriding retry hints" |
3567 | hints for any of the addresses are overridden &-- Exim tries to deliver even if | |
168e428f | 3568 | the normal retry time has not yet been reached. This option requires the caller |
9b371988 | 3569 | to be an admin user. However, there is an option called &%prod_requires_admin%& |
168e428f | 3570 | which can be set false to relax this restriction (and also the same requirement |
9b371988 PH |
3571 | for the &%-q%&, &%-R%&, and &%-S%& options). |
3572 | ||
068aaea8 PH |
3573 | The deliveries happen synchronously, that is, the original Exim process does |
3574 | not terminate until all the delivery attempts have finished. No output is | |
3575 | produced unless there is a serious error. If you want to see what is happening, | |
9b371988 | 3576 | use the &%-v%& option as well, or inspect Exim's main log. |
168e428f | 3577 | |
9b371988 PH |
3578 | .vitem &%-Mar%&&~<&'message&~id'&>&~<&'address'&>&~<&'address'&>&~... |
3579 | .oindex "&%-Mar%&" | |
3580 | .cindex "message" "adding recipients" | |
3581 | .cindex "recipient" "adding" | |
168e428f | 3582 | This option requests Exim to add the addresses to the list of recipients of the |
9b371988 PH |
3583 | message (&"ar"& for &"add recipients"&). The first argument must be a message |
3584 | id, and the remaining ones must be email addresses. However, if the message is | |
168e428f PH |
3585 | active (in the middle of a delivery attempt), it is not altered. This option |
3586 | can be used only by an admin user. | |
3587 | ||
4f578862 | 3588 | .vitem "&%-MC%&&~<&'transport'&>&~<&'hostname'&>&~<&'sequence&~number'&>&&& |
9b371988 PH |
3589 | &~<&'message&~id'&>" |
3590 | .oindex "&%-MC%&" | |
3591 | .cindex "SMTP" "passed connection" | |
3592 | .cindex "SMTP" "multiple deliveries" | |
3593 | .cindex "multiple SMTP deliveries" | |
168e428f PH |
3594 | This option is not intended for use by external callers. It is used internally |
3595 | by Exim to invoke another instance of itself to deliver a waiting message using | |
3596 | an existing SMTP connection, which is passed as the standard input. Details are | |
9b371988 PH |
3597 | given in chapter &<<CHAPSMTP>>&. This must be the final option, and the caller |
3598 | must be root or the Exim user in order to use it. | |
168e428f | 3599 | |
9b371988 PH |
3600 | .vitem &%-MCA%& |
3601 | .oindex "&%-MCA%&" | |
168e428f | 3602 | This option is not intended for use by external callers. It is used internally |
9b371988 PH |
3603 | by Exim in conjunction with the &%-MC%& option. It signifies that the |
3604 | connection to the remote host has been authenticated. | |
168e428f | 3605 | |
9b371988 PH |
3606 | .vitem &%-MCP%& |
3607 | .oindex "&%-MCP%&" | |
168e428f | 3608 | This option is not intended for use by external callers. It is used internally |
9b371988 | 3609 | by Exim in conjunction with the &%-MC%& option. It signifies that the server to |
168e428f PH |
3610 | which Exim is connected supports pipelining. |
3611 | ||
9b371988 PH |
3612 | .vitem &%-MCQ%&&~<&'process&~id'&>&~<&'pipe&~fd'&> |
3613 | .oindex "&%-MCQ%&" | |
168e428f | 3614 | This option is not intended for use by external callers. It is used internally |
9b371988 | 3615 | by Exim in conjunction with the &%-MC%& option when the original delivery was |
168e428f PH |
3616 | started by a queue runner. It passes on the process id of the queue runner, |
3617 | together with the file descriptor number of an open pipe. Closure of the pipe | |
3618 | signals the final completion of the sequence of processes that are passing | |
3619 | messages through the same SMTP connection. | |
3620 | ||
9b371988 PH |
3621 | .vitem &%-MCS%& |
3622 | .oindex "&%-MCS%&" | |
168e428f | 3623 | This option is not intended for use by external callers. It is used internally |
9b371988 | 3624 | by Exim in conjunction with the &%-MC%& option, and passes on the fact that the |
168e428f PH |
3625 | SMTP SIZE option should be used on messages delivered down the existing |
3626 | connection. | |
3627 | ||
9b371988 PH |
3628 | .vitem &%-MCT%& |
3629 | .oindex "&%-MCT%&" | |
168e428f | 3630 | This option is not intended for use by external callers. It is used internally |
9b371988 | 3631 | by Exim in conjunction with the &%-MC%& option, and passes on the fact that the |
168e428f PH |
3632 | host to which Exim is connected supports TLS encryption. |
3633 | ||
9b371988 PH |
3634 | .vitem &%-Mc%&&~<&'message&~id'&>&~<&'message&~id'&>&~... |
3635 | .oindex "&%-Mc%&" | |
3636 | .cindex "hints database" "not overridden by &%-Mc%&" | |
3637 | .cindex "delivery" "manually started &-- not forced" | |
168e428f | 3638 | This option requests Exim to run a delivery attempt on each message in turn, |
9b371988 | 3639 | but unlike the &%-M%& option, it does check for retry hints, and respects any |
168e428f PH |
3640 | that are found. This option is not very useful to external callers. It is |
3641 | provided mainly for internal use by Exim when it needs to re-invoke itself in | |
9b371988 PH |
3642 | order to regain root privilege for a delivery (see chapter &<<CHAPsecurity>>&). |
3643 | However, &%-Mc%& can be useful when testing, in order to run a delivery that | |
3644 | respects retry times and other options such as &%hold_domains%& that are | |
3645 | overridden when &%-M%& is used. Such a delivery does not count as a queue run. | |
168e428f | 3646 | If you want to run a specific delivery as if in a queue run, you should use |
9b371988 | 3647 | &%-q%& with a message id argument. A distinction between queue run deliveries |
168e428f PH |
3648 | and other deliveries is made in one or two places. |
3649 | ||
9b371988 PH |
3650 | .vitem &%-Mes%&&~<&'message&~id'&>&~<&'address'&> |
3651 | .oindex "&%-Mes%&" | |
3652 | .cindex "message" "changing sender" | |
3653 | .cindex "sender" "changing" | |
168e428f | 3654 | This option requests Exim to change the sender address in the message to the |
9b371988 PH |
3655 | given address, which must be a fully qualified address or &"<>"& (&"es"& for |
3656 | &"edit sender"&). There must be exactly two arguments. The first argument must | |
3657 | be a message id, and the second one an email address. However, if the message | |
3658 | is active (in the middle of a delivery attempt), its status is not altered. | |
3659 | This option can be used only by an admin user. | |
3660 | ||
3661 | .vitem &%-Mf%&&~<&'message&~id'&>&~<&'message&~id'&>&~... | |
3662 | .oindex "&%-Mf%&" | |
3663 | .cindex "freezing messages" | |
3664 | .cindex "message" "manually freezing" | |
3665 | This option requests Exim to mark each listed message as &"frozen"&. This | |
3666 | prevents any delivery attempts taking place until the message is &"thawed"&, | |
3667 | either manually or as a result of the &%auto_thaw%& configuration option. | |
168e428f PH |
3668 | However, if any of the messages are active (in the middle of a delivery |
3669 | attempt), their status is not altered. This option can be used only by an admin | |
3670 | user. | |
3671 | ||
9b371988 PH |
3672 | .vitem &%-Mg%&&~<&'message&~id'&>&~<&'message&~id'&>&~... |
3673 | .oindex "&%-Mg%&" | |
3674 | .cindex "giving up on messages" | |
3675 | .cindex "message" "abandoning delivery attempts" | |
3676 | .cindex "delivery" "abandoning further attempts" | |
168e428f PH |
3677 | This option requests Exim to give up trying to deliver the listed messages, |
3678 | including any that are frozen. However, if any of the messages are active, | |
3679 | their status is not altered. For non-bounce messages, a delivery error message | |
9b371988 | 3680 | is sent to the sender, containing the text &"cancelled by administrator"&. |
168e428f PH |
3681 | Bounce messages are just discarded. This option can be used only by an admin |
3682 | user. | |
3683 | ||
9b371988 PH |
3684 | .vitem &%-Mmad%&&~<&'message&~id'&>&~<&'message&~id'&>&~... |
3685 | .oindex "&%-Mmad%&" | |
3686 | .cindex "delivery" "cancelling all" | |
168e428f | 3687 | This option requests Exim to mark all the recipient addresses in the messages |
9b371988 | 3688 | as already delivered (&"mad"& for &"mark all delivered"&). However, if any |
168e428f PH |
3689 | message is active (in the middle of a delivery attempt), its status is not |
3690 | altered. This option can be used only by an admin user. | |
3691 | ||
9b371988 PH |
3692 | .vitem &%-Mmd%&&~<&'message&~id'&>&~<&'address'&>&~<&'address'&>&~... |
3693 | .oindex "&%-Mmd%&" | |
3694 | .cindex "delivery" "cancelling by address" | |
3695 | .cindex "recipient" "removing" | |
3696 | .cindex "removing recipients" | |
168e428f | 3697 | This option requests Exim to mark the given addresses as already delivered |
9b371988 | 3698 | (&"md"& for &"mark delivered"&). The first argument must be a message id, and |
168e428f PH |
3699 | the remaining ones must be email addresses. These are matched to recipient |
3700 | addresses in the message in a case-sensitive manner. If the message is active | |
3701 | (in the middle of a delivery attempt), its status is not altered. This option | |
3702 | can be used only by an admin user. | |
3703 | ||
9b371988 PH |
3704 | .vitem &%-Mrm%&&~<&'message&~id'&>&~<&'message&~id'&>&~... |
3705 | .oindex "&%-Mrm%&" | |
3706 | .cindex "removing messages" | |
3707 | .cindex "abandoning mail" | |
3708 | .cindex "message" "manually discarding" | |
168e428f PH |
3709 | This option requests Exim to remove the given messages from the queue. No |
3710 | bounce messages are sent; each message is simply forgotten. However, if any of | |
3711 | the messages are active, their status is not altered. This option can be used | |
3712 | only by an admin user or by the user who originally caused the message to be | |
3713 | placed on the queue. | |
3714 | ||
3cb1b51e PH |
3715 | .vitem &%-Mset%&&~<&'message&~id'&> |
3716 | .oindex "&%-Mset%& | |
3717 | .cindex "testing" "string expansion" | |
3718 | .cindex "expansion" "testing" | |
3719 | This option is useful only in conjunction with &%-be%& (that is, when testing | |
3720 | string expansions). Exim loads the given message from its spool before doing | |
3721 | the test expansions, thus setting message-specific variables such as | |
3722 | &$message_size$& and the header variables. The &$recipients$& variable is made | |
3723 | available. This feature is provided to make it easier to test expansions that | |
3724 | make use of these variables. However, this option can be used only by an admin | |
3725 | user. See also &%-bem%&. | |
3cb1b51e | 3726 | |
9b371988 PH |
3727 | .vitem &%-Mt%&&~<&'message&~id'&>&~<&'message&~id'&>&~... |
3728 | .oindex "&%-Mt%&" | |
3729 | .cindex "thawing messages" | |
3730 | .cindex "unfreezing messages" | |
3731 | .cindex "frozen messages" "thawing" | |
3732 | .cindex "message" "thawing frozen" | |
3733 | This option requests Exim to &"thaw"& any of the listed messages that are | |
3734 | &"frozen"&, so that delivery attempts can resume. However, if any of the | |
3735 | messages are active, their status is not altered. This option can be used only | |
3736 | by an admin user. | |
3737 | ||
3738 | .vitem &%-Mvb%&&~<&'message&~id'&> | |
3739 | .oindex "&%-Mvb%&" | |
3740 | .cindex "listing" "message body" | |
3741 | .cindex "message" "listing body of" | |
168e428f PH |
3742 | This option causes the contents of the message body (-D) spool file to be |
3743 | written to the standard output. This option can be used only by an admin user. | |
3744 | ||
595028e4 PH |
3745 | .vitem &%-Mvc%&&~<&'message&~id'&> |
3746 | .oindex "&%-Mvc%&" | |
3747 | .cindex "message" "listing in RFC 2822 format" | |
3748 | .cindex "listing" "message in RFC 2922 format" | |
3749 | This option causes a copy of the complete message (header lines plus body) to | |
3750 | be written to the standard output in RFC 2822 format. This option can be used | |
3751 | only by an admin user. | |
595028e4 | 3752 | |
9b371988 PH |
3753 | .vitem &%-Mvh%&&~<&'message&~id'&> |
3754 | .oindex "&%-Mvh%&" | |
3755 | .cindex "listing" "message headers" | |
3756 | .cindex "header lines" "listing" | |
3757 | .cindex "message" "listing header lines" | |
168e428f PH |
3758 | This option causes the contents of the message headers (-H) spool file to be |
3759 | written to the standard output. This option can be used only by an admin user. | |
3760 | ||
9b371988 PH |
3761 | .vitem &%-Mvl%&&~<&'message&~id'&> |
3762 | .oindex "&%-Mvl%&" | |
3763 | .cindex "listing" "message log" | |
3764 | .cindex "message" "listing message log" | |
168e428f PH |
3765 | This option causes the contents of the message log spool file to be written to |
3766 | the standard output. This option can be used only by an admin user. | |
3767 | ||
9b371988 PH |
3768 | .vitem &%-m%& |
3769 | .oindex "&%-m%&" | |
3770 | This is apparently a synonym for &%-om%& that is accepted by Sendmail, so Exim | |
168e428f PH |
3771 | treats it that way too. |
3772 | ||
9b371988 PH |
3773 | .vitem &%-N%& |
3774 | .oindex "&%-N%&" | |
3775 | .cindex "debugging" "&%-N%& option" | |
3776 | .cindex "debugging" "suppressing delivery" | |
168e428f | 3777 | This is a debugging option that inhibits delivery of a message at the transport |
9b371988 | 3778 | level. It implies &%-v%&. Exim goes through many of the motions of delivery &-- |
168e428f PH |
3779 | it just doesn't actually transport the message, but instead behaves as if it |
3780 | had successfully done so. However, it does not make any updates to the retry | |
9b371988 PH |
3781 | database, and the log entries for deliveries are flagged with &"*>"& rather |
3782 | than &"=>"&. | |
3783 | ||
3784 | Because &%-N%& discards any message to which it applies, only root or the Exim | |
3785 | user are allowed to use it with &%-bd%&, &%-q%&, &%-R%& or &%-M%&. In other | |
3786 | words, an ordinary user can use it only when supplying an incoming message to | |
3787 | which it will apply. Although transportation never fails when &%-N%& is set, an | |
3788 | address may be deferred because of a configuration problem on a transport, or a | |
3789 | routing problem. Once &%-N%& has been used for a delivery attempt, it sticks to | |
3790 | the message, and applies to any subsequent delivery attempts that may happen | |
3791 | for that message. | |
3792 | ||
3793 | .vitem &%-n%& | |
3794 | .oindex "&%-n%&" | |
3795 | .cindex "Sendmail compatibility" "&%-n%& option ignored" | |
3796 | This option is interpreted by Sendmail to mean &"no aliasing"&. It is ignored | |
3797 | by Exim. | |
3798 | ||
3799 | .vitem &%-O%&&~<&'data'&> | |
3800 | .oindex "&%-O%&" | |
3801 | This option is interpreted by Sendmail to mean &`set option`&. It is ignored by | |
168e428f PH |
3802 | Exim. |
3803 | ||
9b371988 PH |
3804 | .vitem &%-oA%&&~<&'file&~name'&> |
3805 | .oindex "&%-oA%&" | |
3806 | .cindex "Sendmail compatibility" "&%-oA%& option" | |
3807 | This option is used by Sendmail in conjunction with &%-bi%& to specify an | |
3808 | alternative alias file name. Exim handles &%-bi%& differently; see the | |
168e428f PH |
3809 | description above. |
3810 | ||
9b371988 PH |
3811 | .vitem &%-oB%&&~<&'n'&> |
3812 | .oindex "&%-oB%&" | |
3813 | .cindex "SMTP" "passed connection" | |
3814 | .cindex "SMTP" "multiple deliveries" | |
3815 | .cindex "multiple SMTP deliveries" | |
168e428f | 3816 | This is a debugging option which limits the maximum number of messages that can |
9b371988 PH |
3817 | be delivered down one SMTP connection, overriding the value set in any &(smtp)& |
3818 | transport. If <&'n'&> is omitted, the limit is set to 1. | |
168e428f | 3819 | |
9b371988 PH |
3820 | .vitem &%-odb%& |
3821 | .oindex "&%-odb%&" | |
3822 | .cindex "background delivery" | |
3823 | .cindex "delivery" "in the background" | |
168e428f | 3824 | This option applies to all modes in which Exim accepts incoming messages, |
9b371988 | 3825 | including the listening daemon. It requests &"background"& delivery of such |
168e428f PH |
3826 | messages, which means that the accepting process automatically starts a |
3827 | delivery process for each message received, but does not wait for the delivery | |
3828 | processes to finish. | |
9b371988 | 3829 | |
168e428f PH |
3830 | When all the messages have been received, the reception process exits, |
3831 | leaving the delivery processes to finish in their own time. The standard output | |
3832 | and error streams are closed at the start of each delivery process. | |
9b371988 PH |
3833 | This is the default action if none of the &%-od%& options are present. |
3834 | ||
168e428f | 3835 | If one of the queueing options in the configuration file |
9b371988 PH |
3836 | (&%queue_only%& or &%queue_only_file%&, for example) is in effect, &%-odb%& |
3837 | overrides it if &%queue_only_override%& is set true, which is the default | |
3838 | setting. If &%queue_only_override%& is set false, &%-odb%& has no effect. | |
3839 | ||
3840 | .vitem &%-odf%& | |
3841 | .oindex "&%-odf%&" | |
3842 | .cindex "foreground delivery" | |
3843 | .cindex "delivery" "in the foreground" | |
3844 | This option requests &"foreground"& (synchronous) delivery when Exim has | |
3845 | accepted a locally-generated message. (For the daemon it is exactly the same as | |
3846 | &%-odb%&.) A delivery process is automatically started to deliver the message, | |
3847 | and Exim waits for it to complete before proceeding. | |
3848 | ||
168e428f PH |
3849 | The original Exim reception process does not finish until the delivery |
3850 | process for the final message has ended. The standard error stream is left open | |
3851 | during deliveries. | |
9b371988 PH |
3852 | |
3853 | However, like &%-odb%&, this option has no effect if &%queue_only_override%& is | |
168e428f | 3854 | false and one of the queueing options in the configuration file is in effect. |
9b371988 | 3855 | |
168e428f PH |
3856 | If there is a temporary delivery error during foreground delivery, the |
3857 | message is left on the queue for later delivery, and the original reception | |
9b371988 | 3858 | process exits. See chapter &<<CHAPnonqueueing>>& for a way of setting up a |
168e428f PH |
3859 | restricted configuration that never queues messages. |
3860 | ||
3861 | ||
9b371988 PH |
3862 | .vitem &%-odi%& |
3863 | .oindex "&%-odi%&" | |
3864 | This option is synonymous with &%-odf%&. It is provided for compatibility with | |
168e428f PH |
3865 | Sendmail. |
3866 | ||
9b371988 PH |
3867 | .vitem &%-odq%& |
3868 | .oindex "&%-odq%&" | |
3869 | .cindex "non-immediate delivery" | |
3870 | .cindex "delivery" "suppressing immediate" | |
3871 | .cindex "queueing incoming messages" | |
168e428f PH |
3872 | This option applies to all modes in which Exim accepts incoming messages, |
3873 | including the listening daemon. It specifies that the accepting process should | |
3874 | not automatically start a delivery process for each message received. Messages | |
3875 | are placed on the queue, and remain there until a subsequent queue runner | |
3876 | process encounters them. There are several configuration options (such as | |
9b371988 PH |
3877 | &%queue_only%&) that can be used to queue incoming messages under certain |
3878 | conditions. This option overrides all of them and also &%-odqs%&. It always | |
168e428f PH |
3879 | forces queueing. |
3880 | ||
9b371988 PH |
3881 | .vitem &%-odqs%& |
3882 | .oindex "&%-odqs%&" | |
3883 | .cindex "SMTP" "delaying delivery" | |
3884 | This option is a hybrid between &%-odb%&/&%-odi%& and &%-odq%&. | |
3885 | However, like &%-odb%& and &%-odi%&, this option has no effect if | |
3886 | &%queue_only_override%& is false and one of the queueing options in the | |
168e428f | 3887 | configuration file is in effect. |
9b371988 PH |
3888 | |
3889 | When &%-odqs%& does operate, a delivery process is started for each incoming | |
3890 | message, in the background by default, but in the foreground if &%-odi%& is | |
3891 | also present. The recipient addresses are routed, and local deliveries are done | |
3892 | in the normal way. However, if any SMTP deliveries are required, they are not | |
3893 | done at this time, so the message remains on the queue until a subsequent queue | |
168e428f PH |
3894 | runner process encounters it. Because routing was done, Exim knows which |
3895 | messages are waiting for which hosts, and so a number of messages for the same | |
9b371988 | 3896 | host can be sent in a single SMTP connection. The &%queue_smtp_domains%& |
168e428f | 3897 | configuration option has the same effect for specific domains. See also the |
9b371988 | 3898 | &%-qq%& option. |
168e428f | 3899 | |
9b371988 PH |
3900 | .vitem &%-oee%& |
3901 | .oindex "&%-oee%&" | |
3902 | .cindex "error" "reporting" | |
168e428f PH |
3903 | If an error is detected while a non-SMTP message is being received (for |
3904 | example, a malformed address), the error is reported to the sender in a mail | |
3905 | message. | |
9b371988 PH |
3906 | |
3907 | .cindex "return code" "for &%-oee%&" | |
168e428f | 3908 | Provided |
168e428f PH |
3909 | this error message is successfully sent, the Exim receiving process |
3910 | exits with a return code of zero. If not, the return code is 2 if the problem | |
3911 | is that the original message has no recipients, or 1 any other error. This is | |
9b371988 | 3912 | the default &%-oe%&&'x'& option if Exim is called as &'rmail'&. |
168e428f | 3913 | |
9b371988 PH |
3914 | .vitem &%-oem%& |
3915 | .oindex "&%-oem%&" | |
3916 | .cindex "error" "reporting" | |
3917 | .cindex "return code" "for &%-oem%&" | |
3918 | This is the same as &%-oee%&, except that Exim always exits with a non-zero | |
168e428f | 3919 | return code, whether or not the error message was successfully sent. |
9b371988 | 3920 | This is the default &%-oe%&&'x'& option, unless Exim is called as &'rmail'&. |
168e428f | 3921 | |
9b371988 PH |
3922 | .vitem &%-oep%& |
3923 | .oindex "&%-oep%&" | |
3924 | .cindex "error" "reporting" | |
168e428f PH |
3925 | If an error is detected while a non-SMTP message is being received, the |
3926 | error is reported by writing a message to the standard error file (stderr). | |
9b371988 | 3927 | .cindex "return code" "for &%-oep%&" |
168e428f PH |
3928 | The return code is 1 for all errors. |
3929 | ||
9b371988 PH |
3930 | .vitem &%-oeq%& |
3931 | .oindex "&%-oeq%&" | |
3932 | .cindex "error" "reporting" | |
168e428f | 3933 | This option is supported for compatibility with Sendmail, but has the same |
9b371988 | 3934 | effect as &%-oep%&. |
168e428f | 3935 | |
9b371988 PH |
3936 | .vitem &%-oew%& |
3937 | .oindex "&%-oew%&" | |
3938 | .cindex "error" "reporting" | |
168e428f | 3939 | This option is supported for compatibility with Sendmail, but has the same |
9b371988 PH |
3940 | effect as &%-oem%&. |
3941 | ||
3942 | .vitem &%-oi%& | |
3943 | .oindex "&%-oi%&" | |
f89d2485 | 3944 | .cindex "dot" "in incoming non-SMTP message" |
9b371988 PH |
3945 | This option, which has the same effect as &%-i%&, specifies that a dot on a |
3946 | line by itself should not terminate an incoming, non-SMTP message. Otherwise, a | |
3947 | single dot does terminate, though Exim does no special processing for other | |
3948 | lines that start with a dot. This option is set by default if Exim is called as | |
3949 | &'rmail'&. See also &%-ti%&. | |
3950 | ||
3951 | .vitem &%-oitrue%& | |
3952 | .oindex "&%-oitrue%&" | |
3953 | This option is treated as synonymous with &%-oi%&. | |
3954 | ||
3955 | .vitem &%-oMa%&&~<&'host&~address'&> | |
3956 | .oindex "&%-oMa%&" | |
f89d2485 | 3957 | .cindex "sender" "host address, specifying for local message" |
9b371988 | 3958 | A number of options starting with &%-oM%& can be used to set values associated |
168e428f PH |
3959 | with remote hosts on locally-submitted messages (that is, messages not received |
3960 | over TCP/IP). These options can be used by any caller in conjunction with the | |
9b371988 PH |
3961 | &%-bh%&, &%-be%&, &%-bf%&, &%-bF%&, &%-bt%&, or &%-bv%& testing options. In |
3962 | other circumstances, they are ignored unless the caller is trusted. | |
3963 | ||
3964 | The &%-oMa%& option sets the sender host address. This may include a port | |
3965 | number at the end, after a full stop (period). For example: | |
3966 | .code | |
3967 | exim -bs -oMa 10.9.8.7.1234 | |
3968 | .endd | |
168e428f PH |
3969 | An alternative syntax is to enclose the IP address in square brackets, |
3970 | followed by a colon and the port number: | |
9b371988 PH |
3971 | .code |
3972 | exim -bs -oMa [10.9.8.7]:1234 | |
3973 | .endd | |
3974 | The IP address is placed in the &$sender_host_address$& variable, and the | |
3cb1b51e | 3975 | port, if present, in &$sender_host_port$&. If both &%-oMa%& and &%-bh%& |
db9452a9 | 3976 | are present on the command line, the sender host IP address is taken from |
3cb1b51e | 3977 | whichever one is last. |
9b371988 PH |
3978 | |
3979 | .vitem &%-oMaa%&&~<&'name'&> | |
3980 | .oindex "&%-oMaa%&" | |
f89d2485 | 3981 | .cindex "authentication" "name, specifying for local message" |
9b371988 PH |
3982 | See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMaa%& |
3983 | option sets the value of &$sender_host_authenticated$& (the authenticator | |
3984 | name). See chapter &<<CHAPSMTPAUTH>>& for a discussion of SMTP authentication. | |
3cb1b51e PH |
3985 | This option can be used with &%-bh%& and &%-bs%& to set up an |
3986 | authenticated SMTP session without actually using the SMTP AUTH command. | |
9b371988 PH |
3987 | |
3988 | .vitem &%-oMai%&&~<&'string'&> | |
3989 | .oindex "&%-oMai%&" | |
f89d2485 | 3990 | .cindex "authentication" "id, specifying for local message" |
9b371988 PH |
3991 | See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMai%& |
3992 | option sets the value of &$authenticated_id$& (the id that was authenticated). | |
db9452a9 PH |
3993 | This overrides the default value (the caller's login id, except with &%-bh%&, |
3994 | where there is no default) for messages from local sources. See chapter | |
3995 | &<<CHAPSMTPAUTH>>& for a discussion of authenticated ids. | |
168e428f | 3996 | |
9b371988 PH |
3997 | .vitem &%-oMas%&&~<&'address'&> |
3998 | .oindex "&%-oMas%&" | |
f89d2485 | 3999 | .cindex "authentication" "sender, specifying for local message" |
9b371988 PH |
4000 | See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMas%& |
4001 | option sets the authenticated sender value in &$authenticated_sender$&. It | |
168e428f | 4002 | overrides the sender address that is created from the caller's login id for |
db9452a9 PH |
4003 | messages from local sources, except when &%-bh%& is used, when there is no |
4004 | default. For both &%-bh%& and &%-bs%&, an authenticated sender that is | |
4005 | specified on a MAIL command overrides this value. See chapter | |
4006 | &<<CHAPSMTPAUTH>>& for a discussion of authenticated senders. | |
168e428f | 4007 | |
9b371988 PH |
4008 | .vitem &%-oMi%&&~<&'interface&~address'&> |
4009 | .oindex "&%-oMi%&" | |
f89d2485 | 4010 | .cindex "interface" "address, specifying for local message" |
9b371988 PH |
4011 | See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMi%& |
4012 | option sets the IP interface address value. A port number may be included, | |
4013 | using the same syntax as for &%-oMa%&. The interface address is placed in | |
3cb1b51e | 4014 | &$received_ip_address$& and the port number, if present, in &$received_port$&. |
9b371988 PH |
4015 | |
4016 | .vitem &%-oMr%&&~<&'protocol&~name'&> | |
4017 | .oindex "&%-oMr%&" | |
f89d2485 PH |
4018 | .cindex "protocol, specifying for local message" |
4019 | .vindex "&$received_protocol$&" | |
9b371988 PH |
4020 | See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMr%& |
4021 | option sets the received protocol value that is stored in | |
db9452a9 PH |
4022 | &$received_protocol$&. However, it does not apply (and is ignored) when &%-bh%& |
4023 | or &%-bs%& is used. For &%-bh%&, the protocol is forced to one of the standard | |
4024 | SMTP protocol names (see the description of &$received_protocol$& in section | |
4025 | &<<SECTexpvar>>&). For &%-bs%&, the protocol is always &"local-"& followed by | |
4026 | one of those same names. For &%-bS%& (batched SMTP) however, the protocol can | |
4027 | be set by &%-oMr%&. | |
9b371988 PH |
4028 | |
4029 | .vitem &%-oMs%&&~<&'host&~name'&> | |
4030 | .oindex "&%-oMs%&" | |
f89d2485 | 4031 | .cindex "sender" "host name, specifying for local message" |
9b371988 PH |
4032 | See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMs%& |
4033 | option sets the sender host name in &$sender_host_name$&. When this option is | |
4034 | present, Exim does not attempt to look up a host name from an IP address; it | |
4035 | uses the name it is given. | |
4036 | ||
4037 | .vitem &%-oMt%&&~<&'ident&~string'&> | |
4038 | .oindex "&%-oMt%&" | |
f89d2485 | 4039 | .cindex "sender" "ident string, specifying for local message" |
9b371988 PH |
4040 | See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMt%& |
4041 | option sets the sender ident value in &$sender_ident$&. The default setting for | |
db9452a9 PH |
4042 | local callers is the login id of the calling process, except when &%-bh%& is |
4043 | used, when there is no default. | |
9b371988 PH |
4044 | |
4045 | .vitem &%-om%& | |
4046 | .oindex "&%-om%&" | |
4047 | .cindex "Sendmail compatibility" "&%-om%& option ignored" | |
4048 | In Sendmail, this option means &"me too"&, indicating that the sender of a | |
168e428f PH |
4049 | message should receive a copy of the message if the sender appears in an alias |
4050 | expansion. Exim always does this, so the option does nothing. | |
4051 | ||
9b371988 PH |
4052 | .vitem &%-oo%& |
4053 | .oindex "&%-oo%&" | |
4054 | .cindex "Sendmail compatibility" "&%-oo%& option ignored" | |
4055 | This option is ignored. In Sendmail it specifies &"old style headers"&, | |
4056 | whatever that means. | |
4057 | ||
4058 | .vitem &%-oP%&&~<&'path'&> | |
4059 | .oindex "&%-oP%&" | |
4060 | .cindex "pid (process id)" "of daemon" | |
4061 | .cindex "daemon" "process id (pid)" | |
4062 | This option is useful only in conjunction with &%-bd%& or &%-q%& with a time | |
168e428f | 4063 | value. The option specifies the file to which the process id of the daemon is |
9b371988 PH |
4064 | written. When &%-oX%& is used with &%-bd%&, or when &%-q%& with a time is used |
4065 | without &%-bd%&, this is the only way of causing Exim to write a pid file, | |
168e428f PH |
4066 | because in those cases, the normal pid file is not used. |
4067 | ||
9b371988 PH |
4068 | .vitem &%-or%&&~<&'time'&> |
4069 | .oindex "&%-or%&" | |
4070 | .cindex "timeout" "for non-SMTP input" | |
168e428f PH |
4071 | This option sets a timeout value for incoming non-SMTP messages. If it is not |
4072 | set, Exim will wait forever for the standard input. The value can also be set | |
9b371988 PH |
4073 | by the &%receive_timeout%& option. The format used for specifying times is |
4074 | described in section &<<SECTtimeformat>>&. | |
168e428f | 4075 | |
9b371988 PH |
4076 | .vitem &%-os%&&~<&'time'&> |
4077 | .oindex "&%-os%&" | |
4078 | .cindex "timeout" "for SMTP input" | |
f89d2485 | 4079 | .cindex "SMTP" "input timeout" |
168e428f PH |
4080 | This option sets a timeout value for incoming SMTP messages. The timeout |
4081 | applies to each SMTP command and block of data. The value can also be set by | |
9b371988 PH |
4082 | the &%smtp_receive_timeout%& option; it defaults to 5 minutes. The format used |
4083 | for specifying times is described in section &<<SECTtimeformat>>&. | |
4084 | ||
4085 | .vitem &%-ov%& | |
4086 | .oindex "&%-ov%&" | |
4087 | This option has exactly the same effect as &%-v%&. | |
4088 | ||
4089 | .vitem &%-oX%&&~<&'number&~or&~string'&> | |
4090 | .oindex "&%-oX%&" | |
4091 | .cindex "TCP/IP" "setting listening ports" | |
4092 | .cindex "TCP/IP" "setting listening interfaces" | |
4093 | .cindex "port" "receiving TCP/IP" | |
4094 | This option is relevant only when the &%-bd%& (start listening daemon) option | |
4095 | is also given. It controls which ports and interfaces the daemon uses. Details | |
4096 | of the syntax, and how it interacts with configuration file options, are given | |
4097 | in chapter &<<CHAPinterfaces>>&. When &%-oX%& is used to start a daemon, no pid | |
4098 | file is written unless &%-oP%& is also present to specify a pid file name. | |
4099 | ||
4100 | .vitem &%-pd%& | |
4101 | .oindex "&%-pd%&" | |
4102 | .cindex "Perl" "starting the interpreter" | |
168e428f | 4103 | This option applies when an embedded Perl interpreter is linked with Exim (see |
9b371988 PH |
4104 | chapter &<<CHAPperl>>&). It overrides the setting of the &%perl_at_start%& |
4105 | option, forcing the starting of the interpreter to be delayed until it is | |
4106 | needed. | |
168e428f | 4107 | |
9b371988 PH |
4108 | .vitem &%-ps%& |
4109 | .oindex "&%-ps%&" | |
4110 | .cindex "Perl" "starting the interpreter" | |
168e428f | 4111 | This option applies when an embedded Perl interpreter is linked with Exim (see |
9b371988 PH |
4112 | chapter &<<CHAPperl>>&). It overrides the setting of the &%perl_at_start%& |
4113 | option, forcing the starting of the interpreter to occur as soon as Exim is | |
4114 | started. | |
168e428f | 4115 | |
9b371988 PH |
4116 | .vitem &%-p%&<&'rval'&>:<&'sval'&> |
4117 | .oindex "&%-p%&" | |
168e428f | 4118 | For compatibility with Sendmail, this option is equivalent to |
9b371988 PH |
4119 | .display |
4120 | &`-oMr`& <&'rval'&> &`-oMs`& <&'sval'&> | |
4121 | .endd | |
168e428f PH |
4122 | It sets the incoming protocol and host name (for trusted callers). The |
4123 | host name and its colon can be omitted when only the protocol is to be set. | |
9b371988 PH |
4124 | Note the Exim already has two private options, &%-pd%& and &%-ps%&, that refer |
4125 | to embedded Perl. It is therefore impossible to set a protocol value of &`p`& | |
4126 | or &`s`& using this option (but that does not seem a real limitation). | |
168e428f | 4127 | |
9b371988 PH |
4128 | .vitem &%-q%& |
4129 | .oindex "&%-q%&" | |
4130 | .cindex "queue runner" "starting manually" | |
168e428f | 4131 | This option is normally restricted to admin users. However, there is a |
9b371988 PH |
4132 | configuration option called &%prod_requires_admin%& which can be set false to |
4133 | relax this restriction (and also the same requirement for the &%-M%&, &%-R%&, | |
4134 | and &%-S%& options). | |
4135 | ||
4136 | .cindex "queue runner" "description of operation" | |
4137 | The &%-q%& option starts one queue runner process. This scans the queue of | |
168e428f PH |
4138 | waiting messages, and runs a delivery process for each one in turn. It waits |
4139 | for each delivery process to finish before starting the next one. A delivery | |
4140 | process may not actually do any deliveries if the retry times for the addresses | |
9b371988 PH |
4141 | have not been reached. Use &%-qf%& (see below) if you want to override this. |
4142 | ||
168e428f | 4143 | If |
9b371988 PH |
4144 | .cindex "SMTP" "passed connection" |
4145 | .cindex "SMTP" "multiple deliveries" | |
4146 | .cindex "multiple SMTP deliveries" | |
168e428f PH |
4147 | the delivery process spawns other processes to deliver other messages down |
4148 | passed SMTP connections, the queue runner waits for these to finish before | |
4149 | proceeding. | |
9b371988 | 4150 | |
168e428f PH |
4151 | When all the queued messages have been considered, the original queue runner |
4152 | process terminates. In other words, a single pass is made over the waiting | |
9b371988 PH |
4153 | mail, one message at a time. Use &%-q%& with a time (see below) if you want |
4154 | this to be repeated periodically. | |
4155 | ||
168e428f PH |
4156 | Exim processes the waiting messages in an unpredictable order. It isn't very |
4157 | random, but it is likely to be different each time, which is all that matters. | |
4158 | If one particular message screws up a remote MTA, other messages to the same | |
4159 | MTA have a chance of getting through if they get tried first. | |
9b371988 | 4160 | |
168e428f PH |
4161 | It is possible to cause the messages to be processed in lexical message id |
4162 | order, which is essentially the order in which they arrived, by setting the | |
9b371988 | 4163 | &%queue_run_in_order%& option, but this is not recommended for normal use. |
168e428f | 4164 | |
9b371988 PH |
4165 | .vitem &%-q%&<&'qflags'&> |
4166 | The &%-q%& option may be followed by one or more flag letters that change its | |
168e428f PH |
4167 | behaviour. They are all optional, but if more than one is present, they must |
4168 | appear in the correct order. Each flag is described in a separate item below. | |
4169 | ||
9b371988 PH |
4170 | .vitem &%-qq...%& |
4171 | .oindex "&%-qq%&" | |
4172 | .cindex "queue" "double scanning" | |
4173 | .cindex "queue" "routing" | |
4174 | .cindex "routing" "whole queue before delivery" | |
4175 | An option starting with &%-qq%& requests a two-stage queue run. In the first | |
4176 | stage, the queue is scanned as if the &%queue_smtp_domains%& option matched | |
168e428f PH |
4177 | every domain. Addresses are routed, local deliveries happen, but no remote |
4178 | transports are run. | |
9b371988 PH |
4179 | |
4180 | .cindex "hints database" "remembering routing" | |
4181 | The hints database that remembers which messages are waiting for specific hosts | |
4182 | is updated, as if delivery to those hosts had been deferred. After this is | |
168e428f PH |
4183 | complete, a second, normal queue scan happens, with routing and delivery taking |
4184 | place as normal. Messages that are routed to the same host should mostly be | |
4185 | delivered down a single SMTP | |
9b371988 PH |
4186 | .cindex "SMTP" "passed connection" |
4187 | .cindex "SMTP" "multiple deliveries" | |
4188 | .cindex "multiple SMTP deliveries" | |
168e428f PH |
4189 | connection because of the hints that were set up during the first queue scan. |
4190 | This option may be useful for hosts that are connected to the Internet | |
4191 | intermittently. | |
4192 | ||
9b371988 PH |
4193 | .vitem &%-q[q]i...%& |
4194 | .oindex "&%-qi%&" | |
4195 | .cindex "queue" "initial delivery" | |
4196 | If the &'i'& flag is present, the queue runner runs delivery processes only for | |
4197 | those messages that haven't previously been tried. (&'i'& stands for &"initial | |
4198 | delivery"&.) This can be helpful if you are putting messages on the queue using | |
4199 | &%-odq%& and want a queue runner just to process the new messages. | |
4200 | ||
4201 | .vitem &%-q[q][i]f...%& | |
4202 | .oindex "&%-qf%&" | |
4203 | .cindex "queue" "forcing delivery" | |
4204 | .cindex "delivery" "forcing in queue run" | |
4205 | If one &'f'& flag is present, a delivery attempt is forced for each non-frozen | |
4206 | message, whereas without &'f'& only those non-frozen addresses that have passed | |
168e428f PH |
4207 | their retry times are tried. |
4208 | ||
9b371988 PH |
4209 | .vitem &%-q[q][i]ff...%& |
4210 | .oindex "&%-qff%&" | |
4211 | .cindex "frozen messages" "forcing delivery" | |
4212 | If &'ff'& is present, a delivery attempt is forced for every message, whether | |
168e428f PH |
4213 | frozen or not. |
4214 | ||
9b371988 PH |
4215 | .vitem &%-q[q][i][f[f]]l%& |
4216 | .oindex "&%-ql%&" | |
4217 | .cindex "queue" "local deliveries only" | |
4218 | The &'l'& (the letter &"ell"&) flag specifies that only local deliveries are to | |
4219 | be done. If a message requires any remote deliveries, it remains on the queue | |
4220 | for later delivery. | |
168e428f | 4221 | |
9b371988 PH |
4222 | .vitem &%-q%&<&'qflags'&>&~<&'start&~id'&>&~<&'end&~id'&> |
4223 | .cindex "queue" "delivering specific messages" | |
168e428f | 4224 | When scanning the queue, Exim can be made to skip over messages whose ids are |
9b371988 PH |
4225 | lexically less than a given value by following the &%-q%& option with a |
4226 | starting message id. For example: | |
4227 | .code | |
4228 | exim -q 0t5C6f-0000c8-00 | |
4229 | .endd | |
4230 | Messages that arrived earlier than &`0t5C6f-0000c8-00`& are not inspected. If a | |
168e428f PH |
4231 | second message id is given, messages whose ids are lexically greater than it |
4232 | are also skipped. If the same id is given twice, for example, | |
9b371988 PH |
4233 | .code |
4234 | exim -q 0t5C6f-0000c8-00 0t5C6f-0000c8-00 | |
4235 | .endd | |
4236 | just one delivery process is started, for that message. This differs from | |
4237 | &%-M%& in that retry data is respected, and it also differs from &%-Mc%& in | |
4238 | that it counts as a delivery from a queue run. Note that the selection | |
4239 | mechanism does not affect the order in which the messages are scanned. There | |
4240 | are also other ways of selecting specific sets of messages for delivery in a | |
4241 | queue run &-- see &%-R%& and &%-S%&. | |
4242 | ||
4243 | .vitem &%-q%&<&'qflags'&><&'time'&> | |
4244 | .cindex "queue runner" "starting periodically" | |
4245 | .cindex "periodic queue running" | |
4246 | When a time value is present, the &%-q%& option causes Exim to run as a daemon, | |
168e428f | 4247 | starting a queue runner process at intervals specified by the given time value |
9b371988 PH |
4248 | (whose format is described in section &<<SECTtimeformat>>&). This form of the |
4249 | &%-q%& option is commonly combined with the &%-bd%& option, in which case a | |
4250 | single daemon process handles both functions. A common way of starting up a | |
4251 | combined daemon at system boot time is to use a command such as | |
4252 | .code | |
4253 | /usr/exim/bin/exim -bd -q30m | |
4254 | .endd | |
168e428f PH |
4255 | Such a daemon listens for incoming SMTP calls, and also starts a queue runner |
4256 | process every 30 minutes. | |
9b371988 PH |
4257 | |
4258 | When a daemon is started by &%-q%& with a time value, but without &%-bd%&, no | |
4259 | pid file is written unless one is explicitly requested by the &%-oP%& option. | |
4260 | ||
4261 | .vitem &%-qR%&<&'rsflags'&>&~<&'string'&> | |
4262 | .oindex "&%-qR%&" | |
4263 | This option is synonymous with &%-R%&. It is provided for Sendmail | |
4264 | compatibility. | |
4265 | ||
4266 | .vitem &%-qS%&<&'rsflags'&>&~<&'string'&> | |
4267 | .oindex "&%-qS%&" | |
4268 | This option is synonymous with &%-S%&. | |
4269 | ||
4270 | .vitem &%-R%&<&'rsflags'&>&~<&'string'&> | |
4271 | .oindex "&%-R%&" | |
4272 | .cindex "queue runner" "for specific recipients" | |
4273 | .cindex "delivery" "to given domain" | |
4274 | .cindex "domain" "delivery to" | |
4275 | The <&'rsflags'&> may be empty, in which case the white space before the string | |
4276 | is optional, unless the string is &'f'&, &'ff'&, &'r'&, &'rf'&, or &'rff'&, | |
4277 | which are the possible values for <&'rsflags'&>. White space is required if | |
4278 | <&'rsflags'&> is not empty. | |
4279 | ||
4280 | This option is similar to &%-q%& with no time value, that is, it causes Exim to | |
168e428f PH |
4281 | perform a single queue run, except that, when scanning the messages on the |
4282 | queue, Exim processes only those that have at least one undelivered recipient | |
4283 | address containing the given string, which is checked in a case-independent | |
9b371988 PH |
4284 | way. If the <&'rsflags'&> start with &'r'&, <&'string'&> is interpreted as a |
4285 | regular expression; otherwise it is a literal string. | |
4286 | ||
3cb1b51e PH |
4287 | If you want to do periodic queue runs for messages with specific recipients, |
4288 | you can combine &%-R%& with &%-q%& and a time value. For example: | |
4289 | .code | |
4290 | exim -q25m -R @special.domain.example | |
4291 | .endd | |
4292 | This example does a queue run for messages with recipients in the given domain | |
4293 | every 25 minutes. Any additional flags that are specified with &%-q%& are | |
4294 | applied to each queue run. | |
3cb1b51e PH |
4295 | |
4296 | Once a message is selected for delivery by this mechanism, all its addresses | |
4297 | are processed. For the first selected message, Exim overrides any retry | |
4298 | information and forces a delivery attempt for each undelivered address. This | |
4299 | means that if delivery of any address in the first message is successful, any | |
4300 | existing retry information is deleted, and so delivery attempts for that | |
4301 | address in subsequently selected messages (which are processed without forcing) | |
4302 | will run. However, if delivery of any address does not succeed, the retry | |
4303 | information is updated, and in subsequently selected messages, the failing | |
4304 | address will be skipped. | |
9b371988 PH |
4305 | |
4306 | .cindex "frozen messages" "forcing delivery" | |
4307 | If the <&'rsflags'&> contain &'f'& or &'ff'&, the delivery forcing applies to | |
4308 | all selected messages, not just the first; frozen messages are included when | |
4309 | &'ff'& is present. | |
4310 | ||
4311 | The &%-R%& option makes it straightforward to initiate delivery of all messages | |
168e428f | 4312 | to a given domain after a host has been down for some time. When the SMTP |
9b371988 PH |
4313 | command ETRN is accepted by its ACL (see chapter &<<CHAPACL>>&), its default |
4314 | effect is to run Exim with the &%-R%& option, but it can be configured to run | |
4315 | an arbitrary command instead. | |
4316 | ||
4317 | .vitem &%-r%& | |
4318 | .oindex "&%-r%&" | |
4319 | This is a documented (for Sendmail) obsolete alternative name for &%-f%&. | |
4320 | ||
4321 | .vitem &%-S%&<&'rsflags'&>&~<&'string'&> | |
4322 | .oindex "&%-S%&" | |
4323 | .cindex "delivery" "from given sender" | |
4324 | .cindex "queue runner" "for specific senders" | |
4325 | This option acts like &%-R%& except that it checks the string against each | |
4326 | message's sender instead of against the recipients. If &%-R%& is also set, both | |
168e428f | 4327 | conditions must be met for a message to be selected. If either of the options |
9b371988 | 4328 | has &'f'& or &'ff'& in its flags, the associated action is taken. |
168e428f | 4329 | |
9b371988 PH |
4330 | .vitem &%-Tqt%&&~<&'times'&> |
4331 | .oindex "&%-Tqt%&" | |
168e428f PH |
4332 | This an option that is exclusively for use by the Exim testing suite. It is not |
4333 | recognized when Exim is run normally. It allows for the setting up of explicit | |
9b371988 PH |
4334 | &"queue times"& so that various warning/retry features can be tested. |
4335 | ||
4336 | .vitem &%-t%& | |
9b371988 PH |
4337 | .oindex "&%-t%&" |
4338 | .cindex "recipient" "extracting from header lines" | |
4339 | .cindex "&'Bcc:'& header line" | |
4340 | .cindex "&'Cc:'& header line" | |
4341 | .cindex "&'To:'& header line" | |
168e428f | 4342 | When Exim is receiving a locally-generated, non-SMTP message on its standard |
9b371988 PH |
4343 | input, the &%-t%& option causes the recipients of the message to be obtained |
4344 | from the &'To:'&, &'Cc:'&, and &'Bcc:'& header lines in the message instead of | |
4345 | from the command arguments. The addresses are extracted before any rewriting | |
4346 | takes place and the &'Bcc:'& header line, if present, is then removed. | |
9b371988 PH |
4347 | |
4348 | .cindex "Sendmail compatibility" "&%-t%& option" | |
4349 | If the command has any arguments, they specify addresses to which the message | |
4350 | is &'not'& to be delivered. That is, the argument addresses are removed from | |
168e428f PH |
4351 | the recipients list obtained from the headers. This is compatible with Smail 3 |
4352 | and in accordance with the documented behaviour of several versions of | |
4353 | Sendmail, as described in man pages on a number of operating systems (e.g. | |
9b371988 | 4354 | Solaris 8, IRIX 6.5, HP-UX 11). However, some versions of Sendmail &'add'& |
168e428f PH |
4355 | argument addresses to those obtained from the headers, and the O'Reilly |
4356 | Sendmail book documents it that way. Exim can be made to add argument addresses | |
4357 | instead of subtracting them by setting the option | |
9b371988 PH |
4358 | &%extract_addresses_remove_arguments%& false. |
4359 | ||
4360 | .cindex "&%Resent-%& header lines" "with &%-t%&" | |
4361 | If there are any &%Resent-%& header lines in the message, Exim extracts | |
4362 | recipients from all &'Resent-To:'&, &'Resent-Cc:'&, and &'Resent-Bcc:'& header | |
4363 | lines instead of from &'To:'&, &'Cc:'&, and &'Bcc:'&. This is for compatibility | |
168e428f | 4364 | with Sendmail and other MTAs. (Prior to release 4.20, Exim gave an error if |
9b371988 PH |
4365 | &%-t%& was used in conjunction with &%Resent-%& header lines.) |
4366 | ||
4367 | RFC 2822 talks about different sets of &%Resent-%& header lines (for when a | |
168e428f | 4368 | message is resent several times). The RFC also specifies that they should be |
9b371988 PH |
4369 | added at the front of the message, and separated by &'Received:'& lines. It is |
4370 | not at all clear how &%-t%& should operate in the present of multiple sets, | |
4371 | nor indeed exactly what constitutes a &"set"&. | |
4372 | In practice, it seems that MUAs do not follow the RFC. The &%Resent-%& lines | |
4373 | are often added at the end of the header, and if a message is resent more than | |
4374 | once, it is common for the original set of &%Resent-%& headers to be renamed as | |
4375 | &%X-Resent-%& when a new set is added. This removes any possible ambiguity. | |
4376 | ||
4f578862 | 4377 | .vitem &%-ti%& |
9b371988 PH |
4378 | .oindex "&%-ti%&" |
4379 | This option is exactly equivalent to &%-t%& &%-i%&. It is provided for | |
168e428f PH |
4380 | compatibility with Sendmail. |
4381 | ||
4f578862 | 4382 | .vitem &%-tls-on-connect%& |
9b371988 PH |
4383 | .oindex "&%-tls-on-connect%&" |
4384 | .cindex "TLS" "use without STARTTLS" | |
4385 | .cindex "TLS" "automatic start" | |
168e428f PH |
4386 | This option is available when Exim is compiled with TLS support. It forces all |
4387 | incoming SMTP connections to behave as if the incoming port is listed in the | |
9b371988 PH |
4388 | &%tls_on_connect_ports%& option. See section &<<SECTsupobssmt>>& and chapter |
4389 | &<<CHAPTLS>>& for further details. | |
168e428f PH |
4390 | |
4391 | ||
4f578862 | 4392 | .vitem &%-U%& |
9b371988 PH |
4393 | .oindex "&%-U%&" |
4394 | .cindex "Sendmail compatibility" "&%-U%& option ignored" | |
4395 | Sendmail uses this option for &"initial message submission"&, and its | |
168e428f PH |
4396 | documentation states that in future releases, it may complain about |
4397 | syntactically invalid messages rather than fixing them when this flag is not | |
4398 | set. Exim ignores this option. | |
4399 | ||
4f578862 | 4400 | .vitem &%-v%& |
9b371988 | 4401 | .oindex "&%-v%&" |
168e428f PH |
4402 | This option causes Exim to write information to the standard error stream, |
4403 | describing what it is doing. In particular, it shows the log lines for | |
4404 | receiving and delivering a message, and if an SMTP connection is made, the SMTP | |
4405 | dialogue is shown. Some of the log lines shown may not actually be written to | |
9b371988 PH |
4406 | the log if the setting of &%log_selector%& discards them. Any relevant |
4407 | selectors are shown with each log line. If none are shown, the logging is | |
4408 | unconditional. | |
4409 | ||
4f578862 | 4410 | .vitem &%-x%& |
9b371988 PH |
4411 | .oindex "&%-x%&" |
4412 | AIX uses &%-x%& for a private purpose (&"mail from a local mail program has | |
4413 | National Language Support extended characters in the body of the mail item"&). | |
4414 | It sets &%-x%& when calling the MTA from its &%mail%& command. Exim ignores | |
4415 | this option. | |
4416 | .endlist | |
4417 | ||
4f578862 PH |
4418 | .ecindex IIDclo1 |
4419 | .ecindex IIDclo2 | |
4420 | ||
4421 | ||
9b371988 PH |
4422 | . //////////////////////////////////////////////////////////////////////////// |
4423 | . Insert a stylized DocBook comment here, to identify the end of the command | |
4424 | . line options. This is for the benefit of the Perl script that automatically | |
4425 | . creates a man page for the options. | |
4426 | . //////////////////////////////////////////////////////////////////////////// | |
4427 | ||
4428 | .literal xml | |
168e428f | 4429 | <!-- === End of command line options === --> |
9b371988 | 4430 | .literal off |
168e428f PH |
4431 | |
4432 | ||
4433 | ||
4434 | ||
4435 | ||
9b371988 PH |
4436 | . //////////////////////////////////////////////////////////////////////////// |
4437 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f PH |
4438 | |
4439 | ||
9b371988 PH |
4440 | .chapter "The Exim run time configuration file" "CHAPconf" &&& |
4441 | "The runtime configuration file" | |
168e428f | 4442 | |
9b371988 PH |
4443 | .cindex "run time configuration" |
4444 | .cindex "configuration file" "general description" | |
4445 | .cindex "CONFIGURE_FILE" | |
4446 | .cindex "configuration file" "errors in" | |
4447 | .cindex "error" "in configuration file" | |
4448 | .cindex "return code" "for bad configuration" | |
168e428f PH |
4449 | Exim uses a single run time configuration file that is read whenever an Exim |
4450 | binary is executed. Note that in normal operation, this happens frequently, | |
4451 | because Exim is designed to operate in a distributed manner, without central | |
4452 | control. | |
4453 | ||
4454 | If a syntax error is detected while reading the configuration file, Exim | |
4455 | writes a message on the standard error, and exits with a non-zero return code. | |
9b371988 | 4456 | The message is also written to the panic log. &*Note*&: Only simple syntax |
168e428f PH |
4457 | errors can be detected at this time. The values of any expanded options are |
4458 | not checked until the expansion happens, even when the expansion does not | |
4459 | actually alter the string. | |
4460 | ||
168e428f PH |
4461 | The name of the configuration file is compiled into the binary for security |
4462 | reasons, and is specified by the CONFIGURE_FILE compilation option. In | |
4463 | most configurations, this specifies a single file. However, it is permitted to | |
4464 | give a colon-separated list of file names, in which case Exim uses the first | |
4465 | existing file in the list. | |
4466 | ||
9b371988 PH |
4467 | .cindex "EXIM_USER" |
4468 | .cindex "EXIM_GROUP" | |
4469 | .cindex "CONFIGURE_OWNER" | |
4470 | .cindex "CONFIGURE_GROUP" | |
4471 | .cindex "configuration file" "ownership" | |
4472 | .cindex "ownership" "configuration file" | |
168e428f PH |
4473 | The run time configuration file must be owned by root or by the user that is |
4474 | specified at compile time by the EXIM_USER option, or by the user that is | |
4475 | specified at compile time by the CONFIGURE_OWNER option (if set). The | |
4476 | configuration file must not be world-writeable or group-writeable, unless its | |
9b371988 PH |
4477 | group is the one specified at compile time by the EXIM_GROUP option or by the |
4478 | CONFIGURE_GROUP option. | |
168e428f | 4479 | |
9b371988 | 4480 | &*Warning*&: In a conventional configuration, where the Exim binary is setuid |
168e428f PH |
4481 | to root, anybody who is able to edit the run time configuration file has an |
4482 | easy way to run commands as root. If you make your mail administrators members | |
4483 | of the Exim group, but do not trust them with root, make sure that the run time | |
4484 | configuration is not group writeable. | |
4485 | ||
4486 | A default configuration file, which will work correctly in simple situations, | |
9b371988 | 4487 | is provided in the file &_src/configure.default_&. If CONFIGURE_FILE |
168e428f PH |
4488 | defines just one file name, the installation process copies the default |
4489 | configuration to a new file of that name if it did not previously exist. If | |
4490 | CONFIGURE_FILE is a list, no default is automatically installed. Chapter | |
9b371988 PH |
4491 | &<<CHAPdefconfil>>& is a &"walk-through"& discussion of the default |
4492 | configuration. | |
168e428f PH |
4493 | |
4494 | ||
4495 | ||
f89d2485 | 4496 | .section "Using a different configuration file" "SECID40" |
9b371988 PH |
4497 | .cindex "configuration file" "alternate" |
4498 | A one-off alternate configuration can be specified by the &%-C%& command line | |
4499 | option, which may specify a single file or a list of files. However, when | |
4500 | &%-C%& is used, Exim gives up its root privilege, unless called by root or the | |
4501 | Exim user (or unless the argument for &%-C%& is identical to the built-in value | |
4502 | from CONFIGURE_FILE). &%-C%& is useful mainly for checking the syntax of | |
168e428f | 4503 | configuration files before installing them. No owner or group checks are done |
9b371988 | 4504 | on a configuration file specified by &%-C%&. |
168e428f | 4505 | |
9b371988 PH |
4506 | The privileged use of &%-C%& by the Exim user can be locked out by setting |
4507 | ALT_CONFIG_ROOT_ONLY in &_Local/Makefile_& when building Exim. However, | |
168e428f | 4508 | if you do this, you also lock out the possibility of testing a |
9b371988 PH |
4509 | configuration using &%-C%& right through message reception and delivery, even |
4510 | if the caller is root. The reception works, but by that time, Exim is running | |
4511 | as the Exim user, so when it re-execs to regain privilege for the delivery, the | |
4512 | use of &%-C%& causes privilege to be lost. However, root can test reception and | |
168e428f | 4513 | delivery using two separate commands (one to put a message on the queue, using |
9b371988 | 4514 | &%-odq%&, and another to do the delivery, using &%-M%&). |
168e428f | 4515 | |
9b371988 PH |
4516 | If ALT_CONFIG_PREFIX is defined &_in Local/Makefile_&, it specifies a |
4517 | prefix string with which any file named in a &%-C%& command line option must | |
4518 | start. In addition, the file name must not contain the sequence &"&`/../`&"&. | |
068aaea8 | 4519 | There is no default setting for ALT_CONFIG_PREFIX; when it is unset, any file |
9b371988 | 4520 | name can be used with &%-C%&. |
168e428f | 4521 | |
9b371988 | 4522 | One-off changes to a configuration can be specified by the &%-D%& command line |
168e428f | 4523 | option, which defines and overrides values for macros used inside the |
9b371988 | 4524 | configuration file. However, like &%-C%&, the use of this option by a |
168e428f | 4525 | non-privileged user causes Exim to discard its root privilege. |
9b371988 | 4526 | If DISABLE_D_OPTION is defined in &_Local/Makefile_&, the use of &%-D%& is |
168e428f PH |
4527 | completely disabled, and its use causes an immediate error exit. |
4528 | ||
4529 | Some sites may wish to use the same Exim binary on different machines that | |
4530 | share a file system, but to use different configuration files on each machine. | |
9b371988 | 4531 | If CONFIGURE_FILE_USE_NODE is defined in &_Local/Makefile_&, Exim first |
168e428f | 4532 | looks for a file whose name is the configuration file name followed by a dot |
9b371988 | 4533 | and the machine's node name, as obtained from the &[uname()]& function. If this |
168e428f | 4534 | file does not exist, the standard name is tried. This processing occurs for |
9b371988 | 4535 | each file name in the list given by CONFIGURE_FILE or &%-C%&. |
168e428f PH |
4536 | |
4537 | In some esoteric situations different versions of Exim may be run under | |
4538 | different effective uids and the CONFIGURE_FILE_USE_EUID is defined to | |
9b371988 | 4539 | help with this. See the comments in &_src/EDITME_& for details. |
168e428f PH |
4540 | |
4541 | ||
4542 | ||
9b371988 PH |
4543 | .section "Configuration file format" "SECTconffilfor" |
4544 | .cindex "configuration file" "format of" | |
4545 | .cindex "format" "configuration file" | |
168e428f PH |
4546 | Exim's configuration file is divided into a number of different parts. General |
4547 | option settings must always appear at the start of the file. The other parts | |
4548 | are all optional, and may appear in any order. Each part other than the first | |
9b371988 | 4549 | is introduced by the word &"begin"& followed by the name of the part. The |
168e428f PH |
4550 | optional parts are: |
4551 | ||
9b371988 | 4552 | .ilist |
595028e4 PH |
4553 | &'ACL'&: Access control lists for controlling incoming SMTP mail (see chapter |
4554 | &<<CHAPACL>>&). | |
9b371988 PH |
4555 | .next |
4556 | .cindex "AUTH" "configuration" | |
4557 | &'authenticators'&: Configuration settings for the authenticator drivers. These | |
4558 | are concerned with the SMTP AUTH command (see chapter &<<CHAPSMTPAUTH>>&). | |
4559 | .next | |
4560 | &'routers'&: Configuration settings for the router drivers. Routers process | |
595028e4 PH |
4561 | addresses and determine how the message is to be delivered (see chapters |
4562 | &<<CHAProutergeneric>>&&--&<<CHAPredirect>>&). | |
9b371988 PH |
4563 | .next |
4564 | &'transports'&: Configuration settings for the transport drivers. Transports | |
595028e4 PH |
4565 | define mechanisms for copying messages to destinations (see chapters |
4566 | &<<CHAPtransportgeneric>>&&--&<<CHAPsmtptrans>>&). | |
9b371988 | 4567 | .next |
595028e4 PH |
4568 | &'retry'&: Retry rules, for use when a message cannot be delivered immediately. |
4569 | If there is no retry section, or if it is empty (that is, no retry rules are | |
4570 | defined), Exim will not retry deliveries. In this situation, temporary errors | |
4571 | are treated the same as permanent errors. Retry rules are discussed in chapter | |
4572 | &<<CHAPretry>>&. | |
9b371988 PH |
4573 | .next |
4574 | &'rewrite'&: Global address rewriting rules, for use when a message arrives and | |
595028e4 PH |
4575 | when new addresses are generated during delivery. Rewriting is discussed in |
4576 | chapter &<<CHAPrewrite>>&. | |
9b371988 PH |
4577 | .next |
4578 | &'local_scan'&: Private options for the &[local_scan()]& function. If you | |
168e428f | 4579 | want to use this feature, you must set |
9b371988 PH |
4580 | .code |
4581 | LOCAL_SCAN_HAS_OPTIONS=yes | |
4582 | .endd | |
595028e4 PH |
4583 | in &_Local/Makefile_& before building Exim. Details of the &[local_scan()]& |
4584 | facility are given in chapter &<<CHAPlocalscan>>&. | |
9b371988 PH |
4585 | .endlist |
4586 | ||
4587 | .cindex "configuration file" "leading white space in" | |
4588 | .cindex "configuration file" "trailing white space in" | |
4589 | .cindex "white space" "in configuration file" | |
068aaea8 | 4590 | Leading and trailing white space in configuration lines is always ignored. |
168e428f PH |
4591 | |
4592 | Blank lines in the file, and lines starting with a # character (ignoring | |
9b371988 | 4593 | leading white space) are treated as comments and are ignored. &*Note*&: A |
168e428f PH |
4594 | # character other than at the beginning of a line is not treated specially, |
4595 | and does not introduce a comment. | |
4596 | ||
4597 | Any non-comment line can be continued by ending it with a backslash. Note that | |
068aaea8 PH |
4598 | the general rule for white space means that trailing white space after the |
4599 | backslash and leading white space at the start of continuation | |
4600 | lines is ignored. Comment lines beginning with # (but not empty lines) may | |
168e428f PH |
4601 | appear in the middle of a sequence of continuation lines. |
4602 | ||
4603 | A convenient way to create a configuration file is to start from the | |
9b371988 | 4604 | default, which is supplied in &_src/configure.default_&, and add, delete, or |
168e428f PH |
4605 | change settings as required. |
4606 | ||
4607 | The ACLs, retry rules, and rewriting rules have their own syntax which is | |
9b371988 | 4608 | described in chapters &<<CHAPACL>>&, &<<CHAPretry>>&, and &<<CHAPrewrite>>&, |
168e428f | 4609 | respectively. The other parts of the configuration file have some syntactic |
9b371988 | 4610 | items in common, and these are described below, from section &<<SECTcos>>& |
168e428f PH |
4611 | onwards. Before that, the inclusion, macro, and conditional facilities are |
4612 | described. | |
4613 | ||
4614 | ||
4615 | ||
f89d2485 | 4616 | .section "File inclusions in the configuration file" "SECID41" |
9b371988 PH |
4617 | .cindex "inclusions in configuration file" |
4618 | .cindex "configuration file" "including other files" | |
f89d2485 PH |
4619 | .cindex "&`.include`& in configuration file" |
4620 | .cindex "&`.include_if_exists`& in configuration file" | |
168e428f PH |
4621 | You can include other files inside Exim's run time configuration file by |
4622 | using this syntax: | |
9b371988 PH |
4623 | .display |
4624 | &`.include`& <&'file name'&> | |
4625 | &`.include_if_exists`& <&'file name'&> | |
4626 | .endd | |
168e428f PH |
4627 | on a line by itself. Double quotes round the file name are optional. If you use |
4628 | the first form, a configuration error occurs if the file does not exist; the | |
4f578862 PH |
4629 | second form does nothing for non-existent files. In all cases, an absolute file |
4630 | name is required. | |
168e428f PH |
4631 | |
4632 | Includes may be nested to any depth, but remember that Exim reads its | |
4633 | configuration file often, so it is a good idea to keep them to a minimum. | |
4634 | If you change the contents of an included file, you must HUP the daemon, | |
4635 | because an included file is read only when the configuration itself is read. | |
4636 | ||
4637 | The processing of inclusions happens early, at a physical line level, so, like | |
4638 | comment lines, an inclusion can be used in the middle of an option setting, | |
4639 | for example: | |
9b371988 | 4640 | .code |
168e428f PH |
4641 | hosts_lookup = a.b.c \ |
4642 | .include /some/file | |
9b371988 | 4643 | .endd |
168e428f | 4644 | Include processing happens after macro processing (see below). Its effect is to |
4f578862 PH |
4645 | process the lines of the included file as if they occurred inline where the |
4646 | inclusion appears. | |
168e428f PH |
4647 | |
4648 | ||
4649 | ||
9b371988 PH |
4650 | .section "Macros in the configuration file" "SECTmacrodefs" |
4651 | .cindex "macro" "description of" | |
4652 | .cindex "configuration file" "macros" | |
168e428f | 4653 | If a line in the main part of the configuration (that is, before the first |
9b371988 | 4654 | &"begin"& line) begins with an upper case letter, it is taken as a macro |
168e428f | 4655 | definition, and must be of the form |
9b371988 PH |
4656 | .display |
4657 | <&'name'&> = <&'rest of line'&> | |
4658 | .endd | |
168e428f PH |
4659 | The name must consist of letters, digits, and underscores, and need not all be |
4660 | in upper case, though that is recommended. The rest of the line, including any | |
4661 | continuations, is the replacement text, and has leading and trailing white | |
4662 | space removed. Quotes are not removed. The replacement text can never end with | |
4663 | a backslash character, but this doesn't seem to be a serious limitation. | |
4664 | ||
068aaea8 PH |
4665 | Macros may also be defined between router, transport, authenticator, or ACL |
4666 | definitions. They may not, however, be defined within an individual driver or | |
9b371988 | 4667 | ACL, or in the &%local_scan%&, retry, or rewrite sections of the configuration. |
068aaea8 | 4668 | |
f89d2485 | 4669 | .section "Macro substitution" "SECID42" |
168e428f PH |
4670 | Once a macro is defined, all subsequent lines in the file (and any included |
4671 | files) are scanned for the macro name; if there are several macros, the line is | |
068aaea8 | 4672 | scanned for each in turn, in the order in which the macros are defined. The |
168e428f PH |
4673 | replacement text is not re-scanned for the current macro, though it is scanned |
4674 | for subsequently defined macros. For this reason, a macro name may not contain | |
4675 | the name of a previously defined macro as a substring. You could, for example, | |
4676 | define | |
9b371988 PH |
4677 | .display |
4678 | &`ABCD_XYZ = `&<&'something'&> | |
4679 | &`ABCD = `&<&'something else'&> | |
4680 | .endd | |
168e428f | 4681 | but putting the definitions in the opposite order would provoke a configuration |
068aaea8 PH |
4682 | error. Macro expansion is applied to individual physical lines from the file, |
4683 | before checking for line continuation or file inclusion (see above). If a line | |
4684 | consists solely of a macro name, and the expansion of the macro is empty, the | |
4685 | line is ignored. A macro at the start of a line may turn the line into a | |
9b371988 | 4686 | comment line or a &`.include`& line. |
068aaea8 PH |
4687 | |
4688 | ||
f89d2485 | 4689 | .section "Redefining macros" "SECID43" |
068aaea8 | 4690 | Once defined, the value of a macro can be redefined later in the configuration |
9b371988 PH |
4691 | (or in an included file). Redefinition is specified by using &'=='& instead of |
4692 | &'='&. For example: | |
4693 | .code | |
4694 | MAC = initial value | |
4695 | ... | |
4696 | MAC == updated value | |
4697 | .endd | |
4698 | Redefinition does not alter the order in which the macros are applied to the | |
4699 | subsequent lines of the configuration file. It is still the same order in which | |
4700 | the macros were originally defined. All that changes is the macro's value. | |
4701 | Redefinition makes it possible to accumulate values. For example: | |
4702 | .code | |
4703 | MAC = initial value | |
4704 | ... | |
4705 | MAC == MAC and something added | |
4706 | .endd | |
068aaea8 PH |
4707 | This can be helpful in situations where the configuration file is built |
4708 | from a number of other files. | |
4709 | ||
f89d2485 | 4710 | .section "Overriding macro values" "SECID44" |
068aaea8 | 4711 | The values set for macros in the configuration file can be overridden by the |
9b371988 | 4712 | &%-D%& command line option, but Exim gives up its root privilege when &%-D%& is |
068aaea8 | 4713 | used, unless called by root or the Exim user. A definition on the command line |
9b371988 PH |
4714 | using the &%-D%& option causes all definitions and redefinitions within the |
4715 | file to be ignored. | |
068aaea8 | 4716 | |
168e428f | 4717 | |
168e428f | 4718 | |
f89d2485 | 4719 | .section "Example of macro usage" "SECID45" |
168e428f PH |
4720 | As an example of macro usage, consider a configuration where aliases are looked |
4721 | up in a MySQL database. It helps to keep the file less cluttered if long | |
4722 | strings such as SQL statements are defined separately as macros, for example: | |
9b371988 | 4723 | .code |
168e428f | 4724 | ALIAS_QUERY = select mailbox from user where \ |
c4c02c55 | 4725 | login='${quote_mysql:$local_part}'; |
9b371988 PH |
4726 | .endd |
4727 | This can then be used in a &(redirect)& router setting like this: | |
4728 | .code | |
4729 | data = ${lookup mysql{ALIAS_QUERY}} | |
4730 | .endd | |
168e428f | 4731 | In earlier versions of Exim macros were sometimes used for domain, host, or |
9b371988 PH |
4732 | address lists. In Exim 4 these are handled better by named lists &-- see |
4733 | section &<<SECTnamedlists>>&. | |
168e428f | 4734 | |
168e428f | 4735 | |
f89d2485 | 4736 | .section "Conditional skips in the configuration file" "SECID46" |
9b371988 | 4737 | .cindex "configuration file" "conditional skips" |
f89d2485 | 4738 | .cindex "&`.ifdef`&" |
9b371988 PH |
4739 | You can use the directives &`.ifdef`&, &`.ifndef`&, &`.elifdef`&, |
4740 | &`.elifndef`&, &`.else`&, and &`.endif`& to dynamically include or exclude | |
168e428f PH |
4741 | portions of the configuration file. The processing happens whenever the file is |
4742 | read (that is, when an Exim binary starts to run). | |
4743 | ||
4744 | The implementation is very simple. Instances of the first four directives must | |
4745 | be followed by text that includes the names of one or macros. The condition | |
4746 | that is tested is whether or not any macro substitution has taken place in the | |
4747 | line. Thus: | |
9b371988 PH |
4748 | .code |
4749 | .ifdef AAA | |
4750 | message_size_limit = 50M | |
4751 | .else | |
4752 | message_size_limit = 100M | |
4753 | .endif | |
4754 | .endd | |
4755 | sets a message size limit of 50M if the macro &`AAA`& is defined, and 100M | |
168e428f | 4756 | otherwise. If there is more than one macro named on the line, the condition |
9b371988 PH |
4757 | is true if any of them are defined. That is, it is an &"or"& condition. To |
4758 | obtain an &"and"& condition, you need to use nested &`.ifdef`&s. | |
168e428f PH |
4759 | |
4760 | Although you can use a macro expansion to generate one of these directives, | |
9b371988 PH |
4761 | it is not very useful, because the condition &"there was a macro substitution |
4762 | in this line"& will always be true. | |
168e428f | 4763 | |
9b371988 | 4764 | Text following &`.else`& and &`.endif`& is ignored, and can be used as comment |
168e428f PH |
4765 | to clarify complicated nestings. |
4766 | ||
4767 | ||
4768 | ||
9b371988 PH |
4769 | .section "Common option syntax" "SECTcos" |
4770 | .cindex "common option syntax" | |
4771 | .cindex "syntax of common options" | |
4772 | .cindex "configuration file" "common option syntax" | |
4773 | For the main set of options, driver options, and &[local_scan()]& options, | |
168e428f PH |
4774 | each setting is on a line by itself, and starts with a name consisting of |
4775 | lower-case letters and underscores. Many options require a data value, and in | |
4776 | these cases the name must be followed by an equals sign (with optional white | |
4777 | space) and then the value. For example: | |
9b371988 PH |
4778 | .code |
4779 | qualify_domain = mydomain.example.com | |
4780 | .endd | |
595028e4 PH |
4781 | .cindex "hiding configuration option values" |
4782 | .cindex "configuration options" "hiding value of" | |
4783 | .cindex "options" "hiding value of" | |
168e428f | 4784 | Some option settings may contain sensitive data, for example, passwords for |
9b371988 PH |
4785 | accessing databases. To stop non-admin users from using the &%-bP%& command |
4786 | line option to read these values, you can precede the option settings with the | |
4787 | word &"hide"&. For example: | |
4788 | .code | |
4789 | hide mysql_servers = localhost/users/admin/secret-password | |
4790 | .endd | |
168e428f | 4791 | For non-admin users, such options are displayed like this: |
9b371988 PH |
4792 | .code |
4793 | mysql_servers = <value not displayable> | |
4794 | .endd | |
4795 | If &"hide"& is used on a driver option, it hides the value of that option on | |
4796 | all instances of the same driver. | |
168e428f PH |
4797 | |
4798 | The following sections describe the syntax used for the different data types | |
4799 | that are found in option settings. | |
4800 | ||
4801 | ||
f89d2485 | 4802 | .section "Boolean options" "SECID47" |
9b371988 PH |
4803 | .cindex "format" "boolean" |
4804 | .cindex "boolean configuration values" | |
4805 | .oindex "&%no_%&&'xxx'&" | |
4806 | .oindex "&%not_%&&'xxx'&" | |
168e428f PH |
4807 | Options whose type is given as boolean are on/off switches. There are two |
4808 | different ways of specifying such options: with and without a data value. If | |
4809 | the option name is specified on its own without data, the switch is turned on; | |
9b371988 | 4810 | if it is preceded by &"no_"& or &"not_"& the switch is turned off. However, |
068aaea8 | 4811 | boolean options may be followed by an equals sign and one of the words |
9b371988 | 4812 | &"true"&, &"false"&, &"yes"&, or &"no"&, as an alternative syntax. For example, |
168e428f | 4813 | the following two settings have exactly the same effect: |
9b371988 PH |
4814 | .code |
4815 | queue_only | |
4816 | queue_only = true | |
4817 | .endd | |
168e428f | 4818 | The following two lines also have the same (opposite) effect: |
9b371988 PH |
4819 | .code |
4820 | no_queue_only | |
4821 | queue_only = false | |
4822 | .endd | |
168e428f PH |
4823 | You can use whichever syntax you prefer. |
4824 | ||
4825 | ||
4826 | ||
4827 | ||
f89d2485 | 4828 | .section "Integer values" "SECID48" |
9b371988 PH |
4829 | .cindex "integer configuration values" |
4830 | .cindex "format" "integer" | |
f89d2485 PH |
4831 | If an option's type is given as &"integer"&, the value can be given in decimal, |
4832 | hexadecimal, or octal. If it starts with a digit greater than zero, a decimal | |
4833 | number is assumed. Otherwise, it is treated as an octal number unless it starts | |
4834 | with the characters &"0x"&, in which case the remainder is interpreted as a | |
4835 | hexadecimal number. | |
168e428f | 4836 | |
f89d2485 PH |
4837 | If an integer value is followed by the letter K, it is multiplied by 1024; if |
4838 | it is followed by the letter M, it is multiplied by 1024x1024. When the values | |
4839 | of integer option settings are output, values which are an exact multiple of | |
4840 | 1024 or 1024x1024 are sometimes, but not always, printed using the letters K | |
4841 | and M. The printing style is independent of the actual input format that was | |
4842 | used. | |
168e428f PH |
4843 | |
4844 | ||
f89d2485 | 4845 | .section "Octal integer values" "SECID49" |
9b371988 PH |
4846 | .cindex "integer format" |
4847 | .cindex "format" "octal integer" | |
f89d2485 PH |
4848 | If an option's type is given as &"octal integer"&, its value is always |
4849 | interpreted as an octal number, whether or not it starts with the digit zero. | |
4850 | Such options are always output in octal. | |
168e428f PH |
4851 | |
4852 | ||
f89d2485 | 4853 | .section "Fixed point numbers" "SECID50" |
9b371988 PH |
4854 | .cindex "fixed point configuration values" |
4855 | .cindex "format" "fixed point" | |
f89d2485 PH |
4856 | If an option's type is given as &"fixed-point"&, its value must be a decimal |
4857 | integer, optionally followed by a decimal point and up to three further digits. | |
168e428f PH |
4858 | |
4859 | ||
4860 | ||
f89d2485 | 4861 | .section "Time intervals" "SECTtimeformat" |
9b371988 PH |
4862 | .cindex "time interval" "specifying in configuration" |
4863 | .cindex "format" "time interval" | |
168e428f PH |
4864 | A time interval is specified as a sequence of numbers, each followed by one of |
4865 | the following letters, with no intervening white space: | |
4866 | ||
f89d2485 PH |
4867 | .table2 30pt |
4868 | .irow &%s%& seconds | |
4869 | .irow &%m%& minutes | |
4870 | .irow &%h%& hours | |
4871 | .irow &%d%& days | |
4872 | .irow &%w%& weeks | |
9b371988 | 4873 | .endtable |
168e428f | 4874 | |
9b371988 | 4875 | For example, &"3h50m"& specifies 3 hours and 50 minutes. The values of time |
168e428f | 4876 | intervals are output in the same format. Exim does not restrict the values; it |
9b371988 | 4877 | is perfectly acceptable, for example, to specify &"90m"& instead of &"1h30m"&. |
168e428f PH |
4878 | |
4879 | ||
4880 | ||
9b371988 PH |
4881 | .section "String values" "SECTstrings" |
4882 | .cindex "string" "format of configuration values" | |
4883 | .cindex "format" "string" | |
f89d2485 PH |
4884 | If an option's type is specified as &"string"&, the value can be specified with |
4885 | or without double-quotes. If it does not start with a double-quote, the value | |
4886 | consists of the remainder of the line plus any continuation lines, starting at | |
4887 | the first character after any leading white space, with trailing white space | |
4888 | removed, and with no interpretation of the characters in the string. Because | |
4889 | Exim removes comment lines (those beginning with #) at an early stage, they can | |
4890 | appear in the middle of a multi-line string. The following two settings are | |
4891 | therefore equivalent: | |
9b371988 | 4892 | .code |
168e428f | 4893 | trusted_users = uucp:mail |
168e428f PH |
4894 | trusted_users = uucp:\ |
4895 | # This comment line is ignored | |
4896 | ||
9b371988 PH |
4897 | .endd |
4898 | .cindex "string" "quoted" | |
4899 | .cindex "escape characters in quoted strings" | |
168e428f PH |
4900 | If a string does start with a double-quote, it must end with a closing |
4901 | double-quote, and any backslash characters other than those used for line | |
4902 | continuation are interpreted as escape characters, as follows: | |
4903 | ||
9b371988 | 4904 | .table2 100pt |
f89d2485 PH |
4905 | .irow &`\\`& "single backslash" |
4906 | .irow &`\n`& "newline" | |
4907 | .irow &`\r`& "carriage return" | |
4908 | .irow &`\t`& "tab" | |
4909 | .irow "&`\`&<&'octal digits'&>" "up to 3 octal digits specify one character" | |
4910 | .irow "&`\x`&<&'hex digits'&>" "up to 2 hexadecimal digits specify one &&& | |
9b371988 PH |
4911 | character" |
4912 | .endtable | |
168e428f PH |
4913 | |
4914 | If a backslash is followed by some other character, including a double-quote | |
4915 | character, that character replaces the pair. | |
4916 | ||
4917 | Quoting is necessary only if you want to make use of the backslash escapes to | |
4918 | insert special characters, or if you need to specify a value with leading or | |
4919 | trailing spaces. These cases are rare, so quoting is almost never needed in | |
4920 | current versions of Exim. In versions of Exim before 3.14, quoting was required | |
4921 | in order to continue lines, so you may come across older configuration files | |
4922 | and examples that apparently quote unnecessarily. | |
4923 | ||
4924 | ||
f89d2485 | 4925 | .section "Expanded strings" "SECID51" |
9b371988 PH |
4926 | .cindex "expansion" "definition of" |
4927 | Some strings in the configuration file are subjected to &'string expansion'&, | |
168e428f | 4928 | by which means various parts of the string may be changed according to the |
9b371988 PH |
4929 | circumstances (see chapter &<<CHAPexpand>>&). The input syntax for such strings |
4930 | is as just described; in particular, the handling of backslashes in quoted | |
4931 | strings is done as part of the input process, before expansion takes place. | |
4932 | However, backslash is also an escape character for the expander, so any | |
4933 | backslashes that are required for that reason must be doubled if they are | |
4934 | within a quoted configuration string. | |
4935 | ||
4936 | ||
f89d2485 | 4937 | .section "User and group names" "SECID52" |
9b371988 PH |
4938 | .cindex "user name" "format of" |
4939 | .cindex "format" "user name" | |
f89d2485 | 4940 | .cindex "groups" "name format" |
9b371988 | 4941 | .cindex "format" "group name" |
168e428f PH |
4942 | User and group names are specified as strings, using the syntax described |
4943 | above, but the strings are interpreted specially. A user or group name must | |
4944 | either consist entirely of digits, or be a name that can be looked up using the | |
9b371988 | 4945 | &[getpwnam()]& or &[getgrnam()]& function, as appropriate. |
168e428f PH |
4946 | |
4947 | ||
9b371988 PH |
4948 | .section "List construction" "SECTlistconstruct" |
4949 | .cindex "list" "syntax of in configuration" | |
4950 | .cindex "format" "list item in configuration" | |
f89d2485 | 4951 | .cindex "string" "list, definition of" |
168e428f | 4952 | The data for some configuration options is a list of items, with colon as the |
9b371988 PH |
4953 | default separator. Many of these options are shown with type &"string list"& in |
4954 | the descriptions later in this document. Others are listed as &"domain list"&, | |
4955 | &"host list"&, &"address list"&, or &"local part list"&. Syntactically, they | |
4956 | are all the same; however, those other than &"string list"& are subject to | |
068aaea8 | 4957 | particular kinds of interpretation, as described in chapter |
9b371988 | 4958 | &<<CHAPdomhosaddlists>>&. |
168e428f PH |
4959 | |
4960 | In all these cases, the entire list is treated as a single string as far as the | |
9b371988 PH |
4961 | input syntax is concerned. The &%trusted_users%& setting in section |
4962 | &<<SECTstrings>>& above is an example. If a colon is actually needed in an item | |
4963 | in a list, it must be entered as two colons. Leading and trailing white space | |
4964 | on each item in a list is ignored. This makes it possible to include items that | |
168e428f PH |
4965 | start with a colon, and in particular, certain forms of IPv6 address. For |
4966 | example, the list | |
9b371988 PH |
4967 | .code |
4968 | local_interfaces = 127.0.0.1 : ::::1 | |
4969 | .endd | |
068aaea8 PH |
4970 | contains two IP addresses, the IPv4 address 127.0.0.1 and the IPv6 address ::1. |
4971 | ||
9b371988 PH |
4972 | &*Note*&: Although leading and trailing white space is ignored in individual |
4973 | list items, it is not ignored when parsing the list. The space after the first | |
4974 | colon in the example above is necessary. If it were not there, the list would | |
4975 | be interpreted as the two items 127.0.0.1:: and 1. | |
168e428f | 4976 | |
f89d2485 | 4977 | .section "Changing list separators" "SECID53" |
9b371988 PH |
4978 | .cindex "list separator" "changing" |
4979 | .cindex "IPv6" "addresses in lists" | |
168e428f PH |
4980 | Doubling colons in IPv6 addresses is an unwelcome chore, so a mechanism was |
4981 | introduced to allow the separator character to be changed. If a list begins | |
4982 | with a left angle bracket, followed by any punctuation character, that | |
4983 | character is used instead of colon as the list separator. For example, the list | |
4984 | above can be rewritten to use a semicolon separator like this: | |
9b371988 PH |
4985 | .code |
4986 | local_interfaces = <; 127.0.0.1 ; ::1 | |
4987 | .endd | |
168e428f | 4988 | This facility applies to all lists, with the exception of the list in |
9b371988 | 4989 | &%log_file_path%&. It is recommended that the use of non-colon separators be |
168e428f PH |
4990 | confined to circumstances where they really are needed. |
4991 | ||
f89d2485 | 4992 | .cindex "list separator" "newline as" |
595028e4 | 4993 | .cindex "newline" "as list separator" |
f89d2485 PH |
4994 | It is also possible to use newline and other control characters (those with |
4995 | code values less than 32, plus DEL) as separators in lists. Such separators | |
4996 | must be provided literally at the time the list is processed. For options that | |
4997 | are string-expanded, you can write the separator using a normal escape | |
4998 | sequence. This will be processed by the expander before the string is | |
4999 | interpreted as a list. For example, if a newline-separated list of domains is | |
5000 | generated by a lookup, you can process it directly by a line such as this: | |
5001 | .code | |
5002 | domains = <\n ${lookup mysql{.....}} | |
5003 | .endd | |
5004 | This avoids having to change the list separator in such data. You are unlikely | |
5005 | to want to use a control character as a separator in an option that is not | |
5006 | expanded, because the value is literal text. However, it can be done by giving | |
5007 | the value in quotes. For example: | |
5008 | .code | |
5009 | local_interfaces = "<\n 127.0.0.1 \n ::1" | |
5010 | .endd | |
5011 | Unlike printing character separators, which can be included in list items by | |
5012 | doubling, it is not possible to include a control character as data when it is | |
5013 | set as the separator. Two such characters in succession are interpreted as | |
5014 | enclosing an empty list item. | |
f89d2485 | 5015 | |
168e428f PH |
5016 | |
5017 | ||
9b371988 PH |
5018 | .section "Empty items in lists" "SECTempitelis" |
5019 | .cindex "list" "empty item in" | |
168e428f PH |
5020 | An empty item at the end of a list is always ignored. In other words, trailing |
5021 | separator characters are ignored. Thus, the list in | |
9b371988 PH |
5022 | .code |
5023 | senders = user@domain : | |
5024 | .endd | |
168e428f PH |
5025 | contains only a single item. If you want to include an empty string as one item |
5026 | in a list, it must not be the last item. For example, this list contains three | |
5027 | items, the second of which is empty: | |
9b371988 PH |
5028 | .code |
5029 | senders = user1@domain : : user2@domain | |
5030 | .endd | |
5031 | &*Note*&: There must be white space between the two colons, as otherwise they | |
168e428f PH |
5032 | are interpreted as representing a single colon data character (and the list |
5033 | would then contain just one item). If you want to specify a list that contains | |
5034 | just one, empty item, you can do it as in this example: | |
9b371988 PH |
5035 | .code |
5036 | senders = : | |
5037 | .endd | |
168e428f PH |
5038 | In this case, the first item is empty, and the second is discarded because it |
5039 | is at the end of the list. | |
5040 | ||
5041 | ||
5042 | ||
5043 | ||
9b371988 PH |
5044 | .section "Format of driver configurations" "SECTfordricon" |
5045 | .cindex "drivers" "configuration format" | |
168e428f PH |
5046 | There are separate parts in the configuration for defining routers, transports, |
5047 | and authenticators. In each part, you are defining a number of driver | |
5048 | instances, each with its own set of options. Each driver instance is defined by | |
5049 | a sequence of lines like this: | |
9b371988 PH |
5050 | .display |
5051 | <&'instance name'&>: | |
5052 | <&'option'&> | |
168e428f | 5053 | ... |
9b371988 PH |
5054 | <&'option'&> |
5055 | .endd | |
5056 | In the following example, the instance name is &(localuser)&, and it is | |
168e428f | 5057 | followed by three options settings: |
9b371988 PH |
5058 | .code |
5059 | localuser: | |
5060 | driver = accept | |
5061 | check_local_user | |
5062 | transport = local_delivery | |
5063 | .endd | |
5064 | For each driver instance, you specify which Exim code module it uses &-- by the | |
5065 | setting of the &%driver%& option &-- and (optionally) some configuration | |
5066 | settings. For example, in the case of transports, if you want a transport to | |
5067 | deliver with SMTP you would use the &(smtp)& driver; if you want to deliver to | |
5068 | a local file you would use the &(appendfile)& driver. Each of the drivers is | |
5069 | described in detail in its own separate chapter later in this manual. | |
168e428f PH |
5070 | |
5071 | You can have several routers, transports, or authenticators that are based on | |
068aaea8 | 5072 | the same underlying driver (each must have a different instance name). |
168e428f PH |
5073 | |
5074 | The order in which routers are defined is important, because addresses are | |
5075 | passed to individual routers one by one, in order. The order in which | |
5076 | transports are defined does not matter at all. The order in which | |
5077 | authenticators are defined is used only when Exim, as a client, is searching | |
5078 | them to find one that matches an authentication mechanism offered by the | |
5079 | server. | |
5080 | ||
9b371988 PH |
5081 | .cindex "generic options" |
5082 | .cindex "options" "generic &-- definition of" | |
5083 | Within a driver instance definition, there are two kinds of option: &'generic'& | |
5084 | and &'private'&. The generic options are those that apply to all drivers of the | |
5085 | same type (that is, all routers, all transports or all authenticators). The | |
5086 | &%driver%& option is a generic option that must appear in every definition. | |
5087 | .cindex "private options" | |
168e428f PH |
5088 | The private options are special for each driver, and none need appear, because |
5089 | they all have default values. | |
5090 | ||
9b371988 | 5091 | The options may appear in any order, except that the &%driver%& option must |
168e428f | 5092 | precede any private options, since these depend on the particular driver. For |
9b371988 | 5093 | this reason, it is recommended that &%driver%& always be the first option. |
168e428f PH |
5094 | |
5095 | Driver instance names, which are used for reference in log entries and | |
5096 | elsewhere, can be any sequence of letters, digits, and underscores (starting | |
5097 | with a letter) and must be unique among drivers of the same type. A router and | |
5098 | a transport (for example) can each have the same name, but no two router | |
5099 | instances can have the same name. The name of a driver instance should not be | |
5100 | confused with the name of the underlying driver module. For example, the | |
5101 | configuration lines: | |
9b371988 PH |
5102 | .code |
5103 | remote_smtp: | |
5104 | driver = smtp | |
5105 | .endd | |
5106 | create an instance of the &(smtp)& transport driver whose name is | |
5107 | &(remote_smtp)&. The same driver code can be used more than once, with | |
168e428f | 5108 | different instance names and different option settings each time. A second |
9b371988 | 5109 | instance of the &(smtp)& transport, with different options, might be defined |
168e428f | 5110 | thus: |
9b371988 PH |
5111 | .code |
5112 | special_smtp: | |
5113 | driver = smtp | |
5114 | port = 1234 | |
5115 | command_timeout = 10s | |
5116 | .endd | |
5117 | The names &(remote_smtp)& and &(special_smtp)& would be used to reference | |
168e428f PH |
5118 | these transport instances from routers, and these names would appear in log |
5119 | lines. | |
5120 | ||
5121 | Comment lines may be present in the middle of driver specifications. The full | |
5122 | list of option settings for any particular driver instance, including all the | |
9b371988 | 5123 | defaulted values, can be extracted by making use of the &%-bP%& command line |
168e428f PH |
5124 | option. |
5125 | ||
5126 | ||
5127 | ||
5128 | ||
5129 | ||
5130 | ||
9b371988 PH |
5131 | . //////////////////////////////////////////////////////////////////////////// |
5132 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 5133 | |
9b371988 | 5134 | .chapter "The default configuration file" "CHAPdefconfil" |
4f578862 | 5135 | .scindex IIDconfiwal "configuration file" "default &""walk through""&" |
9b371988 PH |
5136 | .cindex "default" "configuration file &""walk through""&" |
5137 | The default configuration file supplied with Exim as &_src/configure.default_& | |
168e428f | 5138 | is sufficient for a host with simple mail requirements. As an introduction to |
9b371988 | 5139 | the way Exim is configured, this chapter &"walks through"& the default |
168e428f PH |
5140 | configuration, giving brief explanations of the settings. Detailed descriptions |
5141 | of the options are given in subsequent chapters. The default configuration file | |
5142 | itself contains extensive comments about ways you might want to modify the | |
5143 | initial settings. However, note that there are many options that are not | |
5144 | mentioned at all in the default configuration. | |
5145 | ||
5146 | ||
5147 | ||
6083aca0 | 5148 | .section "Main configuration settings" "SECTdefconfmain" |
168e428f PH |
5149 | The main (global) configuration option settings must always come first in the |
5150 | file. The first thing you'll see in the file, after some initial comments, is | |
5151 | the line | |
9b371988 PH |
5152 | .code |
5153 | # primary_hostname = | |
5154 | .endd | |
5155 | This is a commented-out setting of the &%primary_hostname%& option. Exim needs | |
168e428f PH |
5156 | to know the official, fully qualified name of your host, and this is where you |
5157 | can specify it. However, in most cases you do not need to set this option. When | |
9b371988 | 5158 | it is unset, Exim uses the &[uname()]& system function to obtain the host name. |
168e428f PH |
5159 | |
5160 | The first three non-comment configuration lines are as follows: | |
9b371988 PH |
5161 | .code |
5162 | domainlist local_domains = @ | |
5163 | domainlist relay_to_domains = | |
5164 | hostlist relay_from_hosts = 127.0.0.1 | |
5165 | .endd | |
168e428f PH |
5166 | These are not, in fact, option settings. They are definitions of two named |
5167 | domain lists and one named host list. Exim allows you to give names to lists of | |
5168 | domains, hosts, and email addresses, in order to make it easier to manage the | |
9b371988 | 5169 | configuration file (see section &<<SECTnamedlists>>&). |
168e428f | 5170 | |
9b371988 | 5171 | The first line defines a domain list called &'local_domains'&; this is used |
168e428f PH |
5172 | later in the configuration to identify domains that are to be delivered |
5173 | on the local host. | |
5174 | ||
9b371988 PH |
5175 | .cindex "@ in a domain list" |
5176 | There is just one item in this list, the string &"@"&. This is a special form | |
5177 | of entry which means &"the name of the local host"&. Thus, if the local host is | |
5178 | called &'a.host.example'&, mail to &'any.user@a.host.example'& is expected to | |
168e428f PH |
5179 | be delivered locally. Because the local host's name is referenced indirectly, |
5180 | the same configuration file can be used on different hosts. | |
5181 | ||
9b371988 | 5182 | The second line defines a domain list called &'relay_to_domains'&, but the |
168e428f PH |
5183 | list itself is empty. Later in the configuration we will come to the part that |
5184 | controls mail relaying through the local host; it allows relaying to any | |
5185 | domains in this list. By default, therefore, no relaying on the basis of a mail | |
5186 | domain is permitted. | |
5187 | ||
9b371988 | 5188 | The third line defines a host list called &'relay_from_hosts'&. This list is |
168e428f PH |
5189 | used later in the configuration to permit relaying from any host or IP address |
5190 | that matches the list. The default contains just the IP address of the IPv4 | |
5191 | loopback interface, which means that processes on the local host are able to | |
5192 | submit mail for relaying by sending it over TCP/IP to that interface. No other | |
5193 | hosts are permitted to submit messages for relaying. | |
5194 | ||
5195 | Just to be sure there's no misunderstanding: at this point in the configuration | |
5196 | we aren't actually setting up any controls. We are just defining some domains | |
5197 | and hosts that will be used in the controls that are specified later. | |
5198 | ||
068aaea8 | 5199 | The next two configuration lines are genuine option settings: |
9b371988 PH |
5200 | .code |
5201 | acl_smtp_rcpt = acl_check_rcpt | |
5202 | acl_smtp_data = acl_check_data | |
5203 | .endd | |
9b371988 PH |
5204 | These options specify &'Access Control Lists'& (ACLs) that are to be used |
5205 | during an incoming SMTP session for every recipient of a message (every RCPT | |
5206 | command), and after the contents of the message have been received, | |
5207 | respectively. The names of the lists are &'acl_check_rcpt'& and | |
5208 | &'acl_check_data'&, and we will come to their definitions below, in the ACL | |
5209 | section of the configuration. The RCPT ACL controls which recipients are | |
5210 | accepted for an incoming message &-- if a configuration does not provide an ACL | |
5211 | to check recipients, no SMTP mail can be accepted. The DATA ACL allows the | |
5212 | contents of a message to be checked. | |
168e428f | 5213 | |
068aaea8 | 5214 | Two commented-out option settings are next: |
9b371988 | 5215 | .code |
068aaea8 PH |
5216 | # av_scanner = clamd:/tmp/clamd |
5217 | # spamd_address = 127.0.0.1 783 | |
9b371988 | 5218 | .endd |
068aaea8 PH |
5219 | These are example settings that can be used when Exim is compiled with the |
5220 | content-scanning extension. The first specifies the interface to the virus | |
5221 | scanner, and the second specifies the interface to SpamAssassin. Further | |
9b371988 | 5222 | details are given in chapter &<<CHAPexiscan>>&. |
168e428f | 5223 | |
6083aca0 TF |
5224 | Three more commented-out option settings follow: |
5225 | .code | |
5226 | # tls_advertise_hosts = * | |
5227 | # tls_certificate = /etc/ssl/exim.crt | |
5228 | # tls_privatekey = /etc/ssl/exim.pem | |
5229 | .endd | |
5230 | These are example settings that can be used when Exim is compiled with | |
db9452a9 PH |
5231 | support for TLS (aka SSL) as described in section &<<SECTinctlsssl>>&. The |
5232 | first one specifies the list of clients that are allowed to use TLS when | |
5233 | connecting to this server; in this case the wildcard means all clients. The | |
5234 | other options specify where Exim should find its TLS certificate and private | |
5235 | key, which together prove the server's identity to any clients that connect. | |
5236 | More details are given in chapter &<<CHAPTLS>>&. | |
6083aca0 TF |
5237 | |
5238 | Another two commented-out option settings follow: | |
5239 | .code | |
5240 | # daemon_smtp_ports = 25 : 465 : 587 | |
5241 | # tls_on_connect_ports = 465 | |
5242 | .endd | |
db9452a9 PH |
5243 | .cindex "port" "465 and 587" |
5244 | .cindex "port" "for message submission" | |
5245 | .cindex "message" "submission, ports for" | |
5246 | .cindex "ssmtp protocol" | |
5247 | .cindex "smtps protocol" | |
5248 | .cindex "SMTP" "ssmtp protocol" | |
5249 | .cindex "SMTP" "smtps protocol" | |
5250 | These options provide better support for roaming users who wish to use this | |
5251 | server for message submission. They are not much use unless you have turned on | |
5252 | TLS (as described in the previous paragraph) and authentication (about which | |
5253 | more in section &<<SECTdefconfauth>>&). The usual SMTP port 25 is often blocked | |
5254 | on end-user networks, so RFC 4409 specifies that message submission should use | |
5255 | port 587 instead. However some software (notably Microsoft Outlook) cannot be | |
5256 | configured to use port 587 correctly, so these settings also enable the | |
5257 | non-standard &"smtps"& (aka &"ssmtp"&) port 465 (see section | |
5258 | &<<SECTsupobssmt>>&). | |
6083aca0 | 5259 | |
068aaea8 | 5260 | Two more commented-out options settings follow: |
9b371988 PH |
5261 | .code |
5262 | # qualify_domain = | |
5263 | # qualify_recipient = | |
5264 | .endd | |
168e428f PH |
5265 | The first of these specifies a domain that Exim uses when it constructs a |
5266 | complete email address from a local login name. This is often needed when Exim | |
9b371988 PH |
5267 | receives a message from a local process. If you do not set &%qualify_domain%&, |
5268 | the value of &%primary_hostname%& is used. If you set both of these options, | |
5269 | you can have different qualification domains for sender and recipient | |
5270 | addresses. If you set only the first one, its value is used in both cases. | |
168e428f | 5271 | |
9b371988 | 5272 | .cindex "domain literal" "recognizing format" |
168e428f | 5273 | The following line must be uncommented if you want Exim to recognize |
9b371988 | 5274 | addresses of the form &'user@[10.11.12.13]'& that is, with a &"domain literal"& |
068aaea8 | 5275 | (an IP address within square brackets) instead of a named domain. |
9b371988 PH |
5276 | .code |
5277 | # allow_domain_literals | |
5278 | .endd | |
168e428f PH |
5279 | The RFCs still require this form, but many people think that in the modern |
5280 | Internet it makes little sense to permit mail to be sent to specific hosts by | |
5281 | quoting their IP addresses. This ancient format has been used by people who | |
5282 | try to abuse hosts by using them for unwanted relaying. However, some | |
5283 | people believe there are circumstances (for example, messages addressed to | |
9b371988 | 5284 | &'postmaster'&) where domain literals are still useful. |
168e428f PH |
5285 | |
5286 | The next configuration line is a kind of trigger guard: | |
9b371988 PH |
5287 | .code |
5288 | never_users = root | |
5289 | .endd | |
168e428f | 5290 | It specifies that no delivery must ever be run as the root user. The normal |
9b371988 | 5291 | convention is to set up &'root'& as an alias for the system administrator. This |
168e428f | 5292 | setting is a guard against slips in the configuration. |
9b371988 PH |
5293 | The list of users specified by &%never_users%& is not, however, the complete |
5294 | list; the build-time configuration in &_Local/Makefile_& has an option called | |
168e428f | 5295 | FIXED_NEVER_USERS specifying a list that cannot be overridden. The |
9b371988 | 5296 | contents of &%never_users%& are added to this list. By default |
168e428f PH |
5297 | FIXED_NEVER_USERS also specifies root. |
5298 | ||
5299 | When a remote host connects to Exim in order to send mail, the only information | |
5300 | Exim has about the host's identity is its IP address. The next configuration | |
5301 | line, | |
9b371988 PH |
5302 | .code |
5303 | host_lookup = * | |
5304 | .endd | |
168e428f PH |
5305 | specifies that Exim should do a reverse DNS lookup on all incoming connections, |
5306 | in order to get a host name. This improves the quality of the logging | |
5307 | information, but if you feel it is too expensive, you can remove it entirely, | |
9b371988 | 5308 | or restrict the lookup to hosts on &"nearby"& networks. |
168e428f PH |
5309 | Note that it is not always possible to find a host name from an IP address, |
5310 | because not all DNS reverse zones are maintained, and sometimes DNS servers are | |
5311 | unreachable. | |
5312 | ||
9b371988 | 5313 | The next two lines are concerned with &'ident'& callbacks, as defined by RFC |
168e428f | 5314 | 1413 (hence their names): |
9b371988 PH |
5315 | .code |
5316 | rfc1413_hosts = * | |
c0712871 | 5317 | rfc1413_query_timeout = 5s |
9b371988 | 5318 | .endd |
168e428f PH |
5319 | These settings cause Exim to make ident callbacks for all incoming SMTP calls. |
5320 | You can limit the hosts to which these calls are made, or change the timeout | |
5321 | that is used. If you set the timeout to zero, all ident calls are disabled. | |
5322 | Although they are cheap and can provide useful information for tracing problem | |
5323 | messages, some hosts and firewalls have problems with ident calls. This can | |
5324 | result in a timeout instead of an immediate refused connection, leading to | |
5325 | delays on starting up an incoming SMTP session. | |
5326 | ||
5327 | When Exim receives messages over SMTP connections, it expects all addresses to | |
5328 | be fully qualified with a domain, as required by the SMTP definition. However, | |
5329 | if you are running a server to which simple clients submit messages, you may | |
5330 | find that they send unqualified addresses. The two commented-out options: | |
9b371988 PH |
5331 | .code |
5332 | # sender_unqualified_hosts = | |
5333 | # recipient_unqualified_hosts = | |
5334 | .endd | |
168e428f PH |
5335 | show how you can specify hosts that are permitted to send unqualified sender |
5336 | and recipient addresses, respectively. | |
5337 | ||
9b371988 PH |
5338 | The &%percent_hack_domains%& option is also commented out: |
5339 | .code | |
5340 | # percent_hack_domains = | |
5341 | .endd | |
5342 | It provides a list of domains for which the &"percent hack"& is to operate. | |
5343 | This is an almost obsolete form of explicit email routing. If you do not know | |
168e428f PH |
5344 | anything about it, you can safely ignore this topic. |
5345 | ||
5346 | The last two settings in the main part of the default configuration are | |
9b371988 PH |
5347 | concerned with messages that have been &"frozen"& on Exim's queue. When a |
5348 | message is frozen, Exim no longer continues to try to deliver it. Freezing | |
5349 | occurs when a bounce message encounters a permanent failure because the sender | |
5350 | address of the original message that caused the bounce is invalid, so the | |
5351 | bounce cannot be delivered. This is probably the most common case, but there | |
5352 | are also other conditions that cause freezing, and frozen messages are not | |
5353 | always bounce messages. | |
5354 | .code | |
5355 | ignore_bounce_errors_after = 2d | |
5356 | timeout_frozen_after = 7d | |
5357 | .endd | |
168e428f PH |
5358 | The first of these options specifies that failing bounce messages are to be |
5359 | discarded after 2 days on the queue. The second specifies that any frozen | |
5360 | message (whether a bounce message or not) is to be timed out (and discarded) | |
5361 | after a week. In this configuration, the first setting ensures that no failing | |
5362 | bounce message ever lasts a week. | |
5363 | ||
5364 | ||
5365 | ||
f89d2485 | 5366 | .section "ACL configuration" "SECID54" |
9b371988 PH |
5367 | .cindex "default" "ACLs" |
5368 | .cindex "&ACL;" "default configuration" | |
168e428f PH |
5369 | In the default configuration, the ACL section follows the main configuration. |
5370 | It starts with the line | |
9b371988 PH |
5371 | .code |
5372 | begin acl | |
5373 | .endd | |
5374 | and it contains the definitions of two ACLs, called &'acl_check_rcpt'& and | |
5375 | &'acl_check_data'&, that were referenced in the settings of &%acl_smtp_rcpt%& | |
5376 | and &%acl_smtp_data%& above. | |
5377 | ||
5378 | .cindex "RCPT" "ACL for" | |
068aaea8 | 5379 | The first ACL is used for every RCPT command in an incoming SMTP message. Each |
168e428f PH |
5380 | RCPT command specifies one of the message's recipients. The ACL statements |
5381 | are considered in order, until the recipient address is either accepted or | |
5382 | rejected. The RCPT command is then accepted or rejected, according to the | |
5383 | result of the ACL processing. | |
9b371988 PH |
5384 | .code |
5385 | acl_check_rcpt: | |
5386 | .endd | |
168e428f PH |
5387 | This line, consisting of a name terminated by a colon, marks the start of the |
5388 | ACL, and names it. | |
9b371988 PH |
5389 | .code |
5390 | accept hosts = : | |
5391 | .endd | |
168e428f PH |
5392 | This ACL statement accepts the recipient if the sending host matches the list. |
5393 | But what does that strange list mean? It doesn't actually contain any host | |
5394 | names or IP addresses. The presence of the colon puts an empty item in the | |
068aaea8 PH |
5395 | list; Exim matches this only if the incoming message did not come from a remote |
5396 | host, because in that case, the remote hostname is empty. The colon is | |
5397 | important. Without it, the list itself is empty, and can never match anything. | |
168e428f PH |
5398 | |
5399 | What this statement is doing is to accept unconditionally all recipients in | |
5400 | messages that are submitted by SMTP from local processes using the standard | |
5401 | input and output (that is, not using TCP/IP). A number of MUAs operate in this | |
5402 | manner. | |
9b371988 PH |
5403 | .code |
5404 | deny message = Restricted characters in address | |
5405 | domains = +local_domains | |
5406 | local_parts = ^[.] : ^.*[@%!/|] | |
5407 | ||
5408 | deny message = Restricted characters in address | |
5409 | domains = !+local_domains | |
5410 | local_parts = ^[./|] : ^.*[@%!] : ^.*/\\.\\./ | |
5411 | .endd | |
168e428f | 5412 | These statements are concerned with local parts that contain any of the |
9b371988 PH |
5413 | characters &"@"&, &"%"&, &"!"&, &"/"&, &"|"&, or dots in unusual places. |
5414 | Although these characters are entirely legal in local parts (in the case of | |
5415 | &"@"& and leading dots, only if correctly quoted), they do not commonly occur | |
5416 | in Internet mail addresses. | |
168e428f PH |
5417 | |
5418 | The first three have in the past been associated with explicitly routed | |
9b371988 | 5419 | addresses (percent is still sometimes used &-- see the &%percent_hack_domains%& |
168e428f PH |
5420 | option). Addresses containing these characters are regularly tried by spammers |
5421 | in an attempt to bypass relaying restrictions, and also by open relay testing | |
5422 | programs. Unless you really need them it is safest to reject these characters | |
5423 | at this early stage. This configuration is heavy-handed in rejecting these | |
5424 | characters for all messages it accepts from remote hosts. This is a deliberate | |
5425 | policy of being as safe as possible. | |
5426 | ||
5427 | The first rule above is stricter, and is applied to messages that are addressed | |
5428 | to one of the local domains handled by this host. This is implemented by the | |
5429 | first condition, which restricts it to domains that are listed in the | |
9b371988 | 5430 | &'local_domains'& domain list. The &"+"& character is used to indicate a |
168e428f | 5431 | reference to a named list. In this configuration, there is just one domain in |
9b371988 | 5432 | &'local_domains'&, but in general there may be many. |
168e428f PH |
5433 | |
5434 | The second condition on the first statement uses two regular expressions to | |
9b371988 PH |
5435 | block local parts that begin with a dot or contain &"@"&, &"%"&, &"!"&, &"/"&, |
5436 | or &"|"&. If you have local accounts that include these characters, you will | |
5437 | have to modify this rule. | |
168e428f PH |
5438 | |
5439 | Empty components (two dots in a row) are not valid in RFC 2822, but Exim | |
9b371988 PH |
5440 | allows them because they have been encountered in practice. (Consider the |
5441 | common convention of local parts constructed as | |
5442 | &"&'first-initial.second-initial.family-name'&"& when applied to someone like | |
5443 | the author of Exim, who has no second initial.) However, a local part starting | |
5444 | with a dot or containing &"/../"& can cause trouble if it is used as part of a | |
5445 | file name (for example, for a mailing list). This is also true for local parts | |
5446 | that contain slashes. A pipe symbol can also be troublesome if the local part | |
5447 | is incorporated unthinkingly into a shell command line. | |
168e428f PH |
5448 | |
5449 | The second rule above applies to all other domains, and is less strict. This | |
5450 | allows your own users to send outgoing messages to sites that use slashes | |
5451 | and vertical bars in their local parts. It blocks local parts that begin | |
5452 | with a dot, slash, or vertical bar, but allows these characters within the | |
9b371988 PH |
5453 | local part. However, the sequence &"/../"& is barred. The use of &"@"&, &"%"&, |
5454 | and &"!"& is blocked, as before. The motivation here is to prevent your users | |
5455 | (or your users' viruses) from mounting certain kinds of attack on remote sites. | |
5456 | .code | |
5457 | accept local_parts = postmaster | |
5458 | domains = +local_domains | |
5459 | .endd | |
168e428f | 5460 | This statement, which has two conditions, accepts an incoming address if the |
9b371988 PH |
5461 | local part is &'postmaster'& and the domain is one of those listed in the |
5462 | &'local_domains'& domain list. The &"+"& character is used to indicate a | |
168e428f | 5463 | reference to a named list. In this configuration, there is just one domain in |
9b371988 | 5464 | &'local_domains'&, but in general there may be many. |
168e428f PH |
5465 | |
5466 | The presence of this statement means that mail to postmaster is never blocked | |
5467 | by any of the subsequent tests. This can be helpful while sorting out problems | |
5468 | in cases where the subsequent tests are incorrectly denying access. | |
9b371988 PH |
5469 | .code |
5470 | require verify = sender | |
5471 | .endd | |
168e428f PH |
5472 | This statement requires the sender address to be verified before any subsequent |
5473 | ACL statement can be used. If verification fails, the incoming recipient | |
5474 | address is refused. Verification consists of trying to route the address, to | |
068aaea8 | 5475 | see if a bounce message could be delivered to it. In the case of remote |
9b371988 PH |
5476 | addresses, basic verification checks only the domain, but &'callouts'& can be |
5477 | used for more verification if required. Section &<<SECTaddressverification>>& | |
068aaea8 | 5478 | discusses the details of address verification. |
9b371988 PH |
5479 | .code |
5480 | accept hosts = +relay_from_hosts | |
5481 | control = submission | |
5482 | .endd | |
068aaea8 PH |
5483 | This statement accepts the address if the message is coming from one of the |
5484 | hosts that are defined as being allowed to relay through this host. Recipient | |
5485 | verification is omitted here, because in many cases the clients are dumb MUAs | |
5486 | that do not cope well with SMTP error responses. For the same reason, the | |
9b371988 PH |
5487 | second line specifies &"submission mode"& for messages that are accepted. This |
5488 | is described in detail in section &<<SECTsubmodnon>>&; it causes Exim to fix | |
068aaea8 | 5489 | messages that are deficient in some way, for example, because they lack a |
9b371988 | 5490 | &'Date:'& header line. If you are actually relaying out from MTAs, you should |
068aaea8 | 5491 | probably add recipient verification here, and disable submission mode. |
9b371988 PH |
5492 | .code |
5493 | accept authenticated = * | |
5494 | control = submission | |
5495 | .endd | |
068aaea8 PH |
5496 | This statement accepts the address if the client host has authenticated itself. |
5497 | Submission mode is again specified, on the grounds that such messages are most | |
5498 | likely to come from MUAs. The default configuration does not define any | |
6083aca0 TF |
5499 | authenticators, though it does include some nearly complete commented-out |
5500 | examples described in &<<SECTdefconfauth>>&. This means that no client can in | |
5501 | fact authenticate until you complete the authenticator definitions. | |
db9452a9 PH |
5502 | .code |
5503 | require message = relay not permitted | |
5504 | domains = +local_domains : +relay_domains | |
5505 | .endd | |
5506 | This statement rejects the address if its domain is neither a local domain nor | |
5507 | one of the domains for which this host is a relay. | |
5508 | .code | |
5509 | require verify = recipient | |
5510 | .endd | |
5511 | This statement requires the recipient address to be verified; if verification | |
5512 | fails, the address is rejected. | |
9b371988 PH |
5513 | .code |
5514 | # deny message = rejected because $sender_host_address \ | |
5515 | # is in a black list at $dnslist_domain\n\ | |
5516 | # $dnslist_text | |
5517 | # dnslists = black.list.example | |
168e428f | 5518 | # |
db9452a9 PH |
5519 | # warn dnslists = black.list.example |
5520 | # add_header = X-Warning: $sender_host_address is in \ | |
5521 | # a black list at $dnslist_domain | |
9b371988 | 5522 | # log_message = found in $dnslist_domain |
9b371988 | 5523 | .endd |
168e428f PH |
5524 | These commented-out lines are examples of how you could configure Exim to check |
5525 | sending hosts against a DNS black list. The first statement rejects messages | |
db9452a9 | 5526 | from blacklisted hosts, whereas the second just inserts a warning header |
168e428f | 5527 | line. |
9b371988 | 5528 | .code |
db9452a9 | 5529 | # require verify = csa |
9b371988 | 5530 | .endd |
db9452a9 PH |
5531 | This commented-out line is an example of how you could turn on client SMTP |
5532 | authorization (CSA) checking. Such checks do DNS lookups for special SRV | |
5533 | records. | |
9b371988 | 5534 | .code |
db9452a9 | 5535 | accept |
9b371988 | 5536 | .endd |
db9452a9 PH |
5537 | The final statement in the first ACL unconditionally accepts any recipient |
5538 | address that has successfully passed all the previous tests. | |
9b371988 PH |
5539 | .code |
5540 | acl_check_data: | |
5541 | .endd | |
068aaea8 PH |
5542 | This line marks the start of the second ACL, and names it. Most of the contents |
5543 | of this ACL are commented out: | |
9b371988 | 5544 | .code |
068aaea8 PH |
5545 | # deny malware = * |
5546 | # message = This message contains a virus \ | |
5547 | # ($malware_name). | |
9b371988 | 5548 | .endd |
068aaea8 PH |
5549 | These lines are examples of how to arrange for messages to be scanned for |
5550 | viruses when Exim has been compiled with the content-scanning extension, and a | |
5551 | suitable virus scanner is installed. If the message is found to contain a | |
5552 | virus, it is rejected with the given custom error message. | |
9b371988 | 5553 | .code |
068aaea8 PH |
5554 | # warn spam = nobody |
5555 | # message = X-Spam_score: $spam_score\n\ | |
5556 | # X-Spam_score_int: $spam_score_int\n\ | |
5557 | # X-Spam_bar: $spam_bar\n\ | |
5558 | # X-Spam_report: $spam_report | |
9b371988 | 5559 | .endd |
068aaea8 PH |
5560 | These lines are an example of how to arrange for messages to be scanned by |
5561 | SpamAssassin when Exim has been compiled with the content-scanning extension, | |
5562 | and SpamAssassin has been installed. The SpamAssassin check is run with | |
9b371988 | 5563 | &`nobody`& as its user parameter, and the results are added to the message as a |
068aaea8 PH |
5564 | series of extra header line. In this case, the message is not rejected, |
5565 | whatever the spam score. | |
9b371988 PH |
5566 | .code |
5567 | accept | |
5568 | .endd | |
068aaea8 PH |
5569 | This final line in the DATA ACL accepts the message unconditionally. |
5570 | ||
168e428f | 5571 | |
f89d2485 | 5572 | .section "Router configuration" "SECID55" |
9b371988 PH |
5573 | .cindex "default" "routers" |
5574 | .cindex "routers" "default" | |
168e428f PH |
5575 | The router configuration comes next in the default configuration, introduced |
5576 | by the line | |
9b371988 PH |
5577 | .code |
5578 | begin routers | |
5579 | .endd | |
168e428f PH |
5580 | Routers are the modules in Exim that make decisions about where to send |
5581 | messages. An address is passed to each router in turn, until it is either | |
5582 | accepted, or failed. This means that the order in which you define the routers | |
5583 | matters. Each router is fully described in its own chapter later in this | |
5584 | manual. Here we give only brief overviews. | |
9b371988 PH |
5585 | .code |
5586 | # domain_literal: | |
5587 | # driver = ipliteral | |
5588 | # domains = !+local_domains | |
5589 | # transport = remote_smtp | |
5590 | .endd | |
5591 | .cindex "domain literal" "default router" | |
168e428f | 5592 | This router is commented out because the majority of sites do not want to |
9b371988 | 5593 | support domain literal addresses (those of the form &'user@[10.9.8.7]'&). If |
168e428f | 5594 | you uncomment this router, you also need to uncomment the setting of |
9b371988 PH |
5595 | &%allow_domain_literals%& in the main part of the configuration. |
5596 | .code | |
5597 | dnslookup: | |
5598 | driver = dnslookup | |
5599 | domains = ! +local_domains | |
5600 | transport = remote_smtp | |
5601 | ignore_target_hosts = 0.0.0.0 : 127.0.0.0/8 | |
5602 | no_more | |
5603 | .endd | |
168e428f PH |
5604 | The first uncommented router handles addresses that do not involve any local |
5605 | domains. This is specified by the line | |
9b371988 PH |
5606 | .code |
5607 | domains = ! +local_domains | |
5608 | .endd | |
5609 | The &%domains%& option lists the domains to which this router applies, but the | |
168e428f | 5610 | exclamation mark is a negation sign, so the router is used only for domains |
9b371988 PH |
5611 | that are not in the domain list called &'local_domains'& (which was defined at |
5612 | the start of the configuration). The plus sign before &'local_domains'& | |
168e428f PH |
5613 | indicates that it is referring to a named list. Addresses in other domains are |
5614 | passed on to the following routers. | |
5615 | ||
9b371988 PH |
5616 | The name of the router driver is &(dnslookup)&, |
5617 | and is specified by the &%driver%& option. Do not be confused by the fact that | |
168e428f | 5618 | the name of this router instance is the same as the name of the driver. The |
9b371988 PH |
5619 | instance name is arbitrary, but the name set in the &%driver%& option must be |
5620 | one of the driver modules that is in the Exim binary. | |
168e428f | 5621 | |
9b371988 | 5622 | The &(dnslookup)& router routes addresses by looking up their domains in the |
168e428f | 5623 | DNS in order to obtain a list of hosts to which the address is routed. If the |
9b371988 PH |
5624 | router succeeds, the address is queued for the &(remote_smtp)& transport, as |
5625 | specified by the &%transport%& option. If the router does not find the domain | |
5626 | in the DNS, no further routers are tried because of the &%no_more%& setting, so | |
5627 | the address fails and is bounced. | |
168e428f | 5628 | |
9b371988 | 5629 | The &%ignore_target_hosts%& option specifies a list of IP addresses that are to |
168e428f PH |
5630 | be entirely ignored. This option is present because a number of cases have been |
5631 | encountered where MX records in the DNS point to host names | |
5632 | whose IP addresses are 0.0.0.0 or are in the 127 subnet (typically 127.0.0.1). | |
5633 | Completely ignoring these IP addresses causes Exim to fail to route the | |
5634 | email address, so it bounces. Otherwise, Exim would log a routing problem, and | |
5635 | continue to try to deliver the message periodically until the address timed | |
5636 | out. | |
9b371988 PH |
5637 | .code |
5638 | system_aliases: | |
5639 | driver = redirect | |
5640 | allow_fail | |
5641 | allow_defer | |
5642 | data = ${lookup{$local_part}lsearch{/etc/aliases}} | |
5643 | # user = exim | |
5644 | file_transport = address_file | |
5645 | pipe_transport = address_pipe | |
5646 | .endd | |
168e428f PH |
5647 | Control reaches this and subsequent routers only for addresses in the local |
5648 | domains. This router checks to see whether the local part is defined as an | |
9b371988 | 5649 | alias in the &_/etc/aliases_& file, and if so, redirects it according to the |
168e428f | 5650 | data that it looks up from that file. If no data is found for the local part, |
9b371988 | 5651 | the value of the &%data%& option is empty, causing the address to be passed to |
168e428f PH |
5652 | the next router. |
5653 | ||
9b371988 | 5654 | &_/etc/aliases_& is a conventional name for the system aliases file that is |
168e428f PH |
5655 | often used. That is why it is referenced by from the default configuration |
5656 | file. However, you can change this by setting SYSTEM_ALIASES_FILE in | |
9b371988 PH |
5657 | &_Local/Makefile_& before building Exim. |
5658 | .code | |
5659 | userforward: | |
5660 | driver = redirect | |
5661 | check_local_user | |
5662 | # local_part_suffix = +* : -* | |
5663 | # local_part_suffix_optional | |
5664 | file = $home/.forward | |
5665 | # allow_filter | |
5666 | no_verify | |
5667 | no_expn | |
5668 | check_ancestor | |
5669 | file_transport = address_file | |
5670 | pipe_transport = address_pipe | |
5671 | reply_transport = address_reply | |
5672 | .endd | |
168e428f PH |
5673 | This is the most complicated router in the default configuration. It is another |
5674 | redirection router, but this time it is looking for forwarding data set up by | |
9b371988 | 5675 | individual users. The &%check_local_user%& setting specifies a check that the |
068aaea8 | 5676 | local part of the address is the login name of a local user. If it is not, the |
9b371988 | 5677 | router is skipped. The two commented options that follow &%check_local_user%&, |
068aaea8 | 5678 | namely: |
9b371988 | 5679 | .code |
068aaea8 PH |
5680 | # local_part_suffix = +* : -* |
5681 | # local_part_suffix_optional | |
9b371988 | 5682 | .endd |
f89d2485 | 5683 | .vindex "&$local_part_suffix$&" |
068aaea8 PH |
5684 | show how you can specify the recognition of local part suffixes. If the first |
5685 | is uncommented, a suffix beginning with either a plus or a minus sign, followed | |
5686 | by any sequence of characters, is removed from the local part and placed in the | |
9b371988 | 5687 | variable &$local_part_suffix$&. The second suffix option specifies that the |
068aaea8 PH |
5688 | presence of a suffix in the local part is optional. When a suffix is present, |
5689 | the check for a local login uses the local part with the suffix removed. | |
5690 | ||
9b371988 | 5691 | When a local user account is found, the file called &_.forward_& in the user's |
068aaea8 | 5692 | home directory is consulted. If it does not exist, or is empty, the router |
9b371988 PH |
5693 | declines. Otherwise, the contents of &_.forward_& are interpreted as |
5694 | redirection data (see chapter &<<CHAPredirect>>& for more details). | |
5695 | ||
5696 | .cindex "Sieve filter" "enabling in default router" | |
5697 | Traditional &_.forward_& files contain just a list of addresses, pipes, or | |
5698 | files. Exim supports this by default. However, if &%allow_filter%& is set (it | |
5699 | is commented out by default), the contents of the file are interpreted as a set | |
5700 | of Exim or Sieve filtering instructions, provided the file begins with &"#Exim | |
5701 | filter"& or &"#Sieve filter"&, respectively. User filtering is discussed in the | |
5702 | separate document entitled &'Exim's interfaces to mail filtering'&. | |
5703 | ||
5704 | The &%no_verify%& and &%no_expn%& options mean that this router is skipped when | |
068aaea8 | 5705 | verifying addresses, or when running as a consequence of an SMTP EXPN command. |
168e428f PH |
5706 | There are two reasons for doing this: |
5707 | ||
9b371988 PH |
5708 | .olist |
5709 | Whether or not a local user has a &_.forward_& file is not really relevant when | |
168e428f PH |
5710 | checking an address for validity; it makes sense not to waste resources doing |
5711 | unnecessary work. | |
9b371988 PH |
5712 | .next |
5713 | More importantly, when Exim is verifying addresses or handling an EXPN | |
168e428f PH |
5714 | command during an SMTP session, it is running as the Exim user, not as root. |
5715 | The group is the Exim group, and no additional groups are set up. | |
9b371988 | 5716 | It may therefore not be possible for Exim to read users' &_.forward_& files at |
168e428f | 5717 | this time. |
9b371988 | 5718 | .endlist |
168e428f | 5719 | |
9b371988 | 5720 | The setting of &%check_ancestor%& prevents the router from generating a new |
168e428f PH |
5721 | address that is the same as any previous address that was redirected. (This |
5722 | works round a problem concerning a bad interaction between aliasing and | |
9b371988 | 5723 | forwarding &-- see section &<<SECTredlocmai>>&). |
168e428f PH |
5724 | |
5725 | The final three option settings specify the transports that are to be used when | |
5726 | forwarding generates a direct delivery to a file, or to a pipe, or sets up an | |
9b371988 PH |
5727 | auto-reply, respectively. For example, if a &_.forward_& file contains |
5728 | .code | |
5729 | a.nother@elsewhere.example, /home/spqr/archive | |
5730 | .endd | |
5731 | the delivery to &_/home/spqr/archive_& is done by running the &%address_file%& | |
168e428f | 5732 | transport. |
9b371988 PH |
5733 | .code |
5734 | localuser: | |
5735 | driver = accept | |
5736 | check_local_user | |
5737 | # local_part_suffix = +* : -* | |
5738 | # local_part_suffix_optional | |
5739 | transport = local_delivery | |
5740 | .endd | |
168e428f | 5741 | The final router sets up delivery into local mailboxes, provided that the local |
068aaea8 | 5742 | part is the name of a local login, by accepting the address and assigning it to |
9b371988 | 5743 | the &(local_delivery)& transport. Otherwise, we have reached the end of the |
068aaea8 | 5744 | routers, so the address is bounced. The commented suffix settings fulfil the |
9b371988 | 5745 | same purpose as they do for the &(userforward)& router. |
168e428f PH |
5746 | |
5747 | ||
f89d2485 | 5748 | .section "Transport configuration" "SECID56" |
9b371988 PH |
5749 | .cindex "default" "transports" |
5750 | .cindex "transports" "default" | |
168e428f PH |
5751 | Transports define mechanisms for actually delivering messages. They operate |
5752 | only when referenced from routers, so the order in which they are defined does | |
5753 | not matter. The transports section of the configuration starts with | |
9b371988 PH |
5754 | .code |
5755 | begin transports | |
5756 | .endd | |
168e428f | 5757 | One remote transport and four local transports are defined. |
9b371988 PH |
5758 | .code |
5759 | remote_smtp: | |
5760 | driver = smtp | |
5761 | .endd | |
168e428f PH |
5762 | This transport is used for delivering messages over SMTP connections. All its |
5763 | options are defaulted. The list of remote hosts comes from the router. | |
9b371988 PH |
5764 | .code |
5765 | local_delivery: | |
5766 | driver = appendfile | |
5767 | file = /var/mail/$local_part | |
5768 | delivery_date_add | |
5769 | envelope_to_add | |
5770 | return_path_add | |
5771 | # group = mail | |
5772 | # mode = 0660 | |
5773 | .endd | |
5774 | This &(appendfile)& transport is used for local delivery to user mailboxes in | |
168e428f | 5775 | traditional BSD mailbox format. By default it runs under the uid and gid of the |
9b371988 | 5776 | local user, which requires the sticky bit to be set on the &_/var/mail_& |
168e428f PH |
5777 | directory. Some systems use the alternative approach of running mail deliveries |
5778 | under a particular group instead of using the sticky bit. The commented options | |
5779 | show how this can be done. | |
5780 | ||
9b371988 PH |
5781 | Exim adds three headers to the message as it delivers it: &'Delivery-date:'&, |
5782 | &'Envelope-to:'& and &'Return-path:'&. This action is requested by the three | |
168e428f | 5783 | similarly-named options above. |
9b371988 PH |
5784 | .code |
5785 | address_pipe: | |
5786 | driver = pipe | |
5787 | return_output | |
5788 | .endd | |
168e428f | 5789 | This transport is used for handling deliveries to pipes that are generated by |
9b371988 | 5790 | redirection (aliasing or users' &_.forward_& files). The &%return_output%& |
168e428f PH |
5791 | option specifies that any output generated by the pipe is to be returned to the |
5792 | sender. | |
9b371988 PH |
5793 | .code |
5794 | address_file: | |
5795 | driver = appendfile | |
5796 | delivery_date_add | |
5797 | envelope_to_add | |
5798 | return_path_add | |
5799 | .endd | |
168e428f PH |
5800 | This transport is used for handling deliveries to files that are generated by |
5801 | redirection. The name of the file is not specified in this instance of | |
9b371988 PH |
5802 | &(appendfile)&, because it comes from the &(redirect)& router. |
5803 | .code | |
5804 | address_reply: | |
5805 | driver = autoreply | |
5806 | .endd | |
168e428f PH |
5807 | This transport is used for handling automatic replies generated by users' |
5808 | filter files. | |
5809 | ||
5810 | ||
5811 | ||
f89d2485 | 5812 | .section "Default retry rule" "SECID57" |
9b371988 PH |
5813 | .cindex "retry" "default rule" |
5814 | .cindex "default" "retry rule" | |
168e428f PH |
5815 | The retry section of the configuration file contains rules which affect the way |
5816 | Exim retries deliveries that cannot be completed at the first attempt. It is | |
5817 | introduced by the line | |
9b371988 PH |
5818 | .code |
5819 | begin retry | |
5820 | .endd | |
168e428f PH |
5821 | In the default configuration, there is just one rule, which applies to all |
5822 | errors: | |
9b371988 PH |
5823 | .code |
5824 | * * F,2h,15m; G,16h,1h,1.5; F,4d,6h | |
5825 | .endd | |
168e428f PH |
5826 | This causes any temporarily failing address to be retried every 15 minutes for |
5827 | 2 hours, then at intervals starting at one hour and increasing by a factor of | |
5828 | 1.5 until 16 hours have passed, then every 6 hours up to 4 days. If an address | |
9b371988 | 5829 | is not delivered after 4 days of temporary failure, it is bounced. |
168e428f | 5830 | |
595028e4 PH |
5831 | If the retry section is removed from the configuration, or is empty (that is, |
5832 | if no retry rules are defined), Exim will not retry deliveries. This turns | |
5833 | temporary errors into permanent errors. | |
168e428f PH |
5834 | |
5835 | ||
f89d2485 | 5836 | .section "Rewriting configuration" "SECID58" |
168e428f | 5837 | The rewriting section of the configuration, introduced by |
9b371988 PH |
5838 | .code |
5839 | begin rewrite | |
5840 | .endd | |
168e428f PH |
5841 | contains rules for rewriting addresses in messages as they arrive. There are no |
5842 | rewriting rules in the default configuration file. | |
5843 | ||
5844 | ||
5845 | ||
6083aca0 | 5846 | .section "Authenticators configuration" "SECTdefconfauth" |
9b371988 | 5847 | .cindex "AUTH" "configuration" |
168e428f | 5848 | The authenticators section of the configuration, introduced by |
9b371988 PH |
5849 | .code |
5850 | begin authenticators | |
5851 | .endd | |
6083aca0 TF |
5852 | defines mechanisms for the use of the SMTP AUTH command. The default |
5853 | configuration file contains two commented-out example authenticators | |
5854 | which support plaintext username/password authentication using the | |
5855 | standard PLAIN mechanism and the traditional but non-standard LOGIN | |
5856 | mechanism, with Exim acting as the server. PLAIN and LOGIN are enough | |
5857 | to support most MUA software. | |
5858 | ||
5859 | The example PLAIN authenticator looks like this: | |
5860 | .code | |
5861 | #PLAIN: | |
f89d2485 PH |
5862 | # driver = plaintext |
5863 | # server_set_id = $auth2 | |
5864 | # server_prompts = : | |
5865 | # server_condition = Authentication is not yet configured | |
6083aca0 TF |
5866 | # server_advertise_condition = ${if def:tls_cipher } |
5867 | .endd | |
5868 | And the example LOGIN authenticator looks like this: | |
5869 | .code | |
5870 | #LOGIN: | |
f89d2485 PH |
5871 | # driver = plaintext |
5872 | # server_set_id = $auth1 | |
5873 | # server_prompts = <| Username: | Password: | |
5874 | # server_condition = Authentication is not yet configured | |
6083aca0 TF |
5875 | # server_advertise_condition = ${if def:tls_cipher } |
5876 | .endd | |
5877 | ||
5878 | The &%server_set_id%& option makes Exim remember the authenticated username | |
5879 | in &$authenticated_id$&, which can be used later in ACLs or routers. The | |
5880 | &%server_prompts%& option configures the &(plaintext)& authenticator so | |
5881 | that it implements the details of the specific authentication mechanism, | |
5882 | i.e. PLAIN or LOGIN. The &%server_advertise_condition%& setting controls | |
5883 | when Exim offers authentication to clients; in the examples, this is only | |
5884 | when TLS or SSL has been started, so to enable the authenticators you also | |
5885 | need to add support for TLS as described in &<<SECTdefconfmain>>&. | |
5886 | ||
5887 | The &%server_condition%& setting defines how to verify that the username and | |
5888 | password are correct. In the examples it just produces an error message. | |
5889 | To make the authenticators work, you can use a string expansion | |
5890 | expression like one of the examples in &<<CHAPplaintext>>&. | |
5891 | ||
e2f03231 TK |
5892 | Beware that the sequence of the parameters to PLAIN and LOGIN differ; the |
5893 | usercode and password are in different positions. &<<CHAPplaintext>>& | |
5894 | covers both. | |
5895 | ||
4f578862 | 5896 | .ecindex IIDconfiwal |
168e428f PH |
5897 | |
5898 | ||
5899 | ||
9b371988 PH |
5900 | . //////////////////////////////////////////////////////////////////////////// |
5901 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 5902 | |
9b371988 | 5903 | .chapter "Regular expressions" "CHAPregexp" |
168e428f | 5904 | |
9b371988 PH |
5905 | .cindex "regular expressions" "library" |
5906 | .cindex "PCRE" | |
168e428f PH |
5907 | Exim supports the use of regular expressions in many of its options. It |
5908 | uses the PCRE regular expression library; this provides regular expression | |
5909 | matching that is compatible with Perl 5. The syntax and semantics of | |
5910 | regular expressions is discussed in many Perl reference books, and also in | |
9b371988 PH |
5911 | Jeffrey Friedl's &'Mastering Regular Expressions'&, which is published by |
5912 | O'Reilly (see &url(http://www.oreilly.com/catalog/regex2/)). | |
168e428f PH |
5913 | |
5914 | The documentation for the syntax and semantics of the regular expressions that | |
40df1be3 TF |
5915 | are supported by PCRE is included in the PCRE distribution, and no further |
5916 | description is included here. The PCRE functions are called from Exim using | |
5917 | the default option settings (that is, with no PCRE options set), except that | |
5918 | the PCRE_CASELESS option is set when the matching is required to be | |
5919 | case-insensitive. | |
168e428f PH |
5920 | |
5921 | In most cases, when a regular expression is required in an Exim configuration, | |
5922 | it has to start with a circumflex, in order to distinguish it from plain text | |
9b371988 | 5923 | or an &"ends with"& wildcard. In this example of a configuration setting, the |
168e428f | 5924 | second item in the colon-separated list is a regular expression. |
9b371988 PH |
5925 | .code |
5926 | domains = a.b.c : ^\\d{3} : *.y.z : ... | |
5927 | .endd | |
168e428f | 5928 | The doubling of the backslash is required because of string expansion that |
9b371988 PH |
5929 | precedes interpretation &-- see section &<<SECTlittext>>& for more discussion |
5930 | of this issue, and a way of avoiding the need for doubling backslashes. The | |
168e428f PH |
5931 | regular expression that is eventually used in this example contains just one |
5932 | backslash. The circumflex is included in the regular expression, and has the | |
9b371988 | 5933 | normal effect of &"anchoring"& it to the start of the string that is being |
168e428f PH |
5934 | matched. |
5935 | ||
5936 | There are, however, two cases where a circumflex is not required for the | |
9b371988 PH |
5937 | recognition of a regular expression: these are the &%match%& condition in a |
5938 | string expansion, and the &%matches%& condition in an Exim filter file. In | |
5939 | these cases, the relevant string is always treated as a regular expression; if | |
5940 | it does not start with a circumflex, the expression is not anchored, and can | |
5941 | match anywhere in the subject string. | |
168e428f PH |
5942 | |
5943 | In all cases, if you want a regular expression to match at the end of a string, | |
9b371988 PH |
5944 | you must code the $ metacharacter to indicate this. For example: |
5945 | .code | |
5946 | domains = ^\\d{3}\\.example | |
5947 | .endd | |
5948 | matches the domain &'123.example'&, but it also matches &'123.example.com'&. | |
168e428f | 5949 | You need to use: |
9b371988 PH |
5950 | .code |
5951 | domains = ^\\d{3}\\.example\$ | |
5952 | .endd | |
5953 | if you want &'example'& to be the top-level domain. The backslash before the | |
5954 | $ is needed because string expansion also interprets dollar characters. | |
168e428f | 5955 | |
168e428f PH |
5956 | |
5957 | ||
9b371988 PH |
5958 | . //////////////////////////////////////////////////////////////////////////// |
5959 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 5960 | |
9b371988 | 5961 | .chapter "File and database lookups" "CHAPfdlookup" |
4f578862 | 5962 | .scindex IIDfidalo1 "file" "lookups" |
f89d2485 | 5963 | .scindex IIDfidalo2 "database" "lookups" |
9b371988 | 5964 | .cindex "lookup" "description of" |
168e428f PH |
5965 | Exim can be configured to look up data in files or databases as it processes |
5966 | messages. Two different kinds of syntax are used: | |
5967 | ||
9b371988 PH |
5968 | .olist |
5969 | A string that is to be expanded may contain explicit lookup requests. These | |
168e428f | 5970 | cause parts of the string to be replaced by data that is obtained from the |
9b371988 PH |
5971 | lookup. Lookups of this type are conditional expansion items. Different results |
5972 | can be defined for the cases of lookup success and failure. See chapter | |
5973 | &<<CHAPexpand>>&, where string expansions are described in detail. | |
5974 | .next | |
5975 | Lists of domains, hosts, and email addresses can contain lookup requests as a | |
168e428f PH |
5976 | way of avoiding excessively long linear lists. In this case, the data that is |
5977 | returned by the lookup is often (but not always) discarded; whether the lookup | |
5978 | succeeds or fails is what really counts. These kinds of list are described in | |
9b371988 PH |
5979 | chapter &<<CHAPdomhosaddlists>>&. |
5980 | .endlist | |
168e428f | 5981 | |
068aaea8 PH |
5982 | String expansions, lists, and lookups interact with each other in such a way |
5983 | that there is no order in which to describe any one of them that does not | |
5984 | involve references to the others. Each of these three chapters makes more sense | |
5985 | if you have read the other two first. If you are reading this for the first | |
5986 | time, be aware that some of it will make a lot more sense after you have read | |
9b371988 | 5987 | chapters &<<CHAPdomhosaddlists>>& and &<<CHAPexpand>>&. |
068aaea8 | 5988 | |
f89d2485 | 5989 | .section "Examples of different lookup syntax" "SECID60" |
168e428f PH |
5990 | It is easy to confuse the two different kinds of lookup, especially as the |
5991 | lists that may contain the second kind are always expanded before being | |
5992 | processed as lists. Therefore, they may also contain lookups of the first kind. | |
5993 | Be careful to distinguish between the following two examples: | |
9b371988 PH |
5994 | .code |
5995 | domains = ${lookup{$sender_host_address}lsearch{/some/file}} | |
5996 | domains = lsearch;/some/file | |
5997 | .endd | |
168e428f | 5998 | The first uses a string expansion, the result of which must be a domain list. |
9b371988 PH |
5999 | No strings have been specified for a successful or a failing lookup; the |
6000 | defaults in this case are the looked-up data and an empty string, respectively. | |
068aaea8 PH |
6001 | The expansion takes place before the string is processed as a list, and the |
6002 | file that is searched could contain lines like this: | |
9b371988 PH |
6003 | .code |
6004 | 192.168.3.4: domain1:domain2:... | |
6005 | 192.168.1.9: domain3:domain4:... | |
6006 | .endd | |
6007 | When the lookup succeeds, the result of the expansion is a list of domains (and | |
6008 | possibly other types of item that are allowed in domain lists). | |
168e428f | 6009 | |
068aaea8 | 6010 | In the second example, the lookup is a single item in a domain list. It causes |
168e428f PH |
6011 | Exim to use a lookup to see if the domain that is being processed can be found |
6012 | in the file. The file could contains lines like this: | |
9b371988 PH |
6013 | .code |
6014 | domain1: | |
6015 | domain2: | |
6016 | .endd | |
168e428f PH |
6017 | Any data that follows the keys is not relevant when checking that the domain |
6018 | matches the list item. | |
6019 | ||
068aaea8 PH |
6020 | It is possible, though no doubt confusing, to use both kinds of lookup at once. |
6021 | Consider a file containing lines like this: | |
9b371988 PH |
6022 | .code |
6023 | 192.168.5.6: lsearch;/another/file | |
6024 | .endd | |
6025 | If the value of &$sender_host_address$& is 192.168.5.6, expansion of the | |
6026 | first &%domains%& setting above generates the second setting, which therefore | |
168e428f PH |
6027 | causes a second lookup to occur. |
6028 | ||
6029 | The rest of this chapter describes the different lookup types that are | |
068aaea8 PH |
6030 | available. Any of them can be used in any part of the configuration where a |
6031 | lookup is permitted. | |
168e428f PH |
6032 | |
6033 | ||
f89d2485 | 6034 | .section "Lookup types" "SECID61" |
9b371988 PH |
6035 | .cindex "lookup" "types of" |
6036 | .cindex "single-key lookup" "definition of" | |
068aaea8 | 6037 | Two different types of data lookup are implemented: |
168e428f | 6038 | |
9b371988 PH |
6039 | .ilist |
6040 | The &'single-key'& type requires the specification of a file in which to look, | |
168e428f PH |
6041 | and a single key to search for. The key must be a non-empty string for the |
6042 | lookup to succeed. The lookup type determines how the file is searched. | |
9b371988 PH |
6043 | .next |
6044 | .cindex "query-style lookup" "definition of" | |
6045 | The &'query-style'& type accepts a generalized database query. No particular | |
6046 | key value is assumed by Exim for query-style lookups. You can use whichever | |
6047 | Exim variables you need to construct the database query. | |
6048 | .endlist | |
168e428f PH |
6049 | |
6050 | The code for each lookup type is in a separate source file that is included in | |
6051 | the binary of Exim only if the corresponding compile-time option is set. The | |
9b371988 PH |
6052 | default settings in &_src/EDITME_& are: |
6053 | .code | |
6054 | LOOKUP_DBM=yes | |
6055 | LOOKUP_LSEARCH=yes | |
6056 | .endd | |
168e428f PH |
6057 | which means that only linear searching and DBM lookups are included by default. |
6058 | For some types of lookup (e.g. SQL databases), you need to install appropriate | |
6059 | libraries and header files before building Exim. | |
6060 | ||
6061 | ||
6062 | ||
6063 | ||
9b371988 PH |
6064 | .section "Single-key lookup types" "SECTsinglekeylookups" |
6065 | .cindex "lookup" "single-key types" | |
6066 | .cindex "single-key lookup" "list of types" | |
168e428f PH |
6067 | The following single-key lookup types are implemented: |
6068 | ||
9b371988 PH |
6069 | .ilist |
6070 | .cindex "cdb" "description of" | |
6071 | .cindex "lookup" "cdb" | |
6072 | .cindex "binary zero" "in lookup key" | |
6073 | &(cdb)&: The given file is searched as a Constant DataBase file, using the key | |
168e428f PH |
6074 | string without a terminating binary zero. The cdb format is designed for |
6075 | indexed files that are read frequently and never updated, except by total | |
f89d2485 | 6076 | re-creation. As such, it is particularly suitable for large files containing |
168e428f PH |
6077 | aliases or other indexed data referenced by an MTA. Information about cdb can |
6078 | be found in several places: | |
9b371988 PH |
6079 | .display |
6080 | &url(http://www.pobox.com/~djb/cdb.html) | |
6081 | &url(ftp://ftp.corpit.ru/pub/tinycdb/) | |
6082 | &url(http://packages.debian.org/stable/utils/freecdb.html) | |
6083 | .endd | |
168e428f PH |
6084 | A cdb distribution is not needed in order to build Exim with cdb support, |
6085 | because the code for reading cdb files is included directly in Exim itself. | |
6086 | However, no means of building or testing cdb files is provided with Exim, so | |
6087 | you need to obtain a cdb distribution in order to do this. | |
9b371988 PH |
6088 | .next |
6089 | .cindex "DBM" "lookup type" | |
6090 | .cindex "lookup" "dbm" | |
6091 | .cindex "binary zero" "in lookup key" | |
6092 | &(dbm)&: Calls to DBM library functions are used to extract data from the given | |
168e428f PH |
6093 | DBM file by looking up the record with the given key. A terminating binary |
6094 | zero is included in the key that is passed to the DBM library. See section | |
9b371988 PH |
6095 | &<<SECTdb>>& for a discussion of DBM libraries. |
6096 | ||
6097 | .cindex "Berkeley DB library" "file format" | |
168e428f | 6098 | For all versions of Berkeley DB, Exim uses the DB_HASH style of database |
9b371988 PH |
6099 | when building DBM files using the &%exim_dbmbuild%& utility. However, when |
6100 | using Berkeley DB versions 3 or 4, it opens existing databases for reading with | |
6101 | the DB_UNKNOWN option. This enables it to handle any of the types of database | |
168e428f PH |
6102 | that the library supports, and can be useful for accessing DBM files created by |
6103 | other applications. (For earlier DB versions, DB_HASH is always used.) | |
9b371988 PH |
6104 | .next |
6105 | .cindex "lookup" "dbmnz" | |
6106 | .cindex "lookup" "dbm &-- terminating zero" | |
6107 | .cindex "binary zero" "in lookup key" | |
6108 | .cindex "Courier" | |
6109 | .cindex "&_/etc/userdbshadow.dat_&" | |
6110 | .cindex "dmbnz lookup type" | |
6111 | &(dbmnz)&: This is the same as &(dbm)&, except that a terminating binary zero | |
168e428f PH |
6112 | is not included in the key that is passed to the DBM library. You may need this |
6113 | if you want to look up data in files that are created by or shared with some | |
6114 | other application that does not use terminating zeros. For example, you need to | |
9b371988 PH |
6115 | use &(dbmnz)& rather than &(dbm)& if you want to authenticate incoming SMTP |
6116 | calls using the passwords from Courier's &_/etc/userdbshadow.dat_& file. Exim's | |
6117 | utility program for creating DBM files (&'exim_dbmbuild'&) includes the zeros | |
6118 | by default, but has an option to omit them (see section &<<SECTdbmbuild>>&). | |
6119 | .next | |
6120 | .cindex "lookup" "dsearch" | |
6121 | .cindex "dsearch lookup type" | |
595028e4 PH |
6122 | &(dsearch)&: The given file must be a directory; this is searched for an entry |
6123 | whose name is the key by calling the &[lstat()]& function. The key may not | |
6124 | contain any forward slash characters. If &[lstat()]& succeeds, the result of | |
6125 | the lookup is the name of the entry, which may be a file, directory, | |
6126 | symbolic link, or any other kind of directory entry. An example of how this | |
6127 | lookup can be used to support virtual domains is given in section | |
9b371988 PH |
6128 | &<<SECTvirtualdomains>>&. |
6129 | .next | |
6130 | .cindex "lookup" "iplsearch" | |
6131 | .cindex "iplsearch lookup type" | |
6132 | &(iplsearch)&: The given file is a text file containing keys and data. A key is | |
168e428f PH |
6133 | terminated by a colon or white space or the end of the line. The keys in the |
6134 | file must be IP addresses, or IP addresses with CIDR masks. Keys that involve | |
6135 | IPv6 addresses must be enclosed in quotes to prevent the first internal colon | |
6136 | being interpreted as a key terminator. For example: | |
9b371988 PH |
6137 | .code |
6138 | 1.2.3.4: data for 1.2.3.4 | |
d5331c3e | 6139 | 192.168.0.0/16: data for 192.168.0.0/16 |
9b371988 PH |
6140 | "abcd::cdab": data for abcd::cdab |
6141 | "abcd:abcd::/32" data for abcd:abcd::/32 | |
6142 | .endd | |
6143 | The key for an &(iplsearch)& lookup must be an IP address (without a mask). The | |
168e428f PH |
6144 | file is searched linearly, using the CIDR masks where present, until a matching |
6145 | key is found. The first key that matches is used; there is no attempt to find a | |
9b371988 PH |
6146 | &"best"& match. Apart from the way the keys are matched, the processing for |
6147 | &(iplsearch)& is the same as for &(lsearch)&. | |
6148 | ||
6149 | &*Warning 1*&: Unlike most other single-key lookup types, a file of data for | |
6150 | &(iplsearch)& can &'not'& be turned into a DBM or cdb file, because those | |
168e428f | 6151 | lookup types support only literal keys. |
9b371988 PH |
6152 | |
6153 | &*Warning 2*&: In a host list, you must always use &(net-iplsearch)& so that | |
168e428f | 6154 | the implicit key is the host's IP address rather than its name (see section |
9b371988 | 6155 | &<<SECThoslispatsikey>>&). |
9b371988 PH |
6156 | .next |
6157 | .cindex "linear search" | |
6158 | .cindex "lookup" "lsearch" | |
6159 | .cindex "lsearch lookup type" | |
db9452a9 | 6160 | .cindex "case sensitivity" "in lsearch lookup" |
9b371988 | 6161 | &(lsearch)&: The given file is a text file that is searched linearly for a |
168e428f | 6162 | line beginning with the search key, terminated by a colon or white space or the |
db9452a9 PH |
6163 | end of the line. The search is case-insensitive; that is, upper and lower case |
6164 | letters are treated as the same. The first occurrence of the key that is found | |
6165 | in the file is used. | |
db9452a9 PH |
6166 | |
6167 | White space between the key and the colon is permitted. The remainder of the | |
6168 | line, with leading and trailing white space removed, is the data. This can be | |
168e428f PH |
6169 | continued onto subsequent lines by starting them with any amount of white |
6170 | space, but only a single space character is included in the data at such a | |
6171 | junction. If the data begins with a colon, the key must be terminated by a | |
6172 | colon, for example: | |
9b371988 PH |
6173 | .code |
6174 | baduser: :fail: | |
6175 | .endd | |
168e428f PH |
6176 | Empty lines and lines beginning with # are ignored, even if they occur in the |
6177 | middle of an item. This is the traditional textual format of alias files. Note | |
9b371988 | 6178 | that the keys in an &(lsearch)& file are literal strings. There is no |
168e428f | 6179 | wildcarding of any kind. |
9b371988 PH |
6180 | |
6181 | .cindex "lookup" "lsearch &-- colons in keys" | |
6182 | .cindex "white space" "in lsearch key" | |
6183 | In most &(lsearch)& files, keys are not required to contain colons or # | |
068aaea8 | 6184 | characters, or white space. However, if you need this feature, it is available. |
168e428f PH |
6185 | If a key begins with a doublequote character, it is terminated only by a |
6186 | matching quote (or end of line), and the normal escaping rules apply to its | |
9b371988 | 6187 | contents (see section &<<SECTstrings>>&). An optional colon is permitted after |
168e428f | 6188 | quoted keys (exactly as for unquoted keys). There is no special handling of |
9b371988 | 6189 | quotes for the data part of an &(lsearch)& line. |
168e428f | 6190 | |
9b371988 PH |
6191 | .next |
6192 | .cindex "NIS lookup type" | |
6193 | .cindex "lookup" "NIS" | |
6194 | .cindex "binary zero" "in lookup key" | |
6195 | &(nis)&: The given file is the name of a NIS map, and a NIS lookup is done with | |
168e428f | 6196 | the given key, without a terminating binary zero. There is a variant called |
9b371988 | 6197 | &(nis0)& which does include the terminating binary zero in the key. This is |
168e428f PH |
6198 | reportedly needed for Sun-style alias files. Exim does not recognize NIS |
6199 | aliases; the full map names must be used. | |
6200 | ||
9b371988 PH |
6201 | .next |
6202 | .cindex "wildlsearch lookup type" | |
6203 | .cindex "lookup" "wildlsearch" | |
6204 | .cindex "nwildlsearch lookup type" | |
6205 | .cindex "lookup" "nwildlsearch" | |
6206 | &(wildlsearch)& or &(nwildlsearch)&: These search a file linearly, like | |
6207 | &(lsearch)&, but instead of being interpreted as a literal string, each key in | |
6208 | the file may be wildcarded. The difference between these two lookup types is | |
6209 | that for &(wildlsearch)&, each key in the file is string-expanded before being | |
6210 | used, whereas for &(nwildlsearch)&, no expansion takes place. | |
6211 | ||
db9452a9 PH |
6212 | .cindex "case sensitivity" "in (n)wildlsearch lookup" |
6213 | Like &(lsearch)&, the testing is done case-insensitively. However, keys in the | |
6214 | file that are regular expressions can be made case-sensitive by the use of | |
6215 | &`(-i)`& within the pattern. The following forms of wildcard are recognized: | |
168e428f | 6216 | |
9b371988 PH |
6217 | . ==== As this is a nested list, any displays it contains must be indented |
6218 | . ==== as otherwise they are too far to the left. | |
6219 | ||
6220 | .olist | |
6221 | The string may begin with an asterisk to mean &"ends with"&. For example: | |
6222 | .code | |
6223 | *.a.b.c data for anything.a.b.c | |
6224 | *fish data for anythingfish | |
6225 | .endd | |
6226 | .next | |
6227 | The string may begin with a circumflex to indicate a regular expression. For | |
6228 | example, for &(wildlsearch)&: | |
6229 | .code | |
6230 | ^\N\d+\.a\.b\N data for <digits>.a.b | |
6231 | .endd | |
6232 | Note the use of &`\N`& to disable expansion of the contents of the regular | |
6233 | expression. If you are using &(nwildlsearch)&, where the keys are not | |
168e428f | 6234 | string-expanded, the equivalent entry is: |
9b371988 PH |
6235 | .code |
6236 | ^\d+\.a\.b data for <digits>.a.b | |
6237 | .endd | |
db9452a9 PH |
6238 | The case-insensitive flag is set at the start of compiling the regular |
6239 | expression, but it can be turned off by using &`(-i)`& at an appropriate point. | |
6240 | For example, to make the entire pattern case-sensitive: | |
6241 | .code | |
6242 | ^(?-i)\d+\.a\.b data for <digits>.a.b | |
6243 | .endd | |
db9452a9 | 6244 | |
168e428f | 6245 | If the regular expression contains white space or colon characters, you must |
9b371988 PH |
6246 | either quote it (see &(lsearch)& above), or represent these characters in other |
6247 | ways. For example, &`\s`& can be used for white space and &`\x3A`& for a | |
168e428f PH |
6248 | colon. This may be easier than quoting, because if you quote, you have to |
6249 | escape all the backslashes inside the quotes. | |
6250 | ||
9b371988 PH |
6251 | &*Note*&: It is not possible to capture substrings in a regular expression |
6252 | match for later use, because the results of all lookups are cached. If a lookup | |
6253 | is repeated, the result is taken from the cache, and no actual pattern matching | |
d1e83bff | 6254 | takes place. The values of all the numeric variables are unset after a |
9b371988 | 6255 | &((n)wildlsearch)& match. |
d1e83bff | 6256 | |
9b371988 PH |
6257 | .next |
6258 | Although I cannot see it being of much use, the general matching function that | |
6259 | is used to implement &((n)wildlsearch)& means that the string may begin with a | |
6260 | lookup name terminated by a semicolon, and followed by lookup data. For | |
168e428f | 6261 | example: |
9b371988 PH |
6262 | .code |
6263 | cdb;/some/file data for keys that match the file | |
6264 | .endd | |
168e428f | 6265 | The data that is obtained from the nested lookup is discarded. |
9b371988 PH |
6266 | .endlist olist |
6267 | ||
168e428f | 6268 | Keys that do not match any of these patterns are interpreted literally. The |
9b371988 | 6269 | continuation rules for the data are the same as for &(lsearch)&, and keys may |
168e428f | 6270 | be followed by optional colons. |
168e428f | 6271 | |
9b371988 PH |
6272 | &*Warning*&: Unlike most other single-key lookup types, a file of data for |
6273 | &((n)wildlsearch)& can &'not'& be turned into a DBM or cdb file, because those | |
6274 | lookup types support only literal keys. | |
6275 | .endlist ilist | |
168e428f PH |
6276 | |
6277 | ||
f89d2485 | 6278 | .section "Query-style lookup types" "SECID62" |
9b371988 PH |
6279 | .cindex "lookup" "query-style types" |
6280 | .cindex "query-style lookup" "list of types" | |
168e428f PH |
6281 | The supported query-style lookup types are listed below. Further details about |
6282 | many of them are given in later sections. | |
6283 | ||
9b371988 PH |
6284 | .ilist |
6285 | .cindex "DNS" "as a lookup type" | |
6286 | .cindex "lookup" "DNS" | |
6287 | &(dnsdb)&: This does a DNS search for one or more records whose domain names | |
6288 | are given in the supplied query. The resulting data is the contents of the | |
6289 | records. See section &<<SECTdnsdb>>&. | |
6290 | .next | |
db9452a9 PH |
6291 | .cindex "InterBase lookup type" |
6292 | .cindex "lookup" "InterBase" | |
6293 | &(ibase)&: This does a lookup in an InterBase database. | |
9b371988 PH |
6294 | .next |
6295 | .cindex "LDAP" "lookup type" | |
6296 | .cindex "lookup" "LDAP" | |
6297 | &(ldap)&: This does an LDAP lookup using a query in the form of a URL, and | |
6298 | returns attributes from a single entry. There is a variant called &(ldapm)& | |
168e428f | 6299 | that permits values from multiple entries to be returned. A third variant |
9b371988 PH |
6300 | called &(ldapdn)& returns the Distinguished Name of a single entry instead of |
6301 | any attribute values. See section &<<SECTldap>>&. | |
6302 | .next | |
6303 | .cindex "MySQL" "lookup type" | |
6304 | .cindex "lookup" "MySQL" | |
6305 | &(mysql)&: The format of the query is an SQL statement that is passed to a | |
6306 | MySQL database. See section &<<SECTsql>>&. | |
6307 | .next | |
6308 | .cindex "NIS+ lookup type" | |
6309 | .cindex "lookup" "NIS+" | |
6310 | &(nisplus)&: This does a NIS+ lookup using a query that can specify the name of | |
6311 | the field to be returned. See section &<<SECTnisplus>>&. | |
6312 | .next | |
6313 | .cindex "Oracle" "lookup type" | |
6314 | .cindex "lookup" "Oracle" | |
6315 | &(oracle)&: The format of the query is an SQL statement that is passed to an | |
6316 | Oracle database. See section &<<SECTsql>>&. | |
6317 | .next | |
6318 | .cindex "lookup" "passwd" | |
6319 | .cindex "passwd lookup type" | |
6320 | .cindex "&_/etc/passwd_&" | |
6321 | &(passwd)& is a query-style lookup with queries that are just user names. The | |
6322 | lookup calls &[getpwnam()]& to interrogate the system password data, and on | |
6323 | success, the result string is the same as you would get from an &(lsearch)& | |
6324 | lookup on a traditional &_/etc/passwd file_&, though with &`*`& for the | |
168e428f | 6325 | password value. For example: |
9b371988 PH |
6326 | .code |
6327 | *:42:42:King Rat:/home/kr:/bin/bash | |
6328 | .endd | |
6329 | .next | |
6330 | .cindex "PostgreSQL lookup type" | |
6331 | .cindex "lookup" "PostgreSQL" | |
6332 | &(pgsql)&: The format of the query is an SQL statement that is passed to a | |
6333 | PostgreSQL database. See section &<<SECTsql>>&. | |
6334 | ||
6335 | .next | |
9b371988 PH |
6336 | .cindex "sqlite lookup type" |
6337 | .cindex "lookup" "sqlite" | |
6338 | &(sqlite)&: The format of the query is a file name followed by an SQL statement | |
6339 | that is passed to an SQLite database. See section &<<SECTsqlite>>&. | |
9b371988 PH |
6340 | |
6341 | .next | |
6342 | &(testdb)&: This is a lookup type that is used for testing Exim. It is | |
168e428f | 6343 | not likely to be useful in normal operation. |
9b371988 PH |
6344 | .next |
6345 | .cindex "whoson lookup type" | |
6346 | .cindex "lookup" "whoson" | |
f89d2485 PH |
6347 | &(whoson)&: &'Whoson'& (&url(http://whoson.sourceforge.net)) is a protocol that |
6348 | allows a server to check whether a particular (dynamically allocated) IP | |
6349 | address is currently allocated to a known (trusted) user and, optionally, to | |
6350 | obtain the identity of the said user. For SMTP servers, &'Whoson'& was popular | |
6351 | at one time for &"POP before SMTP"& authentication, but that approach has been | |
6352 | superseded by SMTP authentication. In Exim, &'Whoson'& can be used to implement | |
6353 | &"POP before SMTP"& checking using ACL statements such as | |
9b371988 | 6354 | .code |
168e428f PH |
6355 | require condition = \ |
6356 | ${lookup whoson {$sender_host_address}{yes}{no}} | |
9b371988 | 6357 | .endd |
168e428f | 6358 | The query consists of a single IP address. The value returned is the name of |
9b371988 PH |
6359 | the authenticated user, which is stored in the variable &$value$&. However, in |
6360 | this example, the data in &$value$& is not used; the result of the lookup is | |
6361 | one of the fixed strings &"yes"& or &"no"&. | |
9b371988 | 6362 | .endlist |
168e428f PH |
6363 | |
6364 | ||
6365 | ||
f89d2485 | 6366 | .section "Temporary errors in lookups" "SECID63" |
9b371988 | 6367 | .cindex "lookup" "temporary error in" |
168e428f | 6368 | Lookup functions can return temporary error codes if the lookup cannot be |
068aaea8 | 6369 | completed. For example, an SQL or LDAP database might be unavailable. For this |
168e428f PH |
6370 | reason, it is not advisable to use a lookup that might do this for critical |
6371 | options such as a list of local domains. | |
6372 | ||
6373 | When a lookup cannot be completed in a router or transport, delivery | |
6374 | of the message (to the relevant address) is deferred, as for any other | |
6375 | temporary error. In other circumstances Exim may assume the lookup has failed, | |
6376 | or may give up altogether. | |
6377 | ||
6378 | ||
6379 | ||
9b371988 PH |
6380 | .section "Default values in single-key lookups" "SECTdefaultvaluelookups" |
6381 | .cindex "wildcard lookups" | |
6382 | .cindex "lookup" "default values" | |
6383 | .cindex "lookup" "wildcard" | |
6384 | .cindex "lookup" "* added to type" | |
6385 | .cindex "default" "in single-key lookups" | |
6386 | In this context, a &"default value"& is a value specified by the administrator | |
168e428f PH |
6387 | that is to be used if a lookup fails. |
6388 | ||
3cb1b51e PH |
6389 | &*Note:*& This section applies only to single-key lookups. For query-style |
6390 | lookups, the facilities of the query language must be used. An attempt to | |
6391 | specify a default for a query-style lookup provokes an error. | |
3cb1b51e | 6392 | |
9b371988 PH |
6393 | If &"*"& is added to a single-key lookup type (for example, &%lsearch*%&) |
6394 | and the initial lookup fails, the key &"*"& is looked up in the file to | |
6395 | provide a default value. See also the section on partial matching below. | |
168e428f | 6396 | |
9b371988 PH |
6397 | .cindex "*@ with single-key lookup" |
6398 | .cindex "lookup" "*@ added to type" | |
6399 | .cindex "alias file" "per-domain default" | |
6400 | Alternatively, if &"*@"& is added to a single-key lookup type (for example | |
6401 | &%dbm*@%&) then, if the initial lookup fails and the key contains an @ | |
168e428f | 6402 | character, a second lookup is done with everything before the last @ replaced |
9b371988 | 6403 | by *. This makes it possible to provide per-domain defaults in alias files |
168e428f | 6404 | that include the domains in the keys. If the second lookup fails (or doesn't |
9b371988 PH |
6405 | take place because there is no @ in the key), &"*"& is looked up. |
6406 | For example, a &(redirect)& router might contain: | |
6407 | .code | |
6408 | data = ${lookup{$local_part@$domain}lsearch*@{/etc/mix-aliases}} | |
6409 | .endd | |
6410 | Suppose the address that is being processed is &'jane@eyre.example'&. Exim | |
168e428f | 6411 | looks up these keys, in this order: |
9b371988 PH |
6412 | .code |
6413 | jane@eyre.example | |
6414 | *@eyre.example | |
6415 | * | |
6416 | .endd | |
6417 | The data is taken from whichever key it finds first. &*Note*&: In an | |
6418 | &(lsearch)& file, this does not mean the first of these keys in the file. A | |
168e428f PH |
6419 | complete scan is done for each key, and only if it is not found at all does |
6420 | Exim move on to try the next key. | |
6421 | ||
6422 | ||
6423 | ||
9b371988 PH |
6424 | .section "Partial matching in single-key lookups" "SECTpartiallookup" |
6425 | .cindex "partial matching" | |
6426 | .cindex "wildcard lookups" | |
6427 | .cindex "lookup" "partial matching" | |
6428 | .cindex "lookup" "wildcard" | |
6429 | .cindex "asterisk" "in search type" | |
168e428f PH |
6430 | The normal operation of a single-key lookup is to search the file for an exact |
6431 | match with the given key. However, in a number of situations where domains are | |
6432 | being looked up, it is useful to be able to do partial matching. In this case, | |
9b371988 | 6433 | information in the file that has a key starting with &"*."& is matched by any |
168e428f PH |
6434 | domain that ends with the components that follow the full stop. For example, if |
6435 | a key in a DBM file is | |
9b371988 PH |
6436 | .code |
6437 | *.dates.fict.example | |
6438 | .endd | |
168e428f | 6439 | then when partial matching is enabled this is matched by (amongst others) |
9b371988 PH |
6440 | &'2001.dates.fict.example'& and &'1984.dates.fict.example'&. It is also matched |
6441 | by &'dates.fict.example'&, if that does not appear as a separate key in the | |
168e428f PH |
6442 | file. |
6443 | ||
9b371988 | 6444 | &*Note*&: Partial matching is not available for query-style lookups. It is |
168e428f | 6445 | also not available for any lookup items in address lists (see section |
9b371988 | 6446 | &<<SECTaddresslist>>&). |
168e428f PH |
6447 | |
6448 | Partial matching is implemented by doing a series of separate lookups using | |
6449 | keys constructed by modifying the original subject key. This means that it can | |
6450 | be used with any of the single-key lookup types, provided that | |
6451 | partial matching keys | |
9b371988 | 6452 | beginning with a special prefix (default &"*."&) are included in the data file. |
168e428f PH |
6453 | Keys in the file that do not begin with the prefix are matched only by |
6454 | unmodified subject keys when partial matching is in use. | |
6455 | ||
9b371988 PH |
6456 | Partial matching is requested by adding the string &"partial-"& to the front of |
6457 | the name of a single-key lookup type, for example, &%partial-dbm%&. When this | |
6458 | is done, the subject key is first looked up unmodified; if that fails, &"*."& | |
168e428f | 6459 | is added at the start of the subject key, and it is looked up again. If that |
9b371988 PH |
6460 | fails, further lookups are tried with dot-separated components removed from the |
6461 | start of the subject key, one-by-one, and &"*."& added on the front of what | |
6462 | remains. | |
168e428f | 6463 | |
9b371988 | 6464 | A minimum number of two non-* components are required. This can be adjusted |
168e428f | 6465 | by including a number before the hyphen in the search type. For example, |
9b371988 PH |
6466 | &%partial3-lsearch%& specifies a minimum of three non-* components in the |
6467 | modified keys. Omitting the number is equivalent to &"partial2-"&. If the | |
6468 | subject key is &'2250.dates.fict.example'& then the following keys are looked | |
6469 | up when the minimum number of non-* components is two: | |
6470 | .code | |
6471 | 2250.dates.fict.example | |
6472 | *.2250.dates.fict.example | |
6473 | *.dates.fict.example | |
6474 | *.fict.example | |
6475 | .endd | |
168e428f PH |
6476 | As soon as one key in the sequence is successfully looked up, the lookup |
6477 | finishes. | |
6478 | ||
9b371988 PH |
6479 | .cindex "lookup" "partial matching &-- changing prefix" |
6480 | .cindex "prefix" "for partial matching" | |
6481 | The use of &"*."& as the partial matching prefix is a default that can be | |
168e428f PH |
6482 | changed. The motivation for this feature is to allow Exim to operate with file |
6483 | formats that are used by other MTAs. A different prefix can be supplied in | |
9b371988 PH |
6484 | parentheses instead of the hyphen after &"partial"&. For example: |
6485 | .code | |
6486 | domains = partial(.)lsearch;/some/file | |
6487 | .endd | |
6488 | In this example, if the domain is &'a.b.c'&, the sequence of lookups is | |
6489 | &`a.b.c`&, &`.a.b.c`&, and &`.b.c`& (the default minimum of 2 non-wild | |
168e428f PH |
6490 | components is unchanged). The prefix may consist of any punctuation characters |
6491 | other than a closing parenthesis. It may be empty, for example: | |
9b371988 PH |
6492 | .code |
6493 | domains = partial1()cdb;/some/file | |
6494 | .endd | |
6495 | For this example, if the domain is &'a.b.c'&, the sequence of lookups is | |
6496 | &`a.b.c`&, &`b.c`&, and &`c`&. | |
6497 | ||
6498 | If &"partial0"& is specified, what happens at the end (when the lookup with | |
6499 | just one non-wild component has failed, and the original key is shortened right | |
6500 | down to the null string) depends on the prefix: | |
6501 | ||
6502 | .ilist | |
6503 | If the prefix has zero length, the whole lookup fails. | |
6504 | .next | |
6505 | If the prefix has length 1, a lookup for just the prefix is done. For | |
6506 | example, the final lookup for &"partial0(.)"& is for &`.`& alone. | |
6507 | .next | |
6508 | Otherwise, if the prefix ends in a dot, the dot is removed, and the | |
168e428f | 6509 | remainder is looked up. With the default prefix, therefore, the final lookup is |
9b371988 PH |
6510 | for &"*"& on its own. |
6511 | .next | |
6512 | Otherwise, the whole prefix is looked up. | |
6513 | .endlist | |
168e428f | 6514 | |
168e428f | 6515 | |
9b371988 PH |
6516 | If the search type ends in &"*"& or &"*@"& (see section |
6517 | &<<SECTdefaultvaluelookups>>& above), the search for an ultimate default that | |
6518 | this implies happens after all partial lookups have failed. If &"partial0"& is | |
6519 | specified, adding &"*"& to the search type has no effect with the default | |
6520 | prefix, because the &"*"& key is already included in the sequence of partial | |
168e428f | 6521 | lookups. However, there might be a use for lookup types such as |
9b371988 | 6522 | &"partial0(.)lsearch*"&. |
168e428f | 6523 | |
9b371988 | 6524 | The use of &"*"& in lookup partial matching differs from its use as a wildcard |
168e428f | 6525 | in domain lists and the like. Partial matching works only in terms of |
9b371988 | 6526 | dot-separated components; a key such as &`*fict.example`& |
168e428f PH |
6527 | in a database file is useless, because the asterisk in a partial matching |
6528 | subject key is always followed by a dot. | |
6529 | ||
6530 | ||
6531 | ||
6532 | ||
f89d2485 | 6533 | .section "Lookup caching" "SECID64" |
9b371988 PH |
6534 | .cindex "lookup" "caching" |
6535 | .cindex "caching" "lookup data" | |
168e428f PH |
6536 | Exim caches all lookup results in order to avoid needless repetition of |
6537 | lookups. However, because (apart from the daemon) Exim operates as a collection | |
6538 | of independent, short-lived processes, this caching applies only within a | |
9b371988 | 6539 | single Exim process. There is no inter-process lookup caching facility. |
168e428f PH |
6540 | |
6541 | For single-key lookups, Exim keeps the relevant files open in case there is | |
6542 | another lookup that needs them. In some types of configuration this can lead to | |
6543 | many files being kept open for messages with many recipients. To avoid hitting | |
6544 | the operating system limit on the number of simultaneously open files, Exim | |
6545 | closes the least recently used file when it needs to open more files than its | |
9b371988 | 6546 | own internal limit, which can be changed via the &%lookup_open_max%& option. |
168e428f PH |
6547 | |
6548 | The single-key lookup files are closed and the lookup caches are flushed at | |
9b371988 PH |
6549 | strategic points during delivery &-- for example, after all routing is |
6550 | complete. | |
168e428f PH |
6551 | |
6552 | ||
6553 | ||
6554 | ||
f89d2485 | 6555 | .section "Quoting lookup data" "SECID65" |
9b371988 PH |
6556 | .cindex "lookup" "quoting" |
6557 | .cindex "quoting" "in lookups" | |
168e428f PH |
6558 | When data from an incoming message is included in a query-style lookup, there |
6559 | is the possibility of special characters in the data messing up the syntax of | |
6560 | the query. For example, a NIS+ query that contains | |
9b371988 PH |
6561 | .code |
6562 | [name=$local_part] | |
6563 | .endd | |
168e428f PH |
6564 | will be broken if the local part happens to contain a closing square bracket. |
6565 | For NIS+, data can be enclosed in double quotes like this: | |
9b371988 PH |
6566 | .code |
6567 | [name="$local_part"] | |
6568 | .endd | |
168e428f PH |
6569 | but this still leaves the problem of a double quote in the data. The rule for |
6570 | NIS+ is that double quotes must be doubled. Other lookup types have different | |
6571 | rules, and to cope with the differing requirements, an expansion operator | |
6572 | of the following form is provided: | |
9b371988 PH |
6573 | .code |
6574 | ${quote_<lookup-type>:<string>} | |
6575 | .endd | |
168e428f | 6576 | For example, the safest way to write the NIS+ query is |
9b371988 PH |
6577 | .code |
6578 | [name="${quote_nisplus:$local_part}"] | |
6579 | .endd | |
6580 | See chapter &<<CHAPexpand>>& for full coverage of string expansions. The quote | |
168e428f PH |
6581 | operator can be used for all lookup types, but has no effect for single-key |
6582 | lookups, since no quoting is ever needed in their key strings. | |
6583 | ||
6584 | ||
6585 | ||
6586 | ||
9b371988 PH |
6587 | .section "More about dnsdb" "SECTdnsdb" |
6588 | .cindex "dnsdb lookup" | |
6589 | .cindex "lookup" "dnsdb" | |
6590 | .cindex "DNS" "as a lookup type" | |
6591 | The &(dnsdb)& lookup type uses the DNS as its database. A simple query consists | |
168e428f PH |
6592 | of a record type and a domain name, separated by an equals sign. For example, |
6593 | an expansion string could contain: | |
9b371988 PH |
6594 | .code |
6595 | ${lookup dnsdb{mx=a.b.example}{$value}fail} | |
6596 | .endd | |
9b371988 | 6597 | If the lookup succeeds, the result is placed in &$value$&, which in this case |
3cb1b51e | 6598 | is used on its own as the result. If the lookup does not succeed, the |
db9452a9 PH |
6599 | &`fail`& keyword causes a &'forced expansion failure'& &-- see section |
6600 | &<<SECTforexpfai>>& for an explanation of what this means. | |
168e428f PH |
6601 | |
6602 | The supported DNS record types are A, CNAME, MX, NS, PTR, SRV, and TXT, and, | |
6603 | when Exim is compiled with IPv6 support, AAAA (and A6 if that is also | |
6604 | configured). If no type is given, TXT is assumed. When the type is PTR, | |
6605 | the data can be an IP address, written as normal; inversion and the addition of | |
9b371988 PH |
6606 | &%in-addr.arpa%& or &%ip6.arpa%& happens automatically. For example: |
6607 | .code | |
6608 | ${lookup dnsdb{ptr=192.168.4.5}{$value}fail} | |
6609 | .endd | |
168e428f PH |
6610 | If the data for a PTR record is not a syntactically valid IP address, it is not |
6611 | altered and nothing is added. | |
6612 | ||
9b371988 PH |
6613 | .cindex "MX record" "in &(dnsdb)& lookup" |
6614 | .cindex "SRV record" "in &(dnsdb)& lookup" | |
068aaea8 PH |
6615 | For an MX lookup, both the preference value and the host name are returned for |
6616 | each record, separated by a space. For an SRV lookup, the priority, weight, | |
6617 | port, and host name are returned for each record, separated by spaces. | |
6618 | ||
168e428f PH |
6619 | For any record type, if multiple records are found (or, for A6 lookups, if a |
6620 | single record leads to multiple addresses), the data is returned as a | |
6621 | concatenation, with newline as the default separator. The order, of course, | |
6622 | depends on the DNS resolver. You can specify a different separator character | |
6623 | between multiple records by putting a right angle-bracket followed immediately | |
6624 | by the new separator at the start of the query. For example: | |
9b371988 PH |
6625 | .code |
6626 | ${lookup dnsdb{>: a=host1.example}} | |
6627 | .endd | |
168e428f | 6628 | It is permitted to specify a space as the separator character. Further |
068aaea8 | 6629 | white space is ignored. |
168e428f | 6630 | |
0d0c6357 NM |
6631 | .new |
6632 | .cindex "TXT record" "in &(dnsdb)& lookup" | |
6633 | For TXT records with multiple items of data, only the first item is returned, | |
6634 | unless a separator for them is specified using a comma after the separator | |
6635 | character followed immediately by the TXT record item separator. To concatenate | |
6636 | items without a separator, use a semicolon instead. | |
6637 | .code | |
6638 | ${lookup dnsdb{>\n,: txt=a.b.example}} | |
6639 | ${lookup dnsdb{>\n; txt=a.b.example}} | |
6640 | .endd | |
6641 | It is permitted to specify a space as the separator character. Further | |
6642 | white space is ignored. | |
6643 | .wen | |
6644 | ||
f89d2485 | 6645 | .section "Pseudo dnsdb record types" "SECID66" |
9b371988 | 6646 | .cindex "MX record" "in &(dnsdb)& lookup" |
068aaea8 PH |
6647 | By default, both the preference value and the host name are returned for |
6648 | each MX record, separated by a space. If you want only host names, you can use | |
6649 | the pseudo-type MXH: | |
9b371988 PH |
6650 | .code |
6651 | ${lookup dnsdb{mxh=a.b.example}} | |
6652 | .endd | |
068aaea8 PH |
6653 | In this case, the preference values are omitted, and just the host names are |
6654 | returned. | |
168e428f | 6655 | |
f89d2485 | 6656 | .cindex "name server for enclosing domain" |
9b371988 | 6657 | Another pseudo-type is ZNS (for &"zone NS"&). It performs a lookup for NS |
168e428f PH |
6658 | records on the given domain, but if none are found, it removes the first |
6659 | component of the domain name, and tries again. This process continues until NS | |
6660 | records are found or there are no more components left (or there is a DNS | |
6661 | error). In other words, it may return the name servers for a top-level domain, | |
6662 | but it never returns the root name servers. If there are no NS records for the | |
6663 | top-level domain, the lookup fails. Consider these examples: | |
9b371988 PH |
6664 | .code |
6665 | ${lookup dnsdb{zns=xxx.quercite.com}} | |
6666 | ${lookup dnsdb{zns=xxx.edu}} | |
6667 | .endd | |
168e428f | 6668 | Assuming that in each case there are no NS records for the full domain name, |
9b371988 PH |
6669 | the first returns the name servers for &%quercite.com%&, and the second returns |
6670 | the name servers for &%edu%&. | |
168e428f PH |
6671 | |
6672 | You should be careful about how you use this lookup because, unless the | |
6673 | top-level domain does not exist, the lookup always returns some host names. The | |
6674 | sort of use to which this might be put is for seeing if the name servers for a | |
6675 | given domain are on a blacklist. You can probably assume that the name servers | |
9b371988 PH |
6676 | for the high-level domains such as &%com%& or &%co.uk%& are not going to be on |
6677 | such a list. | |
168e428f | 6678 | |
9b371988 PH |
6679 | .cindex "CSA" "in &(dnsdb)& lookup" |
6680 | A third pseudo-type is CSA (Client SMTP Authorization). This looks up SRV | |
068aaea8 | 6681 | records according to the CSA rules, which are described in section |
9b371988 PH |
6682 | &<<SECTverifyCSA>>&. Although &(dnsdb)& supports SRV lookups directly, this is |
6683 | not sufficient because of the extra parent domain search behaviour of CSA. The | |
068aaea8 | 6684 | result of a successful lookup such as: |
9b371988 | 6685 | .code |
068aaea8 | 6686 | ${lookup dnsdb {csa=$sender_helo_name}} |
9b371988 | 6687 | .endd |
068aaea8 | 6688 | has two space-separated fields: an authorization code and a target host name. |
9b371988 PH |
6689 | The authorization code can be &"Y"& for yes, &"N"& for no, &"X"& for explicit |
6690 | authorization required but absent, or &"?"& for unknown. | |
168e428f PH |
6691 | |
6692 | ||
f89d2485 | 6693 | .section "Multiple dnsdb lookups" "SECID67" |
9b371988 | 6694 | In the previous sections, &(dnsdb)& lookups for a single domain are described. |
168e428f | 6695 | However, you can specify a list of domains or IP addresses in a single |
9b371988 | 6696 | &(dnsdb)& lookup. The list is specified in the normal Exim way, with colon as |
168e428f | 6697 | the default separator, but with the ability to change this. For example: |
9b371988 PH |
6698 | .code |
6699 | ${lookup dnsdb{one.domain.com:two.domain.com}} | |
6700 | ${lookup dnsdb{a=one.host.com:two.host.com}} | |
6701 | ${lookup dnsdb{ptr = <; 1.2.3.4 ; 4.5.6.8}} | |
6702 | .endd | |
168e428f PH |
6703 | In order to retain backwards compatibility, there is one special case: if |
6704 | the lookup type is PTR and no change of separator is specified, Exim looks | |
6705 | to see if the rest of the string is precisely one IPv6 address. In this | |
6706 | case, it does not treat it as a list. | |
6707 | ||
6708 | The data from each lookup is concatenated, with newline separators by default, | |
6709 | in the same way that multiple DNS records for a single item are handled. A | |
6710 | different separator can be specified, as described above. | |
6711 | ||
9b371988 | 6712 | The &(dnsdb)& lookup fails only if all the DNS lookups fail. If there is a |
168e428f PH |
6713 | temporary DNS error for any of them, the behaviour is controlled by |
6714 | an optional keyword followed by a comma that may appear before the record | |
9b371988 PH |
6715 | type. The possible keywords are &"defer_strict"&, &"defer_never"&, and |
6716 | &"defer_lax"&. With &"strict"& behaviour, any temporary DNS error causes the | |
6717 | whole lookup to defer. With &"never"& behaviour, a temporary DNS error is | |
168e428f | 6718 | ignored, and the behaviour is as if the DNS lookup failed to find anything. |
9b371988 | 6719 | With &"lax"& behaviour, all the queries are attempted, but a temporary DNS |
168e428f | 6720 | error causes the whole lookup to defer only if none of the other lookups |
9b371988 PH |
6721 | succeed. The default is &"lax"&, so the following lookups are equivalent: |
6722 | .code | |
6723 | ${lookup dnsdb{defer_lax,a=one.host.com:two.host.com}} | |
6724 | ${lookup dnsdb{a=one.host.com:two.host.com}} | |
6725 | .endd | |
168e428f PH |
6726 | Thus, in the default case, as long as at least one of the DNS lookups |
6727 | yields some data, the lookup succeeds. | |
6728 | ||
6729 | ||
6730 | ||
6731 | ||
9b371988 | 6732 | .section "More about LDAP" "SECTldap" |
f89d2485 | 6733 | .cindex "LDAP" "lookup, more about" |
9b371988 PH |
6734 | .cindex "lookup" "LDAP" |
6735 | .cindex "Solaris" "LDAP" | |
168e428f | 6736 | The original LDAP implementation came from the University of Michigan; this has |
9b371988 | 6737 | become &"Open LDAP"&, and there are now two different releases. Another |
168e428f PH |
6738 | implementation comes from Netscape, and Solaris 7 and subsequent releases |
6739 | contain inbuilt LDAP support. Unfortunately, though these are all compatible at | |
6740 | the lookup function level, their error handling is different. For this reason | |
6741 | it is necessary to set a compile-time variable when building Exim with LDAP, to | |
6742 | indicate which LDAP library is in use. One of the following should appear in | |
9b371988 PH |
6743 | your &_Local/Makefile_&: |
6744 | .code | |
6745 | LDAP_LIB_TYPE=UMICHIGAN | |
6746 | LDAP_LIB_TYPE=OPENLDAP1 | |
6747 | LDAP_LIB_TYPE=OPENLDAP2 | |
6748 | LDAP_LIB_TYPE=NETSCAPE | |
6749 | LDAP_LIB_TYPE=SOLARIS | |
6750 | .endd | |
6751 | If LDAP_LIB_TYPE is not set, Exim assumes &`OPENLDAP1`&, which has the | |
168e428f PH |
6752 | same interface as the University of Michigan version. |
6753 | ||
6754 | There are three LDAP lookup types in Exim. These behave slightly differently in | |
6755 | the way they handle the results of a query: | |
6756 | ||
9b371988 PH |
6757 | .ilist |
6758 | &(ldap)& requires the result to contain just one entry; if there are more, it | |
168e428f | 6759 | gives an error. |
9b371988 PH |
6760 | .next |
6761 | &(ldapdn)& also requires the result to contain just one entry, but it is the | |
168e428f | 6762 | Distinguished Name that is returned rather than any attribute values. |
9b371988 PH |
6763 | .next |
6764 | &(ldapm)& permits the result to contain more than one entry; the attributes | |
6765 | from all of them are returned. | |
6766 | .endlist | |
168e428f PH |
6767 | |
6768 | ||
9b371988 | 6769 | For &(ldap)& and &(ldapm)&, if a query finds only entries with no attributes, |
168e428f PH |
6770 | Exim behaves as if the entry did not exist, and the lookup fails. The format of |
6771 | the data returned by a successful lookup is described in the next section. | |
6772 | First we explain how LDAP queries are coded. | |
6773 | ||
6774 | ||
9b371988 PH |
6775 | .section "Format of LDAP queries" "SECTforldaque" |
6776 | .cindex "LDAP" "query format" | |
168e428f | 6777 | An LDAP query takes the form of a URL as defined in RFC 2255. For example, in |
9b371988 PH |
6778 | the configuration of a &(redirect)& router one might have this setting: |
6779 | .code | |
168e428f PH |
6780 | data = ${lookup ldap \ |
6781 | {ldap:///cn=$local_part,o=University%20of%20Cambridge,\ | |
6782 | c=UK?mailbox?base?}} | |
9b371988 PH |
6783 | .endd |
6784 | .cindex "LDAP" "with TLS" | |
6785 | The URL may begin with &`ldap`& or &`ldaps`& if your LDAP library supports | |
168e428f PH |
6786 | secure (encrypted) LDAP connections. The second of these ensures that an |
6787 | encrypted TLS connection is used. | |
6788 | ||
6789 | ||
f89d2485 | 6790 | .section "LDAP quoting" "SECID68" |
9b371988 | 6791 | .cindex "LDAP" "quoting" |
168e428f PH |
6792 | Two levels of quoting are required in LDAP queries, the first for LDAP itself |
6793 | and the second because the LDAP query is represented as a URL. Furthermore, | |
6794 | within an LDAP query, two different kinds of quoting are required. For this | |
6795 | reason, there are two different LDAP-specific quoting operators. | |
6796 | ||
9b371988 | 6797 | The &%quote_ldap%& operator is designed for use on strings that are part of |
168e428f PH |
6798 | filter specifications. Conceptually, it first does the following conversions on |
6799 | the string: | |
9b371988 | 6800 | .code |
168e428f PH |
6801 | * => \2A |
6802 | ( => \28 | |
6803 | ) => \29 | |
6804 | \ => \5C | |
9b371988 | 6805 | .endd |
168e428f | 6806 | in accordance with RFC 2254. The resulting string is then quoted according |
9b371988 PH |
6807 | to the rules for URLs, that is, all non-alphanumeric characters except |
6808 | .code | |
6809 | ! $ ' - . _ ( ) * + | |
6810 | .endd | |
168e428f | 6811 | are converted to their hex values, preceded by a percent sign. For example: |
9b371988 PH |
6812 | .code |
6813 | ${quote_ldap: a(bc)*, a<yz>; } | |
6814 | .endd | |
168e428f | 6815 | yields |
9b371988 PH |
6816 | .code |
6817 | %20a%5C28bc%5C29%5C2A%2C%20a%3Cyz%3E%3B%20 | |
6818 | .endd | |
168e428f | 6819 | Removing the URL quoting, this is (with a leading and a trailing space): |
9b371988 PH |
6820 | .code |
6821 | a\28bc\29\2A, a<yz>; | |
6822 | .endd | |
6823 | The &%quote_ldap_dn%& operator is designed for use on strings that are part of | |
168e428f PH |
6824 | base DN specifications in queries. Conceptually, it first converts the string |
6825 | by inserting a backslash in front of any of the following characters: | |
9b371988 PH |
6826 | .code |
6827 | , + " \ < > ; | |
6828 | .endd | |
168e428f PH |
6829 | It also inserts a backslash before any leading spaces or # characters, and |
6830 | before any trailing spaces. (These rules are in RFC 2253.) The resulting string | |
6831 | is then quoted according to the rules for URLs. For example: | |
9b371988 PH |
6832 | .code |
6833 | ${quote_ldap_dn: a(bc)*, a<yz>; } | |
6834 | .endd | |
168e428f | 6835 | yields |
9b371988 PH |
6836 | .code |
6837 | %5C%20a(bc)*%5C%2C%20a%5C%3Cyz%5C%3E%5C%3B%5C%20 | |
6838 | .endd | |
168e428f | 6839 | Removing the URL quoting, this is (with a trailing space): |
9b371988 | 6840 | .code |
168e428f | 6841 | \ a(bc)*\, a\<yz\>\;\ |
9b371988 | 6842 | .endd |
168e428f PH |
6843 | There are some further comments about quoting in the section on LDAP |
6844 | authentication below. | |
6845 | ||
6846 | ||
f89d2485 | 6847 | .section "LDAP connections" "SECID69" |
9b371988 | 6848 | .cindex "LDAP" "connections" |
168e428f PH |
6849 | The connection to an LDAP server may either be over TCP/IP, or, when OpenLDAP |
6850 | is in use, via a Unix domain socket. The example given above does not specify | |
6851 | an LDAP server. A server that is reached by TCP/IP can be specified in a query | |
6852 | by starting it with | |
9b371988 PH |
6853 | .code |
6854 | ldap://<hostname>:<port>/... | |
6855 | .endd | |
168e428f PH |
6856 | If the port (and preceding colon) are omitted, the standard LDAP port (389) is |
6857 | used. When no server is specified in a query, a list of default servers is | |
9b371988 | 6858 | taken from the &%ldap_default_servers%& configuration option. This supplies a |
168e428f PH |
6859 | colon-separated list of servers which are tried in turn until one successfully |
6860 | handles a query, or there is a serious error. Successful handling either | |
6861 | returns the requested data, or indicates that it does not exist. Serious errors | |
6862 | are syntactical, or multiple values when only a single value is expected. | |
6863 | Errors which cause the next server to be tried are connection failures, bind | |
6864 | failures, and timeouts. | |
6865 | ||
6866 | For each server name in the list, a port number can be given. The standard way | |
f89d2485 | 6867 | of specifying a host and port is to use a colon separator (RFC 1738). Because |
9b371988 | 6868 | &%ldap_default_servers%& is a colon-separated list, such colons have to be |
168e428f | 6869 | doubled. For example |
9b371988 PH |
6870 | .code |
6871 | ldap_default_servers = ldap1.example.com::145:ldap2.example.com | |
6872 | .endd | |
6873 | If &%ldap_default_servers%& is unset, a URL with no server name is passed | |
168e428f PH |
6874 | to the LDAP library with no server name, and the library's default (normally |
6875 | the local host) is used. | |
6876 | ||
6877 | If you are using the OpenLDAP library, you can connect to an LDAP server using | |
6878 | a Unix domain socket instead of a TCP/IP connection. This is specified by using | |
9b371988 | 6879 | &`ldapi`& instead of &`ldap`& in LDAP queries. What follows here applies only |
168e428f PH |
6880 | to OpenLDAP. If Exim is compiled with a different LDAP library, this feature is |
6881 | not available. | |
6882 | ||
6883 | For this type of connection, instead of a host name for the server, a pathname | |
6884 | for the socket is required, and the port number is not relevant. The pathname | |
9b371988 | 6885 | can be specified either as an item in &%ldap_default_servers%&, or inline in |
168e428f | 6886 | the query. In the former case, you can have settings such as |
9b371988 PH |
6887 | .code |
6888 | ldap_default_servers = /tmp/ldap.sock : backup.ldap.your.domain | |
6889 | .endd | |
168e428f | 6890 | When the pathname is given in the query, you have to escape the slashes as |
9b371988 PH |
6891 | &`%2F`& to fit in with the LDAP URL syntax. For example: |
6892 | .code | |
6893 | ${lookup ldap {ldapi://%2Ftmp%2Fldap.sock/o=... | |
6894 | .endd | |
6895 | When Exim processes an LDAP lookup and finds that the &"hostname"& is really | |
168e428f | 6896 | a pathname, it uses the Unix domain socket code, even if the query actually |
9b371988 | 6897 | specifies &`ldap`& or &`ldaps`&. In particular, no encryption is used for a |
168e428f | 6898 | socket connection. This behaviour means that you can use a setting of |
9b371988 PH |
6899 | &%ldap_default_servers%& such as in the example above with traditional &`ldap`& |
6900 | or &`ldaps`& queries, and it will work. First, Exim tries a connection via | |
168e428f PH |
6901 | the Unix domain socket; if that fails, it tries a TCP/IP connection to the |
6902 | backup host. | |
6903 | ||
9b371988 | 6904 | If an explicit &`ldapi`& type is given in a query when a host name is |
168e428f | 6905 | specified, an error is diagnosed. However, if there are more items in |
9b371988 | 6906 | &%ldap_default_servers%&, they are tried. In other words: |
168e428f | 6907 | |
9b371988 PH |
6908 | .ilist |
6909 | Using a pathname with &`ldap`& or &`ldaps`& forces the use of the Unix domain | |
168e428f | 6910 | interface. |
9b371988 PH |
6911 | .next |
6912 | Using &`ldapi`& with a host name causes an error. | |
6913 | .endlist | |
168e428f PH |
6914 | |
6915 | ||
9b371988 PH |
6916 | Using &`ldapi`& with no host or path in the query, and no setting of |
6917 | &%ldap_default_servers%&, does whatever the library does by default. | |
168e428f PH |
6918 | |
6919 | ||
6920 | ||
f89d2485 | 6921 | .section "LDAP authentication and control information" "SECID70" |
9b371988 | 6922 | .cindex "LDAP" "authentication" |
168e428f PH |
6923 | The LDAP URL syntax provides no way of passing authentication and other control |
6924 | information to the server. To make this possible, the URL in an LDAP query may | |
9b371988 | 6925 | be preceded by any number of <&'name'&>=<&'value'&> settings, separated by |
168e428f PH |
6926 | spaces. If a value contains spaces it must be enclosed in double quotes, and |
6927 | when double quotes are used, backslash is interpreted in the usual way inside | |
6928 | them. The following names are recognized: | |
9b371988 PH |
6929 | .display |
6930 | &`DEREFERENCE`& set the dereferencing parameter | |
6931 | &`NETTIME `& set a timeout for a network operation | |
6932 | &`USER `& set the DN, for authenticating the LDAP bind | |
6933 | &`PASS `& set the password, likewise | |
db9452a9 | 6934 | &`REFERRALS `& set the referrals parameter |
9b371988 PH |
6935 | &`SIZE `& set the limit for the number of entries returned |
6936 | &`TIME `& set the maximum waiting time for a query | |
6937 | .endd | |
6938 | The value of the DEREFERENCE parameter must be one of the words &"never"&, | |
db9452a9 PH |
6939 | &"searching"&, &"finding"&, or &"always"&. The value of the REFERRALS parameter |
6940 | must be &"follow"& (the default) or &"nofollow"&. The latter stops the LDAP | |
6941 | library from trying to follow referrals issued by the LDAP server. | |
168e428f PH |
6942 | |
6943 | The name CONNECT is an obsolete name for NETTIME, retained for | |
6944 | backwards compatibility. This timeout (specified as a number of seconds) is | |
6945 | enforced from the client end for operations that can be carried out over a | |
6946 | network. Specifically, it applies to network connections and calls to the | |
9b371988 | 6947 | &'ldap_result()'& function. If the value is greater than zero, it is used if |
168e428f PH |
6948 | LDAP_OPT_NETWORK_TIMEOUT is defined in the LDAP headers (OpenLDAP), or |
6949 | if LDAP_X_OPT_CONNECT_TIMEOUT is defined in the LDAP headers (Netscape | |
9b371988 | 6950 | SDK 4.1). A value of zero forces an explicit setting of &"no timeout"& for |
168e428f PH |
6951 | Netscape SDK; for OpenLDAP no action is taken. |
6952 | ||
6953 | The TIME parameter (also a number of seconds) is passed to the server to | |
6954 | set a server-side limit on the time taken to complete a search. | |
6955 | ||
6956 | ||
6957 | Here is an example of an LDAP query in an Exim lookup that uses some of these | |
9b371988 PH |
6958 | values. This is a single line, folded to fit on the page: |
6959 | .code | |
6960 | ${lookup ldap | |
6961 | {user="cn=manager,o=University of Cambridge,c=UK" pass=secret | |
6962 | ldap:///o=University%20of%20Cambridge,c=UK?sn?sub?(cn=foo)} | |
6963 | {$value}fail} | |
6964 | .endd | |
6965 | The encoding of spaces as &`%20`& is a URL thing which should not be done for | |
6966 | any of the auxiliary data. Exim configuration settings that include lookups | |
6967 | which contain password information should be preceded by &"hide"& to prevent | |
6968 | non-admin users from using the &%-bP%& option to see their values. | |
168e428f PH |
6969 | |
6970 | The auxiliary data items may be given in any order. The default is no | |
6971 | connection timeout (the system timeout is used), no user or password, no limit | |
6972 | on the number of entries returned, and no time limit on queries. | |
6973 | ||
6974 | When a DN is quoted in the USER= setting for LDAP authentication, Exim | |
6975 | removes any URL quoting that it may contain before passing it LDAP. Apparently | |
6976 | some libraries do this for themselves, but some do not. Removing the URL | |
6977 | quoting has two advantages: | |
6978 | ||
9b371988 PH |
6979 | .ilist |
6980 | It makes it possible to use the same &%quote_ldap_dn%& expansion for USER= | |
168e428f | 6981 | DNs as with DNs inside actual queries. |
9b371988 PH |
6982 | .next |
6983 | It permits spaces inside USER= DNs. | |
6984 | .endlist | |
168e428f PH |
6985 | |
6986 | For example, a setting such as | |
9b371988 PH |
6987 | .code |
6988 | USER=cn=${quote_ldap_dn:$1} | |
6989 | .endd | |
6990 | should work even if &$1$& contains spaces. | |
168e428f | 6991 | |
9b371988 | 6992 | Expanded data for the PASS= value should be quoted using the &%quote%& |
168e428f PH |
6993 | expansion operator, rather than the LDAP quote operators. The only reason this |
6994 | field needs quoting is to ensure that it conforms to the Exim syntax, which | |
6995 | does not allow unquoted spaces. For example: | |
9b371988 PH |
6996 | .code |
6997 | PASS=${quote:$3} | |
6998 | .endd | |
168e428f | 6999 | The LDAP authentication mechanism can be used to check passwords as part of |
9b371988 PH |
7000 | SMTP authentication. See the &%ldapauth%& expansion string condition in chapter |
7001 | &<<CHAPexpand>>&. | |
168e428f | 7002 | |
168e428f PH |
7003 | |
7004 | ||
f89d2485 | 7005 | .section "Format of data returned by LDAP" "SECID71" |
9b371988 PH |
7006 | .cindex "LDAP" "returned data formats" |
7007 | The &(ldapdn)& lookup type returns the Distinguished Name from a single entry | |
7008 | as a sequence of values, for example | |
7009 | .code | |
7010 | cn=manager, o=University of Cambridge, c=UK | |
7011 | .endd | |
7012 | The &(ldap)& lookup type generates an error if more than one entry matches the | |
7013 | search filter, whereas &(ldapm)& permits this case, and inserts a newline in | |
168e428f | 7014 | the result between the data from different entries. It is possible for multiple |
9b371988 | 7015 | values to be returned for both &(ldap)& and &(ldapm)&, but in the former case |
168e428f PH |
7016 | you know that whatever values are returned all came from a single entry in the |
7017 | directory. | |
7018 | ||
7019 | In the common case where you specify a single attribute in your LDAP query, the | |
7020 | result is not quoted, and does not contain the attribute name. If the attribute | |
7021 | has multiple values, they are separated by commas. | |
7022 | ||
7023 | If you specify multiple attributes, the result contains space-separated, quoted | |
7024 | strings, each preceded by the attribute name and an equals sign. Within the | |
7025 | quotes, the quote character, backslash, and newline are escaped with | |
7026 | backslashes, and commas are used to separate multiple values for the attribute. | |
7027 | Apart from the escaping, the string within quotes takes the same form as the | |
7028 | output when a single attribute is requested. Specifying no attributes is the | |
7029 | same as specifying all of an entry's attributes. | |
7030 | ||
7031 | Here are some examples of the output format. The first line of each pair is an | |
7032 | LDAP query, and the second is the data that is returned. The attribute called | |
9b371988 PH |
7033 | &%attr1%& has two values, whereas &%attr2%& has only one value: |
7034 | .code | |
7035 | ldap:///o=base?attr1?sub?(uid=fred) | |
7036 | value1.1, value1.2 | |
168e428f | 7037 | |
9b371988 PH |
7038 | ldap:///o=base?attr2?sub?(uid=fred) |
7039 | value two | |
168e428f | 7040 | |
9b371988 PH |
7041 | ldap:///o=base?attr1,attr2?sub?(uid=fred) |
7042 | attr1="value1.1, value1.2" attr2="value two" | |
168e428f | 7043 | |
9b371988 PH |
7044 | ldap:///o=base??sub?(uid=fred) |
7045 | objectClass="top" attr1="value1.1, value1.2" attr2="value two" | |
7046 | .endd | |
7047 | The &%extract%& operator in string expansions can be used to pick out | |
7048 | individual fields from data that consists of &'key'&=&'value'& pairs. You can | |
7049 | make use of Exim's &%-be%& option to run expansion tests and thereby check the | |
7050 | results of LDAP lookups. | |
168e428f | 7051 | |
168e428f | 7052 | |
168e428f PH |
7053 | |
7054 | ||
9b371988 PH |
7055 | .section "More about NIS+" "SECTnisplus" |
7056 | .cindex "NIS+ lookup type" | |
7057 | .cindex "lookup" "NIS+" | |
7058 | NIS+ queries consist of a NIS+ &'indexed name'& followed by an optional colon | |
168e428f PH |
7059 | and field name. If this is given, the result of a successful query is the |
7060 | contents of the named field; otherwise the result consists of a concatenation | |
9b371988 | 7061 | of &'field-name=field-value'& pairs, separated by spaces. Empty values and |
168e428f | 7062 | values containing spaces are quoted. For example, the query |
9b371988 PH |
7063 | .code |
7064 | [name=mg1456],passwd.org_dir | |
7065 | .endd | |
168e428f | 7066 | might return the string |
9b371988 PH |
7067 | .code |
7068 | name=mg1456 passwd="" uid=999 gid=999 gcos="Martin Guerre" | |
7069 | home=/home/mg1456 shell=/bin/bash shadow="" | |
7070 | .endd | |
168e428f | 7071 | (split over two lines here to fit on the page), whereas |
9b371988 PH |
7072 | .code |
7073 | [name=mg1456],passwd.org_dir:gcos | |
7074 | .endd | |
168e428f | 7075 | would just return |
9b371988 PH |
7076 | .code |
7077 | Martin Guerre | |
7078 | .endd | |
168e428f | 7079 | with no quotes. A NIS+ lookup fails if NIS+ returns more than one table entry |
9b371988 | 7080 | for the given indexed key. The effect of the &%quote_nisplus%& expansion |
168e428f PH |
7081 | operator is to double any quote characters within the text. |
7082 | ||
7083 | ||
7084 | ||
9b371988 | 7085 | .section "SQL lookups" "SECTsql" |
9b371988 | 7086 | .cindex "SQL lookup types" |
595028e4 PH |
7087 | .cindex "MySQL" "lookup type" |
7088 | .cindex "PostgreSQL lookup type" | |
7089 | .cindex "lookup" "MySQL" | |
7090 | .cindex "lookup" "PostgreSQL" | |
7091 | .cindex "Oracle" "lookup type" | |
7092 | .cindex "lookup" "Oracle" | |
7093 | .cindex "InterBase lookup type" | |
7094 | .cindex "lookup" "InterBase" | |
db9452a9 | 7095 | Exim can support lookups in InterBase, MySQL, Oracle, PostgreSQL, and SQLite |
068aaea8 PH |
7096 | databases. Queries for these databases contain SQL statements, so an example |
7097 | might be | |
9b371988 | 7098 | .code |
068aaea8 PH |
7099 | ${lookup mysql{select mailbox from users where id='userx'}\ |
7100 | {$value}fail} | |
9b371988 | 7101 | .endd |
068aaea8 PH |
7102 | If the result of the query contains more than one field, the data for each |
7103 | field in the row is returned, preceded by its name, so the result of | |
9b371988 | 7104 | .code |
068aaea8 PH |
7105 | ${lookup pgsql{select home,name from users where id='userx'}\ |
7106 | {$value}} | |
9b371988 | 7107 | .endd |
068aaea8 | 7108 | might be |
9b371988 PH |
7109 | .code |
7110 | home=/home/userx name="Mister X" | |
7111 | .endd | |
068aaea8 PH |
7112 | Empty values and values containing spaces are double quoted, with embedded |
7113 | quotes escaped by a backslash. If the result of the query contains just one | |
7114 | field, the value is passed back verbatim, without a field name, for example: | |
9b371988 PH |
7115 | .code |
7116 | Mister X | |
7117 | .endd | |
068aaea8 PH |
7118 | If the result of the query yields more than one row, it is all concatenated, |
7119 | with a newline between the data for each row. | |
7120 | ||
7121 | ||
f89d2485 | 7122 | .section "More about MySQL, PostgreSQL, Oracle, and InterBase" "SECID72" |
9b371988 PH |
7123 | .cindex "MySQL" "lookup type" |
7124 | .cindex "PostgreSQL lookup type" | |
7125 | .cindex "lookup" "MySQL" | |
7126 | .cindex "lookup" "PostgreSQL" | |
7127 | .cindex "Oracle" "lookup type" | |
7128 | .cindex "lookup" "Oracle" | |
db9452a9 PH |
7129 | .cindex "InterBase lookup type" |
7130 | .cindex "lookup" "InterBase" | |
7131 | If any MySQL, PostgreSQL, Oracle, or InterBase lookups are used, the | |
9b371988 PH |
7132 | &%mysql_servers%&, &%pgsql_servers%&, &%oracle_servers%&, or &%ibase_servers%& |
7133 | option (as appropriate) must be set to a colon-separated list of server | |
595028e4 | 7134 | information. |
7d0ab55c | 7135 | (For MySQL and PostgreSQL only, the global option need not be set if all |
595028e4 | 7136 | queries contain their own server information &-- see section |
7d0ab55c | 7137 | &<<SECTspeserque>>&.) Each item in the list is a slash-separated list of four |
595028e4 PH |
7138 | items: host name, database name, user name, and password. In the case of |
7139 | Oracle, the host name field is used for the &"service name"&, and the database | |
7140 | name field is not used and should be empty. For example: | |
9b371988 PH |
7141 | .code |
7142 | hide oracle_servers = oracle.plc.example//userx/abcdwxyz | |
7143 | .endd | |
168e428f | 7144 | Because password data is sensitive, you should always precede the setting with |
9b371988 | 7145 | &"hide"&, to prevent non-admin users from obtaining the setting via the &%-bP%& |
168e428f | 7146 | option. Here is an example where two MySQL servers are listed: |
9b371988 | 7147 | .code |
168e428f PH |
7148 | hide mysql_servers = localhost/users/root/secret:\ |
7149 | otherhost/users/root/othersecret | |
9b371988 PH |
7150 | .endd |
7151 | For MySQL and PostgreSQL, a host may be specified as <&'name'&>:<&'port'&> but | |
068aaea8 | 7152 | because this is a colon-separated list, the colon has to be doubled. For each |
595028e4 PH |
7153 | query, these parameter groups are tried in order until a connection is made and |
7154 | a query is successfully processed. The result of a query may be that no data is | |
7155 | found, but that is still a successful query. In other words, the list of | |
7156 | servers provides a backup facility, not a list of different places to look. | |
168e428f | 7157 | |
9b371988 | 7158 | The &%quote_mysql%&, &%quote_pgsql%&, and &%quote_oracle%& expansion operators |
168e428f PH |
7159 | convert newline, tab, carriage return, and backspace to \n, \t, \r, and \b |
7160 | respectively, and the characters single-quote, double-quote, and backslash | |
9b371988 | 7161 | itself are escaped with backslashes. The &%quote_pgsql%& expansion operator, in |
168e428f PH |
7162 | addition, escapes the percent and underscore characters. This cannot be done |
7163 | for MySQL because these escapes are not recognized in contexts where these | |
7164 | characters are not special. | |
7165 | ||
595028e4 PH |
7166 | .section "Specifying the server in the query" "SECTspeserque" |
7167 | For MySQL and PostgreSQL lookups (but not currently for Oracle and InterBase), | |
7168 | it is possible to specify a list of servers with an individual query. This is | |
7169 | done by starting the query with | |
7170 | .display | |
7171 | &`servers=`&&'server1:server2:server3:...'&&`;`& | |
7172 | .endd | |
7173 | Each item in the list may take one of two forms: | |
7174 | .olist | |
7175 | If it contains no slashes it is assumed to be just a host name. The appropriate | |
7176 | global option (&%mysql_servers%& or &%pgsql_servers%&) is searched for a host | |
7177 | of the same name, and the remaining parameters (database, user, password) are | |
7178 | taken from there. | |
7179 | .next | |
7180 | If it contains any slashes, it is taken as a complete parameter set. | |
7181 | .endlist | |
7182 | The list of servers is used in exactly the same way as the global list. | |
7183 | Once a connection to a server has happened and a query has been | |
7184 | successfully executed, processing of the lookup ceases. | |
7185 | ||
7186 | This feature is intended for use in master/slave situations where updates | |
7187 | are occurring and you want to update the master rather than a slave. If the | |
7188 | master is in the list as a backup for reading, you might have a global setting | |
7189 | like this: | |
7190 | .code | |
7191 | mysql_servers = slave1/db/name/pw:\ | |
7192 | slave2/db/name/pw:\ | |
7193 | master/db/name/pw | |
7194 | .endd | |
7195 | In an updating lookup, you could then write: | |
7196 | .code | |
512314e9 | 7197 | ${lookup mysql{servers=master; UPDATE ...} } |
595028e4 PH |
7198 | .endd |
7199 | That query would then be sent only to the master server. If, on the other hand, | |
7200 | the master is not to be used for reading, and so is not present in the global | |
7201 | option, you can still update it by a query of this form: | |
7202 | .code | |
512314e9 | 7203 | ${lookup pgsql{servers=master/db/name/pw; UPDATE ...} } |
595028e4 | 7204 | .endd |
595028e4 | 7205 | |
168e428f | 7206 | |
f89d2485 | 7207 | .section "Special MySQL features" "SECID73" |
9b371988 | 7208 | For MySQL, an empty host name or the use of &"localhost"& in &%mysql_servers%& |
168e428f PH |
7209 | causes a connection to the server on the local host by means of a Unix domain |
7210 | socket. An alternate socket can be specified in parentheses. The full syntax of | |
9b371988 PH |
7211 | each item in &%mysql_servers%& is: |
7212 | .display | |
7213 | <&'hostname'&>::<&'port'&>(<&'socket name'&>)/<&'database'&>/&&& | |
7214 | <&'user'&>/<&'password'&> | |
7215 | .endd | |
168e428f | 7216 | Any of the three sub-parts of the first field can be omitted. For normal use on |
9b371988 | 7217 | the local host it can be left blank or set to just &"localhost"&. |
168e428f | 7218 | |
9b371988 | 7219 | No database need be supplied &-- but if it is absent here, it must be given in |
168e428f PH |
7220 | the queries. |
7221 | ||
7222 | If a MySQL query is issued that does not request any data (an insert, update, | |
7223 | or delete command), the result of the lookup is the number of rows affected. | |
7224 | ||
9b371988 | 7225 | &*Warning*&: This can be misleading. If an update does not actually change |
168e428f PH |
7226 | anything (for example, setting a field to the value it already has), the result |
7227 | is zero because no rows are affected. | |
7228 | ||
7229 | ||
f89d2485 | 7230 | .section "Special PostgreSQL features" "SECID74" |
168e428f PH |
7231 | PostgreSQL lookups can also use Unix domain socket connections to the database. |
7232 | This is usually faster and costs less CPU time than a TCP/IP connection. | |
7233 | However it can be used only if the mail server runs on the same machine as the | |
7234 | database server. A configuration line for PostgreSQL via Unix domain sockets | |
7235 | looks like this: | |
9b371988 PH |
7236 | .code |
7237 | hide pgsql_servers = (/tmp/.s.PGSQL.5432)/db/user/password : ... | |
7238 | .endd | |
168e428f PH |
7239 | In other words, instead of supplying a host name, a path to the socket is |
7240 | given. The path name is enclosed in parentheses so that its slashes aren't | |
7241 | visually confused with the delimiters for the other server parameters. | |
7242 | ||
7243 | If a PostgreSQL query is issued that does not request any data (an insert, | |
7244 | update, or delete command), the result of the lookup is the number of rows | |
7245 | affected. | |
7246 | ||
9b371988 PH |
7247 | .section "More about SQLite" "SECTsqlite" |
7248 | .cindex "lookup" "SQLite" | |
f89d2485 | 7249 | .cindex "sqlite lookup type" |
068aaea8 PH |
7250 | SQLite is different to the other SQL lookups because a file name is required in |
7251 | addition to the SQL query. An SQLite database is a single file, and there is no | |
7252 | daemon as in the other SQL databases. The interface to Exim requires the name | |
7253 | of the file, as an absolute path, to be given at the start of the query. It is | |
7254 | separated from the query by white space. This means that the path name cannot | |
7255 | contain white space. Here is a lookup expansion example: | |
9b371988 | 7256 | .code |
068aaea8 PH |
7257 | ${lookup sqlite {/some/thing/sqlitedb \ |
7258 | select name from aliases where id='userx';}} | |
9b371988 | 7259 | .endd |
068aaea8 | 7260 | In a list, the syntax is similar. For example: |
9b371988 | 7261 | .code |
068aaea8 PH |
7262 | domainlist relay_domains = sqlite;/some/thing/sqlitedb \ |
7263 | select * from relays where ip='$sender_host_address'; | |
9b371988 PH |
7264 | .endd |
7265 | The only character affected by the &%quote_sqlite%& operator is a single | |
068aaea8 PH |
7266 | quote, which it doubles. |
7267 | ||
068aaea8 PH |
7268 | The SQLite library handles multiple simultaneous accesses to the database |
7269 | internally. Multiple readers are permitted, but only one process can | |
7270 | update at once. Attempts to access the database while it is being updated | |
7271 | are rejected after a timeout period, during which the SQLite library | |
7272 | waits for the lock to be released. In Exim, the default timeout is set | |
9b371988 | 7273 | to 5 seconds, but it can be changed by means of the &%sqlite_lock_timeout%& |
068aaea8 | 7274 | option. |
4f578862 PH |
7275 | .ecindex IIDfidalo1 |
7276 | .ecindex IIDfidalo2 | |
168e428f PH |
7277 | |
7278 | ||
9b371988 PH |
7279 | . //////////////////////////////////////////////////////////////////////////// |
7280 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 7281 | |
9b371988 PH |
7282 | .chapter "Domain, host, address, and local part lists" &&& |
7283 | "CHAPdomhosaddlists" &&& | |
7284 | "Domain, host, and address lists" | |
4f578862 | 7285 | .scindex IIDdohoadli "lists of domains; hosts; etc." |
168e428f | 7286 | A number of Exim configuration options contain lists of domains, hosts, |
9b371988 | 7287 | email addresses, or local parts. For example, the &%hold_domains%& option |
168e428f | 7288 | contains a list of domains whose delivery is currently suspended. These lists |
9b371988 PH |
7289 | are also used as data in ACL statements (see chapter &<<CHAPACL>>&), and as |
7290 | arguments to expansion conditions such as &%match_domain%&. | |
168e428f PH |
7291 | |
7292 | Each item in one of these lists is a pattern to be matched against a domain, | |
7293 | host, email address, or local part, respectively. In the sections below, the | |
7294 | different types of pattern for each case are described, but first we cover some | |
7295 | general facilities that apply to all four kinds of list. | |
7296 | ||
7297 | ||
7298 | ||
f89d2485 | 7299 | .section "Expansion of lists" "SECID75" |
9b371988 | 7300 | .cindex "expansion" "of lists" |
168e428f PH |
7301 | Each list is expanded as a single string before it is used. The result of |
7302 | expansion must be a list, possibly containing empty items, which is split up | |
7303 | into separate items for matching. By default, colon is the separator character, | |
9b371988 PH |
7304 | but this can be varied if necessary. See sections &<<SECTlistconstruct>>& and |
7305 | &<<SECTempitelis>>& for details of the list syntax; the second of these | |
7306 | discusses the way to specify empty list items. | |
168e428f PH |
7307 | |
7308 | ||
7309 | If the string expansion is forced to fail, Exim behaves as if the item it is | |
7310 | testing (domain, host, address, or local part) is not in the list. Other | |
7311 | expansion failures cause temporary errors. | |
7312 | ||
7313 | If an item in a list is a regular expression, backslashes, dollars and possibly | |
7314 | other special characters in the expression must be protected against | |
7315 | misinterpretation by the string expander. The easiest way to do this is to use | |
9b371988 | 7316 | the &`\N`& expansion feature to indicate that the contents of the regular |
168e428f | 7317 | expression should not be expanded. For example, in an ACL you might have: |
9b371988 | 7318 | .code |
168e428f PH |
7319 | deny senders = \N^\d{8}\w@.*\.baddomain\.example$\N : \ |
7320 | ${lookup{$domain}lsearch{/badsenders/bydomain}} | |
9b371988 | 7321 | .endd |
168e428f | 7322 | The first item is a regular expression that is protected from expansion by |
9b371988 | 7323 | &`\N`&, whereas the second uses the expansion to obtain a list of unwanted |
168e428f PH |
7324 | senders based on the receiving domain. |
7325 | ||
7326 | ||
7327 | ||
7328 | ||
f89d2485 | 7329 | .section "Negated items in lists" "SECID76" |
9b371988 | 7330 | .cindex "list" "negation" |
4f578862 | 7331 | .cindex "negation" "in lists" |
168e428f PH |
7332 | Items in a list may be positive or negative. Negative items are indicated by a |
7333 | leading exclamation mark, which may be followed by optional white space. A list | |
7334 | defines a set of items (domains, etc). When Exim processes one of these lists, | |
7335 | it is trying to find out whether a domain, host, address, or local part | |
7336 | (respectively) is in the set that is defined by the list. It works like this: | |
7337 | ||
7338 | The list is scanned from left to right. If a positive item is matched, the | |
7339 | subject that is being checked is in the set; if a negative item is matched, the | |
7340 | subject is not in the set. If the end of the list is reached without the | |
7341 | subject having matched any of the patterns, it is in the set if the last item | |
7342 | was a negative one, but not if it was a positive one. For example, the list in | |
9b371988 PH |
7343 | .code |
7344 | domainlist relay_domains = !a.b.c : *.b.c | |
7345 | .endd | |
7346 | matches any domain ending in &'.b.c'& except for &'a.b.c'&. Domains that match | |
7347 | neither &'a.b.c'& nor &'*.b.c'& do not match, because the last item in the | |
168e428f | 7348 | list is positive. However, if the setting were |
9b371988 PH |
7349 | .code |
7350 | domainlist relay_domains = !a.b.c | |
7351 | .endd | |
7352 | then all domains other than &'a.b.c'& would match because the last item in the | |
168e428f | 7353 | list is negative. In other words, a list that ends with a negative item behaves |
9b371988 | 7354 | as if it had an extra item &`:*`& on the end. |
168e428f PH |
7355 | |
7356 | Another way of thinking about positive and negative items in lists is to read | |
9b371988 | 7357 | the connector as &"or"& after a positive item and as &"and"& after a negative |
168e428f PH |
7358 | item. |
7359 | ||
7360 | ||
7361 | ||
9b371988 PH |
7362 | .section "File names in lists" "SECTfilnamlis" |
7363 | .cindex "list" "file name in" | |
168e428f PH |
7364 | If an item in a domain, host, address, or local part list is an absolute file |
7365 | name (beginning with a slash character), each line of the file is read and | |
7366 | processed as if it were an independent item in the list, except that further | |
7367 | file names are not allowed, | |
7368 | and no expansion of the data from the file takes place. | |
7369 | Empty lines in the file are ignored, and the file may also contain comment | |
7370 | lines: | |
7371 | ||
9b371988 PH |
7372 | .ilist |
7373 | For domain and host lists, if a # character appears anywhere in a line of the | |
168e428f | 7374 | file, it and all following characters are ignored. |
9b371988 PH |
7375 | .next |
7376 | Because local parts may legitimately contain # characters, a comment in an | |
168e428f PH |
7377 | address list or local part list file is recognized only if # is preceded by |
7378 | white space or the start of the line. For example: | |
9b371988 PH |
7379 | .code |
7380 | not#comment@x.y.z # but this is a comment | |
7381 | .endd | |
7382 | .endlist | |
168e428f PH |
7383 | |
7384 | Putting a file name in a list has the same effect as inserting each line of the | |
7385 | file as an item in the list (blank lines and comments excepted). However, there | |
7386 | is one important difference: the file is read each time the list is processed, | |
7387 | so if its contents vary over time, Exim's behaviour changes. | |
7388 | ||
7389 | If a file name is preceded by an exclamation mark, the sense of any match | |
7390 | within the file is inverted. For example, if | |
9b371988 PH |
7391 | .code |
7392 | hold_domains = !/etc/nohold-domains | |
7393 | .endd | |
168e428f | 7394 | and the file contains the lines |
9b371988 PH |
7395 | .code |
7396 | !a.b.c | |
7397 | *.b.c | |
7398 | .endd | |
7399 | then &'a.b.c'& is in the set of domains defined by &%hold_domains%&, whereas | |
7400 | any domain matching &`*.b.c`& is not. | |
168e428f | 7401 | |
168e428f PH |
7402 | |
7403 | ||
f89d2485 | 7404 | .section "An lsearch file is not an out-of-line list" "SECID77" |
168e428f PH |
7405 | As will be described in the sections that follow, lookups can be used in lists |
7406 | to provide indexed methods of checking list membership. There has been some | |
9b371988 PH |
7407 | confusion about the way &(lsearch)& lookups work in lists. Because |
7408 | an &(lsearch)& file contains plain text and is scanned sequentially, it is | |
168e428f | 7409 | sometimes thought that it is allowed to contain wild cards and other kinds of |
9b371988 | 7410 | non-constant pattern. This is not the case. The keys in an &(lsearch)& file are |
168e428f PH |
7411 | always fixed strings, just as for any other single-key lookup type. |
7412 | ||
7413 | If you want to use a file to contain wild-card patterns that form part of a | |
7414 | list, just give the file name on its own, without a search type, as described | |
db9452a9 PH |
7415 | in the previous section. You could also use the &(wildlsearch)& or |
7416 | &(nwildlsearch)&, but there is no advantage in doing this. | |
168e428f PH |
7417 | |
7418 | ||
7419 | ||
7420 | ||
9b371988 PH |
7421 | .section "Named lists" "SECTnamedlists" |
7422 | .cindex "named lists" | |
7423 | .cindex "list" "named" | |
168e428f PH |
7424 | A list of domains, hosts, email addresses, or local parts can be given a name |
7425 | which is then used to refer to the list elsewhere in the configuration. This is | |
7426 | particularly convenient if the same list is required in several different | |
7427 | places. It also allows lists to be given meaningful names, which can improve | |
7428 | the readability of the configuration. For example, it is conventional to define | |
9b371988 | 7429 | a domain list called &'local_domains'& for all the domains that are handled |
168e428f | 7430 | locally on a host, using a configuration line such as |
9b371988 PH |
7431 | .code |
7432 | domainlist local_domains = localhost:my.dom.example | |
7433 | .endd | |
168e428f PH |
7434 | Named lists are referenced by giving their name preceded by a plus sign, so, |
7435 | for example, a router that is intended to handle local domains would be | |
7436 | configured with the line | |
9b371988 PH |
7437 | .code |
7438 | domains = +local_domains | |
7439 | .endd | |
168e428f PH |
7440 | The first router in a configuration is often one that handles all domains |
7441 | except the local ones, using a configuration with a negated item like this: | |
9b371988 PH |
7442 | .code |
7443 | dnslookup: | |
7444 | driver = dnslookup | |
7445 | domains = ! +local_domains | |
7446 | transport = remote_smtp | |
7447 | no_more | |
7448 | .endd | |
168e428f | 7449 | The four kinds of named list are created by configuration lines starting with |
9b371988 | 7450 | the words &%domainlist%&, &%hostlist%&, &%addresslist%&, or &%localpartlist%&, |
168e428f PH |
7451 | respectively. Then there follows the name that you are defining, followed by an |
7452 | equals sign and the list itself. For example: | |
9b371988 PH |
7453 | .code |
7454 | hostlist relay_hosts = 192.168.23.0/24 : my.friend.example | |
7455 | addresslist bad_senders = cdb;/etc/badsenders | |
7456 | .endd | |
168e428f | 7457 | A named list may refer to other named lists: |
9b371988 PH |
7458 | .code |
7459 | domainlist dom1 = first.example : second.example | |
7460 | domainlist dom2 = +dom1 : third.example | |
7461 | domainlist dom3 = fourth.example : +dom2 : fifth.example | |
7462 | .endd | |
7463 | &*Warning*&: If the last item in a referenced list is a negative one, the | |
168e428f PH |
7464 | effect may not be what you intended, because the negation does not propagate |
7465 | out to the higher level. For example, consider: | |
9b371988 PH |
7466 | .code |
7467 | domainlist dom1 = !a.b | |
7468 | domainlist dom2 = +dom1 : *.b | |
7469 | .endd | |
7470 | The second list specifies &"either in the &%dom1%& list or &'*.b'&"&. The first | |
7471 | list specifies just &"not &'a.b'&"&, so the domain &'x.y'& matches it. That | |
7472 | means it matches the second list as well. The effect is not the same as | |
7473 | .code | |
7474 | domainlist dom2 = !a.b : *.b | |
7475 | .endd | |
7476 | where &'x.y'& does not match. It's best to avoid negation altogether in | |
168e428f PH |
7477 | referenced lists if you can. |
7478 | ||
7479 | Named lists may have a performance advantage. When Exim is routing an | |
7480 | address or checking an incoming message, it caches the result of tests on named | |
7481 | lists. So, if you have a setting such as | |
9b371988 PH |
7482 | .code |
7483 | domains = +local_domains | |
7484 | .endd | |
168e428f PH |
7485 | on several of your routers |
7486 | or in several ACL statements, | |
7487 | the actual test is done only for the first one. However, the caching works only | |
7488 | if there are no expansions within the list itself or any sublists that it | |
7489 | references. In other words, caching happens only for lists that are known to be | |
7490 | the same each time they are referenced. | |
7491 | ||
7492 | By default, there may be up to 16 named lists of each type. This limit can be | |
7493 | extended by changing a compile-time variable. The use of domain and host lists | |
7494 | is recommended for concepts such as local domains, relay domains, and relay | |
7495 | hosts. The default configuration is set up like this. | |
7496 | ||
7497 | ||
7498 | ||
f89d2485 | 7499 | .section "Named lists compared with macros" "SECID78" |
9b371988 PH |
7500 | .cindex "list" "named compared with macro" |
7501 | .cindex "macro" "compared with named list" | |
168e428f PH |
7502 | At first sight, named lists might seem to be no different from macros in the |
7503 | configuration file. However, macros are just textual substitutions. If you | |
7504 | write | |
9b371988 PH |
7505 | .code |
7506 | ALIST = host1 : host2 | |
7507 | auth_advertise_hosts = !ALIST | |
7508 | .endd | |
168e428f | 7509 | it probably won't do what you want, because that is exactly the same as |
9b371988 PH |
7510 | .code |
7511 | auth_advertise_hosts = !host1 : host2 | |
7512 | .endd | |
168e428f PH |
7513 | Notice that the second host name is not negated. However, if you use a host |
7514 | list, and write | |
9b371988 PH |
7515 | .code |
7516 | hostlist alist = host1 : host2 | |
7517 | auth_advertise_hosts = ! +alist | |
7518 | .endd | |
168e428f | 7519 | the negation applies to the whole list, and so that is equivalent to |
9b371988 PH |
7520 | .code |
7521 | auth_advertise_hosts = !host1 : !host2 | |
7522 | .endd | |
168e428f PH |
7523 | |
7524 | ||
f89d2485 | 7525 | .section "Named list caching" "SECID79" |
9b371988 PH |
7526 | .cindex "list" "caching of named" |
7527 | .cindex "caching" "named lists" | |
168e428f PH |
7528 | While processing a message, Exim caches the result of checking a named list if |
7529 | it is sure that the list is the same each time. In practice, this means that | |
9b371988 | 7530 | the cache operates only if the list contains no $ characters, which guarantees |
168e428f PH |
7531 | that it will not change when it is expanded. Sometimes, however, you may have |
7532 | an expanded list that you know will be the same each time within a given | |
7533 | message. For example: | |
9b371988 | 7534 | .code |
168e428f PH |
7535 | domainlist special_domains = \ |
7536 | ${lookup{$sender_host_address}cdb{/some/file}} | |
9b371988 | 7537 | .endd |
168e428f PH |
7538 | This provides a list of domains that depends only on the sending host's IP |
7539 | address. If this domain list is referenced a number of times (for example, | |
7540 | in several ACL lines, or in several routers) the result of the check is not | |
7541 | cached by default, because Exim does not know that it is going to be the | |
7542 | same list each time. | |
7543 | ||
9b371988 | 7544 | By appending &`_cache`& to &`domainlist`& you can tell Exim to go ahead and |
168e428f | 7545 | cache the result anyway. For example: |
9b371988 PH |
7546 | .code |
7547 | domainlist_cache special_domains = ${lookup{... | |
7548 | .endd | |
168e428f PH |
7549 | If you do this, you should be absolutely sure that caching is going to do |
7550 | the right thing in all cases. When in doubt, leave it out. | |
7551 | ||
7552 | ||
7553 | ||
9b371988 PH |
7554 | .section "Domain lists" "SECTdomainlist" |
7555 | .cindex "domain list" "patterns for" | |
7556 | .cindex "list" "domain list" | |
168e428f PH |
7557 | Domain lists contain patterns that are to be matched against a mail domain. |
7558 | The following types of item may appear in domain lists: | |
7559 | ||
9b371988 PH |
7560 | .ilist |
7561 | .cindex "primary host name" | |
7562 | .cindex "host name" "matched in domain list" | |
0a4e3112 | 7563 | .oindex "&%primary_hostname%&" |
9b371988 PH |
7564 | .cindex "domain list" "matching primary host name" |
7565 | .cindex "@ in a domain list" | |
168e428f | 7566 | If a pattern consists of a single @ character, it matches the local host name, |
9b371988 PH |
7567 | as set by the &%primary_hostname%& option (or defaulted). This makes it |
7568 | possible to use the same configuration file on several different hosts that | |
7569 | differ only in their names. | |
7570 | .next | |
7571 | .cindex "@[] in a domain list" | |
7572 | .cindex "domain list" "matching local IP interfaces" | |
7573 | .cindex "domain literal" | |
595028e4 PH |
7574 | If a pattern consists of the string &`@[]`& it matches an IP address enclosed |
7575 | in square brackets (as in an email address that contains a domain literal), but | |
7576 | only if that IP address is recognized as local for email routing purposes. The | |
7577 | &%local_interfaces%& and &%extra_local_interfaces%& options can be used to | |
7578 | control which of a host's several IP addresses are treated as local. | |
168e428f | 7579 | In today's Internet, the use of domain literals is controversial. |
9b371988 PH |
7580 | .next |
7581 | .cindex "@mx_any" | |
7582 | .cindex "@mx_primary" | |
7583 | .cindex "@mx_secondary" | |
7584 | .cindex "domain list" "matching MX pointers to local host" | |
7585 | If a pattern consists of the string &`@mx_any`& it matches any domain that | |
168e428f | 7586 | has an MX record pointing to the local host or to any host that is listed in |
0a4e3112 | 7587 | .oindex "&%hosts_treat_as_local%&" |
9b371988 | 7588 | &%hosts_treat_as_local%&. The items &`@mx_primary`& and &`@mx_secondary`& |
168e428f PH |
7589 | are similar, except that the first matches only when a primary MX target is the |
7590 | local host, and the second only when no primary MX target is the local host, | |
9b371988 PH |
7591 | but a secondary MX target is. &"Primary"& means an MX record with the lowest |
7592 | preference value &-- there may of course be more than one of them. | |
7593 | ||
168e428f PH |
7594 | The MX lookup that takes place when matching a pattern of this type is |
7595 | performed with the resolver options for widening names turned off. Thus, for | |
9b371988 PH |
7596 | example, a single-component domain will &'not'& be expanded by adding the |
7597 | resolver's default domain. See the &%qualify_single%& and &%search_parents%& | |
7598 | options of the &(dnslookup)& router for a discussion of domain widening. | |
7599 | ||
168e428f | 7600 | Sometimes you may want to ignore certain IP addresses when using one of these |
9b371988 PH |
7601 | patterns. You can specify this by following the pattern with &`/ignore=`&<&'ip |
7602 | list'&>, where <&'ip list'&> is a list of IP addresses. These addresses are | |
7603 | ignored when processing the pattern (compare the &%ignore_target_hosts%& option | |
168e428f | 7604 | on a router). For example: |
9b371988 PH |
7605 | .code |
7606 | domains = @mx_any/ignore=127.0.0.1 | |
7607 | .endd | |
168e428f PH |
7608 | This example matches any domain that has an MX record pointing to one of |
7609 | the local host's IP addresses other than 127.0.0.1. | |
9b371988 | 7610 | |
168e428f PH |
7611 | The list of IP addresses is in fact processed by the same code that processes |
7612 | host lists, so it may contain CIDR-coded network specifications and it may also | |
7613 | contain negative items. | |
9b371988 | 7614 | |
168e428f PH |
7615 | Because the list of IP addresses is a sublist within a domain list, you have to |
7616 | be careful about delimiters if there is more than one address. Like any other | |
7617 | list, the default delimiter can be changed. Thus, you might have: | |
9b371988 | 7618 | .code |
168e428f PH |
7619 | domains = @mx_any/ignore=<;127.0.0.1;0.0.0.0 : \ |
7620 | an.other.domain : ... | |
9b371988 | 7621 | .endd |
168e428f PH |
7622 | so that the sublist uses semicolons for delimiters. When IPv6 addresses are |
7623 | involved, it is easiest to change the delimiter for the main list as well: | |
9b371988 | 7624 | .code |
168e428f PH |
7625 | domains = <? @mx_any/ignore=<;127.0.0.1;::1 ? \ |
7626 | an.other.domain ? ... | |
9b371988 PH |
7627 | .endd |
7628 | .next | |
7629 | .cindex "asterisk" "in domain list" | |
7630 | .cindex "domain list" "asterisk in" | |
7631 | .cindex "domain list" "matching &""ends with""&" | |
168e428f | 7632 | If a pattern starts with an asterisk, the remaining characters of the pattern |
9b371988 | 7633 | are compared with the terminating characters of the domain. The use of &"*"& in |
168e428f PH |
7634 | domain lists differs from its use in partial matching lookups. In a domain |
7635 | list, the character following the asterisk need not be a dot, whereas partial | |
7636 | matching works only in terms of dot-separated components. For example, a domain | |
9b371988 PH |
7637 | list item such as &`*key.ex`& matches &'donkey.ex'& as well as |
7638 | &'cipher.key.ex'&. | |
168e428f | 7639 | |
9b371988 PH |
7640 | .next |
7641 | .cindex "regular expressions" "in domain list" | |
7642 | .cindex "domain list" "matching regular expression" | |
168e428f PH |
7643 | If a pattern starts with a circumflex character, it is treated as a regular |
7644 | expression, and matched against the domain using a regular expression matching | |
7645 | function. The circumflex is treated as part of the regular expression. | |
595028e4 PH |
7646 | Email domains are case-independent, so this regular expression match is by |
7647 | default case-independent, but you can make it case-dependent by starting it | |
7648 | with &`(?-i)`&. References to descriptions of the syntax of regular expressions | |
7649 | are given in chapter &<<CHAPregexp>>&. | |
168e428f | 7650 | |
9b371988 PH |
7651 | &*Warning*&: Because domain lists are expanded before being processed, you |
7652 | must escape any backslash and dollar characters in the regular expression, or | |
7653 | use the special &`\N`& sequence (see chapter &<<CHAPexpand>>&) to specify that | |
7654 | it is not to be expanded (unless you really do want to build a regular | |
7655 | expression by expansion, of course). | |
7656 | .next | |
7657 | .cindex "lookup" "in domain list" | |
7658 | .cindex "domain list" "matching by lookup" | |
168e428f | 7659 | If a pattern starts with the name of a single-key lookup type followed by a |
9b371988 | 7660 | semicolon (for example, &"dbm;"& or &"lsearch;"&), the remainder of the pattern |
168e428f | 7661 | must be a file name in a suitable format for the lookup type. For example, for |
9b371988 PH |
7662 | &"cdb;"& it must be an absolute path: |
7663 | .code | |
7664 | domains = cdb;/etc/mail/local_domains.cdb | |
7665 | .endd | |
168e428f PH |
7666 | The appropriate type of lookup is done on the file using the domain name as the |
7667 | key. In most cases, the data that is looked up is not used; Exim is interested | |
7668 | only in whether or not the key is present in the file. However, when a lookup | |
9b371988 PH |
7669 | is used for the &%domains%& option on a router |
7670 | or a &%domains%& condition in an ACL statement, the data is preserved in the | |
7671 | &$domain_data$& variable and can be referred to in other router options or | |
168e428f PH |
7672 | other statements in the same ACL. |
7673 | ||
9b371988 PH |
7674 | .next |
7675 | Any of the single-key lookup type names may be preceded by | |
7676 | &`partial`&<&'n'&>&`-`&, where the <&'n'&> is optional, for example, | |
7677 | .code | |
7678 | domains = partial-dbm;/partial/domains | |
7679 | .endd | |
168e428f | 7680 | This causes partial matching logic to be invoked; a description of how this |
9b371988 | 7681 | works is given in section &<<SECTpartiallookup>>&. |
168e428f | 7682 | |
9b371988 PH |
7683 | .next |
7684 | .cindex "asterisk" "in lookup type" | |
168e428f PH |
7685 | Any of the single-key lookup types may be followed by an asterisk. This causes |
7686 | a default lookup for a key consisting of a single asterisk to be done if the | |
7687 | original lookup fails. This is not a useful feature when using a domain list to | |
7688 | select particular domains (because any domain would match), but it might have | |
9b371988 | 7689 | value if the result of the lookup is being used via the &$domain_data$& |
168e428f | 7690 | expansion variable. |
9b371988 PH |
7691 | .next |
7692 | If the pattern starts with the name of a query-style lookup type followed by a | |
7693 | semicolon (for example, &"nisplus;"& or &"ldap;"&), the remainder of the | |
7694 | pattern must be an appropriate query for the lookup type, as described in | |
7695 | chapter &<<CHAPfdlookup>>&. For example: | |
7696 | .code | |
168e428f PH |
7697 | hold_domains = mysql;select domain from holdlist \ |
7698 | where domain = '$domain'; | |
9b371988 | 7699 | .endd |
168e428f PH |
7700 | In most cases, the data that is looked up is not used (so for an SQL query, for |
7701 | example, it doesn't matter what field you select). Exim is interested only in | |
7702 | whether or not the query succeeds. However, when a lookup is used for the | |
9b371988 | 7703 | &%domains%& option on a router, the data is preserved in the &$domain_data$& |
168e428f | 7704 | variable and can be referred to in other options. |
9b371988 PH |
7705 | .next |
7706 | .cindex "domain list" "matching literal domain name" | |
168e428f PH |
7707 | If none of the above cases apply, a caseless textual comparison is made |
7708 | between the pattern and the domain. | |
9b371988 | 7709 | .endlist |
168e428f PH |
7710 | |
7711 | Here is an example that uses several different kinds of pattern: | |
9b371988 | 7712 | .code |
168e428f PH |
7713 | domainlist funny_domains = \ |
7714 | @ : \ | |
7715 | lib.unseen.edu : \ | |
7716 | *.foundation.fict.example : \ | |
7717 | \N^[1-2]\d{3}\.fict\.example$\N : \ | |
7718 | partial-dbm;/opt/data/penguin/book : \ | |
7719 | nis;domains.byname : \ | |
7720 | nisplus;[name=$domain,status=local],domains.org_dir | |
9b371988 | 7721 | .endd |
168e428f PH |
7722 | There are obvious processing trade-offs among the various matching modes. Using |
7723 | an asterisk is faster than a regular expression, and listing a few names | |
7724 | explicitly probably is too. The use of a file or database lookup is expensive, | |
7725 | but may be the only option if hundreds of names are required. Because the | |
7726 | patterns are tested in order, it makes sense to put the most commonly matched | |
7727 | patterns earlier. | |
7728 | ||
7729 | ||
7730 | ||
9b371988 PH |
7731 | .section "Host lists" "SECThostlist" |
7732 | .cindex "host list" "patterns in" | |
7733 | .cindex "list" "host list" | |
168e428f PH |
7734 | Host lists are used to control what remote hosts are allowed to do. For |
7735 | example, some hosts may be allowed to use the local host as a relay, and some | |
7736 | may be permitted to use the SMTP ETRN command. Hosts can be identified in | |
7737 | two different ways, by name or by IP address. In a host list, some types of | |
7738 | pattern are matched to a host name, and some are matched to an IP address. | |
7739 | You need to be particularly careful with this when single-key lookups are | |
7740 | involved, to ensure that the right value is being used as the key. | |
7741 | ||
7742 | ||
f89d2485 | 7743 | .section "Special host list patterns" "SECID80" |
9b371988 PH |
7744 | .cindex "empty item in hosts list" |
7745 | .cindex "host list" "empty string in" | |
168e428f PH |
7746 | If a host list item is the empty string, it matches only when no remote host is |
7747 | involved. This is the case when a message is being received from a local | |
7748 | process using SMTP on the standard input, that is, when a TCP/IP connection is | |
7749 | not used. | |
7750 | ||
9b371988 PH |
7751 | .cindex "asterisk" "in host list" |
7752 | The special pattern &"*"& in a host list matches any host or no host. Neither | |
168e428f PH |
7753 | the IP address nor the name is actually inspected. |
7754 | ||
7755 | ||
7756 | ||
9b371988 PH |
7757 | .section "Host list patterns that match by IP address" "SECThoslispatip" |
7758 | .cindex "host list" "matching IP addresses" | |
168e428f PH |
7759 | If an IPv4 host calls an IPv6 host and the call is accepted on an IPv6 socket, |
7760 | the incoming address actually appears in the IPv6 host as | |
9b371988 | 7761 | &`::ffff:`&<&'v4address'&>. When such an address is tested against a host |
168e428f PH |
7762 | list, it is converted into a traditional IPv4 address first. (Not all operating |
7763 | systems accept IPv4 calls on IPv6 sockets, as there have been some security | |
7764 | concerns.) | |
7765 | ||
7766 | The following types of pattern in a host list check the remote host by | |
7767 | inspecting its IP address: | |
7768 | ||
9b371988 PH |
7769 | .ilist |
7770 | If the pattern is a plain domain name (not a regular expression, not starting | |
7771 | with *, not a lookup of any kind), Exim calls the operating system function | |
168e428f | 7772 | to find the associated IP address(es). Exim uses the newer |
9b371988 | 7773 | &[getipnodebyname()]& function when available, otherwise &[gethostbyname()]&. |
168e428f PH |
7774 | This typically causes a forward DNS lookup of the name. The result is compared |
7775 | with the IP address of the subject host. | |
9b371988 | 7776 | |
168e428f PH |
7777 | If there is a temporary problem (such as a DNS timeout) with the host name |
7778 | lookup, a temporary error occurs. For example, if the list is being used in an | |
9b371988 PH |
7779 | ACL condition, the ACL gives a &"defer"& response, usually leading to a |
7780 | temporary SMTP error code. If no IP address can be found for the host name, | |
7781 | what happens is described in section &<<SECTbehipnot>>& below. | |
168e428f | 7782 | |
9b371988 PH |
7783 | .next |
7784 | .cindex "@ in a host list" | |
7785 | If the pattern is &"@"&, the primary host name is substituted and used as a | |
168e428f PH |
7786 | domain name, as just described. |
7787 | ||
9b371988 PH |
7788 | .next |
7789 | If the pattern is an IP address, it is matched against the IP address of the | |
7790 | subject host. IPv4 addresses are given in the normal &"dotted-quad"& notation. | |
168e428f PH |
7791 | IPv6 addresses can be given in colon-separated format, but the colons have to |
7792 | be doubled so as not to be taken as item separators when the default list | |
7793 | separator is used. IPv6 addresses are recognized even when Exim is compiled | |
7794 | without IPv6 support. This means that if they appear in a host list on an | |
7795 | IPv4-only host, Exim will not treat them as host names. They are just addresses | |
7796 | that can never match a client host. | |
7797 | ||
9b371988 PH |
7798 | .next |
7799 | .cindex "@[] in a host list" | |
7800 | If the pattern is &"@[]"&, it matches the IP address of any IP interface on | |
168e428f PH |
7801 | the local host. For example, if the local host is an IPv4 host with one |
7802 | interface address 10.45.23.56, these two ACL statements have the same effect: | |
9b371988 PH |
7803 | .code |
7804 | accept hosts = 127.0.0.1 : 10.45.23.56 | |
7805 | accept hosts = @[] | |
7806 | .endd | |
7807 | .next | |
7808 | .cindex "CIDR notation" | |
168e428f PH |
7809 | If the pattern is an IP address followed by a slash and a mask length (for |
7810 | example 10.11.42.0/24), it is matched against the IP address of the subject | |
7811 | host under the given mask. This allows, an entire network of hosts to be | |
7812 | included (or excluded) by a single item. The mask uses CIDR notation; it | |
7813 | specifies the number of address bits that must match, starting from the most | |
7814 | significant end of the address. | |
9b371988 PH |
7815 | |
7816 | &*Note*&: The mask is &'not'& a count of addresses, nor is it the high number | |
168e428f PH |
7817 | of a range of addresses. It is the number of bits in the network portion of the |
7818 | address. The above example specifies a 24-bit netmask, so it matches all 256 | |
7819 | addresses in the 10.11.42.0 network. An item such as | |
9b371988 PH |
7820 | .code |
7821 | 192.168.23.236/31 | |
7822 | .endd | |
168e428f PH |
7823 | matches just two addresses, 192.168.23.236 and 192.168.23.237. A mask value of |
7824 | 32 for an IPv4 address is the same as no mask at all; just a single address | |
7825 | matches. | |
9b371988 | 7826 | |
168e428f | 7827 | Here is another example which shows an IPv4 and an IPv6 network: |
9b371988 | 7828 | .code |
168e428f PH |
7829 | recipient_unqualified_hosts = 192.168.0.0/16: \ |
7830 | 3ffe::ffff::836f::::/48 | |
9b371988 | 7831 | .endd |
168e428f PH |
7832 | The doubling of list separator characters applies only when these items |
7833 | appear inline in a host list. It is not required when indirecting via a file. | |
9b371988 PH |
7834 | For example: |
7835 | .code | |
7836 | recipient_unqualified_hosts = /opt/exim/unqualnets | |
7837 | .endd | |
168e428f | 7838 | could make use of a file containing |
9b371988 PH |
7839 | .code |
7840 | 172.16.0.0/12 | |
7841 | 3ffe:ffff:836f::/48 | |
7842 | .endd | |
168e428f PH |
7843 | to have exactly the same effect as the previous example. When listing IPv6 |
7844 | addresses inline, it is usually more convenient to use the facility for | |
7845 | changing separator characters. This list contains the same two networks: | |
9b371988 | 7846 | .code |
168e428f PH |
7847 | recipient_unqualified_hosts = <; 172.16.0.0/12; \ |
7848 | 3ffe:ffff:836f::/48 | |
9b371988 PH |
7849 | .endd |
7850 | The separator is changed to semicolon by the leading &"<;"& at the start of the | |
168e428f | 7851 | list. |
9b371988 | 7852 | .endlist |
168e428f PH |
7853 | |
7854 | ||
7855 | ||
9b371988 PH |
7856 | .section "Host list patterns for single-key lookups by host address" &&& |
7857 | "SECThoslispatsikey" | |
7858 | .cindex "host list" "lookup of IP address" | |
168e428f PH |
7859 | When a host is to be identified by a single-key lookup of its complete IP |
7860 | address, the pattern takes this form: | |
9b371988 PH |
7861 | .display |
7862 | &`net-<`&&'single-key-search-type'&&`>;<`&&'search-data'&&`>`& | |
7863 | .endd | |
168e428f | 7864 | For example: |
9b371988 PH |
7865 | .code |
7866 | hosts_lookup = net-cdb;/hosts-by-ip.db | |
7867 | .endd | |
168e428f PH |
7868 | The text form of the IP address of the subject host is used as the lookup key. |
7869 | IPv6 addresses are converted to an unabbreviated form, using lower case | |
7870 | letters, with dots as separators because colon is the key terminator in | |
9b371988 | 7871 | &(lsearch)& files. [Colons can in fact be used in keys in &(lsearch)& files by |
168e428f PH |
7872 | quoting the keys, but this is a facility that was added later.] The data |
7873 | returned by the lookup is not used. | |
7874 | ||
9b371988 PH |
7875 | .cindex "IP address" "masking" |
7876 | .cindex "host list" "masked IP address" | |
168e428f PH |
7877 | Single-key lookups can also be performed using masked IP addresses, using |
7878 | patterns of this form: | |
9b371988 PH |
7879 | .display |
7880 | &`net<`&&'number'&&`>-<`&&'single-key-search-type'&&`>;<`&&'search-data'&&`>`& | |
7881 | .endd | |
168e428f | 7882 | For example: |
9b371988 PH |
7883 | .code |
7884 | net24-dbm;/networks.db | |
7885 | .endd | |
7886 | The IP address of the subject host is masked using <&'number'&> as the mask | |
168e428f PH |
7887 | length. A textual string is constructed from the masked value, followed by the |
7888 | mask, and this is used as the lookup key. For example, if the host's IP address | |
7889 | is 192.168.34.6, the key that is looked up for the above example is | |
595028e4 PH |
7890 | &"192.168.34.0/24"&. |
7891 | ||
595028e4 PH |
7892 | When an IPv6 address is converted to a string, dots are normally used instead |
7893 | of colons, so that keys in &(lsearch)& files need not contain colons (which | |
7894 | terminate &(lsearch)& keys). This was implemented some time before the ability | |
7895 | to quote keys was made available in &(lsearch)& files. However, the more | |
7896 | recently implemented &(iplsearch)& files do require colons in IPv6 keys | |
7897 | (notated using the quoting facility) so as to distinguish them from IPv4 keys. | |
7898 | For this reason, when the lookup type is &(iplsearch)&, IPv6 addresses are | |
7899 | converted using colons and not dots. In all cases, full, unabbreviated IPv6 | |
168e428f PH |
7900 | addresses are always used. |
7901 | ||
595028e4 PH |
7902 | Ideally, it would be nice to tidy up this anomalous situation by changing to |
7903 | colons in all cases, given that quoting is now available for &(lsearch)&. | |
7904 | However, this would be an incompatible change that might break some existing | |
7905 | configurations. | |
595028e4 | 7906 | |
f89d2485 PH |
7907 | &*Warning*&: Specifying &%net32-%& (for an IPv4 address) or &%net128-%& (for an |
7908 | IPv6 address) is not the same as specifying just &%net-%& without a number. In | |
168e428f PH |
7909 | the former case the key strings include the mask value, whereas in the latter |
7910 | case the IP address is used on its own. | |
7911 | ||
7912 | ||
7913 | ||
9b371988 PH |
7914 | .section "Host list patterns that match by host name" "SECThoslispatnam" |
7915 | .cindex "host" "lookup failures" | |
7916 | .cindex "unknown host name" | |
7917 | .cindex "host list" "matching host name" | |
168e428f PH |
7918 | There are several types of pattern that require Exim to know the name of the |
7919 | remote host. These are either wildcard patterns or lookups by name. (If a | |
7920 | complete hostname is given without any wildcarding, it is used to find an IP | |
9b371988 PH |
7921 | address to match against, as described in the section &<<SECThoslispatip>>& |
7922 | above.) | |
168e428f PH |
7923 | |
7924 | If the remote host name is not already known when Exim encounters one of these | |
7925 | patterns, it has to be found from the IP address. | |
7926 | Although many sites on the Internet are conscientious about maintaining reverse | |
7927 | DNS data for their hosts, there are also many that do not do this. | |
7928 | Consequently, a name cannot always be found, and this may lead to unwanted | |
7929 | effects. Take care when configuring host lists with wildcarded name patterns. | |
7930 | Consider what will happen if a name cannot be found. | |
7931 | ||
7932 | Because of the problems of determining host names from IP addresses, matching | |
7933 | against host names is not as common as matching against IP addresses. | |
7934 | ||
7935 | By default, in order to find a host name, Exim first does a reverse DNS lookup; | |
9b371988 PH |
7936 | if no name is found in the DNS, the system function (&[gethostbyaddr()]& or |
7937 | &[getipnodebyaddr()]& if available) is tried. The order in which these lookups | |
ad268134 PH |
7938 | are done can be changed by setting the &%host_lookup_order%& option. For |
7939 | security, once Exim has found one or more names, it looks up the IP addresses | |
7940 | for these names and compares them with the IP address that it started with. | |
7941 | Only those names whose IP addresses match are accepted. Any other names are | |
7942 | discarded. If no names are left, Exim behaves as if the host name cannot be | |
7943 | found. In the most common case there is only one name and one IP address. | |
168e428f PH |
7944 | |
7945 | There are some options that control what happens if a host name cannot be | |
9b371988 | 7946 | found. These are described in section &<<SECTbehipnot>>& below. |
168e428f | 7947 | |
9b371988 PH |
7948 | .cindex "host" "alias for" |
7949 | .cindex "alias for host" | |
168e428f PH |
7950 | As a result of aliasing, hosts may have more than one name. When processing any |
7951 | of the following types of pattern, all the host's names are checked: | |
7952 | ||
9b371988 PH |
7953 | .ilist |
7954 | .cindex "asterisk" "in host list" | |
7955 | If a pattern starts with &"*"& the remainder of the item must match the end of | |
7956 | the host name. For example, &`*.b.c`& matches all hosts whose names end in | |
7957 | &'.b.c'&. This special simple form is provided because this is a very common | |
168e428f PH |
7958 | requirement. Other kinds of wildcarding require the use of a regular |
7959 | expression. | |
9b371988 PH |
7960 | .next |
7961 | .cindex "regular expressions" "in host list" | |
7962 | .cindex "host list" "regular expression in" | |
7963 | If the item starts with &"^"& it is taken to be a regular expression which is | |
595028e4 PH |
7964 | matched against the host name. Host names are case-independent, so this regular |
7965 | expression match is by default case-independent, but you can make it | |
7966 | case-dependent by starting it with &`(?-i)`&. References to descriptions of the | |
7967 | syntax of regular expressions are given in chapter &<<CHAPregexp>>&. For | |
7968 | example, | |
9b371988 PH |
7969 | .code |
7970 | ^(a|b)\.c\.d$ | |
7971 | .endd | |
7972 | is a regular expression that matches either of the two hosts &'a.c.d'& or | |
7973 | &'b.c.d'&. When a regular expression is used in a host list, you must take care | |
168e428f | 7974 | that backslash and dollar characters are not misinterpreted as part of the |
9b371988 | 7975 | string expansion. The simplest way to do this is to use &`\N`& to mark that |
168e428f | 7976 | part of the string as non-expandable. For example: |
9b371988 PH |
7977 | .code |
7978 | sender_unqualified_hosts = \N^(a|b)\.c\.d$\N : .... | |
7979 | .endd | |
7980 | &*Warning*&: If you want to match a complete host name, you must include the | |
7981 | &`$`& terminating metacharacter in the regular expression, as in the above | |
168e428f PH |
7982 | example. Without it, a match at the start of the host name is all that is |
7983 | required. | |
9b371988 | 7984 | .endlist |
168e428f PH |
7985 | |
7986 | ||
7987 | ||
7988 | ||
9b371988 | 7989 | .section "Behaviour when an IP address or name cannot be found" "SECTbehipnot" |
595028e4 | 7990 | .cindex "host" "lookup failures, permanent" |
168e428f | 7991 | While processing a host list, Exim may need to look up an IP address from a |
9b371988 PH |
7992 | name (see section &<<SECThoslispatip>>&), or it may need to look up a host name |
7993 | from an IP address (see section &<<SECThoslispatnam>>&). In either case, the | |
168e428f PH |
7994 | behaviour when it fails to find the information it is seeking is the same. |
7995 | ||
595028e4 PH |
7996 | &*Note*&: This section applies to permanent lookup failures. It does &'not'& |
7997 | apply to temporary DNS errors, whose handling is described in the next section. | |
595028e4 | 7998 | |
9b371988 PH |
7999 | .cindex "&`+include_unknown`&" |
8000 | .cindex "&`+ignore_unknown`&" | |
168e428f PH |
8001 | By default, Exim behaves as if the host does not match the list. This may not |
8002 | always be what you want to happen. To change Exim's behaviour, the special | |
9b371988 PH |
8003 | items &`+include_unknown`& or &`+ignore_unknown`& may appear in the list (at |
8004 | top level &-- they are not recognized in an indirected file). | |
168e428f | 8005 | |
9b371988 PH |
8006 | .ilist |
8007 | If any item that follows &`+include_unknown`& requires information that | |
168e428f | 8008 | cannot found, Exim behaves as if the host does match the list. For example, |
9b371988 PH |
8009 | .code |
8010 | host_reject_connection = +include_unknown:*.enemy.ex | |
8011 | .endd | |
8012 | rejects connections from any host whose name matches &`*.enemy.ex`&, and also | |
168e428f PH |
8013 | any hosts whose name it cannot find. |
8014 | ||
9b371988 PH |
8015 | .next |
8016 | If any item that follows &`+ignore_unknown`& requires information that cannot | |
168e428f PH |
8017 | be found, Exim ignores that item and proceeds to the rest of the list. For |
8018 | example: | |
9b371988 | 8019 | .code |
168e428f PH |
8020 | accept hosts = +ignore_unknown : friend.example : \ |
8021 | 192.168.4.5 | |
9b371988 PH |
8022 | .endd |
8023 | accepts from any host whose name is &'friend.example'& and from 192.168.4.5, | |
8024 | whether or not its host name can be found. Without &`+ignore_unknown`&, if no | |
168e428f | 8025 | name can be found for 192.168.4.5, it is rejected. |
9b371988 | 8026 | .endlist |
168e428f | 8027 | |
9b371988 | 8028 | Both &`+include_unknown`& and &`+ignore_unknown`& may appear in the same |
168e428f PH |
8029 | list. The effect of each one lasts until the next, or until the end of the |
8030 | list. | |
8031 | ||
595028e4 | 8032 | |
595028e4 PH |
8033 | .section "Temporary DNS errors when looking up host information" &&& |
8034 | "SECTtemdnserr" | |
8035 | .cindex "host" "lookup failures, temporary" | |
8036 | .cindex "&`+include_defer`&" | |
8037 | .cindex "&`+ignore_defer`&" | |
8038 | A temporary DNS lookup failure normally causes a defer action (except when | |
8039 | &%dns_again_means_nonexist%& converts it into a permanent error). However, | |
8040 | host lists can include &`+ignore_defer`& and &`+include_defer`&, analagous to | |
8041 | &`+ignore_unknown`& and &`+include_unknown`&, as described in the previous | |
8042 | section. These options should be used with care, probably only in non-critical | |
8043 | host lists such as whitelists. | |
168e428f PH |
8044 | |
8045 | ||
8046 | ||
9b371988 PH |
8047 | .section "Host list patterns for single-key lookups by host name" &&& |
8048 | "SECThoslispatnamsk" | |
9b371988 PH |
8049 | .cindex "unknown host name" |
8050 | .cindex "host list" "matching host name" | |
168e428f | 8051 | If a pattern is of the form |
9b371988 PH |
8052 | .display |
8053 | <&'single-key-search-type'&>;<&'search-data'&> | |
8054 | .endd | |
168e428f | 8055 | for example |
9b371988 PH |
8056 | .code |
8057 | dbm;/host/accept/list | |
8058 | .endd | |
f89d2485 | 8059 | a single-key lookup is performed, using the host name as its key. If the |
168e428f PH |
8060 | lookup succeeds, the host matches the item. The actual data that is looked up |
8061 | is not used. | |
8062 | ||
9b371988 | 8063 | &*Reminder*&: With this kind of pattern, you must have host &'names'& as |
168e428f | 8064 | keys in the file, not IP addresses. If you want to do lookups based on IP |
9b371988 PH |
8065 | addresses, you must precede the search type with &"net-"& (see section |
8066 | &<<SECThoslispatsikey>>&). There is, however, no reason why you could not use | |
8067 | two items in the same list, one doing an address lookup and one doing a name | |
168e428f PH |
8068 | lookup, both using the same file. |
8069 | ||
8070 | ||
8071 | ||
f89d2485 | 8072 | .section "Host list patterns for query-style lookups" "SECID81" |
168e428f | 8073 | If a pattern is of the form |
9b371988 PH |
8074 | .display |
8075 | <&'query-style-search-type'&>;<&'query'&> | |
8076 | .endd | |
168e428f | 8077 | the query is obeyed, and if it succeeds, the host matches the item. The actual |
9b371988 PH |
8078 | data that is looked up is not used. The variables &$sender_host_address$& and |
8079 | &$sender_host_name$& can be used in the query. For example: | |
8080 | .code | |
168e428f PH |
8081 | hosts_lookup = pgsql;\ |
8082 | select ip from hostlist where ip='$sender_host_address' | |
9b371988 PH |
8083 | .endd |
8084 | The value of &$sender_host_address$& for an IPv6 address contains colons. You | |
8085 | can use the &%sg%& expansion item to change this if you need to. If you want to | |
8086 | use masked IP addresses in database queries, you can use the &%mask%& expansion | |
168e428f PH |
8087 | operator. |
8088 | ||
9b371988 | 8089 | If the query contains a reference to &$sender_host_name$&, Exim automatically |
168e428f | 8090 | looks up the host name if has not already done so. (See section |
9b371988 | 8091 | &<<SECThoslispatnam>>& for comments on finding host names.) |
168e428f PH |
8092 | |
8093 | Historical note: prior to release 4.30, Exim would always attempt to find a | |
8094 | host name before running the query, unless the search type was preceded by | |
9b371988 | 8095 | &`net-`&. This is no longer the case. For backwards compatibility, &`net-`& is |
168e428f | 8096 | still recognized for query-style lookups, but its presence or absence has no |
9b371988 PH |
8097 | effect. (Of course, for single-key lookups, &`net-`& &'is'& important. |
8098 | See section &<<SECThoslispatsikey>>&.) | |
168e428f PH |
8099 | |
8100 | ||
8101 | ||
9b371988 PH |
8102 | .section "Mixing wildcarded host names and addresses in host lists" &&& |
8103 | "SECTmixwilhos" | |
8104 | .cindex "host list" "mixing names and addresses in" | |
168e428f PH |
8105 | If you have name lookups or wildcarded host names and IP addresses in the same |
8106 | host list, you should normally put the IP addresses first. For example, in an | |
8107 | ACL you could have: | |
9b371988 PH |
8108 | .code |
8109 | accept hosts = 10.9.8.7 : *.friend.example | |
8110 | .endd | |
168e428f PH |
8111 | The reason for this lies in the left-to-right way that Exim processes lists. |
8112 | It can test IP addresses without doing any DNS lookups, but when it reaches an | |
8113 | item that requires a host name, it fails if it cannot find a host name to | |
8114 | compare with the pattern. If the above list is given in the opposite order, the | |
9b371988 | 8115 | &%accept%& statement fails for a host whose name cannot be found, even if its |
168e428f PH |
8116 | IP address is 10.9.8.7. |
8117 | ||
8118 | If you really do want to do the name check first, and still recognize the IP | |
8119 | address, you can rewrite the ACL like this: | |
9b371988 PH |
8120 | .code |
8121 | accept hosts = *.friend.example | |
8122 | accept hosts = 10.9.8.7 | |
8123 | .endd | |
8124 | If the first &%accept%& fails, Exim goes on to try the second one. See chapter | |
8125 | &<<CHAPACL>>& for details of ACLs. | |
168e428f PH |
8126 | |
8127 | ||
8128 | ||
8129 | ||
8130 | ||
9b371988 PH |
8131 | .section "Address lists" "SECTaddresslist" |
8132 | .cindex "list" "address list" | |
8133 | .cindex "address list" "empty item" | |
8134 | .cindex "address list" "patterns" | |
168e428f PH |
8135 | Address lists contain patterns that are matched against mail addresses. There |
8136 | is one special case to be considered: the sender address of a bounce message is | |
8137 | always empty. You can test for this by providing an empty item in an address | |
8138 | list. For example, you can set up a router to process bounce messages by | |
8139 | using this option setting: | |
9b371988 PH |
8140 | .code |
8141 | senders = : | |
8142 | .endd | |
168e428f PH |
8143 | The presence of the colon creates an empty item. If you do not provide any |
8144 | data, the list is empty and matches nothing. The empty sender can also be | |
8145 | detected by a regular expression that matches an empty string, | |
9b371988 | 8146 | and by a query-style lookup that succeeds when &$sender_address$& is empty. |
168e428f | 8147 | |
4f578862 PH |
8148 | Non-empty items in an address list can be straightforward email addresses. For |
8149 | example: | |
8150 | .code | |
8151 | senders = jbc@askone.example : hs@anacreon.example | |
8152 | .endd | |
8153 | A certain amount of wildcarding is permitted. If a pattern contains an @ | |
8154 | character, but is not a regular expression and does not begin with a | |
8155 | semicolon-terminated lookup type (described below), the local part of the | |
8156 | subject address is compared with the local part of the pattern, which may start | |
8157 | with an asterisk. If the local parts match, the domain is checked in exactly | |
8158 | the same way as for a pattern in a domain list. For example, the domain can be | |
8159 | wildcarded, refer to a named list, or be a lookup: | |
8160 | .code | |
8161 | deny senders = *@*.spamming.site:\ | |
8162 | *@+hostile_domains:\ | |
8163 | bozo@partial-lsearch;/list/of/dodgy/sites:\ | |
8164 | *@dbm;/bad/domains.db | |
8165 | .endd | |
8166 | .cindex "local part" "starting with !" | |
8167 | .cindex "address list" "local part starting with !" | |
8168 | If a local part that begins with an exclamation mark is required, it has to be | |
8169 | specified using a regular expression, because otherwise the exclamation mark is | |
8170 | treated as a sign of negation, as is standard in lists. | |
8171 | ||
8172 | If a non-empty pattern that is not a regular expression or a lookup does not | |
8173 | contain an @ character, it is matched against the domain part of the subject | |
8174 | address. The only two formats that are recognized this way are a literal | |
8175 | domain, or a domain pattern that starts with *. In both these cases, the effect | |
8176 | is the same as if &`*@`& preceded the pattern. For example: | |
8177 | .code | |
8178 | deny senders = enemy.domain : *.enemy.domain | |
8179 | .endd | |
168e428f | 8180 | |
4f578862 PH |
8181 | The following kinds of more complicated address list pattern can match any |
8182 | address, including the empty address that is characteristic of bounce message | |
8183 | senders: | |
168e428f | 8184 | |
4f578862 | 8185 | .ilist |
9b371988 PH |
8186 | .cindex "regular expressions" "in address list" |
8187 | .cindex "address list" "regular expression in" | |
8188 | If (after expansion) a pattern starts with &"^"&, a regular expression match is | |
168e428f PH |
8189 | done against the complete address, with the pattern as the regular expression. |
8190 | You must take care that backslash and dollar characters are not misinterpreted | |
9b371988 | 8191 | as part of the string expansion. The simplest way to do this is to use &`\N`& |
168e428f | 8192 | to mark that part of the string as non-expandable. For example: |
9b371988 | 8193 | .code |
4f578862 PH |
8194 | deny senders = \N^.*this.*@example\.com$\N : \ |
8195 | \N^\d{8}.+@spamhaus.example$\N : ... | |
9b371988 | 8196 | .endd |
4f578862 PH |
8197 | The &`\N`& sequences are removed by the expansion, so these items do indeed |
8198 | start with &"^"& by the time they are being interpreted as address patterns. | |
9b371988 PH |
8199 | |
8200 | .next | |
8201 | .cindex "address list" "lookup for complete address" | |
168e428f PH |
8202 | Complete addresses can be looked up by using a pattern that starts with a |
8203 | lookup type terminated by a semicolon, followed by the data for the lookup. For | |
8204 | example: | |
9b371988 | 8205 | .code |
168e428f PH |
8206 | deny senders = cdb;/etc/blocked.senders : \ |
8207 | mysql;select address from blocked where \ | |
8208 | address='${quote_mysql:$sender_address}' | |
9b371988 | 8209 | .endd |
168e428f PH |
8210 | Both query-style and single-key lookup types can be used. For a single-key |
8211 | lookup type, Exim uses the complete address as the key. However, empty keys are | |
8212 | not supported for single-key lookups, so a match against the empty address | |
8213 | always fails. This restriction does not apply to query-style lookups. | |
9b371988 PH |
8214 | |
8215 | Partial matching for single-key lookups (section &<<SECTpartiallookup>>&) | |
8216 | cannot be used, and is ignored if specified, with an entry being written to the | |
8217 | panic log. | |
8218 | .cindex "*@ with single-key lookup" | |
168e428f | 8219 | However, you can configure lookup defaults, as described in section |
9b371988 | 8220 | &<<SECTdefaultvaluelookups>>&, but this is useful only for the &"*@"& type of |
168e428f | 8221 | default. For example, with this lookup: |
9b371988 PH |
8222 | .code |
8223 | accept senders = lsearch*@;/some/file | |
8224 | .endd | |
168e428f | 8225 | the file could contains lines like this: |
9b371988 PH |
8226 | .code |
8227 | user1@domain1.example | |
8228 | *@domain2.example | |
8229 | .endd | |
8230 | and for the sender address &'nimrod@jaeger.example'&, the sequence of keys | |
168e428f | 8231 | that are tried is: |
9b371988 PH |
8232 | .code |
8233 | nimrod@jaeger.example | |
8234 | *@jaeger.example | |
8235 | * | |
8236 | .endd | |
8237 | &*Warning 1*&: Do not include a line keyed by &"*"& in the file, because that | |
168e428f | 8238 | would mean that every address matches, thus rendering the test useless. |
168e428f | 8239 | |
9b371988 PH |
8240 | &*Warning 2*&: Do not confuse these two kinds of item: |
8241 | .code | |
8242 | deny recipients = dbm*@;/some/file | |
8243 | deny recipients = *@dbm;/some/file | |
8244 | .endd | |
168e428f PH |
8245 | The first does a whole address lookup, with defaulting, as just described, |
8246 | because it starts with a lookup type. The second matches the local part and | |
8247 | domain independently, as described in a bullet point below. | |
9b371988 | 8248 | .endlist |
168e428f PH |
8249 | |
8250 | ||
8251 | The following kinds of address list pattern can match only non-empty addresses. | |
8252 | If the subject address is empty, a match against any of these pattern types | |
8253 | always fails. | |
8254 | ||
8255 | ||
9b371988 PH |
8256 | .ilist |
8257 | .cindex "@@ with single-key lookup" | |
8258 | .cindex "address list" "@@ lookup type" | |
8259 | .cindex "address list" "split local part and domain" | |
8260 | If a pattern starts with &"@@"& followed by a single-key lookup item | |
8261 | (for example, &`@@lsearch;/some/file`&), the address that is being checked is | |
168e428f PH |
8262 | split into a local part and a domain. The domain is looked up in the file. If |
8263 | it is not found, there is no match. If it is found, the data that is looked up | |
8264 | from the file is treated as a colon-separated list of local part patterns, each | |
8265 | of which is matched against the subject local part in turn. | |
168e428f | 8266 | |
9b371988 PH |
8267 | .cindex "asterisk" "in address list" |
8268 | The lookup may be a partial one, and/or one involving a search for a default | |
8269 | keyed by &"*"& (see section &<<SECTdefaultvaluelookups>>&). The local part | |
8270 | patterns that are looked up can be regular expressions or begin with &"*"&, or | |
8271 | even be further lookups. They may also be independently negated. For example, | |
8272 | with | |
8273 | .code | |
8274 | deny senders = @@dbm;/etc/reject-by-domain | |
8275 | .endd | |
168e428f | 8276 | the data from which the DBM file is built could contain lines like |
9b371988 PH |
8277 | .code |
8278 | baddomain.com: !postmaster : * | |
8279 | .endd | |
8280 | to reject all senders except &%postmaster%& from that domain. | |
168e428f | 8281 | |
9b371988 | 8282 | .cindex "local part" "starting with !" |
168e428f | 8283 | If a local part that actually begins with an exclamation mark is required, it |
9b371988 | 8284 | has to be specified using a regular expression. In &(lsearch)& files, an entry |
168e428f PH |
8285 | may be split over several lines by indenting the second and subsequent lines, |
8286 | but the separating colon must still be included at line breaks. White space | |
8287 | surrounding the colons is ignored. For example: | |
9b371988 PH |
8288 | .code |
8289 | aol.com: spammer1 : spammer2 : ^[0-9]+$ : | |
8290 | spammer3 : spammer4 | |
8291 | .endd | |
168e428f PH |
8292 | As in all colon-separated lists in Exim, a colon can be included in an item by |
8293 | doubling. | |
9b371988 | 8294 | |
168e428f PH |
8295 | If the last item in the list starts with a right angle-bracket, the remainder |
8296 | of the item is taken as a new key to look up in order to obtain a continuation | |
8297 | list of local parts. The new key can be any sequence of characters. Thus one | |
8298 | might have entries like | |
9b371988 PH |
8299 | .code |
8300 | aol.com: spammer1 : spammer 2 : >* | |
8301 | xyz.com: spammer3 : >* | |
8302 | *: ^\d{8}$ | |
8303 | .endd | |
8304 | in a file that was searched with &%@@dbm*%&, to specify a match for 8-digit | |
168e428f PH |
8305 | local parts for all domains, in addition to the specific local parts listed for |
8306 | each domain. Of course, using this feature costs another lookup each time a | |
8307 | chain is followed, but the effort needed to maintain the data is reduced. | |
9b371988 PH |
8308 | |
8309 | .cindex "loop" "in lookups" | |
168e428f PH |
8310 | It is possible to construct loops using this facility, and in order to catch |
8311 | them, the chains may be no more than fifty items long. | |
8312 | ||
9b371988 PH |
8313 | .next |
8314 | The @@<&'lookup'&> style of item can also be used with a query-style | |
168e428f PH |
8315 | lookup, but in this case, the chaining facility is not available. The lookup |
8316 | can only return a single list of local parts. | |
9b371988 | 8317 | .endlist |
168e428f | 8318 | |
9b371988 | 8319 | &*Warning*&: There is an important difference between the address list items |
168e428f | 8320 | in these two examples: |
9b371988 PH |
8321 | .code |
8322 | senders = +my_list | |
8323 | senders = *@+my_list | |
8324 | .endd | |
8325 | In the first one, &`my_list`& is a named address list, whereas in the second | |
168e428f PH |
8326 | example it is a named domain list. |
8327 | ||
8328 | ||
8329 | ||
8330 | ||
9b371988 PH |
8331 | .section "Case of letters in address lists" "SECTcasletadd" |
8332 | .cindex "case of local parts" | |
8333 | .cindex "address list" "case forcing" | |
8334 | .cindex "case forcing in address lists" | |
168e428f | 8335 | Domains in email addresses are always handled caselessly, but for local parts |
9b371988 PH |
8336 | case may be significant on some systems (see &%caseful_local_part%& for how |
8337 | Exim deals with this when routing addresses). However, RFC 2505 (&'Anti-Spam | |
8338 | Recommendations for SMTP MTAs'&) suggests that matching of addresses to | |
8339 | blocking lists should be done in a case-independent manner. Since most address | |
8340 | lists in Exim are used for this kind of control, Exim attempts to do this by | |
8341 | default. | |
168e428f PH |
8342 | |
8343 | The domain portion of an address is always lowercased before matching it to an | |
8344 | address list. The local part is lowercased by default, and any string | |
8345 | comparisons that take place are done caselessly. This means that the data in | |
8346 | the address list itself, in files included as plain file names, and in any file | |
9b371988 PH |
8347 | that is looked up using the &"@@"& mechanism, can be in any case. However, the |
8348 | keys in files that are looked up by a search type other than &(lsearch)& (which | |
168e428f PH |
8349 | works caselessly) must be in lower case, because these lookups are not |
8350 | case-independent. | |
8351 | ||
9b371988 | 8352 | .cindex "&`+caseful`&" |
168e428f | 8353 | To allow for the possibility of caseful address list matching, if an item in |
9b371988 | 8354 | an address list is the string &"+caseful"&, the original case of the local |
168e428f PH |
8355 | part is restored for any comparisons that follow, and string comparisons are no |
8356 | longer case-independent. This does not affect the domain, which remains in | |
8357 | lower case. However, although independent matches on the domain alone are still | |
8358 | performed caselessly, regular expressions that match against an entire address | |
9b371988 | 8359 | become case-sensitive after &"+caseful"& has been seen. |
168e428f PH |
8360 | |
8361 | ||
8362 | ||
9b371988 PH |
8363 | .section "Local part lists" "SECTlocparlis" |
8364 | .cindex "list" "local part list" | |
8365 | .cindex "local part" "list" | |
168e428f | 8366 | Case-sensitivity in local part lists is handled in the same way as for address |
9b371988 PH |
8367 | lists, as just described. The &"+caseful"& item can be used if required. In a |
8368 | setting of the &%local_parts%& option in a router with &%caseful_local_part%& | |
168e428f | 8369 | set false, the subject is lowercased and the matching is initially |
9b371988 PH |
8370 | case-insensitive. In this case, &"+caseful"& will restore case-sensitive |
8371 | matching in the local part list, but not elsewhere in the router. If | |
8372 | &%caseful_local_part%& is set true in a router, matching in the &%local_parts%& | |
168e428f PH |
8373 | option is case-sensitive from the start. |
8374 | ||
9b371988 PH |
8375 | If a local part list is indirected to a file (see section &<<SECTfilnamlis>>&), |
8376 | comments are handled in the same way as address lists &-- they are recognized | |
168e428f PH |
8377 | only if the # is preceded by white space or the start of the line. |
8378 | Otherwise, local part lists are matched in the same way as domain lists, except | |
9b371988 PH |
8379 | that the special items that refer to the local host (&`@`&, &`@[]`&, |
8380 | &`@mx_any`&, &`@mx_primary`&, and &`@mx_secondary`&) are not recognized. | |
8381 | Refer to section &<<SECTdomainlist>>& for details of the other available item | |
168e428f | 8382 | types. |
4f578862 | 8383 | .ecindex IIDdohoadli |
168e428f PH |
8384 | |
8385 | ||
8386 | ||
8387 | ||
9b371988 PH |
8388 | . //////////////////////////////////////////////////////////////////////////// |
8389 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 8390 | |
9b371988 | 8391 | .chapter "String expansions" "CHAPexpand" |
4f578862 | 8392 | .scindex IIDstrexp "expansion" "of strings" |
168e428f PH |
8393 | Many strings in Exim's run time configuration are expanded before use. Some of |
8394 | them are expanded every time they are used; others are expanded only once. | |
8395 | ||
8396 | When a string is being expanded it is copied verbatim from left to right except | |
8397 | when a dollar or backslash character is encountered. A dollar specifies the | |
068aaea8 | 8398 | start of a portion of the string that is interpreted and replaced as described |
9b371988 PH |
8399 | below in section &<<SECTexpansionitems>>& onwards. Backslash is used as an |
8400 | escape character, as described in the following section. | |
168e428f PH |
8401 | |
8402 | ||
8403 | ||
9b371988 PH |
8404 | .section "Literal text in expanded strings" "SECTlittext" |
8405 | .cindex "expansion" "including literal text" | |
168e428f PH |
8406 | An uninterpreted dollar can be included in an expanded string by putting a |
8407 | backslash in front of it. A backslash can be used to prevent any special | |
068aaea8 PH |
8408 | character being treated specially in an expansion, including backslash itself. |
8409 | If the string appears in quotes in the configuration file, two backslashes are | |
168e428f | 8410 | required because the quotes themselves cause interpretation of backslashes when |
9b371988 | 8411 | the string is read in (see section &<<SECTstrings>>&). |
168e428f | 8412 | |
9b371988 | 8413 | .cindex "expansion" "non-expandable substrings" |
168e428f | 8414 | A portion of the string can specified as non-expandable by placing it between |
9b371988 | 8415 | two occurrences of &`\N`&. This is particularly useful for protecting regular |
168e428f | 8416 | expressions, which often contain backslashes and dollar signs. For example: |
9b371988 PH |
8417 | .code |
8418 | deny senders = \N^\d{8}[a-z]@some\.site\.example$\N | |
8419 | .endd | |
8420 | On encountering the first &`\N`&, the expander copies subsequent characters | |
8421 | without interpretation until it reaches the next &`\N`& or the end of the | |
168e428f PH |
8422 | string. |
8423 | ||
8424 | ||
8425 | ||
f89d2485 | 8426 | .section "Character escape sequences in expanded strings" "SECID82" |
9b371988 PH |
8427 | .cindex "expansion" "escape sequences" |
8428 | A backslash followed by one of the letters &"n"&, &"r"&, or &"t"& in an | |
8429 | expanded string is recognized as an escape sequence for the character newline, | |
8430 | carriage return, or tab, respectively. A backslash followed by up to three | |
8431 | octal digits is recognized as an octal encoding for a single character, and a | |
8432 | backslash followed by &"x"& and up to two hexadecimal digits is a hexadecimal | |
8433 | encoding. | |
168e428f PH |
8434 | |
8435 | These escape sequences are also recognized in quoted strings when they are read | |
8436 | in. Their interpretation in expansions as well is useful for unquoted strings, | |
8437 | and for other cases such as looked-up strings that are then expanded. | |
8438 | ||
8439 | ||
f89d2485 | 8440 | .section "Testing string expansions" "SECID83" |
9b371988 PH |
8441 | .cindex "expansion" "testing" |
8442 | .cindex "testing" "string expansion" | |
f89d2485 | 8443 | .oindex "&%-be%&" |
9b371988 PH |
8444 | Many expansions can be tested by calling Exim with the &%-be%& option. This |
8445 | takes the command arguments, or lines from the standard input if there are no | |
168e428f PH |
8446 | arguments, runs them through the string expansion code, and writes the results |
8447 | to the standard output. Variables based on configuration values are set up, but | |
9b371988 PH |
8448 | since no message is being processed, variables such as &$local_part$& have no |
8449 | value. Nevertheless the &%-be%& option can be useful for checking out file and | |
8450 | database lookups, and the use of expansion operators such as &%sg%&, &%substr%& | |
8451 | and &%nhash%&. | |
168e428f | 8452 | |
9b371988 | 8453 | Exim gives up its root privilege when it is called with the &%-be%& option, and |
168e428f | 8454 | instead runs under the uid and gid it was called with, to prevent users from |
9b371988 | 8455 | using &%-be%& for reading files to which they do not have access. |
168e428f | 8456 | |
f89d2485 | 8457 | .oindex "&%-bem%&" |
3cb1b51e PH |
8458 | If you want to test expansions that include variables whose values are taken |
8459 | from a message, there are two other options that can be used. The &%-bem%& | |
8460 | option is like &%-be%& except that it is followed by a file name. The file is | |
8461 | read as a message before doing the test expansions. For example: | |
8462 | .code | |
8463 | exim -bem /tmp/test.message '$h_subject:' | |
8464 | .endd | |
8465 | The &%-Mset%& option is used in conjunction with &%-be%& and is followed by an | |
8466 | Exim message identifier. For example: | |
8467 | .code | |
8468 | exim -be -Mset 1GrA8W-0004WS-LQ '$recipients' | |
8469 | .endd | |
8470 | This loads the message from Exim's spool before doing the test expansions, and | |
8471 | is therefore restricted to admin users. | |
168e428f PH |
8472 | |
8473 | ||
9b371988 PH |
8474 | .section "Forced expansion failure" "SECTforexpfai" |
8475 | .cindex "expansion" "forced failure" | |
168e428f | 8476 | A number of expansions that are described in the following section have |
9b371988 PH |
8477 | alternative &"true"& and &"false"& substrings, enclosed in brace characters |
8478 | (which are sometimes called &"curly brackets"&). Which of the two strings is | |
068aaea8 | 8479 | used depends on some condition that is evaluated as part of the expansion. If, |
9b371988 | 8480 | instead of a &"false"& substring, the word &"fail"& is used (not in braces), |
068aaea8 | 8481 | the entire string expansion fails in a way that can be detected by the code |
9b371988 | 8482 | that requested the expansion. This is called &"forced expansion failure"&, and |
068aaea8 PH |
8483 | its consequences depend on the circumstances. In some cases it is no different |
8484 | from any other expansion failure, but in others a different action may be | |
8485 | taken. Such variations are mentioned in the documentation of the option that is | |
8486 | being expanded. | |
168e428f PH |
8487 | |
8488 | ||
8489 | ||
8490 | ||
9b371988 | 8491 | .section "Expansion items" "SECTexpansionitems" |
168e428f PH |
8492 | The following items are recognized in expanded strings. White space may be used |
8493 | between sub-items that are keywords or substrings enclosed in braces inside an | |
9b371988 | 8494 | outer set of braces, to improve readability. &*Warning*&: Within braces, |
168e428f PH |
8495 | white space is significant. |
8496 | ||
9b371988 PH |
8497 | .vlist |
8498 | .vitem &*$*&<&'variable&~name'&>&~or&~&*${*&<&'variable&~name'&>&*}*& | |
8499 | .cindex "expansion" "variables" | |
8500 | Substitute the contents of the named variable, for example: | |
8501 | .code | |
8502 | $local_part | |
8503 | ${domain} | |
8504 | .endd | |
168e428f | 8505 | The second form can be used to separate the name from subsequent alphanumeric |
068aaea8 | 8506 | characters. This form (using braces) is available only for variables; it does |
9b371988 PH |
8507 | &'not'& apply to message headers. The names of the variables are given in |
8508 | section &<<SECTexpvar>>& below. If the name of a non-existent variable is | |
8509 | given, the expansion fails. | |
8510 | ||
8511 | .vitem &*${*&<&'op'&>&*:*&<&'string'&>&*}*& | |
8512 | .cindex "expansion" "operators" | |
8513 | The string is first itself expanded, and then the operation specified by | |
8514 | <&'op'&> is applied to it. For example: | |
8515 | .code | |
8516 | ${lc:$local_part} | |
8517 | .endd | |
168e428f | 8518 | The string starts with the first character after the colon, which may be |
9b371988 | 8519 | leading white space. A list of operators is given in section &<<SECTexpop>>& |
168e428f PH |
8520 | below. The operator notation is used for simple expansion items that have just |
8521 | one argument, because it reduces the number of braces and therefore makes the | |
8522 | string easier to understand. | |
8523 | ||
595028e4 PH |
8524 | .vitem &*$bheader_*&<&'header&~name'&>&*:*&&~or&~&*$bh_*&<&'header&~name'&>&*:*& |
8525 | This item inserts &"basic"& header lines. It is described with the &%header%& | |
8526 | expansion item below. | |
8527 | ||
9b371988 PH |
8528 | .vitem "&*${dlfunc{*&<&'file'&>&*}{*&<&'function'&>&*}{*&<&'arg'&>&*}&&& |
8529 | {*&<&'arg'&>&*}...}*&" | |
4f578862 | 8530 | .cindex &%dlfunc%& |
068aaea8 PH |
8531 | This expansion dynamically loads and then calls a locally-written C function. |
8532 | This functionality is available only if Exim is compiled with | |
9b371988 PH |
8533 | .code |
8534 | EXPAND_DLFUNC=yes | |
8535 | .endd | |
8536 | set in &_Local/Makefile_&. Once loaded, Exim remembers the dynamically loaded | |
068aaea8 PH |
8537 | object so that it doesn't reload the same object file in the same Exim process |
8538 | (but of course Exim does start new processes frequently). | |
9b371988 | 8539 | |
068aaea8 | 8540 | There may be from zero to eight arguments to the function. When compiling |
9b371988 | 8541 | a local function that is to be called in this way, &_local_scan.h_& should be |
068aaea8 PH |
8542 | included. The Exim variables and functions that are defined by that API |
8543 | are also available for dynamically loaded functions. The function itself | |
8544 | must have the following type: | |
9b371988 | 8545 | .code |
068aaea8 | 8546 | int dlfunction(uschar **yield, int argc, uschar *argv[]) |
9b371988 PH |
8547 | .endd |
8548 | Where &`uschar`& is a typedef for &`unsigned char`& in &_local_scan.h_&. The | |
068aaea8 | 8549 | function should return one of the following values: |
068aaea8 | 8550 | |
9b371988 PH |
8551 | &`OK`&: Success. The string that is placed in the variable &'yield'& is put |
8552 | into the expanded string that is being built. | |
8553 | ||
8554 | &`FAIL`&: A non-forced expansion failure occurs, with the error message taken | |
8555 | from &'yield'&, if it is set. | |
8556 | ||
8557 | &`FAIL_FORCED`&: A forced expansion failure occurs, with the error message | |
8558 | taken from &'yield'& if it is set. | |
8559 | ||
8560 | &`ERROR`&: Same as &`FAIL`&, except that a panic log entry is written. | |
068aaea8 | 8561 | |
9b371988 PH |
8562 | When compiling a function that is to be used in this way with gcc, |
8563 | you need to add &%-shared%& to the gcc command. Also, in the Exim build-time | |
8564 | configuration, you must add &%-export-dynamic%& to EXTRALIBS. | |
9b371988 PH |
8565 | |
8566 | .vitem "&*${extract{*&<&'key'&>&*}{*&<&'string1'&>&*}{*&<&'string2'&>&*}&&& | |
8567 | {*&<&'string3'&>&*}}*&" | |
8568 | .cindex "expansion" "extracting substrings by key" | |
4f578862 | 8569 | .cindex "&%extract%&" "substrings by key" |
9b371988 | 8570 | The key and <&'string1'&> are first expanded separately. Leading and trailing |
068aaea8 | 8571 | white space is removed from the key (but not from any of the strings). The key |
9b371988 | 8572 | must not consist entirely of digits. The expanded <&'string1'&> must be of the |
068aaea8 | 8573 | form: |
9b371988 PH |
8574 | .display |
8575 | <&'key1'&> = <&'value1'&> <&'key2'&> = <&'value2'&> ... | |
8576 | .endd | |
f89d2485 | 8577 | .vindex "&$value$&" |
068aaea8 PH |
8578 | where the equals signs and spaces (but not both) are optional. If any of the |
8579 | values contain white space, they must be enclosed in double quotes, and any | |
8580 | values that are enclosed in double quotes are subject to escape processing as | |
9b371988 PH |
8581 | described in section &<<SECTstrings>>&. The expanded <&'string1'&> is searched |
8582 | for the value that corresponds to the key. The search is case-insensitive. If | |
8583 | the key is found, <&'string2'&> is expanded, and replaces the whole item; | |
8584 | otherwise <&'string3'&> is used. During the expansion of <&'string2'&> the | |
8585 | variable &$value$& contains the value that has been extracted. Afterwards, it | |
8586 | is restored to any previous value it might have had. | |
8587 | ||
8588 | If {<&'string3'&>} is omitted, the item is replaced by an empty string if the | |
8589 | key is not found. If {<&'string2'&>} is also omitted, the value that was | |
168e428f | 8590 | extracted is used. Thus, for example, these two expansions are identical, and |
9b371988 PH |
8591 | yield &"2001"&: |
8592 | .code | |
8593 | ${extract{gid}{uid=1984 gid=2001}} | |
8594 | ${extract{gid}{uid=1984 gid=2001}{$value}} | |
8595 | .endd | |
8596 | Instead of {<&'string3'&>} the word &"fail"& (not in curly brackets) can | |
168e428f | 8597 | appear, for example: |
9b371988 PH |
8598 | .code |
8599 | ${extract{Z}{A=... B=...}{$value} fail } | |
8600 | .endd | |
8601 | This forces an expansion failure (see section &<<SECTforexpfai>>&); | |
8602 | {<&'string2'&>} must be present for &"fail"& to be recognized. | |
168e428f PH |
8603 | |
8604 | ||
9b371988 PH |
8605 | .vitem "&*${extract{*&<&'number'&>&*}{*&<&'separators'&>&*}&&& |
8606 | {*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*&" | |
8607 | .cindex "expansion" "extracting substrings by number" | |
4f578862 | 8608 | .cindex "&%extract%&" "substrings by number" |
9b371988 | 8609 | The <&'number'&> argument must consist entirely of decimal digits, |
068aaea8 | 8610 | apart from leading and trailing white space, which is ignored. |
9b371988 | 8611 | This is what distinguishes this form of &%extract%& from the previous kind. It |
168e428f | 8612 | behaves in the same way, except that, instead of extracting a named field, it |
9b371988 PH |
8613 | extracts from <&'string1'&> the field whose number is given as the first |
8614 | argument. You can use &$value$& in <&'string2'&> or &`fail`& instead of | |
8615 | <&'string3'&> as before. | |
8616 | ||
168e428f PH |
8617 | The fields in the string are separated by any one of the characters in the |
8618 | separator string. These may include space or tab characters. | |
8619 | The first field is numbered one. If the number is negative, the fields are | |
8620 | counted from the end of the string, with the rightmost one numbered -1. If the | |
8621 | number given is zero, the entire string is returned. If the modulus of the | |
8622 | number is greater than the number of fields in the string, the result is the | |
9b371988 PH |
8623 | expansion of <&'string3'&>, or the empty string if <&'string3'&> is not |
8624 | provided. For example: | |
8625 | .code | |
8626 | ${extract{2}{:}{x:42:99:& Mailer::/bin/bash}} | |
8627 | .endd | |
8628 | yields &"42"&, and | |
8629 | .code | |
8630 | ${extract{-4}{:}{x:42:99:& Mailer::/bin/bash}} | |
8631 | .endd | |
8632 | yields &"99"&. Two successive separators mean that the field between them is | |
168e428f PH |
8633 | empty (for example, the fifth field above). |
8634 | ||
8635 | ||
f89d2485 PH |
8636 | .vitem &*${filter{*&<&'string'&>&*}{*&<&'condition'&>&*}}*& |
8637 | .cindex "list" "selecting by condition" | |
8638 | .cindex "expansion" "selecting from list by condition" | |
8639 | .vindex "&$item$&" | |
8640 | After expansion, <&'string'&> is interpreted as a list, colon-separated by | |
8641 | default, but the separator can be changed in the usual way. For each item | |
8642 | in this list, its value is place in &$item$&, and then the condition is | |
8643 | evaluated. If the condition is true, &$item$& is added to the output as an | |
8644 | item in a new list; if the condition is false, the item is discarded. The | |
8645 | separator used for the output list is the same as the one used for the | |
8646 | input, but a separator setting is not included in the output. For example: | |
8647 | .code | |
8648 | ${filter{a:b:c}{!eq{$item}{b}} | |
8649 | .endd | |
8650 | yields &`a:c`&. At the end of the expansion, the value of &$item$& is restored | |
8651 | to what it was before. See also the &*map*& and &*reduce*& expansion items. | |
f89d2485 PH |
8652 | |
8653 | ||
9b371988 PH |
8654 | .vitem &*${hash{*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*& |
8655 | .cindex "hash function" "textual" | |
8656 | .cindex "expansion" "textual hash" | |
168e428f PH |
8657 | This is a textual hashing function, and was the first to be implemented in |
8658 | early versions of Exim. In current releases, there are other hashing functions | |
8659 | (numeric, MD5, and SHA-1), which are described below. | |
9b371988 PH |
8660 | |
8661 | The first two strings, after expansion, must be numbers. Call them <&'m'&> and | |
8662 | <&'n'&>. If you are using fixed values for these numbers, that is, if | |
8663 | <&'string1'&> and <&'string2'&> do not change when they are expanded, you can | |
8664 | use the simpler operator notation that avoids some of the braces: | |
8665 | .code | |
8666 | ${hash_<n>_<m>:<string>} | |
8667 | .endd | |
8668 | The second number is optional (in both notations). If <&'n'&> is greater than | |
8669 | or equal to the length of the string, the expansion item returns the string. | |
8670 | Otherwise it computes a new string of length <&'n'&> by applying a hashing | |
8671 | function to the string. The new string consists of characters taken from the | |
8672 | first <&'m'&> characters of the string | |
8673 | .code | |
8674 | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQWRSTUVWXYZ0123456789 | |
8675 | .endd | |
8676 | If <&'m'&> is not present the value 26 is used, so that only lower case | |
168e428f | 8677 | letters appear. For example: |
9b371988 PH |
8678 | .display |
8679 | &`$hash{3}{monty}} `& yields &`jmg`& | |
8680 | &`$hash{5}{monty}} `& yields &`monty`& | |
8681 | &`$hash{4}{62}{monty python}}`& yields &`fbWx`& | |
8682 | .endd | |
8683 | ||
8684 | .vitem "&*$header_*&<&'header&~name'&>&*:*&&~or&~&&& | |
595028e4 PH |
8685 | &*$h_*&<&'header&~name'&>&*:*&" &&& |
8686 | "&*$bheader_*&<&'header&~name'&>&*:*&&~or&~&&& | |
8687 | &*$bh_*&<&'header&~name'&>&*:*&" &&& | |
8688 | "&*$rheader_*&<&'header&~name'&>&*:*&&~or&~&&& | |
9b371988 PH |
8689 | &*$rh_*&<&'header&~name'&>&*:*&" |
8690 | .cindex "expansion" "header insertion" | |
f89d2485 PH |
8691 | .vindex "&$header_$&" |
8692 | .vindex "&$bheader_$&" | |
8693 | .vindex "&$rheader_$&" | |
9b371988 PH |
8694 | .cindex "header lines" "in expansion strings" |
8695 | .cindex "header lines" "character sets" | |
8696 | .cindex "header lines" "decoding" | |
168e428f | 8697 | Substitute the contents of the named message header line, for example |
9b371988 PH |
8698 | .code |
8699 | $header_reply-to: | |
8700 | .endd | |
168e428f PH |
8701 | The newline that terminates a header line is not included in the expansion, but |
8702 | internal newlines (caused by splitting the header line over several physical | |
8703 | lines) may be present. | |
9b371988 PH |
8704 | |
8705 | The difference between &%rheader%&, &%bheader%&, and &%header%& is in the way | |
8706 | the data in the header line is interpreted. | |
8707 | ||
8708 | .ilist | |
8709 | .cindex "white space" "in header lines" | |
8710 | &%rheader%& gives the original &"raw"& content of the header line, with no | |
068aaea8 | 8711 | processing at all, and without the removal of leading and trailing white space. |
168e428f | 8712 | |
9b371988 PH |
8713 | .next |
8714 | .cindex "base64 encoding" "in header lines" | |
8715 | &%bheader%& removes leading and trailing white space, and then decodes base64 | |
8716 | or quoted-printable MIME &"words"& within the header text, but does no | |
8717 | character set translation. If decoding of what looks superficially like a MIME | |
8718 | &"word"& fails, the raw string is returned. If decoding | |
8719 | .cindex "binary zero" "in header line" | |
8720 | produces a binary zero character, it is replaced by a question mark &-- this is | |
168e428f PH |
8721 | what Exim does for binary zeros that are actually received in header lines. |
8722 | ||
9b371988 PH |
8723 | .next |
8724 | &%header%& tries to translate the string as decoded by &%bheader%& to a | |
8725 | standard character set. This is an attempt to produce the same string as would | |
8726 | be displayed on a user's MUA. If translation fails, the &%bheader%& string is | |
168e428f | 8727 | returned. Translation is attempted only on operating systems that support the |
9b371988 PH |
8728 | &[iconv()]& function. This is indicated by the compile-time macro HAVE_ICONV in |
8729 | a system Makefile or in &_Local/Makefile_&. | |
8730 | .endlist ilist | |
168e428f | 8731 | |
9b371988 PH |
8732 | In a filter file, the target character set for &%header%& can be specified by a |
8733 | command of the following form: | |
8734 | .code | |
8735 | headers charset "UTF-8" | |
8736 | .endd | |
8737 | This command affects all references to &$h_$& (or &$header_$&) expansions in | |
168e428f | 8738 | subsequently obeyed filter commands. In the absence of this command, the target |
9b371988 | 8739 | character set in a filter is taken from the setting of the &%headers_charset%& |
168e428f | 8740 | option in the runtime configuration. The value of this option defaults to the |
9b371988 | 8741 | value of HEADERS_CHARSET in &_Local/Makefile_&. The ultimate default is |
168e428f | 8742 | ISO-8859-1. |
9b371988 | 8743 | |
168e428f PH |
8744 | Header names follow the syntax of RFC 2822, which states that they may contain |
8745 | any printing characters except space and colon. Consequently, curly brackets | |
9b371988 | 8746 | &'do not'& terminate header names, and should not be used to enclose them as |
168e428f | 8747 | if they were variables. Attempting to do so causes a syntax error. |
9b371988 | 8748 | |
168e428f PH |
8749 | Only header lines that are common to all copies of a message are visible to |
8750 | this mechanism. These are the original header lines that are received with the | |
3cb1b51e | 8751 | message, and any that are added by an ACL statement or by a system |
168e428f PH |
8752 | filter. Header lines that are added to a particular copy of a message by a |
8753 | router or transport are not accessible. | |
9b371988 | 8754 | |
168e428f PH |
8755 | For incoming SMTP messages, no header lines are visible in ACLs that are obeyed |
8756 | before the DATA ACL, because the header structure is not set up until the | |
3cb1b51e PH |
8757 | message is received. Header lines that are added in a RCPT ACL (for example) |
8758 | are saved until the message's incoming header lines are available, at which | |
8759 | point they are added. When a DATA ACL is running, however, header lines added | |
8760 | by earlier ACLs are visible. | |
9b371988 | 8761 | |
168e428f PH |
8762 | Upper case and lower case letters are synonymous in header names. If the |
8763 | following character is white space, the terminating colon may be omitted, but | |
8764 | this is not recommended, because you may then forget it when it is needed. When | |
8765 | white space terminates the header name, it is included in the expanded string. | |
8766 | If the message does not contain the given header, the expansion item is | |
9b371988 PH |
8767 | replaced by an empty string. (See the &%def%& condition in section |
8768 | &<<SECTexpcond>>& for a means of testing for the existence of a header.) | |
8769 | ||
3cb1b51e PH |
8770 | If there is more than one header with the same name, they are all concatenated |
8771 | to form the substitution string, up to a maximum length of 64K. Unless | |
8772 | &%rheader%& is being used, leading and trailing white space is removed from | |
8773 | each header before concatenation, and a completely empty header is ignored. A | |
8774 | newline character is then inserted between non-empty headers, but there is no | |
8775 | newline at the very end. For the &%header%& and &%bheader%& expansion, for | |
8776 | those headers that contain lists of addresses, a comma is also inserted at the | |
8777 | junctions between headers. This does not happen for the &%rheader%& expansion. | |
168e428f PH |
8778 | |
8779 | ||
9b371988 PH |
8780 | .vitem &*${hmac{*&<&'hashname'&>&*}{*&<&'secret'&>&*}{*&<&'string'&>&*}}*& |
8781 | .cindex "expansion" "hmac hashing" | |
4f578862 | 8782 | .cindex &%hmac%& |
168e428f PH |
8783 | This function uses cryptographic hashing (either MD5 or SHA-1) to convert a |
8784 | shared secret and some text into a message authentication code, as specified in | |
9b371988 PH |
8785 | RFC 2104. This differs from &`${md5:secret_text...}`& or |
8786 | &`${sha1:secret_text...}`& in that the hmac step adds a signature to the | |
168e428f | 8787 | cryptographic hash, allowing for authentication that is not possible with MD5 |
9b371988 PH |
8788 | or SHA-1 alone. The hash name must expand to either &`md5`& or &`sha1`& at |
8789 | present. For example: | |
8790 | .code | |
8791 | ${hmac{md5}{somesecret}{$primary_hostname $tod_log}} | |
8792 | .endd | |
8793 | For the hostname &'mail.example.com'& and time 2002-10-17 11:30:59, this | |
168e428f | 8794 | produces: |
9b371988 PH |
8795 | .code |
8796 | dd97e3ba5d1a61b5006108f8c8252953 | |
8797 | .endd | |
168e428f PH |
8798 | As an example of how this might be used, you might put in the main part of |
8799 | an Exim configuration: | |
9b371988 PH |
8800 | .code |
8801 | SPAMSCAN_SECRET=cohgheeLei2thahw | |
8802 | .endd | |
168e428f | 8803 | In a router or a transport you could then have: |
9b371988 | 8804 | .code |
168e428f | 8805 | headers_add = \ |
d1e83bff | 8806 | X-Spam-Scanned: ${primary_hostname} ${message_exim_id} \ |
168e428f | 8807 | ${hmac{md5}{SPAMSCAN_SECRET}\ |
d1e83bff | 8808 | {${primary_hostname},${message_exim_id},$h_message-id:}} |
9b371988 | 8809 | .endd |
168e428f | 8810 | Then given a message, you can check where it was scanned by looking at the |
9b371988 PH |
8811 | &'X-Spam-Scanned:'& header line. If you know the secret, you can check that |
8812 | this header line is authentic by recomputing the authentication code from the | |
8813 | host name, message ID and the &'Message-id:'& header line. This can be done | |
8814 | using Exim's &%-be%& option, or by other means, for example by using the | |
8815 | &'hmac_md5_hex()'& function in Perl. | |
8816 | ||
8817 | ||
8818 | .vitem &*${if&~*&<&'condition'&>&*&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}}*& | |
8819 | .cindex "expansion" "conditional" | |
4f578862 | 8820 | .cindex "&%if%&, expansion item" |
9b371988 PH |
8821 | If <&'condition'&> is true, <&'string1'&> is expanded and replaces the whole |
8822 | item; otherwise <&'string2'&> is used. The available conditions are described | |
8823 | in section &<<SECTexpcond>>& below. For example: | |
8824 | .code | |
8825 | ${if eq {$local_part}{postmaster} {yes}{no} } | |
8826 | .endd | |
168e428f | 8827 | The second string need not be present; if it is not and the condition is not |
9b371988 PH |
8828 | true, the item is replaced with nothing. Alternatively, the word &"fail"& may |
8829 | be present instead of the second string (without any curly brackets). In this | |
168e428f | 8830 | case, the expansion is forced to fail if the condition is not true (see section |
9b371988 PH |
8831 | &<<SECTforexpfai>>&). |
8832 | ||
8833 | If both strings are omitted, the result is the string &`true`& if the condition | |
168e428f PH |
8834 | is true, and the empty string if the condition is false. This makes it less |
8835 | cumbersome to write custom ACL and router conditions. For example, instead of | |
9b371988 PH |
8836 | .code |
8837 | condition = ${if >{$acl_m4}{3}{true}{false}} | |
8838 | .endd | |
168e428f | 8839 | you can use |
9b371988 PH |
8840 | .code |
8841 | condition = ${if >{$acl_m4}{3}} | |
8842 | .endd | |
8843 | ||
8844 | .vitem &*${length{*&<&'string1'&>&*}{*&<&'string2'&>&*}}*& | |
8845 | .cindex "expansion" "string truncation" | |
f89d2485 | 8846 | .cindex "&%length%& expansion item" |
9b371988 PH |
8847 | The &%length%& item is used to extract the initial portion of a string. Both |
8848 | strings are expanded, and the first one must yield a number, <&'n'&>, say. If | |
8849 | you are using a fixed value for the number, that is, if <&'string1'&> does not | |
8850 | change when expanded, you can use the simpler operator notation that avoids | |
8851 | some of the braces: | |
8852 | .code | |
8853 | ${length_<n>:<string>} | |
8854 | .endd | |
8855 | The result of this item is either the first <&'n'&> characters or the whole | |
8856 | of <&'string2'&>, whichever is the shorter. Do not confuse &%length%& with | |
8857 | &%strlen%&, which gives the length of a string. | |
8858 | ||
8859 | ||
8860 | .vitem "&*${lookup{*&<&'key'&>&*}&~*&<&'search&~type'&>&*&~&&& | |
8861 | {*&<&'file'&>&*}&~{*&<&'string1'&>&*}&~{*&<&'string2'&>&*}}*&" | |
168e428f PH |
8862 | This is the first of one of two different types of lookup item, which are both |
8863 | described in the next item. | |
8864 | ||
9b371988 PH |
8865 | .vitem "&*${lookup&~*&<&'search&~type'&>&*&~{*&<&'query'&>&*}&~&&& |
8866 | {*&<&'string1'&>&*}&~{*&<&'string2'&>&*}}*&" | |
8867 | .cindex "expansion" "lookup in" | |
4f578862 | 8868 | .cindex "file" "lookups" |
9b371988 | 8869 | .cindex "lookup" "in expanded string" |
168e428f | 8870 | The two forms of lookup item specify data lookups in files and databases, as |
9b371988 PH |
8871 | discussed in chapter &<<CHAPfdlookup>>&. The first form is used for single-key |
8872 | lookups, and the second is used for query-style lookups. The <&'key'&>, | |
8873 | <&'file'&>, and <&'query'&> strings are expanded before use. | |
8874 | ||
168e428f | 8875 | If there is any white space in a lookup item which is part of a filter command, |
9b371988 | 8876 | a retry or rewrite rule, a routing rule for the &(manualroute)& router, or any |
168e428f PH |
8877 | other place where white space is significant, the lookup item must be enclosed |
8878 | in double quotes. The use of data lookups in users' filter files may be locked | |
8879 | out by the system administrator. | |
9b371988 | 8880 | |
f89d2485 | 8881 | .vindex "&$value$&" |
9b371988 PH |
8882 | If the lookup succeeds, <&'string1'&> is expanded and replaces the entire item. |
8883 | During its expansion, the variable &$value$& contains the data returned by the | |
168e428f | 8884 | lookup. Afterwards it reverts to the value it had previously (at the outer |
9b371988 PH |
8885 | level it is empty). If the lookup fails, <&'string2'&> is expanded and replaces |
8886 | the entire item. If {<&'string2'&>} is omitted, the replacement is the empty | |
8887 | string on failure. If <&'string2'&> is provided, it can itself be a nested | |
168e428f PH |
8888 | lookup, thus providing a mechanism for looking up a default value when the |
8889 | original lookup fails. | |
9b371988 PH |
8890 | |
8891 | If a nested lookup is used as part of <&'string1'&>, &$value$& contains the | |
8892 | data for the outer lookup while the parameters of the second lookup are | |
8893 | expanded, and also while <&'string2'&> of the second lookup is expanded, should | |
8894 | the second lookup fail. Instead of {<&'string2'&>} the word &"fail"& can | |
8895 | appear, and in this case, if the lookup fails, the entire expansion is forced | |
8896 | to fail (see section &<<SECTforexpfai>>&). If both {<&'string1'&>} and | |
8897 | {<&'string2'&>} are omitted, the result is the looked up value in the case of a | |
8898 | successful lookup, and nothing in the case of failure. | |
8899 | ||
8900 | For single-key lookups, the string &"partial"& is permitted to precede the | |
8901 | search type in order to do partial matching, and * or *@ may follow a search | |
168e428f | 8902 | type to request default lookups if the key does not match (see sections |
9b371988 PH |
8903 | &<<SECTdefaultvaluelookups>>& and &<<SECTpartiallookup>>& for details). |
8904 | ||
8905 | .cindex "numerical variables (&$1$& &$2$& etc)" "in lookup expansion" | |
8906 | If a partial search is used, the variables &$1$& and &$2$& contain the wild | |
168e428f PH |
8907 | and non-wild parts of the key during the expansion of the replacement text. |
8908 | They return to their previous values at the end of the lookup item. | |
168e428f | 8909 | |
9b371988 PH |
8910 | This example looks up the postmaster alias in the conventional alias file: |
8911 | .code | |
8912 | ${lookup {postmaster} lsearch {/etc/aliases} {$value}} | |
8913 | .endd | |
168e428f PH |
8914 | This example uses NIS+ to look up the full name of the user corresponding to |
8915 | the local part of an address, forcing the expansion to fail if it is not found: | |
9b371988 | 8916 | .code |
168e428f PH |
8917 | ${lookup nisplus {[name=$local_part],passwd.org_dir:gcos} \ |
8918 | {$value}fail} | |
9b371988 | 8919 | .endd |
168e428f | 8920 | |
f89d2485 | 8921 | |
f89d2485 PH |
8922 | .vitem &*${map{*&<&'string1'&>&*}{*&<&'string2'&>&*}}*& |
8923 | .cindex "expansion" "list creation" | |
8924 | .vindex "&$item$&" | |
8925 | After expansion, <&'string1'&> is interpreted as a list, colon-separated by | |
8926 | default, but the separator can be changed in the usual way. For each item | |
8927 | in this list, its value is place in &$item$&, and then <&'string2'&> is | |
8928 | expanded and added to the output as an item in a new list. The separator used | |
8929 | for the output list is the same as the one used for the input, but a separator | |
8930 | setting is not included in the output. For example: | |
8931 | .code | |
8932 | ${map{a:b:c}{[$item]}} ${map{<- x-y-z}{($item)}} | |
8933 | .endd | |
8934 | expands to &`[a]:[b]:[c] (x)-(y)-(z)`&. At the end of the expansion, the | |
8935 | value of &$item$& is restored to what it was before. See also the &*filter*& | |
8936 | and &*reduce*& expansion items. | |
f89d2485 | 8937 | |
9b371988 PH |
8938 | .vitem &*${nhash{*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*& |
8939 | .cindex "expansion" "numeric hash" | |
8940 | .cindex "hash function" "numeric" | |
168e428f | 8941 | The three strings are expanded; the first two must yield numbers. Call them |
9b371988 PH |
8942 | <&'n'&> and <&'m'&>. If you are using fixed values for these numbers, that is, |
8943 | if <&'string1'&> and <&'string2'&> do not change when they are expanded, you | |
8944 | can use the simpler operator notation that avoids some of the braces: | |
8945 | .code | |
8946 | ${nhash_<n>_<m>:<string>} | |
8947 | .endd | |
168e428f | 8948 | The second number is optional (in both notations). If there is only one number, |
9b371988 | 8949 | the result is a number in the range 0&--<&'n'&>-1. Otherwise, the string is |
168e428f | 8950 | processed by a div/mod hash function that returns two numbers, separated by a |
9b371988 PH |
8951 | slash, in the ranges 0 to <&'n'&>-1 and 0 to <&'m'&>-1, respectively. For |
8952 | example, | |
8953 | .code | |
8954 | ${nhash{8}{64}{supercalifragilisticexpialidocious}} | |
8955 | .endd | |
8956 | returns the string &"6/33"&. | |
168e428f PH |
8957 | |
8958 | ||
8959 | ||
9b371988 PH |
8960 | .vitem &*${perl{*&<&'subroutine'&>&*}{*&<&'arg'&>&*}{*&<&'arg'&>&*}...}*& |
8961 | .cindex "Perl" "use in expanded string" | |
8962 | .cindex "expansion" "calling Perl from" | |
168e428f PH |
8963 | This item is available only if Exim has been built to include an embedded Perl |
8964 | interpreter. The subroutine name and the arguments are first separately | |
8965 | expanded, and then the Perl subroutine is called with those arguments. No | |
8966 | additional arguments need be given; the maximum number permitted, including the | |
8967 | name of the subroutine, is nine. | |
9b371988 | 8968 | |
168e428f | 8969 | The return value of the subroutine is inserted into the expanded string, unless |
9b371988 PH |
8970 | the return value is &%undef%&. In that case, the expansion fails in the same |
8971 | way as an explicit &"fail"& on a lookup item. The return value is a scalar. | |
8972 | Whatever you return is evaluated in a scalar context. For example, if you | |
8973 | return the name of a Perl vector, the return value is the size of the vector, | |
8974 | not its contents. | |
8975 | ||
8976 | If the subroutine exits by calling Perl's &%die%& function, the expansion fails | |
8977 | with the error message that was passed to &%die%&. More details of the embedded | |
8978 | Perl facility are given in chapter &<<CHAPperl>>&. | |
8979 | ||
8980 | The &(redirect)& router has an option called &%forbid_filter_perl%& which locks | |
168e428f PH |
8981 | out the use of this expansion item in filter files. |
8982 | ||
8983 | ||
9b371988 | 8984 | .vitem &*${prvs{*&<&'address'&>&*}{*&<&'secret'&>&*}{*&<&'keynumber'&>&*}}*& |
f89d2485 | 8985 | .cindex "&%prvs%& expansion item" |
068aaea8 PH |
8986 | The first argument is a complete email address and the second is secret |
8987 | keystring. The third argument, specifying a key number, is optional. If absent, | |
8988 | it defaults to 0. The result of the expansion is a prvs-signed email address, | |
9b371988 PH |
8989 | to be typically used with the &%return_path%& option on an &(smtp)& transport |
8990 | as part of a bounce address tag validation (BATV) scheme. For more discussion | |
8991 | and an example, see section &<<SECTverifyPRVS>>&. | |
9b371988 | 8992 | |
9b371988 PH |
8993 | .vitem "&*${prvscheck{*&<&'address'&>&*}{*&<&'secret'&>&*}&&& |
8994 | {*&<&'string'&>&*}}*&" | |
f89d2485 | 8995 | .cindex "&%prvscheck%& expansion item" |
9b371988 | 8996 | This expansion item is the complement of the &%prvs%& item. It is used for |
068aaea8 PH |
8997 | checking prvs-signed addresses. If the expansion of the first argument does not |
8998 | yield a syntactically valid prvs-signed address, the whole item expands to the | |
8999 | empty string. When the first argument does expand to a syntactically valid | |
9000 | prvs-signed address, the second argument is expanded, with the prvs-decoded | |
9001 | version of the address and the key number extracted from the address in the | |
9b371988 PH |
9002 | variables &$prvscheck_address$& and &$prvscheck_keynum$&, respectively. |
9003 | ||
068aaea8 PH |
9004 | These two variables can be used in the expansion of the second argument to |
9005 | retrieve the secret. The validity of the prvs-signed address is then checked | |
9b371988 PH |
9006 | against the secret. The result is stored in the variable &$prvscheck_result$&, |
9007 | which is empty for failure or &"1"& for success. | |
9008 | ||
068aaea8 PH |
9009 | The third argument is optional; if it is missing, it defaults to an empty |
9010 | string. This argument is now expanded. If the result is an empty string, the | |
9011 | result of the expansion is the decoded version of the address. This is the case | |
9012 | whether or not the signature was valid. Otherwise, the result of the expansion | |
9013 | is the expansion of the third argument. | |
068aaea8 | 9014 | |
9b371988 PH |
9015 | All three variables can be used in the expansion of the third argument. |
9016 | However, once the expansion is complete, only &$prvscheck_result$& remains set. | |
9017 | For more discussion and an example, see section &<<SECTverifyPRVS>>&. | |
068aaea8 | 9018 | |
9b371988 PH |
9019 | .vitem &*${readfile{*&<&'file&~name'&>&*}{*&<&'eol&~string'&>&*}}*& |
9020 | .cindex "expansion" "inserting an entire file" | |
9021 | .cindex "file" "inserting into expansion" | |
4f578862 | 9022 | .cindex "&%readfile%& expansion item" |
168e428f PH |
9023 | The file name and end-of-line string are first expanded separately. The file is |
9024 | then read, and its contents replace the entire item. All newline characters in | |
9025 | the file are replaced by the end-of-line string if it is present. Otherwise, | |
9026 | newlines are left in the string. | |
9027 | String expansion is not applied to the contents of the file. If you want this, | |
9b371988 PH |
9028 | you must wrap the item in an &%expand%& operator. If the file cannot be read, |
9029 | the string expansion fails. | |
9030 | ||
9031 | The &(redirect)& router has an option called &%forbid_filter_readfile%& which | |
168e428f PH |
9032 | locks out the use of this expansion item in filter files. |
9033 | ||
9034 | ||
9035 | ||
9b371988 PH |
9036 | .vitem "&*${readsocket{*&<&'name'&>&*}{*&<&'request'&>&*}&&& |
9037 | {*&<&'timeout'&>&*}{*&<&'eol&~string'&>&*}{*&<&'fail&~string'&>&*}}*&" | |
9038 | .cindex "expansion" "inserting from a socket" | |
f89d2485 | 9039 | .cindex "socket, use of in expansion" |
4f578862 | 9040 | .cindex "&%readsocket%& expansion item" |
c0712871 PH |
9041 | This item inserts data from a Unix domain or Internet socket into the expanded |
9042 | string. The minimal way of using it uses just two arguments, as in these | |
9043 | examples: | |
9b371988 PH |
9044 | .code |
9045 | ${readsocket{/socket/name}{request string}} | |
c0712871 | 9046 | ${readsocket{inet:some.host:1234}{request string}} |
9b371988 | 9047 | .endd |
c0712871 PH |
9048 | For a Unix domain socket, the first substring must be the path to the socket. |
9049 | For an Internet socket, the first substring must contain &`inet:`& followed by | |
9050 | a host name or IP address, followed by a colon and a port, which can be a | |
9051 | number or the name of a TCP port in &_/etc/services_&. An IP address may | |
9052 | optionally be enclosed in square brackets. This is best for IPv6 addresses. For | |
9053 | example: | |
9054 | .code | |
9055 | ${readsocket{inet:[::1]:1234}{request string}} | |
9056 | .endd | |
9057 | Only a single host name may be given, but if looking it up yields more than | |
9058 | one IP address, they are each tried in turn until a connection is made. For | |
9059 | both kinds of socket, Exim makes a connection, writes the request string | |
9060 | (unless it is an empty string) and reads from the socket until an end-of-file | |
9061 | is read. A timeout of 5 seconds is applied. Additional, optional arguments | |
9062 | extend what can be done. Firstly, you can vary the timeout. For example: | |
9b371988 | 9063 | .code |
db9452a9 | 9064 | ${readsocket{/socket/name}{request string}{3s}} |
9b371988 | 9065 | .endd |
168e428f | 9066 | A fourth argument allows you to change any newlines that are in the data |
9b371988 PH |
9067 | that is read, in the same way as for &%readfile%& (see above). This example |
9068 | turns them into spaces: | |
9069 | .code | |
db9452a9 | 9070 | ${readsocket{inet:127.0.0.1:3294}{request string}{3s}{ }} |
9b371988 | 9071 | .endd |
168e428f PH |
9072 | As with all expansions, the substrings are expanded before the processing |
9073 | happens. Errors in these sub-expansions cause the expansion to fail. In | |
9074 | addition, the following errors can occur: | |
168e428f | 9075 | |
9b371988 PH |
9076 | .ilist |
9077 | Failure to create a socket file descriptor; | |
9078 | .next | |
9079 | Failure to connect the socket; | |
9080 | .next | |
db9452a9 | 9081 | Failure to write the request string; |
9b371988 PH |
9082 | .next |
9083 | Timeout on reading from the socket. | |
9084 | .endlist | |
168e428f | 9085 | |
168e428f PH |
9086 | By default, any of these errors causes the expansion to fail. However, if |
9087 | you supply a fifth substring, it is expanded and used when any of the above | |
9088 | errors occurs. For example: | |
9b371988 | 9089 | .code |
db9452a9 | 9090 | ${readsocket{/socket/name}{request string}{3s}{\n}\ |
9b371988 PH |
9091 | {socket failure}} |
9092 | .endd | |
c0712871 PH |
9093 | You can test for the existence of a Unix domain socket by wrapping this |
9094 | expansion in &`${if exists`&, but there is a race condition between that test | |
9095 | and the actual opening of the socket, so it is safer to use the fifth argument | |
9096 | if you want to be absolutely sure of avoiding an expansion error for a | |
9097 | non-existent Unix domain socket, or a failure to connect to an Internet socket. | |
9b371988 PH |
9098 | |
9099 | The &(redirect)& router has an option called &%forbid_filter_readsocket%& which | |
168e428f PH |
9100 | locks out the use of this expansion item in filter files. |
9101 | ||
f89d2485 | 9102 | |
f89d2485 PH |
9103 | .vitem &*${reduce{*&<&'string1'&>}{<&'string2'&>&*}{*&<&'string3'&>&*}}*& |
9104 | .cindex "expansion" "reducing a list to a scalar" | |
9105 | .cindex "list" "reducing to a scalar" | |
9106 | .vindex "&$value$&" | |
9107 | .vindex "&$item$&" | |
9108 | This operation reduces a list to a single, scalar string. After expansion, | |
9109 | <&'string1'&> is interpreted as a list, colon-separated by default, but the | |
9110 | separator can be changed in the usual way. Then <&'string2'&> is expanded and | |
9111 | assigned to the &$value$& variable. After this, each item in the <&'string1'&> | |
9112 | list is assigned to &$item$& in turn, and <&'string3'&> is expanded for each of | |
9113 | them. The result of that expansion is assigned to &$value$& before the next | |
9114 | iteration. When the end of the list is reached, the final value of &$value$& is | |
9115 | added to the expansion output. The &*reduce*& expansion item can be used in a | |
9116 | number of ways. For example, to add up a list of numbers: | |
9117 | .code | |
9118 | ${reduce {<, 1,2,3}{0}{${eval:$value+$item}}} | |
9119 | .endd | |
9120 | The result of that expansion would be &`6`&. The maximum of a list of numbers | |
9121 | can be found: | |
9122 | .code | |
9123 | ${reduce {3:0:9:4:6}{0}{${if >{$item}{$value}{$item}{$value}}}} | |
9124 | .endd | |
9125 | At the end of a &*reduce*& expansion, the values of &$item$& and &$value$& are | |
9126 | restored to what they were before. See also the &*filter*& and &*map*& | |
9127 | expansion items. | |
f89d2485 | 9128 | |
595028e4 | 9129 | .vitem &*$rheader_*&<&'header&~name'&>&*:*&&~or&~&*$rh_*&<&'header&~name'&>&*:*& |
9b371988 | 9130 | This item inserts &"raw"& header lines. It is described with the &%header%& |
168e428f PH |
9131 | expansion item above. |
9132 | ||
9b371988 PH |
9133 | .vitem "&*${run{*&<&'command'&>&*&~*&<&'args'&>&*}{*&<&'string1'&>&*}&&& |
9134 | {*&<&'string2'&>&*}}*&" | |
9135 | .cindex "expansion" "running a command" | |
4f578862 | 9136 | .cindex "&%run%& expansion item" |
168e428f PH |
9137 | The command and its arguments are first expanded separately, and then the |
9138 | command is run in a separate process, but under the same uid and gid. As in | |
9139 | other command executions from Exim, a shell is not used by default. If you want | |
9140 | a shell, you must explicitly code it. | |
168e428f | 9141 | |
3cb1b51e PH |
9142 | The standard input for the command exists, but is empty. The standard output |
9143 | and standard error are set to the same file descriptor. | |
9b371988 | 9144 | .cindex "return code" "from &%run%& expansion" |
f89d2485 | 9145 | .vindex "&$value$&" |
9b371988 | 9146 | If the command succeeds (gives a zero return code) <&'string1'&> is expanded |
3cb1b51e PH |
9147 | and replaces the entire item; during this expansion, the standard output/error |
9148 | from the command is in the variable &$value$&. If the command fails, | |
9149 | <&'string2'&>, if present, is expanded and used. Once again, during the | |
9150 | expansion, the standard output/error from the command is in the variable | |
9151 | &$value$&. | |
9152 | ||
9153 | If <&'string2'&> is absent, the result is empty. Alternatively, <&'string2'&> | |
9154 | can be the word &"fail"& (not in braces) to force expansion failure if the | |
9155 | command does not succeed. If both strings are omitted, the result is contents | |
9156 | of the standard output/error on success, and nothing on failure. | |
9b371988 | 9157 | |
f89d2485 | 9158 | .vindex "&$runrc$&" |
9b371988 PH |
9159 | The return code from the command is put in the variable &$runrc$&, and this |
9160 | remains set afterwards, so in a filter file you can do things like this: | |
9161 | .code | |
9162 | if "${run{x y z}{}}$runrc" is 1 then ... | |
9163 | elif $runrc is 2 then ... | |
9164 | ... | |
9165 | endif | |
9166 | .endd | |
168e428f | 9167 | If execution of the command fails (for example, the command does not exist), |
9b371988 | 9168 | the return code is 127 &-- the same code that shells use for non-existent |
168e428f | 9169 | commands. |
9b371988 PH |
9170 | |
9171 | &*Warning*&: In a router or transport, you cannot assume the order in which | |
9172 | option values are expanded, except for those preconditions whose order of | |
9173 | testing is documented. Therefore, you cannot reliably expect to set &$runrc$& | |
168e428f | 9174 | by the expansion of one option, and use it in another. |
9b371988 PH |
9175 | |
9176 | The &(redirect)& router has an option called &%forbid_filter_run%& which locks | |
168e428f PH |
9177 | out the use of this expansion item in filter files. |
9178 | ||
9179 | ||
9b371988 PH |
9180 | .vitem &*${sg{*&<&'subject'&>&*}{*&<&'regex'&>&*}{*&<&'replacement'&>&*}}*& |
9181 | .cindex "expansion" "string substitution" | |
4f578862 | 9182 | .cindex "&%sg%& expansion item" |
168e428f PH |
9183 | This item works like Perl's substitution operator (s) with the global (/g) |
9184 | option; hence its name. However, unlike the Perl equivalent, Exim does not | |
9185 | modify the subject string; instead it returns the modified string for insertion | |
9186 | into the overall expansion. The item takes three arguments: the subject string, | |
9b371988 PH |
9187 | a regular expression, and a substitution string. For example: |
9188 | .code | |
9189 | ${sg{abcdefabcdef}{abc}{xyz}} | |
9190 | .endd | |
9191 | yields &"xyzdefxyzdef"&. Because all three arguments are expanded before use, | |
9192 | if any $ or \ characters are required in the regular expression or in the | |
9193 | substitution string, they have to be escaped. For example: | |
9194 | .code | |
9195 | ${sg{abcdef}{^(...)(...)\$}{\$2\$1}} | |
9196 | .endd | |
9197 | yields &"defabc"&, and | |
9198 | .code | |
9199 | ${sg{1=A 4=D 3=C}{\N(\d+)=\N}{K\$1=}} | |
9200 | .endd | |
9201 | yields &"K1=A K4=D K3=C"&. Note the use of &`\N`& to protect the contents of | |
168e428f PH |
9202 | the regular expression from string expansion. |
9203 | ||
9204 | ||
9205 | ||
9b371988 | 9206 | .vitem &*${substr{*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*& |
f89d2485 | 9207 | .cindex "&%substr%& expansion item" |
9b371988 PH |
9208 | .cindex "substring extraction" |
9209 | .cindex "expansion" "substring extraction" | |
168e428f | 9210 | The three strings are expanded; the first two must yield numbers. Call them |
9b371988 PH |
9211 | <&'n'&> and <&'m'&>. If you are using fixed values for these numbers, that is, |
9212 | if <&'string1'&> and <&'string2'&> do not change when they are expanded, you | |
9213 | can use the simpler operator notation that avoids some of the braces: | |
9214 | .code | |
9215 | ${substr_<n>_<m>:<string>} | |
9216 | .endd | |
168e428f PH |
9217 | The second number is optional (in both notations). |
9218 | If it is absent in the simpler format, the preceding underscore must also be | |
9219 | omitted. | |
168e428f | 9220 | |
9b371988 PH |
9221 | The &%substr%& item can be used to extract more general substrings than |
9222 | &%length%&. The first number, <&'n'&>, is a starting offset, and <&'m'&> is the | |
9223 | length required. For example | |
9224 | .code | |
9225 | ${substr{3}{2}{$local_part}} | |
9226 | .endd | |
168e428f PH |
9227 | If the starting offset is greater than the string length the result is the |
9228 | null string; if the length plus starting offset is greater than the string | |
9229 | length, the result is the right-hand part of the string, starting from the | |
9230 | given offset. The first character in the string has offset zero. | |
9b371988 PH |
9231 | |
9232 | The &%substr%& expansion item can take negative offset values to count | |
168e428f PH |
9233 | from the right-hand end of its operand. The last character is offset -1, the |
9234 | second-last is offset -2, and so on. Thus, for example, | |
9b371988 PH |
9235 | .code |
9236 | ${substr{-5}{2}{1234567}} | |
9237 | .endd | |
9238 | yields &"34"&. If the absolute value of a negative offset is greater than the | |
168e428f PH |
9239 | length of the string, the substring starts at the beginning of the string, and |
9240 | the length is reduced by the amount of overshoot. Thus, for example, | |
9b371988 PH |
9241 | .code |
9242 | ${substr{-5}{2}{12}} | |
9243 | .endd | |
168e428f | 9244 | yields an empty string, but |
9b371988 PH |
9245 | .code |
9246 | ${substr{-3}{2}{12}} | |
9247 | .endd | |
9248 | yields &"1"&. | |
168e428f | 9249 | |
9b371988 | 9250 | When the second number is omitted from &%substr%&, the remainder of the string |
168e428f PH |
9251 | is taken if the offset is positive. If it is negative, all characters in the |
9252 | string preceding the offset point are taken. For example, an offset of -1 and | |
9253 | no length, as in these semantically identical examples: | |
9b371988 PH |
9254 | .code |
9255 | ${substr_-1:abcde} | |
9256 | ${substr{-1}{abcde}} | |
9257 | .endd | |
9258 | yields all but the last character of the string, that is, &"abcd"&. | |
168e428f PH |
9259 | |
9260 | ||
9261 | ||
9b371988 PH |
9262 | .vitem "&*${tr{*&<&'subject'&>&*}{*&<&'characters'&>&*}&&& |
9263 | {*&<&'replacements'&>&*}}*&" | |
9264 | .cindex "expansion" "character translation" | |
4f578862 | 9265 | .cindex "&%tr%& expansion item" |
168e428f PH |
9266 | This item does single-character translation on its subject string. The second |
9267 | argument is a list of characters to be translated in the subject string. Each | |
9268 | matching character is replaced by the corresponding character from the | |
9269 | replacement list. For example | |
9b371988 PH |
9270 | .code |
9271 | ${tr{abcdea}{ac}{13}} | |
9272 | .endd | |
9273 | yields &`1b3de1`&. If there are duplicates in the second character string, the | |
168e428f PH |
9274 | last occurrence is used. If the third string is shorter than the second, its |
9275 | last character is replicated. However, if it is empty, no translation takes | |
9276 | place. | |
9b371988 | 9277 | .endlist |
168e428f PH |
9278 | |
9279 | ||
9280 | ||
9b371988 PH |
9281 | .section "Expansion operators" "SECTexpop" |
9282 | .cindex "expansion" "operators" | |
168e428f | 9283 | For expansion items that perform transformations on a single argument string, |
9b371988 | 9284 | the &"operator"& notation is used because it is simpler and uses fewer braces. |
168e428f PH |
9285 | The substring is first expanded before the operation is applied to it. The |
9286 | following operations can be performed: | |
9287 | ||
9b371988 PH |
9288 | .vlist |
9289 | .vitem &*${address:*&<&'string'&>&*}*& | |
9290 | .cindex "expansion" "RFC 2822 address handling" | |
f89d2485 | 9291 | .cindex "&%address%& expansion item" |
168e428f PH |
9292 | The string is interpreted as an RFC 2822 address, as it might appear in a |
9293 | header line, and the effective address is extracted from it. If the string does | |
9294 | not parse successfully, the result is empty. | |
9295 | ||
9296 | ||
f89d2485 PH |
9297 | .vitem &*${addresses:*&<&'string'&>&*}*& |
9298 | .cindex "expansion" "RFC 2822 address handling" | |
9299 | .cindex "&%addresses%& expansion item" | |
9300 | The string (after expansion) is interpreted as a list of addresses in RFC | |
9301 | 2822 format, such as can be found in a &'To:'& or &'Cc:'& header line. The | |
9302 | operative address (&'local-part@domain'&) is extracted from each item, and the | |
9303 | result of the expansion is a colon-separated list, with appropriate | |
9304 | doubling of colons should any happen to be present in the email addresses. | |
9305 | Syntactically invalid RFC2822 address items are omitted from the output. | |
9306 | ||
9307 | It is possible to specify a character other than colon for the output | |
9308 | separator by starting the string with > followed by the new separator | |
9309 | character. For example: | |
9310 | .code | |
9311 | ${addresses:>& Chief <ceo@up.stairs>, sec@base.ment (dogsbody)} | |
9312 | .endd | |
9313 | expands to &`ceo@up.stairs&&sec@base.ment`&. Compare the &*address*& (singular) | |
9314 | expansion item, which extracts the working address from a single RFC2822 | |
9315 | address. See the &*filter*&, &*map*&, and &*reduce*& items for ways of | |
9316 | processing lists. | |
f89d2485 PH |
9317 | |
9318 | ||
9b371988 | 9319 | .vitem &*${base62:*&<&'digits'&>&*}*& |
0a4e3112 | 9320 | .cindex "&%base62%& expansion item" |
9b371988 | 9321 | .cindex "expansion" "conversion to base 62" |
168e428f | 9322 | The string must consist entirely of decimal digits. The number is converted to |
068aaea8 PH |
9323 | base 62 and output as a string of six characters, including leading zeros. In |
9324 | the few operating environments where Exim uses base 36 instead of base 62 for | |
9325 | its message identifiers (because those systems do not have case-sensitive file | |
9b371988 PH |
9326 | names), base 36 is used by this operator, despite its name. &*Note*&: Just to |
9327 | be absolutely clear: this is &'not'& base64 encoding. | |
9b371988 | 9328 | |
9b371988 | 9329 | .vitem &*${base62d:*&<&'base-62&~digits'&>&*}*& |
0a4e3112 | 9330 | .cindex "&%base62d%& expansion item" |
9b371988 | 9331 | .cindex "expansion" "conversion to base 62" |
068aaea8 PH |
9332 | The string must consist entirely of base-62 digits, or, in operating |
9333 | environments where Exim uses base 36 instead of base 62 for its message | |
9334 | identifiers, base-36 digits. The number is converted to decimal and output as a | |
9335 | string. | |
168e428f | 9336 | |
9b371988 PH |
9337 | .vitem &*${domain:*&<&'string'&>&*}*& |
9338 | .cindex "domain" "extraction" | |
9339 | .cindex "expansion" "domain extraction" | |
168e428f PH |
9340 | The string is interpreted as an RFC 2822 address and the domain is extracted |
9341 | from it. If the string does not parse successfully, the result is empty. | |
9342 | ||
9343 | ||
9b371988 PH |
9344 | .vitem &*${escape:*&<&'string'&>&*}*& |
9345 | .cindex "expansion" "escaping non-printing characters" | |
0a4e3112 | 9346 | .cindex "&%escape%& expansion item" |
168e428f PH |
9347 | If the string contains any non-printing characters, they are converted to |
9348 | escape sequences starting with a backslash. Whether characters with the most | |
9b371988 PH |
9349 | significant bit set (so-called &"8-bit characters"&) count as printing or not |
9350 | is controlled by the &%print_topbitchars%& option. | |
168e428f PH |
9351 | |
9352 | ||
9b371988 PH |
9353 | .vitem &*${eval:*&<&'string'&>&*}*&&~and&~&*${eval10:*&<&'string'&>&*}*& |
9354 | .cindex "expansion" "expression evaluation" | |
9355 | .cindex "expansion" "arithmetic expression" | |
4f578862 | 9356 | .cindex "&%eval%& expansion item" |
3cb1b51e PH |
9357 | These items supports simple arithmetic and bitwise logical operations in |
9358 | expansion strings. The string (after expansion) must be a conventional | |
9359 | arithmetic expression, but it is limited to basic arithmetic operators, bitwise | |
9360 | logical operators, and parentheses. All operations are carried out using | |
9361 | integer arithmetic. The operator priorities are as follows (the same as in the | |
9362 | C programming language): | |
f89d2485 PH |
9363 | .table2 70pt 300pt |
9364 | .irow &'highest:'& "not (~), negate (-)" | |
9365 | .irow "" "multiply (*), divide (/), remainder (%)" | |
9366 | .irow "" "plus (+), minus (-)" | |
9367 | .irow "" "shift-left (<<), shift-right (>>)" | |
9368 | .irow "" "and (&&)" | |
9369 | .irow "" "xor (^)" | |
9370 | .irow &'lowest:'& "or (|)" | |
3cb1b51e PH |
9371 | .endtable |
9372 | Binary operators with the same priority are evaluated from left to right. White | |
9373 | space is permitted before or after operators. | |
9374 | ||
9b371988 PH |
9375 | For &%eval%&, numbers may be decimal, octal (starting with &"0"&) or |
9376 | hexadecimal (starting with &"0x"&). For &%eval10%&, all numbers are taken as | |
db9452a9 PH |
9377 | decimal, even if they start with a leading zero; hexadecimal numbers are not |
9378 | permitted. This can be useful when processing numbers extracted from dates or | |
9379 | times, which often do have leading zeros. | |
9b371988 PH |
9380 | |
9381 | A number may be followed by &"K"& or &"M"& to multiply it by 1024 or 1024*1024, | |
168e428f | 9382 | respectively. Negative numbers are supported. The result of the computation is |
9b371988 PH |
9383 | a decimal representation of the answer (without &"K"& or &"M"&). For example: |
9384 | ||
9b371988 | 9385 | .display |
3cb1b51e PH |
9386 | &`${eval:1+1} `& yields 2 |
9387 | &`${eval:1+2*3} `& yields 7 | |
9388 | &`${eval:(1+2)*3} `& yields 9 | |
9389 | &`${eval:2+42%5} `& yields 4 | |
9390 | &`${eval:0xc&5} `& yields 4 | |
9391 | &`${eval:0xc|5} `& yields 13 | |
9392 | &`${eval:0xc^5} `& yields 9 | |
9393 | &`${eval:0xc>>1} `& yields 6 | |
9394 | &`${eval:0xc<<1} `& yields 24 | |
9395 | &`${eval:~255&0x1234} `& yields 4608 | |
9396 | &`${eval:-(~255&0x1234)} `& yields -4608 | |
9b371988 | 9397 | .endd |
9b371988 | 9398 | |
168e428f | 9399 | As a more realistic example, in an ACL you might have |
9b371988 | 9400 | .code |
168e428f PH |
9401 | deny message = Too many bad recipients |
9402 | condition = \ | |
9403 | ${if and { \ | |
9404 | {>{$rcpt_count}{10}} \ | |
9405 | { \ | |
9406 | < \ | |
9407 | {$recipients_count} \ | |
9408 | {${eval:$rcpt_count/2}} \ | |
9409 | } \ | |
9410 | }{yes}{no}} | |
9b371988 | 9411 | .endd |
168e428f PH |
9412 | The condition is true if there have been more than 10 RCPT commands and |
9413 | fewer than half of them have resulted in a valid recipient. | |
9414 | ||
9415 | ||
9b371988 PH |
9416 | .vitem &*${expand:*&<&'string'&>&*}*& |
9417 | .cindex "expansion" "re-expansion of substring" | |
9418 | The &%expand%& operator causes a string to be expanded for a second time. For | |
168e428f | 9419 | example, |
9b371988 PH |
9420 | .code |
9421 | ${expand:${lookup{$domain}dbm{/some/file}{$value}}} | |
9422 | .endd | |
9423 | first looks up a string in a file while expanding the operand for &%expand%&, | |
9424 | and then re-expands what it has found. | |
168e428f | 9425 | |
168e428f | 9426 | |
9b371988 PH |
9427 | .vitem &*${from_utf8:*&<&'string'&>&*}*& |
9428 | .cindex "Unicode" | |
9429 | .cindex "UTF-8" "conversion from" | |
9430 | .cindex "expansion" "UTF-8 conversion" | |
0a4e3112 | 9431 | .cindex "&%from_utf8%& expansion item" |
168e428f PH |
9432 | The world is slowly moving towards Unicode, although there are no standards for |
9433 | email yet. However, other applications (including some databases) are starting | |
9434 | to store data in Unicode, using UTF-8 encoding. This operator converts from a | |
9435 | UTF-8 string to an ISO-8859-1 string. UTF-8 code values greater than 255 are | |
9436 | converted to underscores. The input must be a valid UTF-8 string. If it is not, | |
9437 | the result is an undefined sequence of bytes. | |
9b371988 | 9438 | |
168e428f PH |
9439 | Unicode code points with values less than 256 are compatible with ASCII and |
9440 | ISO-8859-1 (also known as Latin-1). | |
9441 | For example, character 169 is the copyright symbol in both cases, though the | |
9442 | way it is encoded is different. In UTF-8, more than one byte is needed for | |
9443 | characters with code values greater than 127, whereas ISO-8859-1 is a | |
9444 | single-byte encoding (but thereby limited to 256 characters). This makes | |
9445 | translation from UTF-8 to ISO-8859-1 straightforward. | |
9446 | ||
9447 | ||
9b371988 PH |
9448 | .vitem &*${hash_*&<&'n'&>&*_*&<&'m'&>&*:*&<&'string'&>&*}*& |
9449 | .cindex "hash function" "textual" | |
9450 | .cindex "expansion" "textual hash" | |
9451 | The &%hash%& operator is a simpler interface to the hashing function that can | |
9452 | be used when the two parameters are fixed numbers (as opposed to strings that | |
168e428f | 9453 | change when expanded). The effect is the same as |
9b371988 PH |
9454 | .code |
9455 | ${hash{<n>}{<m>}{<string>}} | |
9456 | .endd | |
9457 | See the description of the general &%hash%& item above for details. The | |
9458 | abbreviation &%h%& can be used when &%hash%& is used as an operator. | |
168e428f PH |
9459 | |
9460 | ||
9461 | ||
9b371988 PH |
9462 | .vitem &*${hex2b64:*&<&'hexstring'&>&*}*& |
9463 | .cindex "base64 encoding" "conversion from hex" | |
9464 | .cindex "expansion" "hex to base64" | |
0a4e3112 | 9465 | .cindex "&%hex2b64%& expansion item" |
168e428f PH |
9466 | This operator converts a hex string into one that is base64 encoded. This can |
9467 | be useful for processing the output of the MD5 and SHA-1 hashing functions. | |
9468 | ||
9469 | ||
9b371988 PH |
9470 | .vitem &*${lc:*&<&'string'&>&*}*& |
9471 | .cindex "case forcing in strings" | |
9472 | .cindex "string" "case forcing" | |
9473 | .cindex "lower casing" | |
9474 | .cindex "expansion" "case forcing" | |
4f578862 | 9475 | .cindex "&%lc%& expansion item" |
168e428f | 9476 | This forces the letters in the string into lower-case, for example: |
9b371988 PH |
9477 | .code |
9478 | ${lc:$local_part} | |
9479 | .endd | |
9480 | ||
9481 | .vitem &*${length_*&<&'number'&>&*:*&<&'string'&>&*}*& | |
9482 | .cindex "expansion" "string truncation" | |
f89d2485 | 9483 | .cindex "&%length%& expansion item" |
9b371988 PH |
9484 | The &%length%& operator is a simpler interface to the &%length%& function that |
9485 | can be used when the parameter is a fixed number (as opposed to a string that | |
168e428f | 9486 | changes when expanded). The effect is the same as |
9b371988 PH |
9487 | .code |
9488 | ${length{<number>}{<string>}} | |
9489 | .endd | |
9490 | See the description of the general &%length%& item above for details. Note that | |
9491 | &%length%& is not the same as &%strlen%&. The abbreviation &%l%& can be used | |
9492 | when &%length%& is used as an operator. | |
168e428f | 9493 | |
168e428f | 9494 | |
9b371988 PH |
9495 | .vitem &*${local_part:*&<&'string'&>&*}*& |
9496 | .cindex "expansion" "local part extraction" | |
4f578862 | 9497 | .cindex "&%local_part%& expansion item" |
168e428f PH |
9498 | The string is interpreted as an RFC 2822 address and the local part is |
9499 | extracted from it. If the string does not parse successfully, the result is | |
9500 | empty. | |
9501 | ||
9502 | ||
9b371988 PH |
9503 | .vitem &*${mask:*&<&'IP&~address'&>&*/*&<&'bit&~count'&>&*}*& |
9504 | .cindex "masked IP address" | |
9505 | .cindex "IP address" "masking" | |
9506 | .cindex "CIDR notation" | |
9507 | .cindex "expansion" "IP address masking" | |
0a4e3112 | 9508 | .cindex "&%mask%& expansion item" |
168e428f PH |
9509 | If the form of the string to be operated on is not an IP address followed by a |
9510 | slash and an integer (that is, a network address in CIDR notation), the | |
9511 | expansion fails. Otherwise, this operator converts the IP address to binary, | |
9512 | masks off the least significant bits according to the bit count, and converts | |
9513 | the result back to text, with mask appended. For example, | |
9b371988 PH |
9514 | .code |
9515 | ${mask:10.111.131.206/28} | |
9516 | .endd | |
9517 | returns the string &"10.111.131.192/28"&. Since this operation is expected to | |
9518 | be mostly used for looking up masked addresses in files, the result for an IPv6 | |
168e428f PH |
9519 | address uses dots to separate components instead of colons, because colon |
9520 | terminates a key string in lsearch files. So, for example, | |
9b371988 PH |
9521 | .code |
9522 | ${mask:3ffe:ffff:836f:0a00:000a:0800:200a:c031/99} | |
9523 | .endd | |
168e428f | 9524 | returns the string |
9b371988 PH |
9525 | .code |
9526 | 3ffe.ffff.836f.0a00.000a.0800.2000.0000/99 | |
9527 | .endd | |
168e428f PH |
9528 | Letters in IPv6 addresses are always output in lower case. |
9529 | ||
9530 | ||
9b371988 PH |
9531 | .vitem &*${md5:*&<&'string'&>&*}*& |
9532 | .cindex "MD5 hash" | |
9533 | .cindex "expansion" "MD5 hash" | |
4f578862 | 9534 | .cindex "&%md5%& expansion item" |
9b371988 PH |
9535 | The &%md5%& operator computes the MD5 hash value of the string, and returns it |
9536 | as a 32-digit hexadecimal number, in which any letters are in lower case. | |
168e428f PH |
9537 | |
9538 | ||
9b371988 PH |
9539 | .vitem &*${nhash_*&<&'n'&>&*_*&<&'m'&>&*:*&<&'string'&>&*}*& |
9540 | .cindex "expansion" "numeric hash" | |
9541 | .cindex "hash function" "numeric" | |
9542 | The &%nhash%& operator is a simpler interface to the numeric hashing function | |
168e428f PH |
9543 | that can be used when the two parameters are fixed numbers (as opposed to |
9544 | strings that change when expanded). The effect is the same as | |
9b371988 PH |
9545 | .code |
9546 | ${nhash{<n>}{<m>}{<string>}} | |
9547 | .endd | |
9548 | See the description of the general &%nhash%& item above for details. | |
168e428f | 9549 | |
168e428f | 9550 | |
9b371988 PH |
9551 | .vitem &*${quote:*&<&'string'&>&*}*& |
9552 | .cindex "quoting" "in string expansions" | |
9553 | .cindex "expansion" "quoting" | |
0a4e3112 | 9554 | .cindex "&%quote%& expansion item" |
9b371988 | 9555 | The &%quote%& operator puts its argument into double quotes if it |
168e428f PH |
9556 | is an empty string or |
9557 | contains anything other than letters, digits, underscores, dots, and hyphens. | |
9558 | Any occurrences of double quotes and backslashes are escaped with a backslash. | |
9b371988 | 9559 | Newlines and carriage returns are converted to &`\n`& and &`\r`&, |
168e428f | 9560 | respectively For example, |
9b371988 PH |
9561 | .code |
9562 | ${quote:ab"*"cd} | |
9563 | .endd | |
168e428f | 9564 | becomes |
9b371988 PH |
9565 | .code |
9566 | "ab\"*\"cd" | |
9567 | .endd | |
168e428f PH |
9568 | The place where this is useful is when the argument is a substitution from a |
9569 | variable or a message header. | |
9570 | ||
9b371988 | 9571 | .vitem &*${quote_local_part:*&<&'string'&>&*}*& |
4f578862 | 9572 | .cindex "&%quote_local_part%& expansion item" |
9b371988 | 9573 | This operator is like &%quote%&, except that it quotes the string only if |
168e428f | 9574 | required to do so by the rules of RFC 2822 for quoting local parts. For |
9b371988 PH |
9575 | example, a plus sign would not cause quoting (but it would for &%quote%&). |
9576 | If you are creating a new email address from the contents of &$local_part$& | |
168e428f PH |
9577 | (or any other unknown data), you should always use this operator. |
9578 | ||
9579 | ||
9b371988 PH |
9580 | .vitem &*${quote_*&<&'lookup-type'&>&*:*&<&'string'&>&*}*& |
9581 | .cindex "quoting" "lookup-specific" | |
168e428f PH |
9582 | This operator applies lookup-specific quoting rules to the string. Each |
9583 | query-style lookup type has its own quoting rules which are described with | |
9b371988 PH |
9584 | the lookups in chapter &<<CHAPfdlookup>>&. For example, |
9585 | .code | |
9586 | ${quote_ldap:two * two} | |
9587 | .endd | |
168e428f | 9588 | returns |
9b371988 PH |
9589 | .code |
9590 | two%20%5C2A%20two | |
9591 | .endd | |
168e428f PH |
9592 | For single-key lookup types, no quoting is ever necessary and this operator |
9593 | yields an unchanged string. | |
9594 | ||
9595 | ||
0eb8eedd NM |
9596 | .vitem &*${randint:*&<&'n'&>&*}*& |
9597 | .cindex "random number" | |
9598 | This operator returns a somewhat random number which is less than the | |
9599 | supplied number and is at least 0. The quality of this randomness depends | |
9600 | on how Exim was built; the values are not suitable for keying material. | |
9601 | If Exim is linked against OpenSSL then RAND_pseudo_bytes() is used. | |
9602 | Otherwise, the implementation may be arc4random(), random() seeded by | |
9603 | srandomdev() or srandom(), or a custom implementation even weaker than | |
9604 | random(). | |
9605 | ||
9606 | ||
9b371988 PH |
9607 | .vitem &*${rfc2047:*&<&'string'&>&*}*& |
9608 | .cindex "expansion" "RFC 2047" | |
9609 | .cindex "RFC 2047" "expansion operator" | |
4f578862 | 9610 | .cindex "&%rfc2047%& expansion item" |
168e428f PH |
9611 | This operator encodes text according to the rules of RFC 2047. This is an |
9612 | encoding that is used in header lines to encode non-ASCII characters. It is | |
9613 | assumed that the input string is in the encoding specified by the | |
9b371988 PH |
9614 | &%headers_charset%& option, which defaults to ISO-8859-1. If the string |
9615 | contains only characters in the range 33&--126, and no instances of the | |
9616 | characters | |
9617 | .code | |
9618 | ? = ( ) < > @ , ; : \ " . [ ] _ | |
9619 | .endd | |
168e428f | 9620 | it is not modified. Otherwise, the result is the RFC 2047 encoding of the |
9b371988 | 9621 | string, using as many &"encoded words"& as necessary to encode all the |
168e428f PH |
9622 | characters. |
9623 | ||
9624 | ||
f89d2485 PH |
9625 | .vitem &*${rfc2047d:*&<&'string'&>&*}*& |
9626 | .cindex "expansion" "RFC 2047" | |
9627 | .cindex "RFC 2047" "decoding" | |
9628 | .cindex "&%rfc2047d%& expansion item" | |
9629 | This operator decodes strings that are encoded as per RFC 2047. Binary zero | |
9630 | bytes are replaced by question marks. Characters are converted into the | |
9631 | character set defined by &%headers_charset%&. Overlong RFC 2047 &"words"& are | |
9632 | not recognized unless &%check_rfc2047_length%& is set false. | |
595028e4 | 9633 | |
595028e4 PH |
9634 | &*Note*&: If you use &%$header%&_&'xxx'&&*:*& (or &%$h%&_&'xxx'&&*:*&) to |
9635 | access a header line, RFC 2047 decoding is done automatically. You do not need | |
9636 | to use this operator as well. | |
f89d2485 PH |
9637 | |
9638 | ||
168e428f | 9639 | |
db9452a9 PH |
9640 | .vitem &*${rxquote:*&<&'string'&>&*}*& |
9641 | .cindex "quoting" "in regular expressions" | |
9642 | .cindex "regular expressions" "quoting" | |
9643 | .cindex "&%rxquote%& expansion item" | |
9644 | The &%rxquote%& operator inserts a backslash before any non-alphanumeric | |
9645 | characters in its argument. This is useful when substituting the values of | |
9646 | variables or headers inside regular expressions. | |
9647 | ||
9648 | ||
9b371988 PH |
9649 | .vitem &*${sha1:*&<&'string'&>&*}*& |
9650 | .cindex "SHA-1 hash" | |
9651 | .cindex "expansion" "SHA-1 hashing" | |
4f578862 | 9652 | .cindex "&%sha2%& expansion item" |
9b371988 PH |
9653 | The &%sha1%& operator computes the SHA-1 hash value of the string, and returns |
9654 | it as a 40-digit hexadecimal number, in which any letters are in upper case. | |
168e428f PH |
9655 | |
9656 | ||
9b371988 PH |
9657 | .vitem &*${stat:*&<&'string'&>&*}*& |
9658 | .cindex "expansion" "statting a file" | |
9659 | .cindex "file" "extracting characteristics" | |
4f578862 | 9660 | .cindex "&%stat%& expansion item" |
9b371988 PH |
9661 | The string, after expansion, must be a file path. A call to the &[stat()]& |
9662 | function is made for this path. If &[stat()]& fails, an error occurs and the | |
168e428f | 9663 | expansion fails. If it succeeds, the data from the stat replaces the item, as a |
9b371988 PH |
9664 | series of <&'name'&>=<&'value'&> pairs, where the values are all numerical, |
9665 | except for the value of &"smode"&. The names are: &"mode"& (giving the mode as | |
9666 | a 4-digit octal number), &"smode"& (giving the mode in symbolic format as a | |
9667 | 10-character string, as for the &'ls'& command), &"inode"&, &"device"&, | |
9668 | &"links"&, &"uid"&, &"gid"&, &"size"&, &"atime"&, &"mtime"&, and &"ctime"&. You | |
9669 | can extract individual fields using the &%extract%& expansion item. | |
9670 | ||
9b371988 PH |
9671 | The use of the &%stat%& expansion in users' filter files can be locked out by |
9672 | the system administrator. &*Warning*&: The file size may be incorrect on 32-bit | |
068aaea8 | 9673 | systems for files larger than 2GB. |
168e428f | 9674 | |
9b371988 PH |
9675 | .vitem &*${str2b64:*&<&'string'&>&*}*& |
9676 | .cindex "expansion" "base64 encoding" | |
9677 | .cindex "base64 encoding" "in string expansion" | |
4f578862 | 9678 | .cindex "&%str2b64%& expansion item" |
168e428f PH |
9679 | This operator converts a string into one that is base64 encoded. |
9680 | ||
9681 | ||
9682 | ||
9b371988 PH |
9683 | .vitem &*${strlen:*&<&'string'&>&*}*& |
9684 | .cindex "expansion" "string length" | |
9685 | .cindex "string" "length in expansion" | |
4f578862 | 9686 | .cindex "&%strlen%& expansion item" |
168e428f | 9687 | The item is replace by the length of the expanded string, expressed as a |
9b371988 PH |
9688 | decimal number. &*Note*&: Do not confuse &%strlen%& with &%length%&. |
9689 | ||
9690 | ||
9691 | .vitem &*${substr_*&<&'start'&>&*_*&<&'length'&>&*:*&<&'string'&>&*}*& | |
4f578862 | 9692 | .cindex "&%substr%& expansion item" |
9b371988 PH |
9693 | .cindex "substring extraction" |
9694 | .cindex "expansion" "substring expansion" | |
9695 | The &%substr%& operator is a simpler interface to the &%substr%& function that | |
9696 | can be used when the two parameters are fixed numbers (as opposed to strings | |
9697 | that change when expanded). The effect is the same as | |
9698 | .code | |
9699 | ${substr{<start>}{<length>}{<string>}} | |
9700 | .endd | |
9701 | See the description of the general &%substr%& item above for details. The | |
9702 | abbreviation &%s%& can be used when &%substr%& is used as an operator. | |
9703 | ||
4f578862 PH |
9704 | .vitem &*${time_eval:*&<&'string'&>&*}*& |
9705 | .cindex "&%time_eval%& expansion item" | |
9706 | .cindex "time interval" "decoding" | |
9707 | This item converts an Exim time interval such as &`2d4h5m`& into a number of | |
9708 | seconds. | |
4f578862 | 9709 | |
9b371988 | 9710 | .vitem &*${time_interval:*&<&'string'&>&*}*& |
4f578862 | 9711 | .cindex "&%time_interval%& expansion item" |
9b371988 | 9712 | .cindex "time interval" "formatting" |
168e428f PH |
9713 | The argument (after sub-expansion) must be a sequence of decimal digits that |
9714 | represents an interval of time as a number of seconds. It is converted into a | |
9715 | number of larger units and output in Exim's normal time format, for example, | |
9b371988 | 9716 | &`1w3d4h2m6s`&. |
168e428f | 9717 | |
9b371988 PH |
9718 | .vitem &*${uc:*&<&'string'&>&*}*& |
9719 | .cindex "case forcing in strings" | |
9720 | .cindex "string" "case forcing" | |
9721 | .cindex "upper casing" | |
9722 | .cindex "expansion" "case forcing" | |
4f578862 | 9723 | .cindex "&%uc%& expansion item" |
168e428f | 9724 | This forces the letters in the string into upper-case. |
9b371988 | 9725 | .endlist |
168e428f PH |
9726 | |
9727 | ||
9728 | ||
9729 | ||
9730 | ||
9731 | ||
9b371988 | 9732 | .section "Expansion conditions" "SECTexpcond" |
3cb1b51e | 9733 | .scindex IIDexpcond "expansion" "conditions" |
9b371988 | 9734 | The following conditions are available for testing by the &%${if%& construct |
168e428f PH |
9735 | while expanding strings: |
9736 | ||
9b371988 PH |
9737 | .vlist |
9738 | .vitem &*!*&<&'condition'&> | |
9739 | .cindex "expansion" "negating a condition" | |
4f578862 | 9740 | .cindex "negation" "in expansion condition" |
168e428f PH |
9741 | Preceding any condition with an exclamation mark negates the result of the |
9742 | condition. | |
9743 | ||
9b371988 PH |
9744 | .vitem <&'symbolic&~operator'&>&~&*{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
9745 | .cindex "numeric comparison" | |
9746 | .cindex "expansion" "numeric comparison" | |
168e428f PH |
9747 | There are a number of symbolic operators for doing numeric comparisons. They |
9748 | are: | |
9b371988 PH |
9749 | .display |
9750 | &`= `& equal | |
9751 | &`== `& equal | |
9752 | &`> `& greater | |
9753 | &`>= `& greater or equal | |
9754 | &`< `& less | |
9755 | &`<= `& less or equal | |
9756 | .endd | |
9757 | For example: | |
9758 | .code | |
9759 | ${if >{$message_size}{10M} ... | |
9760 | .endd | |
168e428f PH |
9761 | Note that the general negation operator provides for inequality testing. The |
9762 | two strings must take the form of optionally signed decimal integers, | |
9b371988 PH |
9763 | optionally followed by one of the letters &"K"& or &"M"& (in either upper or |
9764 | lower case), signifying multiplication by 1024 or 1024*1024, respectively. | |
f89d2485 PH |
9765 | As a special case, the numerical value of an empty string is taken as |
9766 | zero. | |
168e428f | 9767 | |
f3766eb5 NM |
9768 | .vitem &*bool&~{*&<&'string'&>&*}*& |
9769 | .cindex "expansion" "boolean parsing" | |
9770 | .cindex "&%bool%& expansion condition" | |
9771 | This condition turns a string holding a true or false representation into | |
9772 | a boolean state. It parses &"true"&, &"false"&, &"yes"& and &"no"& | |
9773 | (case-insensitively); also positive integer numbers map to true if non-zero, | |
9774 | false if zero. Leading whitespace is ignored. | |
9775 | All other string values will result in expansion failure. | |
9776 | ||
9777 | When combined with ACL variables, this expansion condition will let you | |
9778 | make decisions in one place and act on those decisions in another place. | |
9779 | For example, | |
9780 | .code | |
9781 | ${if bool{$acl_m_privileged_sender} ... | |
9782 | .endd | |
9783 | ||
9b371988 PH |
9784 | .vitem &*crypteq&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
9785 | .cindex "expansion" "encrypted comparison" | |
f89d2485 | 9786 | .cindex "encrypted strings, comparing" |
4f578862 | 9787 | .cindex "&%crypteq%& expansion condition" |
168e428f | 9788 | This condition is included in the Exim binary if it is built to support any |
9b371988 PH |
9789 | authentication mechanisms (see chapter &<<CHAPSMTPAUTH>>&). Otherwise, it is |
9790 | necessary to define SUPPORT_CRYPTEQ in &_Local/Makefile_& to get &%crypteq%& | |
168e428f | 9791 | included in the binary. |
9b371988 PH |
9792 | |
9793 | The &%crypteq%& condition has two arguments. The first is encrypted and | |
9794 | compared against the second, which is already encrypted. The second string may | |
9795 | be in the LDAP form for storing encrypted strings, which starts with the | |
9796 | encryption type in curly brackets, followed by the data. If the second string | |
9797 | does not begin with &"{"& it is assumed to be encrypted with &[crypt()]& or | |
9798 | &[crypt16()]& (see below), since such strings cannot begin with &"{"&. | |
9799 | Typically this will be a field from a password file. An example of an encrypted | |
9800 | string in LDAP form is: | |
9801 | .code | |
9802 | {md5}CY9rzUYh03PK3k6DJie09g== | |
9803 | .endd | |
168e428f PH |
9804 | If such a string appears directly in an expansion, the curly brackets have to |
9805 | be quoted, because they are part of the expansion syntax. For example: | |
9b371988 PH |
9806 | .code |
9807 | ${if crypteq {test}{\{md5\}CY9rzUYh03PK3k6DJie09g==}{yes}{no}} | |
9808 | .endd | |
168e428f PH |
9809 | The following encryption types (whose names are matched case-independently) are |
9810 | supported: | |
9b371988 PH |
9811 | |
9812 | .ilist | |
9813 | .cindex "MD5 hash" | |
9814 | .cindex "base64 encoding" "in encrypted password" | |
9815 | &%{md5}%& computes the MD5 digest of the first string, and expresses this as | |
168e428f PH |
9816 | printable characters to compare with the remainder of the second string. If the |
9817 | length of the comparison string is 24, Exim assumes that it is base64 encoded | |
9818 | (as in the above example). If the length is 32, Exim assumes that it is a | |
9819 | hexadecimal encoding of the MD5 digest. If the length not 24 or 32, the | |
9820 | comparison fails. | |
9821 | ||
9b371988 PH |
9822 | .next |
9823 | .cindex "SHA-1 hash" | |
9824 | &%{sha1}%& computes the SHA-1 digest of the first string, and expresses this as | |
168e428f PH |
9825 | printable characters to compare with the remainder of the second string. If the |
9826 | length of the comparison string is 28, Exim assumes that it is base64 encoded. | |
9827 | If the length is 40, Exim assumes that it is a hexadecimal encoding of the | |
9828 | SHA-1 digest. If the length is not 28 or 40, the comparison fails. | |
9829 | ||
9b371988 PH |
9830 | .next |
9831 | .cindex "&[crypt()]&" | |
9832 | &%{crypt}%& calls the &[crypt()]& function, which traditionally used to use | |
9833 | only the first eight characters of the password. However, in modern operating | |
168e428f PH |
9834 | systems this is no longer true, and in many cases the entire password is used, |
9835 | whatever its length. | |
3cb1b51e | 9836 | |
9b371988 PH |
9837 | .next |
9838 | .cindex "&[crypt16()]&" | |
f89d2485 | 9839 | &%{crypt16}%& calls the &[crypt16()]& function, which was originally created to |
3cb1b51e PH |
9840 | use up to 16 characters of the password in some operating systems. Again, in |
9841 | modern operating systems, more characters may be used. | |
9b371988 | 9842 | .endlist |
3cb1b51e PH |
9843 | Exim has its own version of &[crypt16()]&, which is just a double call to |
9844 | &[crypt()]&. For operating systems that have their own version, setting | |
9b371988 | 9845 | HAVE_CRYPT16 in &_Local/Makefile_& when building Exim causes it to use the |
168e428f | 9846 | operating system version instead of its own. This option is set by default in |
9b371988 PH |
9847 | the OS-dependent &_Makefile_& for those operating systems that are known to |
9848 | support &[crypt16()]&. | |
9849 | ||
3cb1b51e PH |
9850 | Some years after Exim's &[crypt16()]& was implemented, a user discovered that |
9851 | it was not using the same algorithm as some operating systems' versions. It | |
9852 | turns out that as well as &[crypt16()]& there is a function called | |
9853 | &[bigcrypt()]& in some operating systems. This may or may not use the same | |
9854 | algorithm, and both of them may be different to Exim's built-in &[crypt16()]&. | |
9855 | ||
9856 | However, since there is now a move away from the traditional &[crypt()]& | |
9857 | functions towards using SHA1 and other algorithms, tidying up this area of | |
9858 | Exim is seen as very low priority. | |
9859 | ||
9860 | If you do not put a encryption type (in curly brackets) in a &%crypteq%& | |
9861 | comparison, the default is usually either &`{crypt}`& or &`{crypt16}`&, as | |
9862 | determined by the setting of DEFAULT_CRYPT in &_Local/Makefile_&. The default | |
9863 | default is &`{crypt}`&. Whatever the default, you can always use either | |
9864 | function by specifying it explicitly in curly brackets. | |
168e428f | 9865 | |
9b371988 PH |
9866 | .vitem &*def:*&<&'variable&~name'&> |
9867 | .cindex "expansion" "checking for empty variable" | |
4f578862 | 9868 | .cindex "&%def%& expansion condition" |
9b371988 PH |
9869 | The &%def%& condition must be followed by the name of one of the expansion |
9870 | variables defined in section &<<SECTexpvar>>&. The condition is true if the | |
9871 | variable does not contain the empty string. For example: | |
9872 | .code | |
9873 | ${if def:sender_ident {from $sender_ident}} | |
9874 | .endd | |
9875 | Note that the variable name is given without a leading &%$%& character. If the | |
168e428f PH |
9876 | variable does not exist, the expansion fails. |
9877 | ||
9b371988 PH |
9878 | .vitem "&*def:header_*&<&'header&~name'&>&*:*&&~&~or&~&&& |
9879 | &~&*def:h_*&<&'header&~name'&>&*:*&" | |
9880 | .cindex "expansion" "checking header line existence" | |
168e428f PH |
9881 | This condition is true if a message is being processed and the named header |
9882 | exists in the message. For example, | |
9b371988 PH |
9883 | .code |
9884 | ${if def:header_reply-to:{$h_reply-to:}{$h_from:}} | |
9885 | .endd | |
9886 | &*Note*&: No &%$%& appears before &%header_%& or &%h_%& in the condition, and | |
9887 | the header name must be terminated by a colon if white space does not follow. | |
9888 | ||
f89d2485 PH |
9889 | .vitem &*eq&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& &&& |
9890 | &*eqi&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& | |
9b371988 PH |
9891 | .cindex "string" "comparison" |
9892 | .cindex "expansion" "string comparison" | |
4f578862 | 9893 | .cindex "&%eq%& expansion condition" |
4f578862 | 9894 | .cindex "&%eqi%& expansion condition" |
168e428f | 9895 | The two substrings are first expanded. The condition is true if the two |
f89d2485 PH |
9896 | resulting strings are identical. For &%eq%& the comparison includes the case of |
9897 | letters, whereas for &%eqi%& the comparison is case-independent. | |
168e428f | 9898 | |
9b371988 PH |
9899 | .vitem &*exists&~{*&<&'file&~name'&>&*}*& |
9900 | .cindex "expansion" "file existence test" | |
9901 | .cindex "file" "existence test" | |
4f578862 | 9902 | .cindex "&%exists%&, expansion condition" |
168e428f PH |
9903 | The substring is first expanded and then interpreted as an absolute path. The |
9904 | condition is true if the named file (or directory) exists. The existence test | |
9b371988 | 9905 | is done by calling the &[stat()]& function. The use of the &%exists%& test in |
168e428f PH |
9906 | users' filter files may be locked out by the system administrator. |
9907 | ||
9b371988 PH |
9908 | .vitem &*first_delivery*& |
9909 | .cindex "delivery" "first" | |
9910 | .cindex "first delivery" | |
9911 | .cindex "expansion" "first delivery test" | |
4f578862 | 9912 | .cindex "&%first_delivery%& expansion condition" |
168e428f PH |
9913 | This condition, which has no data, is true during a message's first delivery |
9914 | attempt. It is false during any subsequent delivery attempts. | |
9915 | ||
168e428f | 9916 | |
f89d2485 PH |
9917 | .vitem "&*forall{*&<&'a list'&>&*}{*&<&'a condition'&>&*}*&" &&& |
9918 | "&*forany{*&<&'a list'&>&*}{*&<&'a condition'&>&*}*&" | |
9919 | .cindex "list" "iterative conditions" | |
9920 | .cindex "expansion" "&*forall*& condition" | |
9921 | .cindex "expansion" "&*forany*& condition" | |
9922 | .vindex "&$item$&" | |
9923 | These conditions iterate over a list. The first argument is expanded to form | |
9924 | the list. By default, the list separator is a colon, but it can be changed by | |
9925 | the normal method. The second argument is interpreted as a condition that is to | |
9926 | be applied to each item in the list in turn. During the interpretation of the | |
9927 | condition, the current list item is placed in a variable called &$item$&. | |
9928 | .ilist | |
9929 | For &*forany*&, interpretation stops if the condition is true for any item, and | |
9930 | the result of the whole condition is true. If the condition is false for all | |
9931 | items in the list, the overall condition is false. | |
9932 | .next | |
9933 | For &*forall*&, interpretation stops if the condition is false for any item, | |
9934 | and the result of the whole condition is false. If the condition is true for | |
9935 | all items in the list, the overall condition is true. | |
9936 | .endlist | |
9937 | Note that negation of &*forany*& means that the condition must be false for all | |
9938 | items for the overall condition to succeed, and negation of &*forall*& means | |
9939 | that the condition must be false for at least one item. In this example, the | |
9940 | list separator is changed to a comma: | |
9941 | .code | |
9942 | ${if forany{<, $recipients}{match{$item}{^user3@}}{yes}{no}} | |
9943 | .endd | |
9944 | The value of &$item$& is saved and restored while &*forany*& or &*forall*& is | |
9945 | being processed, to enable these expansion items to be nested. | |
f89d2485 PH |
9946 | |
9947 | ||
9948 | .vitem &*ge&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& &&& | |
9949 | &*gei&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& | |
9b371988 PH |
9950 | .cindex "string" "comparison" |
9951 | .cindex "expansion" "string comparison" | |
f89d2485 | 9952 | .cindex "&%ge%& expansion condition" |
4f578862 | 9953 | .cindex "&%gei%& expansion condition" |
168e428f | 9954 | The two substrings are first expanded. The condition is true if the first |
f89d2485 | 9955 | string is lexically greater than or equal to the second string. For &%ge%& the |
9b371988 | 9956 | comparison includes the case of letters, whereas for &%gei%& the comparison is |
168e428f PH |
9957 | case-independent. |
9958 | ||
f89d2485 PH |
9959 | .vitem &*gt&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& &&& |
9960 | &*gti&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& | |
9b371988 PH |
9961 | .cindex "string" "comparison" |
9962 | .cindex "expansion" "string comparison" | |
f89d2485 | 9963 | .cindex "&%gt%& expansion condition" |
4f578862 | 9964 | .cindex "&%gti%& expansion condition" |
168e428f | 9965 | The two substrings are first expanded. The condition is true if the first |
f89d2485 | 9966 | string is lexically greater than the second string. For &%gt%& the comparison |
9b371988 | 9967 | includes the case of letters, whereas for &%gti%& the comparison is |
168e428f PH |
9968 | case-independent. |
9969 | ||
f89d2485 PH |
9970 | .vitem &*isip&~{*&<&'string'&>&*}*& &&& |
9971 | &*isip4&~{*&<&'string'&>&*}*& &&& | |
9972 | &*isip6&~{*&<&'string'&>&*}*& | |
9b371988 PH |
9973 | .cindex "IP address" "testing string format" |
9974 | .cindex "string" "testing for IP address" | |
f89d2485 PH |
9975 | .cindex "&%isip%& expansion condition" |
9976 | .cindex "&%isip4%& expansion condition" | |
4f578862 | 9977 | .cindex "&%isip6%& expansion condition" |
168e428f | 9978 | The substring is first expanded, and then tested to see if it has the form of |
9b371988 | 9979 | an IP address. Both IPv4 and IPv6 addresses are valid for &%isip%&, whereas |
595028e4 PH |
9980 | &%isip4%& and &%isip6%& test specifically for IPv4 or IPv6 addresses. |
9981 | ||
595028e4 PH |
9982 | For an IPv4 address, the test is for four dot-separated components, each of |
9983 | which consists of from one to three digits. For an IPv6 address, up to eight | |
9984 | colon-separated components are permitted, each containing from one to four | |
9985 | hexadecimal digits. There may be fewer than eight components if an empty | |
9986 | component (adjacent colons) is present. Only one empty component is permitted. | |
9987 | ||
9988 | &*Note*&: The checks are just on the form of the address; actual numerical | |
9989 | values are not considered. Thus, for example, 999.999.999.999 passes the IPv4 | |
9990 | check. The main use of these tests is to distinguish between IP addresses and | |
9991 | host names, or between IPv4 and IPv6 addresses. For example, you could use | |
9b371988 PH |
9992 | .code |
9993 | ${if isip4{$sender_host_address}... | |
9994 | .endd | |
595028e4 | 9995 | to test which IP version an incoming SMTP connection is using. |
168e428f | 9996 | |
9b371988 PH |
9997 | .vitem &*ldapauth&~{*&<&'ldap&~query'&>&*}*& |
9998 | .cindex "LDAP" "use for authentication" | |
9999 | .cindex "expansion" "LDAP authentication test" | |
4f578862 | 10000 | .cindex "&%ldapauth%& expansion condition" |
168e428f | 10001 | This condition supports user authentication using LDAP. See section |
9b371988 | 10002 | &<<SECTldap>>& for details of how to use LDAP in lookups and the syntax of |
168e428f PH |
10003 | queries. For this use, the query must contain a user name and password. The |
10004 | query itself is not used, and can be empty. The condition is true if the | |
10005 | password is not empty, and the user name and password are accepted by the LDAP | |
10006 | server. An empty password is rejected without calling LDAP because LDAP binds | |
10007 | with an empty password are considered anonymous regardless of the username, and | |
9b371988 PH |
10008 | will succeed in most configurations. See chapter &<<CHAPSMTPAUTH>>& for details |
10009 | of SMTP authentication, and chapter &<<CHAPplaintext>>& for an example of how | |
168e428f PH |
10010 | this can be used. |
10011 | ||
10012 | ||
f89d2485 PH |
10013 | .vitem &*le&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& &&& |
10014 | &*lei&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& | |
9b371988 PH |
10015 | .cindex "string" "comparison" |
10016 | .cindex "expansion" "string comparison" | |
f89d2485 | 10017 | .cindex "&%le%& expansion condition" |
4f578862 | 10018 | .cindex "&%lei%& expansion condition" |
168e428f | 10019 | The two substrings are first expanded. The condition is true if the first |
f89d2485 | 10020 | string is lexically less than or equal to the second string. For &%le%& the |
9b371988 | 10021 | comparison includes the case of letters, whereas for &%lei%& the comparison is |
168e428f PH |
10022 | case-independent. |
10023 | ||
f89d2485 PH |
10024 | .vitem &*lt&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& &&& |
10025 | &*lti&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& | |
9b371988 PH |
10026 | .cindex "string" "comparison" |
10027 | .cindex "expansion" "string comparison" | |
f89d2485 | 10028 | .cindex "&%lt%& expansion condition" |
4f578862 | 10029 | .cindex "&%lti%& expansion condition" |
168e428f | 10030 | The two substrings are first expanded. The condition is true if the first |
f89d2485 | 10031 | string is lexically less than the second string. For &%lt%& the comparison |
9b371988 | 10032 | includes the case of letters, whereas for &%lti%& the comparison is |
168e428f PH |
10033 | case-independent. |
10034 | ||
10035 | ||
9b371988 PH |
10036 | .vitem &*match&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
10037 | .cindex "expansion" "regular expression comparison" | |
10038 | .cindex "regular expressions" "match in expanded string" | |
0a4e3112 | 10039 | .cindex "&%match%& expansion condition" |
168e428f PH |
10040 | The two substrings are first expanded. The second is then treated as a regular |
10041 | expression and applied to the first. Because of the pre-expansion, if the | |
10042 | regular expression contains dollar, or backslash characters, they must be | |
10043 | escaped. Care must also be taken if the regular expression contains braces | |
10044 | (curly brackets). A closing brace must be escaped so that it is not taken as a | |
9b371988 PH |
10045 | premature termination of <&'string2'&>. The easiest approach is to use the |
10046 | &`\N`& feature to disable expansion of the regular expression. | |
168e428f | 10047 | For example, |
9b371988 PH |
10048 | .code |
10049 | ${if match {$local_part}{\N^\d{3}\N} ... | |
10050 | .endd | |
168e428f PH |
10051 | If the whole expansion string is in double quotes, further escaping of |
10052 | backslashes is also required. | |
9b371988 | 10053 | |
168e428f PH |
10054 | The condition is true if the regular expression match succeeds. |
10055 | The regular expression is not required to begin with a circumflex | |
10056 | metacharacter, but if there is no circumflex, the expression is not anchored, | |
10057 | and it may match anywhere in the subject, not just at the start. If you want | |
9b371988 | 10058 | the pattern to match at the end of the subject, you must include the &`$`& |
168e428f | 10059 | metacharacter at an appropriate point. |
9b371988 PH |
10060 | |
10061 | .cindex "numerical variables (&$1$& &$2$& etc)" "in &%if%& expansion" | |
10062 | At the start of an &%if%& expansion the values of the numeric variable | |
10063 | substitutions &$1$& etc. are remembered. Obeying a &%match%& condition that | |
168e428f PH |
10064 | succeeds causes them to be reset to the substrings of that condition and they |
10065 | will have these values during the expansion of the success string. At the end | |
9b371988 PH |
10066 | of the &%if%& expansion, the previous values are restored. After testing a |
10067 | combination of conditions using &%or%&, the subsequent values of the numeric | |
168e428f PH |
10068 | variables are those of the condition that succeeded. |
10069 | ||
9b371988 | 10070 | .vitem &*match_address&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
4f578862 | 10071 | .cindex "&%match_address%& expansion condition" |
9b371988 | 10072 | See &*match_local_part*&. |
168e428f | 10073 | |
9b371988 | 10074 | .vitem &*match_domain&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
4f578862 | 10075 | .cindex "&%match_domain%& expansion condition" |
9b371988 | 10076 | See &*match_local_part*&. |
168e428f | 10077 | |
9b371988 | 10078 | .vitem &*match_ip&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
4f578862 | 10079 | .cindex "&%match_ip%& expansion condition" |
068aaea8 PH |
10080 | This condition matches an IP address to a list of IP address patterns. It must |
10081 | be followed by two argument strings. The first (after expansion) must be an IP | |
10082 | address or an empty string. The second (after expansion) is a restricted host | |
10083 | list that can match only an IP address, not a host name. For example: | |
9b371988 | 10084 | .code |
068aaea8 | 10085 | ${if match_ip{$sender_host_address}{1.2.3.4:5.6.7.8}{...}{...}} |
9b371988 | 10086 | .endd |
068aaea8 | 10087 | The specific types of host list item that are permitted in the list are: |
068aaea8 | 10088 | |
9b371988 PH |
10089 | .ilist |
10090 | An IP address, optionally with a CIDR mask. | |
10091 | .next | |
10092 | A single asterisk, which matches any IP address. | |
10093 | .next | |
10094 | An empty item, which matches only if the IP address is empty. This could be | |
068aaea8 PH |
10095 | useful for testing for a locally submitted message or one from specific hosts |
10096 | in a single test such as | |
9b371988 | 10097 | . ==== As this is a nested list, any displays it contains must be indented |
f89d2485 PH |
10098 | . ==== as otherwise they are too far to the left. This comment applies to |
10099 | . ==== the use of xmlto plus fop. There's no problem when formatting with | |
10100 | . ==== sdop, with or without the extra indent. | |
9b371988 PH |
10101 | .code |
10102 | ${if match_ip{$sender_host_address}{:4.3.2.1:...}{...}{...}} | |
10103 | .endd | |
068aaea8 | 10104 | where the first item in the list is the empty string. |
9b371988 PH |
10105 | .next |
10106 | The item @[] matches any of the local host's interface addresses. | |
10107 | .next | |
f89d2485 PH |
10108 | Single-key lookups are assumed to be like &"net-"& style lookups in host lists, |
10109 | even if &`net-`& is not specified. There is never any attempt to turn the IP | |
10110 | address into a host name. The most common type of linear search for | |
10111 | &*match_ip*& is likely to be &*iplsearch*&, in which the file can contain CIDR | |
10112 | masks. For example: | |
10113 | .code | |
10114 | ${if match_ip{$sender_host_address}{iplsearch;/some/file}... | |
10115 | .endd | |
10116 | It is of course possible to use other kinds of lookup, and in such a case, you | |
10117 | do need to specify the &`net-`& prefix if you want to specify a specific | |
10118 | address mask, for example: | |
9b371988 | 10119 | .code |
f89d2485 | 10120 | ${if match_ip{$sender_host_address}{net24-dbm;/some/file}... |
9b371988 | 10121 | .endd |
f89d2485 PH |
10122 | However, unless you are combining a &%match_ip%& condition with others, it is |
10123 | just as easy to use the fact that a lookup is itself a condition, and write: | |
db9452a9 | 10124 | .code |
f89d2485 | 10125 | ${lookup{${mask:$sender_host_address/24}}dbm{/a/file}... |
db9452a9 | 10126 | .endd |
9b371988 PH |
10127 | .endlist ilist |
10128 | ||
10129 | Consult section &<<SECThoslispatip>>& for further details of these patterns. | |
9b371988 PH |
10130 | |
10131 | .vitem &*match_local_part&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& | |
10132 | .cindex "domain list" "in expansion condition" | |
10133 | .cindex "address list" "in expansion condition" | |
f89d2485 | 10134 | .cindex "local part" "list, in expansion condition" |
4f578862 | 10135 | .cindex "&%match_local_part%& expansion condition" |
9b371988 | 10136 | This condition, together with &%match_address%& and &%match_domain%&, make it |
068aaea8 PH |
10137 | possible to test domain, address, and local part lists within expansions. Each |
10138 | condition requires two arguments: an item and a list to match. A trivial | |
10139 | example is: | |
9b371988 PH |
10140 | .code |
10141 | ${if match_domain{a.b.c}{x.y.z:a.b.c:p.q.r}{yes}{no}} | |
10142 | .endd | |
168e428f PH |
10143 | In each case, the second argument may contain any of the allowable items for a |
10144 | list of the appropriate type. Also, because the second argument (after | |
10145 | expansion) is a standard form of list, it is possible to refer to a named list. | |
10146 | Thus, you can use conditions like this: | |
9b371988 PH |
10147 | .code |
10148 | ${if match_domain{$domain}{+local_domains}{... | |
10149 | .endd | |
10150 | .cindex "&`+caseful`&" | |
10151 | For address lists, the matching starts off caselessly, but the &`+caseful`& | |
168e428f PH |
10152 | item can be used, as in all address lists, to cause subsequent items to |
10153 | have their local parts matched casefully. Domains are always matched | |
10154 | caselessly. | |
9b371988 PH |
10155 | |
10156 | &*Note*&: Host lists are &'not'& supported in this way. This is because | |
168e428f | 10157 | hosts have two identities: a name and an IP address, and it is not clear |
068aaea8 | 10158 | how to specify cleanly how such a test would work. However, IP addresses can be |
9b371988 PH |
10159 | matched using &%match_ip%&. |
10160 | ||
10161 | .vitem &*pam&~{*&<&'string1'&>&*:*&<&'string2'&>&*:...}*& | |
10162 | .cindex "PAM authentication" | |
10163 | .cindex "AUTH" "with PAM" | |
10164 | .cindex "Solaris" "PAM support" | |
10165 | .cindex "expansion" "PAM authentication test" | |
4f578862 | 10166 | .cindex "&%pam%& expansion condition" |
9b371988 PH |
10167 | &'Pluggable Authentication Modules'& |
10168 | (&url(http://www.kernel.org/pub/linux/libs/pam/)) are a facility that is | |
10169 | available in the latest releases of Solaris and in some GNU/Linux | |
10170 | distributions. The Exim support, which is intended for use in conjunction with | |
10171 | the SMTP AUTH command, is available only if Exim is compiled with | |
10172 | .code | |
10173 | SUPPORT_PAM=yes | |
10174 | .endd | |
10175 | in &_Local/Makefile_&. You probably need to add &%-lpam%& to EXTRALIBS, and | |
10176 | in some releases of GNU/Linux &%-ldl%& is also needed. | |
10177 | ||
168e428f | 10178 | The argument string is first expanded, and the result must be a |
068aaea8 | 10179 | colon-separated list of strings. Leading and trailing white space is ignored. |
9b371988 PH |
10180 | The PAM module is initialized with the service name &"exim"& and the user name |
10181 | taken from the first item in the colon-separated data string (<&'string1'&>). | |
10182 | The remaining items in the data string are passed over in response to requests | |
10183 | from the authentication function. In the simple case there will only be one | |
10184 | request, for a password, so the data consists of just two strings. | |
10185 | ||
168e428f PH |
10186 | There can be problems if any of the strings are permitted to contain colon |
10187 | characters. In the usual way, these have to be doubled to avoid being taken as | |
9b371988 | 10188 | separators. If the data is being inserted from a variable, the &%sg%& expansion |
168e428f PH |
10189 | item can be used to double any existing colons. For example, the configuration |
10190 | of a LOGIN authenticator might contain this setting: | |
9b371988 | 10191 | .code |
db9452a9 | 10192 | server_condition = ${if pam{$auth1:${sg{$auth2}{:}{::}}}} |
9b371988 | 10193 | .endd |
168e428f | 10194 | For a PLAIN authenticator you could use: |
9b371988 | 10195 | .code |
db9452a9 | 10196 | server_condition = ${if pam{$auth2:${sg{$auth3}{:}{::}}}} |
9b371988 | 10197 | .endd |
168e428f PH |
10198 | In some operating systems, PAM authentication can be done only from a process |
10199 | running as root. Since Exim is running as the Exim user when receiving | |
10200 | messages, this means that PAM cannot be used directly in those systems. | |
9b371988 PH |
10201 | A patched version of the &'pam_unix'& module that comes with the |
10202 | Linux PAM package is available from &url(http://www.e-admin.de/pam_exim/). | |
168e428f PH |
10203 | The patched module allows one special uid/gid combination, in addition to root, |
10204 | to authenticate. If you build the patched module to allow the Exim user and | |
10205 | group, PAM can then be used from an Exim authenticator. | |
10206 | ||
10207 | ||
9b371988 PH |
10208 | .vitem &*pwcheck&~{*&<&'string1'&>&*:*&<&'string2'&>&*}*& |
10209 | .cindex "&'pwcheck'& daemon" | |
10210 | .cindex "Cyrus" | |
10211 | .cindex "expansion" "&'pwcheck'& authentication test" | |
4f578862 | 10212 | .cindex "&%pwcheck%& expansion condition" |
9b371988 | 10213 | This condition supports user authentication using the Cyrus &'pwcheck'& daemon. |
168e428f | 10214 | This is one way of making it possible for passwords to be checked by a process |
9b371988 PH |
10215 | that is not running as root. &*Note*&: The use of &'pwcheck'& is now |
10216 | deprecated. Its replacement is &'saslauthd'& (see below). | |
10217 | ||
168e428f | 10218 | The pwcheck support is not included in Exim by default. You need to specify |
9b371988 | 10219 | the location of the pwcheck daemon's socket in &_Local/Makefile_& before |
168e428f | 10220 | building Exim. For example: |
9b371988 PH |
10221 | .code |
10222 | CYRUS_PWCHECK_SOCKET=/var/pwcheck/pwcheck | |
10223 | .endd | |
168e428f PH |
10224 | You do not need to install the full Cyrus software suite in order to use |
10225 | the pwcheck daemon. You can compile and install just the daemon alone | |
9b371988 PH |
10226 | from the Cyrus SASL library. Ensure that &'exim'& is the only user that has |
10227 | access to the &_/var/pwcheck_& directory. | |
10228 | ||
10229 | The &%pwcheck%& condition takes one argument, which must be the user name and | |
168e428f PH |
10230 | password, separated by a colon. For example, in a LOGIN authenticator |
10231 | configuration, you might have this: | |
9b371988 | 10232 | .code |
db9452a9 | 10233 | server_condition = ${if pwcheck{$auth1:$auth2}} |
9b371988 | 10234 | .endd |
e2f03231 TK |
10235 | Again, for a PLAIN authenticator configuration, this would be: |
10236 | .code | |
10237 | server_condition = ${if pwcheck{$auth2:$auth3}} | |
10238 | .endd | |
9b371988 PH |
10239 | .vitem &*queue_running*& |
10240 | .cindex "queue runner" "detecting when delivering from" | |
10241 | .cindex "expansion" "queue runner test" | |
f89d2485 | 10242 | .cindex "&%queue_running%& expansion condition" |
168e428f PH |
10243 | This condition, which has no data, is true during delivery attempts that are |
10244 | initiated by queue runner processes, and false otherwise. | |
10245 | ||
10246 | ||
9b371988 PH |
10247 | .vitem &*radius&~{*&<&'authentication&~string'&>&*}*& |
10248 | .cindex "Radius" | |
10249 | .cindex "expansion" "Radius authentication" | |
3cb1b51e | 10250 | .cindex "&%radius%& expansion condition" |
168e428f | 10251 | Radius authentication (RFC 2865) is supported in a similar way to PAM. You must |
9b371988 | 10252 | set RADIUS_CONFIG_FILE in &_Local/Makefile_& to specify the location of |
168e428f PH |
10253 | the Radius client configuration file in order to build Exim with Radius |
10254 | support. | |
9b371988 | 10255 | |
9b371988 | 10256 | With just that one setting, Exim expects to be linked with the &%radiusclient%& |
068aaea8 PH |
10257 | library, using the original API. If you are using release 0.4.0 or later of |
10258 | this library, you need to set | |
9b371988 | 10259 | .code |
068aaea8 | 10260 | RADIUS_LIB_TYPE=RADIUSCLIENTNEW |
9b371988 PH |
10261 | .endd |
10262 | in &_Local/Makefile_& when building Exim. You can also link Exim with the | |
10263 | &%libradius%& library that comes with FreeBSD. To do this, set | |
9b371988 PH |
10264 | .code |
10265 | RADIUS_LIB_TYPE=RADLIB | |
10266 | .endd | |
10267 | in &_Local/Makefile_&, in addition to setting RADIUS_CONFIGURE_FILE. | |
168e428f PH |
10268 | You may also have to supply a suitable setting in EXTRALIBS so that the |
10269 | Radius library can be found when Exim is linked. | |
9b371988 | 10270 | |
168e428f PH |
10271 | The string specified by RADIUS_CONFIG_FILE is expanded and passed to the |
10272 | Radius client library, which calls the Radius server. The condition is true if | |
9b371988 PH |
10273 | the authentication is successful. For example: |
10274 | .code | |
db9452a9 | 10275 | server_condition = ${if radius{<arguments>}} |
9b371988 PH |
10276 | .endd |
10277 | ||
10278 | ||
10279 | .vitem "&*saslauthd&~{{*&<&'user'&>&*}{*&<&'password'&>&*}&&& | |
10280 | {*&<&'service'&>&*}{*&<&'realm'&>&*}}*&" | |
10281 | .cindex "&'saslauthd'& daemon" | |
10282 | .cindex "Cyrus" | |
10283 | .cindex "expansion" "&'saslauthd'& authentication test" | |
4f578862 | 10284 | .cindex "&%saslauthd%& expansion condition" |
9b371988 PH |
10285 | This condition supports user authentication using the Cyrus &'saslauthd'& |
10286 | daemon. This replaces the older &'pwcheck'& daemon, which is now deprecated. | |
168e428f PH |
10287 | Using this daemon is one way of making it possible for passwords to be checked |
10288 | by a process that is not running as root. | |
9b371988 | 10289 | |
168e428f | 10290 | The saslauthd support is not included in Exim by default. You need to specify |
9b371988 | 10291 | the location of the saslauthd daemon's socket in &_Local/Makefile_& before |
168e428f | 10292 | building Exim. For example: |
9b371988 PH |
10293 | .code |
10294 | CYRUS_SASLAUTHD_SOCKET=/var/state/saslauthd/mux | |
10295 | .endd | |
168e428f PH |
10296 | You do not need to install the full Cyrus software suite in order to use |
10297 | the saslauthd daemon. You can compile and install just the daemon alone | |
10298 | from the Cyrus SASL library. | |
168e428f | 10299 | |
9b371988 PH |
10300 | Up to four arguments can be supplied to the &%saslauthd%& condition, but only |
10301 | two are mandatory. For example: | |
10302 | .code | |
db9452a9 | 10303 | server_condition = ${if saslauthd{{$auth1}{$auth2}}} |
9b371988 | 10304 | .endd |
168e428f PH |
10305 | The service and the realm are optional (which is why the arguments are enclosed |
10306 | in their own set of braces). For details of the meaning of the service and | |
10307 | realm, and how to run the daemon, consult the Cyrus documentation. | |
9b371988 | 10308 | .endlist vlist |
168e428f PH |
10309 | |
10310 | ||
10311 | ||
f89d2485 | 10312 | .section "Combining expansion conditions" "SECID84" |
9b371988 PH |
10313 | .cindex "expansion" "combining conditions" |
10314 | Several conditions can be tested at once by combining them using the &%and%& | |
10315 | and &%or%& combination conditions. Note that &%and%& and &%or%& are complete | |
10316 | conditions on their own, and precede their lists of sub-conditions. Each | |
10317 | sub-condition must be enclosed in braces within the overall braces that contain | |
10318 | the list. No repetition of &%if%& is used. | |
168e428f PH |
10319 | |
10320 | ||
9b371988 PH |
10321 | .vlist |
10322 | .vitem &*or&~{{*&<&'cond1'&>&*}{*&<&'cond2'&>&*}...}*& | |
10323 | .cindex "&""or""& expansion condition" | |
10324 | .cindex "expansion" "&""or""& of conditions" | |
168e428f PH |
10325 | The sub-conditions are evaluated from left to right. The condition is true if |
10326 | any one of the sub-conditions is true. | |
10327 | For example, | |
9b371988 PH |
10328 | .code |
10329 | ${if or {{eq{$local_part}{spqr}}{eq{$domain}{testing.com}}}... | |
10330 | .endd | |
168e428f | 10331 | When a true sub-condition is found, the following ones are parsed but not |
9b371988 | 10332 | evaluated. If there are several &"match"& sub-conditions the values of the |
168e428f PH |
10333 | numeric variables afterwards are taken from the first one that succeeds. |
10334 | ||
9b371988 PH |
10335 | .vitem &*and&~{{*&<&'cond1'&>&*}{*&<&'cond2'&>&*}...}*& |
10336 | .cindex "&""and""& expansion condition" | |
10337 | .cindex "expansion" "&""and""& of conditions" | |
168e428f | 10338 | The sub-conditions are evaluated from left to right. The condition is true if |
9b371988 | 10339 | all of the sub-conditions are true. If there are several &"match"& |
168e428f PH |
10340 | sub-conditions, the values of the numeric variables afterwards are taken from |
10341 | the last one. When a false sub-condition is found, the following ones are | |
10342 | parsed but not evaluated. | |
9b371988 | 10343 | .endlist |
3cb1b51e | 10344 | .ecindex IIDexpcond |
168e428f PH |
10345 | |
10346 | ||
10347 | ||
10348 | ||
9b371988 | 10349 | .section "Expansion variables" "SECTexpvar" |
f89d2485 | 10350 | .cindex "expansion" "variables, list of" |
168e428f PH |
10351 | This section contains an alphabetical list of all the expansion variables. Some |
10352 | of them are available only when Exim is compiled with specific options such as | |
10353 | support for TLS or the content scanning extension. | |
10354 | ||
9b371988 PH |
10355 | .vlist |
10356 | .vitem "&$0$&, &$1$&, etc" | |
10357 | .cindex "numerical variables (&$1$& &$2$& etc)" | |
10358 | When a &%match%& expansion condition succeeds, these variables contain the | |
168e428f | 10359 | captured substrings identified by the regular expression during subsequent |
f89d2485 PH |
10360 | processing of the success string of the containing &%if%& expansion item. |
10361 | However, they do not retain their values afterwards; in fact, their previous | |
10362 | values are restored at the end of processing an &%if%& item. The numerical | |
10363 | variables may also be set externally by some other matching process which | |
10364 | precedes the expansion of the string. For example, the commands available in | |
10365 | Exim filter files include an &%if%& command with its own regular expression | |
10366 | matching condition. | |
168e428f | 10367 | |
f89d2485 | 10368 | .vitem "&$acl_c...$&" |
9b371988 | 10369 | Values can be placed in these variables by the &%set%& modifier in an ACL. They |
f89d2485 PH |
10370 | can be given any name that starts with &$acl_c$& and is at least six characters |
10371 | long, but the sixth character must be either a digit or an underscore. For | |
10372 | example: &$acl_c5$&, &$acl_c_mycount$&. The values of the &$acl_c...$& | |
10373 | variables persist throughout the lifetime of an SMTP connection. They can be | |
10374 | used to pass information between ACLs and between different invocations of the | |
10375 | same ACL. When a message is received, the values of these variables are saved | |
10376 | with the message, and can be accessed by filters, routers, and transports | |
168e428f PH |
10377 | during subsequent delivery. |
10378 | ||
f89d2485 PH |
10379 | .vitem "&$acl_m...$&" |
10380 | These variables are like the &$acl_c...$& variables, except that their values | |
10381 | are reset after a message has been received. Thus, if several messages are | |
10382 | received in one SMTP connection, &$acl_m...$& values are not passed on from one | |
10383 | message to the next, as &$acl_c...$& values are. The &$acl_m...$& variables are | |
10384 | also reset by MAIL, RSET, EHLO, HELO, and after starting a TLS session. When a | |
10385 | message is received, the values of these variables are saved with the message, | |
10386 | and can be accessed by filters, routers, and transports during subsequent | |
10387 | delivery. | |
f89d2485 | 10388 | |
9b371988 | 10389 | .vitem &$acl_verify_message$& |
f89d2485 | 10390 | .vindex "&$acl_verify_message$&" |
068aaea8 PH |
10391 | After an address verification has failed, this variable contains the failure |
10392 | message. It retains its value for use in subsequent modifiers. The message can | |
10393 | be preserved by coding like this: | |
9b371988 | 10394 | .code |
068aaea8 PH |
10395 | warn !verify = sender |
10396 | set acl_m0 = $acl_verify_message | |
9b371988 PH |
10397 | .endd |
10398 | You can use &$acl_verify_message$& during the expansion of the &%message%& or | |
10399 | &%log_message%& modifiers, to include information about the verification | |
10400 | failure. | |
9b371988 PH |
10401 | |
10402 | .vitem &$address_data$& | |
f89d2485 | 10403 | .vindex "&$address_data$&" |
9b371988 | 10404 | This variable is set by means of the &%address_data%& option in routers. The |
168e428f PH |
10405 | value then remains with the address while it is processed by subsequent routers |
10406 | and eventually a transport. If the transport is handling multiple addresses, | |
9b371988 PH |
10407 | the value from the first address is used. See chapter &<<CHAProutergeneric>>& |
10408 | for more details. &*Note*&: The contents of &$address_data$& are visible in | |
10409 | user filter files. | |
10410 | ||
10411 | If &$address_data$& is set when the routers are called from an ACL to verify | |
168e428f PH |
10412 | a recipient address, the final value is still in the variable for subsequent |
10413 | conditions and modifiers of the ACL statement. If routing the address caused it | |
10414 | to be redirected to just one address, the child address is also routed as part | |
9b371988 | 10415 | of the verification, and in this case the final value of &$address_data$& is |
168e428f | 10416 | from the child's routing. |
9b371988 PH |
10417 | |
10418 | If &$address_data$& is set when the routers are called from an ACL to verify a | |
168e428f | 10419 | sender address, the final value is also preserved, but this time in |
9b371988 | 10420 | &$sender_address_data$&, to distinguish it from data from a recipient |
168e428f | 10421 | address. |
9b371988 | 10422 | |
168e428f PH |
10423 | In both cases (recipient and sender verification), the value does not persist |
10424 | after the end of the current ACL statement. If you want to preserve | |
10425 | these values for longer, you can save them in ACL variables. | |
10426 | ||
9b371988 | 10427 | .vitem &$address_file$& |
f89d2485 | 10428 | .vindex "&$address_file$&" |
168e428f PH |
10429 | When, as a result of aliasing, forwarding, or filtering, a message is directed |
10430 | to a specific file, this variable holds the name of the file when the transport | |
10431 | is running. At other times, the variable is empty. For example, using the | |
9b371988 PH |
10432 | default configuration, if user &%r2d2%& has a &_.forward_& file containing |
10433 | .code | |
10434 | /home/r2d2/savemail | |
10435 | .endd | |
10436 | then when the &(address_file)& transport is running, &$address_file$& | |
f89d2485 | 10437 | contains the text string &`/home/r2d2/savemail`&. |
9b371988 PH |
10438 | .cindex "Sieve filter" "value of &$address_file$&" |
10439 | For Sieve filters, the value may be &"inbox"& or a relative folder name. It is | |
168e428f PH |
10440 | then up to the transport configuration to generate an appropriate absolute path |
10441 | to the relevant file. | |
10442 | ||
9b371988 | 10443 | .vitem &$address_pipe$& |
f89d2485 | 10444 | .vindex "&$address_pipe$&" |
168e428f PH |
10445 | When, as a result of aliasing or forwarding, a message is directed to a pipe, |
10446 | this variable holds the pipe command when the transport is running. | |
10447 | ||
4f578862 | 10448 | .vitem "&$auth1$& &-- &$auth3$&" |
f89d2485 | 10449 | .vindex "&$auth1$&, &$auth2$&, etc" |
4f578862 PH |
10450 | These variables are used in SMTP authenticators (see chapters |
10451 | &<<CHAPplaintext>>&&--&<<CHAPspa>>&). Elsewhere, they are empty. | |
4f578862 | 10452 | |
9b371988 PH |
10453 | .vitem &$authenticated_id$& |
10454 | .cindex "authentication" "id" | |
f89d2485 | 10455 | .vindex "&$authenticated_id$&" |
168e428f PH |
10456 | When a server successfully authenticates a client it may be configured to |
10457 | preserve some of the authentication information in the variable | |
9b371988 PH |
10458 | &$authenticated_id$& (see chapter &<<CHAPSMTPAUTH>>&). For example, a |
10459 | user/password authenticator configuration might preserve the user name for use | |
10460 | in the routers. Note that this is not the same information that is saved in | |
db9452a9 | 10461 | &$sender_host_authenticated$&. |
3cb1b51e | 10462 | When a message is submitted locally (that is, not over a TCP connection) |
db9452a9 PH |
10463 | the value of &$authenticated_id$& is normally the login name of the calling |
10464 | process. However, a trusted user can override this by means of the &%-oMai%& | |
3cb1b51e | 10465 | command line option. |
db9452a9 PH |
10466 | |
10467 | ||
10468 | ||
9b371988 PH |
10469 | |
10470 | .vitem &$authenticated_sender$& | |
10471 | .cindex "sender" "authenticated" | |
10472 | .cindex "authentication" "sender" | |
10473 | .cindex "AUTH" "on MAIL command" | |
f89d2485 | 10474 | .vindex "&$authenticated_sender$&" |
168e428f PH |
10475 | When acting as a server, Exim takes note of the AUTH= parameter on an incoming |
10476 | SMTP MAIL command if it believes the sender is sufficiently trusted, as | |
9b371988 PH |
10477 | described in section &<<SECTauthparamail>>&. Unless the data is the string |
10478 | &"<>"&, it is set as the authenticated sender of the message, and the value is | |
10479 | available during delivery in the &$authenticated_sender$& variable. If the | |
10480 | sender is not trusted, Exim accepts the syntax of AUTH=, but ignores the data. | |
10481 | ||
f89d2485 | 10482 | .vindex "&$qualify_domain$&" |
168e428f | 10483 | When a message is submitted locally (that is, not over a TCP connection), the |
9b371988 | 10484 | value of &$authenticated_sender$& is an address constructed from the login |
db9452a9 PH |
10485 | name of the calling process and &$qualify_domain$&, except that a trusted user |
10486 | can override this by means of the &%-oMas%& command line option. | |
9b371988 PH |
10487 | |
10488 | ||
10489 | .vitem &$authentication_failed$& | |
10490 | .cindex "authentication" "failure" | |
f89d2485 | 10491 | .vindex "&$authentication_failed$&" |
9b371988 PH |
10492 | This variable is set to &"1"& in an Exim server if a client issues an AUTH |
10493 | command that does not succeed. Otherwise it is set to &"0"&. This makes it | |
10494 | possible to distinguish between &"did not try to authenticate"& | |
10495 | (&$sender_host_authenticated$& is empty and &$authentication_failed$& is set to | |
10496 | &"0"&) and &"tried to authenticate but failed"& (&$sender_host_authenticated$& | |
10497 | is empty and &$authentication_failed$& is set to &"1"&). Failure includes any | |
168e428f PH |
10498 | negative response to an AUTH command, including (for example) an attempt to use |
10499 | an undefined mechanism. | |
10500 | ||
9b371988 PH |
10501 | .vitem &$body_linecount$& |
10502 | .cindex "message body" "line count" | |
10503 | .cindex "body of message" "line count" | |
f89d2485 | 10504 | .vindex "&$body_linecount$&" |
168e428f | 10505 | When a message is being received or delivered, this variable contains the |
9b371988 | 10506 | number of lines in the message's body. See also &$message_linecount$&. |
168e428f | 10507 | |
9b371988 PH |
10508 | .vitem &$body_zerocount$& |
10509 | .cindex "message body" "binary zero count" | |
10510 | .cindex "body of message" "binary zero count" | |
10511 | .cindex "binary zero" "in message body" | |
f89d2485 | 10512 | .vindex "&$body_zerocount$&" |
168e428f PH |
10513 | When a message is being received or delivered, this variable contains the |
10514 | number of binary zero bytes in the message's body. | |
10515 | ||
9b371988 | 10516 | .vitem &$bounce_recipient$& |
f89d2485 | 10517 | .vindex "&$bounce_recipient$&" |
168e428f PH |
10518 | This is set to the recipient address of a bounce message while Exim is creating |
10519 | it. It is useful if a customized bounce message text file is in use (see | |
9b371988 | 10520 | chapter &<<CHAPemsgcust>>&). |
168e428f | 10521 | |
9b371988 | 10522 | .vitem &$bounce_return_size_limit$& |
f89d2485 | 10523 | .vindex "&$bounce_return_size_limit$&" |
9b371988 | 10524 | This contains the value set in the &%bounce_return_size_limit%& option, rounded |
168e428f | 10525 | up to a multiple of 1000. It is useful when a customized error message text |
9b371988 | 10526 | file is in use (see chapter &<<CHAPemsgcust>>&). |
168e428f | 10527 | |
9b371988 PH |
10528 | .vitem &$caller_gid$& |
10529 | .cindex "gid (group id)" "caller" | |
f89d2485 | 10530 | .vindex "&$caller_gid$&" |
168e428f PH |
10531 | The real group id under which the process that called Exim was running. This is |
10532 | not the same as the group id of the originator of a message (see | |
9b371988 | 10533 | &$originator_gid$&). If Exim re-execs itself, this variable in the new |
168e428f PH |
10534 | incarnation normally contains the Exim gid. |
10535 | ||
9b371988 PH |
10536 | .vitem &$caller_uid$& |
10537 | .cindex "uid (user id)" "caller" | |
f89d2485 | 10538 | .vindex "&$caller_uid$&" |
168e428f PH |
10539 | The real user id under which the process that called Exim was running. This is |
10540 | not the same as the user id of the originator of a message (see | |
9b371988 | 10541 | &$originator_uid$&). If Exim re-execs itself, this variable in the new |
168e428f PH |
10542 | incarnation normally contains the Exim uid. |
10543 | ||
9b371988 | 10544 | .vitem &$compile_date$& |
f89d2485 | 10545 | .vindex "&$compile_date$&" |
168e428f PH |
10546 | The date on which the Exim binary was compiled. |
10547 | ||
9b371988 | 10548 | .vitem &$compile_number$& |
f89d2485 | 10549 | .vindex "&$compile_number$&" |
168e428f PH |
10550 | The building process for Exim keeps a count of the number |
10551 | of times it has been compiled. This serves to distinguish different | |
10552 | compilations of the same version of the program. | |
10553 | ||
9b371988 | 10554 | .vitem &$demime_errorlevel$& |
f89d2485 | 10555 | .vindex "&$demime_errorlevel$&" |
168e428f | 10556 | This variable is available when Exim is compiled with |
9b371988 PH |
10557 | the content-scanning extension and the obsolete &%demime%& condition. For |
10558 | details, see section &<<SECTdemimecond>>&. | |
168e428f | 10559 | |
9b371988 | 10560 | .vitem &$demime_reason$& |
f89d2485 | 10561 | .vindex "&$demime_reason$&" |
168e428f | 10562 | This variable is available when Exim is compiled with the |
9b371988 PH |
10563 | content-scanning extension and the obsolete &%demime%& condition. For details, |
10564 | see section &<<SECTdemimecond>>&. | |
168e428f | 10565 | |
595028e4 PH |
10566 | .vitem &$dnslist_domain$& &&& |
10567 | &$dnslist_matched$& &&& | |
10568 | &$dnslist_text$& &&& | |
10569 | &$dnslist_value$& | |
f89d2485 | 10570 | .vindex "&$dnslist_domain$&" |
595028e4 | 10571 | .vindex "&$dnslist_matched$&" |
f89d2485 | 10572 | .vindex "&$dnslist_text$&" |
f89d2485 | 10573 | .vindex "&$dnslist_value$&" |
595028e4 PH |
10574 | .cindex "black list (DNS)" |
10575 | When a DNS (black) list lookup succeeds, these variables are set to contain | |
10576 | the following data from the lookup: the list's domain name, the key that was | |
10577 | looked up, the contents of any associated TXT record, and the value from the | |
10578 | main A record. See section &<<SECID204>>& for more details. | |
168e428f | 10579 | |
9b371988 | 10580 | .vitem &$domain$& |
f89d2485 | 10581 | .vindex "&$domain$&" |
068aaea8 | 10582 | When an address is being routed, or delivered on its own, this variable |
3cb1b51e PH |
10583 | contains the domain. Uppercase letters in the domain are converted into lower |
10584 | case for &$domain$&. | |
3cb1b51e PH |
10585 | |
10586 | Global address rewriting happens when a message is received, so the value of | |
10587 | &$domain$& during routing and delivery is the value after rewriting. &$domain$& | |
10588 | is set during user filtering, but not during system filtering, because a | |
10589 | message may have many recipients and the system filter is called just once. | |
9b371988 | 10590 | |
168e428f | 10591 | When more than one address is being delivered at once (for example, several |
9b371988 | 10592 | RCPT commands in one SMTP delivery), &$domain$& is set only if they all |
168e428f | 10593 | have the same domain. Transports can be restricted to handling only one domain |
9b371988 | 10594 | at a time if the value of &$domain$& is required at transport time &-- this is |
168e428f | 10595 | the default for local transports. For further details of the environment in |
9b371988 PH |
10596 | which local transports are run, see chapter &<<CHAPenvironment>>&. |
10597 | ||
0a4e3112 | 10598 | .oindex "&%delay_warning_condition%&" |
168e428f | 10599 | At the end of a delivery, if all deferred addresses have the same domain, it is |
9b371988 PH |
10600 | set in &$domain$& during the expansion of &%delay_warning_condition%&. |
10601 | ||
10602 | The &$domain$& variable is also used in some other circumstances: | |
10603 | ||
10604 | .ilist | |
10605 | When an ACL is running for a RCPT command, &$domain$& contains the domain of | |
10606 | the recipient address. The domain of the &'sender'& address is in | |
10607 | &$sender_address_domain$& at both MAIL time and at RCPT time. &$domain$& is not | |
068aaea8 PH |
10608 | normally set during the running of the MAIL ACL. However, if the sender address |
10609 | is verified with a callout during the MAIL ACL, the sender domain is placed in | |
9b371988 PH |
10610 | &$domain$& during the expansions of &%hosts%&, &%interface%&, and &%port%& in |
10611 | the &(smtp)& transport. | |
10612 | ||
10613 | .next | |
10614 | When a rewrite item is being processed (see chapter &<<CHAPrewrite>>&), | |
10615 | &$domain$& contains the domain portion of the address that is being rewritten; | |
10616 | it can be used in the expansion of the replacement address, for example, to | |
10617 | rewrite domains by file lookup. | |
10618 | ||
10619 | .next | |
10620 | With one important exception, whenever a domain list is being scanned, | |
10621 | &$domain$& contains the subject domain. &*Exception*&: When a domain list in | |
10622 | a &%sender_domains%& condition in an ACL is being processed, the subject domain | |
10623 | is in &$sender_address_domain$& and not in &$domain$&. It works this way so | |
168e428f | 10624 | that, in a RCPT ACL, the sender domain list can be dependent on the |
9b371988 | 10625 | recipient domain (which is what is in &$domain$& at this time). |
168e428f | 10626 | |
9b371988 PH |
10627 | .next |
10628 | .cindex "ETRN" "value of &$domain$&" | |
0a4e3112 | 10629 | .oindex "&%smtp_etrn_command%&" |
9b371988 PH |
10630 | When the &%smtp_etrn_command%& option is being expanded, &$domain$& contains |
10631 | the complete argument of the ETRN command (see section &<<SECTETRN>>&). | |
10632 | .endlist | |
168e428f PH |
10633 | |
10634 | ||
9b371988 | 10635 | .vitem &$domain_data$& |
f89d2485 | 10636 | .vindex "&$domain_data$&" |
9b371988 | 10637 | When the &%domains%& option on a router matches a domain by |
168e428f | 10638 | means of a lookup, the data read by the lookup is available during the running |
9b371988 | 10639 | of the router as &$domain_data$&. In addition, if the driver routes the |
168e428f PH |
10640 | address to a transport, the value is available in that transport. If the |
10641 | transport is handling multiple addresses, the value from the first address is | |
10642 | used. | |
9b371988 PH |
10643 | |
10644 | &$domain_data$& is also set when the &%domains%& condition in an ACL matches a | |
168e428f PH |
10645 | domain by means of a lookup. The data read by the lookup is available during |
10646 | the rest of the ACL statement. In all other situations, this variable expands | |
10647 | to nothing. | |
10648 | ||
9b371988 | 10649 | .vitem &$exim_gid$& |
f89d2485 | 10650 | .vindex "&$exim_gid$&" |
168e428f PH |
10651 | This variable contains the numerical value of the Exim group id. |
10652 | ||
9b371988 | 10653 | .vitem &$exim_path$& |
f89d2485 | 10654 | .vindex "&$exim_path$&" |
168e428f PH |
10655 | This variable contains the path to the Exim binary. |
10656 | ||
9b371988 | 10657 | .vitem &$exim_uid$& |
f89d2485 | 10658 | .vindex "&$exim_uid$&" |
168e428f PH |
10659 | This variable contains the numerical value of the Exim user id. |
10660 | ||
9b371988 | 10661 | .vitem &$found_extension$& |
f89d2485 | 10662 | .vindex "&$found_extension$&" |
168e428f | 10663 | This variable is available when Exim is compiled with the |
9b371988 PH |
10664 | content-scanning extension and the obsolete &%demime%& condition. For details, |
10665 | see section &<<SECTdemimecond>>&. | |
168e428f | 10666 | |
9b371988 | 10667 | .vitem &$header_$&<&'name'&> |
068aaea8 PH |
10668 | This is not strictly an expansion variable. It is expansion syntax for |
10669 | inserting the message header line with the given name. Note that the name must | |
10670 | be terminated by colon or white space, because it may contain a wide variety of | |
9b371988 | 10671 | characters. Note also that braces must &'not'& be used. |
168e428f | 10672 | |
9b371988 | 10673 | .vitem &$home$& |
f89d2485 | 10674 | .vindex "&$home$&" |
9b371988 PH |
10675 | When the &%check_local_user%& option is set for a router, the user's home |
10676 | directory is placed in &$home$& when the check succeeds. In particular, this | |
168e428f PH |
10677 | means it is set during the running of users' filter files. A router may also |
10678 | explicitly set a home directory for use by a transport; this can be overridden | |
10679 | by a setting on the transport itself. | |
9b371988 PH |
10680 | |
10681 | When running a filter test via the &%-bf%& option, &$home$& is set to the value | |
168e428f PH |
10682 | of the environment variable HOME. |
10683 | ||
9b371988 | 10684 | .vitem &$host$& |
f89d2485 | 10685 | .vindex "&$host$&" |
db9452a9 PH |
10686 | If a router assigns an address to a transport (any transport), and passes a |
10687 | list of hosts with the address, the value of &$host$& when the transport starts | |
10688 | to run is the name of the first host on the list. Note that this applies both | |
10689 | to local and remote transports. | |
9b371988 PH |
10690 | |
10691 | .cindex "transport" "filter" | |
10692 | .cindex "filter" "transport filter" | |
db9452a9 PH |
10693 | For the &(smtp)& transport, if there is more than one host, the value of |
10694 | &$host$& changes as the transport works its way through the list. In | |
10695 | particular, when the &(smtp)& transport is expanding its options for encryption | |
10696 | using TLS, or for specifying a transport filter (see chapter | |
10697 | &<<CHAPtransportgeneric>>&), &$host$& contains the name of the host to which it | |
10698 | is connected. | |
10699 | ||
10700 | When used in the client part of an authenticator configuration (see chapter | |
10701 | &<<CHAPSMTPAUTH>>&), &$host$& contains the name of the server to which the | |
10702 | client is connected. | |
db9452a9 | 10703 | |
9b371988 PH |
10704 | |
10705 | .vitem &$host_address$& | |
f89d2485 | 10706 | .vindex "&$host_address$&" |
9b371988 PH |
10707 | This variable is set to the remote host's IP address whenever &$host$& is set |
10708 | for a remote connection. It is also set to the IP address that is being checked | |
10709 | when the &%ignore_target_hosts%& option is being processed. | |
10710 | ||
10711 | .vitem &$host_data$& | |
f89d2485 | 10712 | .vindex "&$host_data$&" |
9b371988 PH |
10713 | If a &%hosts%& condition in an ACL is satisfied by means of a lookup, the |
10714 | result of the lookup is made available in the &$host_data$& variable. This | |
168e428f | 10715 | allows you, for example, to do things like this: |
9b371988 PH |
10716 | .code |
10717 | deny hosts = net-lsearch;/some/file | |
10718 | message = $host_data | |
10719 | .endd | |
10720 | .vitem &$host_lookup_deferred$& | |
f89d2485 PH |
10721 | .cindex "host name" "lookup, failure of" |
10722 | .vindex "&$host_lookup_deferred$&" | |
9b371988 | 10723 | This variable normally contains &"0"&, as does &$host_lookup_failed$&. When a |
168e428f PH |
10724 | message comes from a remote host and there is an attempt to look up the host's |
10725 | name from its IP address, and the attempt is not successful, one of these | |
9b371988 | 10726 | variables is set to &"1"&. |
168e428f | 10727 | |
9b371988 PH |
10728 | .ilist |
10729 | If the lookup receives a definite negative response (for example, a DNS lookup | |
10730 | succeeded, but no records were found), &$host_lookup_failed$& is set to &"1"&. | |
10731 | ||
10732 | .next | |
10733 | If there is any kind of problem during the lookup, such that Exim cannot | |
168e428f | 10734 | tell whether or not the host name is defined (for example, a timeout for a DNS |
9b371988 PH |
10735 | lookup), &$host_lookup_deferred$& is set to &"1"&. |
10736 | .endlist ilist | |
10737 | ||
168e428f PH |
10738 | Looking up a host's name from its IP address consists of more than just a |
10739 | single reverse lookup. Exim checks that a forward lookup of at least one of the | |
10740 | names it receives from a reverse lookup yields the original IP address. If this | |
10741 | is not the case, Exim does not accept the looked up name(s), and | |
9b371988 | 10742 | &$host_lookup_failed$& is set to &"1"&. Thus, being able to find a name from an |
168e428f PH |
10743 | IP address (for example, the existence of a PTR record in the DNS) is not |
10744 | sufficient on its own for the success of a host name lookup. If the reverse | |
10745 | lookup succeeds, but there is a lookup problem such as a timeout when checking | |
9b371988 PH |
10746 | the result, the name is not accepted, and &$host_lookup_deferred$& is set to |
10747 | &"1"&. See also &$sender_host_name$&. | |
168e428f | 10748 | |
9b371988 | 10749 | .vitem &$host_lookup_failed$& |
f89d2485 | 10750 | .vindex "&$host_lookup_failed$&" |
9b371988 | 10751 | See &$host_lookup_deferred$&. |
168e428f PH |
10752 | |
10753 | ||
9b371988 | 10754 | .vitem &$inode$& |
f89d2485 | 10755 | .vindex "&$inode$&" |
9b371988 PH |
10756 | The only time this variable is set is while expanding the &%directory_file%& |
10757 | option in the &(appendfile)& transport. The variable contains the inode number | |
168e428f PH |
10758 | of the temporary file which is about to be renamed. It can be used to construct |
10759 | a unique name for the file. | |
10760 | ||
9b371988 | 10761 | .vitem &$interface_address$& |
f89d2485 | 10762 | .vindex "&$interface_address$&" |
3cb1b51e | 10763 | This is an obsolete name for &$received_ip_address$&. |
168e428f | 10764 | |
9b371988 | 10765 | .vitem &$interface_port$& |
f89d2485 | 10766 | .vindex "&$interface_port$&" |
3cb1b51e | 10767 | This is an obsolete name for &$received_port$&. |
f89d2485 | 10768 | |
f89d2485 PH |
10769 | .vitem &$item$& |
10770 | .vindex "&$item$&" | |
10771 | This variable is used during the expansion of &*forall*& and &*forany*& | |
0b5038ed | 10772 | conditions (see section &<<SECTexpcond>>&), and &*filter*&, &*map*&, and |
f89d2485 PH |
10773 | &*reduce*& items (see section &<<SECTexpcond>>&). In other circumstances, it is |
10774 | empty. | |
168e428f | 10775 | |
9b371988 | 10776 | .vitem &$ldap_dn$& |
f89d2485 | 10777 | .vindex "&$ldap_dn$&" |
168e428f PH |
10778 | This variable, which is available only when Exim is compiled with LDAP support, |
10779 | contains the DN from the last entry in the most recently successful LDAP | |
10780 | lookup. | |
10781 | ||
9b371988 | 10782 | .vitem &$load_average$& |
f89d2485 | 10783 | .vindex "&$load_average$&" |
4d0893ec | 10784 | This variable contains the system load average, multiplied by 1000 so that it |
168e428f PH |
10785 | is an integer. For example, if the load average is 0.21, the value of the |
10786 | variable is 210. The value is recomputed every time the variable is referenced. | |
10787 | ||
9b371988 | 10788 | .vitem &$local_part$& |
f89d2485 | 10789 | .vindex "&$local_part$&" |
168e428f PH |
10790 | When an address is being routed, or delivered on its own, this |
10791 | variable contains the local part. When a number of addresses are being | |
10792 | delivered together (for example, multiple RCPT commands in an SMTP | |
9b371988 PH |
10793 | session), &$local_part$& is not set. |
10794 | ||
168e428f | 10795 | Global address rewriting happens when a message is received, so the value of |
9b371988 PH |
10796 | &$local_part$& during routing and delivery is the value after rewriting. |
10797 | &$local_part$& is set during user filtering, but not during system filtering, | |
168e428f PH |
10798 | because a message may have many recipients and the system filter is called just |
10799 | once. | |
9b371988 | 10800 | |
f89d2485 PH |
10801 | .vindex "&$local_part_prefix$&" |
10802 | .vindex "&$local_part_suffix$&" | |
168e428f | 10803 | If a local part prefix or suffix has been recognized, it is not included in the |
9b371988 PH |
10804 | value of &$local_part$& during routing and subsequent delivery. The values of |
10805 | any prefix or suffix are in &$local_part_prefix$& and | |
10806 | &$local_part_suffix$&, respectively. | |
10807 | ||
168e428f | 10808 | When a message is being delivered to a file, pipe, or autoreply transport as a |
9b371988 PH |
10809 | result of aliasing or forwarding, &$local_part$& is set to the local part of |
10810 | the parent address, not to the file name or command (see &$address_file$& and | |
10811 | &$address_pipe$&). | |
10812 | ||
10813 | When an ACL is running for a RCPT command, &$local_part$& contains the | |
168e428f | 10814 | local part of the recipient address. |
9b371988 PH |
10815 | |
10816 | When a rewrite item is being processed (see chapter &<<CHAPrewrite>>&), | |
10817 | &$local_part$& contains the local part of the address that is being rewritten; | |
168e428f | 10818 | it can be used in the expansion of the replacement address, for example. |
9b371988 | 10819 | |
168e428f PH |
10820 | In all cases, all quoting is removed from the local part. For example, for both |
10821 | the addresses | |
9b371988 PH |
10822 | .code |
10823 | "abc:xyz"@test.example | |
10824 | abc\:xyz@test.example | |
10825 | .endd | |
10826 | the value of &$local_part$& is | |
10827 | .code | |
10828 | abc:xyz | |
10829 | .endd | |
10830 | If you use &$local_part$& to create another address, you should always wrap it | |
10831 | inside a quoting operator. For example, in a &(redirect)& router you could | |
10832 | have: | |
10833 | .code | |
10834 | data = ${quote_local_part:$local_part}@new.domain.example | |
10835 | .endd | |
10836 | &*Note*&: The value of &$local_part$& is normally lower cased. If you want | |
168e428f | 10837 | to process local parts in a case-dependent manner in a router, you can set the |
9b371988 | 10838 | &%caseful_local_part%& option (see chapter &<<CHAProutergeneric>>&). |
168e428f | 10839 | |
9b371988 | 10840 | .vitem &$local_part_data$& |
f89d2485 | 10841 | .vindex "&$local_part_data$&" |
9b371988 | 10842 | When the &%local_parts%& option on a router matches a local part by means of a |
168e428f | 10843 | lookup, the data read by the lookup is available during the running of the |
9b371988 | 10844 | router as &$local_part_data$&. In addition, if the driver routes the address |
168e428f PH |
10845 | to a transport, the value is available in that transport. If the transport is |
10846 | handling multiple addresses, the value from the first address is used. | |
9b371988 PH |
10847 | |
10848 | &$local_part_data$& is also set when the &%local_parts%& condition in an ACL | |
168e428f PH |
10849 | matches a local part by means of a lookup. The data read by the lookup is |
10850 | available during the rest of the ACL statement. In all other situations, this | |
10851 | variable expands to nothing. | |
10852 | ||
9b371988 | 10853 | .vitem &$local_part_prefix$& |
f89d2485 | 10854 | .vindex "&$local_part_prefix$&" |
168e428f PH |
10855 | When an address is being routed or delivered, and a |
10856 | specific prefix for the local part was recognized, it is available in this | |
9b371988 | 10857 | variable, having been removed from &$local_part$&. |
168e428f | 10858 | |
9b371988 | 10859 | .vitem &$local_part_suffix$& |
f89d2485 | 10860 | .vindex "&$local_part_suffix$&" |
168e428f PH |
10861 | When an address is being routed or delivered, and a |
10862 | specific suffix for the local part was recognized, it is available in this | |
9b371988 PH |
10863 | variable, having been removed from &$local_part$&. |
10864 | ||
10865 | .vitem &$local_scan_data$& | |
f89d2485 | 10866 | .vindex "&$local_scan_data$&" |
9b371988 PH |
10867 | This variable contains the text returned by the &[local_scan()]& function when |
10868 | a message is received. See chapter &<<CHAPlocalscan>>& for more details. | |
10869 | ||
10870 | .vitem &$local_user_gid$& | |
f89d2485 | 10871 | .vindex "&$local_user_gid$&" |
9b371988 PH |
10872 | See &$local_user_uid$&. |
10873 | ||
10874 | .vitem &$local_user_uid$& | |
f89d2485 | 10875 | .vindex "&$local_user_uid$&" |
9b371988 PH |
10876 | This variable and &$local_user_gid$& are set to the uid and gid after the |
10877 | &%check_local_user%& router precondition succeeds. This means that their values | |
10878 | are available for the remaining preconditions (&%senders%&, &%require_files%&, | |
10879 | and &%condition%&), for the &%address_data%& expansion, and for any | |
10880 | router-specific expansions. At all other times, the values in these variables | |
10881 | are &`(uid_t)(-1)`& and &`(gid_t)(-1)`&, respectively. | |
10882 | ||
10883 | .vitem &$localhost_number$& | |
f89d2485 | 10884 | .vindex "&$localhost_number$&" |
168e428f | 10885 | This contains the expanded value of the |
9b371988 | 10886 | &%localhost_number%& option. The expansion happens after the main options have |
168e428f PH |
10887 | been read. |
10888 | ||
9b371988 | 10889 | .vitem &$log_inodes$& |
f89d2485 | 10890 | .vindex "&$log_inodes$&" |
168e428f PH |
10891 | The number of free inodes in the disk partition where Exim's |
10892 | log files are being written. The value is recalculated whenever the variable is | |
10893 | referenced. If the relevant file system does not have the concept of inodes, | |
9b371988 | 10894 | the value of is -1. See also the &%check_log_inodes%& option. |
168e428f | 10895 | |
9b371988 | 10896 | .vitem &$log_space$& |
f89d2485 | 10897 | .vindex "&$log_space$&" |
168e428f PH |
10898 | The amount of free space (as a number of kilobytes) in the disk |
10899 | partition where Exim's log files are being written. The value is recalculated | |
10900 | whenever the variable is referenced. If the operating system does not have the | |
10901 | ability to find the amount of free space (only true for experimental systems), | |
9b371988 | 10902 | the space value is -1. See also the &%check_log_space%& option. |
168e428f PH |
10903 | |
10904 | ||
9b371988 | 10905 | .vitem &$mailstore_basename$& |
f89d2485 | 10906 | .vindex "&$mailstore_basename$&" |
9b371988 PH |
10907 | This variable is set only when doing deliveries in &"mailstore"& format in the |
10908 | &(appendfile)& transport. During the expansion of the &%mailstore_prefix%&, | |
10909 | &%mailstore_suffix%&, &%message_prefix%&, and &%message_suffix%& options, it | |
10910 | contains the basename of the files that are being written, that is, the name | |
10911 | without the &".tmp"&, &".env"&, or &".msg"& suffix. At all other times, this | |
10912 | variable is empty. | |
168e428f | 10913 | |
9b371988 | 10914 | .vitem &$malware_name$& |
f89d2485 | 10915 | .vindex "&$malware_name$&" |
168e428f PH |
10916 | This variable is available when Exim is compiled with the |
10917 | content-scanning extension. It is set to the name of the virus that was found | |
9b371988 | 10918 | when the ACL &%malware%& condition is true (see section &<<SECTscanvirus>>&). |
168e428f | 10919 | |
595028e4 PH |
10920 | .vitem &$max_received_linelength$& |
10921 | .vindex "&$max_received_linelength$&" | |
10922 | .cindex "maximum" "line length" | |
10923 | .cindex "line length" "maximum" | |
10924 | This variable contains the number of bytes in the longest line that was | |
10925 | received as part of the message, not counting the line termination | |
10926 | character(s). | |
168e428f | 10927 | |
9b371988 PH |
10928 | .vitem &$message_age$& |
10929 | .cindex "message" "age of" | |
f89d2485 | 10930 | .vindex "&$message_age$&" |
068aaea8 PH |
10931 | This variable is set at the start of a delivery attempt to contain the number |
10932 | of seconds since the message was received. It does not change during a single | |
10933 | delivery attempt. | |
168e428f | 10934 | |
9b371988 PH |
10935 | .vitem &$message_body$& |
10936 | .cindex "body of message" "expansion variable" | |
10937 | .cindex "message body" "in expansion" | |
10938 | .cindex "binary zero" "in message body" | |
f89d2485 | 10939 | .vindex "&$message_body$&" |
595028e4 PH |
10940 | .oindex "&%message_body_visible%&" |
10941 | This variable contains the initial portion of a message's body while it is | |
10942 | being delivered, and is intended mainly for use in filter files. The maximum | |
10943 | number of characters of the body that are put into the variable is set by the | |
10944 | &%message_body_visible%& configuration option; the default is 500. | |
10945 | ||
595028e4 PH |
10946 | .oindex "&%message_body_newlines%&" |
10947 | By default, newlines are converted into spaces in &$message_body$&, to make it | |
10948 | easier to search for phrases that might be split over a line break. However, | |
10949 | this can be disabled by setting &%message_body_newlines%& to be true. Binary | |
10950 | zeros are always converted into spaces. | |
168e428f | 10951 | |
9b371988 PH |
10952 | .vitem &$message_body_end$& |
10953 | .cindex "body of message" "expansion variable" | |
10954 | .cindex "message body" "in expansion" | |
f89d2485 | 10955 | .vindex "&$message_body_end$&" |
168e428f PH |
10956 | This variable contains the final portion of a message's |
10957 | body while it is being delivered. The format and maximum size are as for | |
9b371988 | 10958 | &$message_body$&. |
168e428f | 10959 | |
9b371988 PH |
10960 | .vitem &$message_body_size$& |
10961 | .cindex "body of message" "size" | |
10962 | .cindex "message body" "size" | |
f89d2485 | 10963 | .vindex "&$message_body_size$&" |
068aaea8 PH |
10964 | When a message is being delivered, this variable contains the size of the body |
10965 | in bytes. The count starts from the character after the blank line that | |
10966 | separates the body from the header. Newlines are included in the count. See | |
9b371988 | 10967 | also &$message_size$&, &$body_linecount$&, and &$body_zerocount$&. |
068aaea8 | 10968 | |
9b371988 | 10969 | .vitem &$message_exim_id$& |
f89d2485 | 10970 | .vindex "&$message_exim_id$&" |
068aaea8 PH |
10971 | When a message is being received or delivered, this variable contains the |
10972 | unique message id that is generated and used by Exim to identify the message. | |
10973 | An id is not created for a message until after its header has been successfully | |
9b371988 PH |
10974 | received. &*Note*&: This is &'not'& the contents of the &'Message-ID:'& header |
10975 | line; it is the local id that Exim assigns to the message, for example: | |
10976 | &`1BXTIK-0001yO-VA`&. | |
168e428f | 10977 | |
9b371988 | 10978 | .vitem &$message_headers$& |
f89d2485 | 10979 | .vindex &$message_headers$& |
168e428f PH |
10980 | This variable contains a concatenation of all the header lines when a message |
10981 | is being processed, except for lines added by routers or transports. The header | |
3cb1b51e PH |
10982 | lines are separated by newline characters. Their contents are decoded in the |
10983 | same way as a header line that is inserted by &%bheader%&. | |
10984 | ||
10985 | .vitem &$message_headers_raw$& | |
f89d2485 | 10986 | .vindex &$message_headers_raw$& |
3cb1b51e PH |
10987 | This variable is like &$message_headers$& except that no processing of the |
10988 | contents of header lines is done. | |
168e428f | 10989 | |
9b371988 | 10990 | .vitem &$message_id$& |
9b371988 | 10991 | This is an old name for &$message_exim_id$&, which is now deprecated. |
068aaea8 | 10992 | |
9b371988 | 10993 | .vitem &$message_linecount$& |
f89d2485 | 10994 | .vindex "&$message_linecount$&" |
068aaea8 | 10995 | This variable contains the total number of lines in the header and body of the |
9b371988 PH |
10996 | message. Compare &$body_linecount$&, which is the count for the body only. |
10997 | During the DATA and content-scanning ACLs, &$message_linecount$& contains the | |
10998 | number of lines received. Before delivery happens (that is, before filters, | |
10999 | routers, and transports run) the count is increased to include the | |
11000 | &'Received:'& header line that Exim standardly adds, and also any other header | |
11001 | lines that are added by ACLs. The blank line that separates the message header | |
11002 | from the body is not counted. Here is an example of the use of this variable in | |
11003 | a DATA ACL: | |
11004 | .code | |
068aaea8 PH |
11005 | deny message = Too many lines in message header |
11006 | condition = \ | |
f89d2485 | 11007 | ${if <{250}{${eval:$message_linecount - $body_linecount}}} |
9b371988 | 11008 | .endd |
068aaea8 PH |
11009 | In the MAIL and RCPT ACLs, the value is zero because at that stage the |
11010 | message has not yet been received. | |
168e428f | 11011 | |
9b371988 PH |
11012 | .vitem &$message_size$& |
11013 | .cindex "size" "of message" | |
11014 | .cindex "message" "size" | |
f89d2485 | 11015 | .vindex "&$message_size$&" |
168e428f PH |
11016 | When a message is being processed, this variable contains its size in bytes. In |
11017 | most cases, the size includes those headers that were received with the | |
9b371988 | 11018 | message, but not those (such as &'Envelope-to:'&) that are added to individual |
168e428f | 11019 | deliveries as they are written. However, there is one special case: during the |
9b371988 PH |
11020 | expansion of the &%maildir_tag%& option in the &(appendfile)& transport while |
11021 | doing a delivery in maildir format, the value of &$message_size$& is the | |
168e428f | 11022 | precise size of the file that has been written. See also |
9b371988 PH |
11023 | &$message_body_size$&, &$body_linecount$&, and &$body_zerocount$&. |
11024 | ||
11025 | .cindex "RCPT" "value of &$message_size$&" | |
400eda43 | 11026 | While running a per message ACL (mail/rcpt/predata), &$message_size$& |
168e428f PH |
11027 | contains the size supplied on the MAIL command, or -1 if no size was given. The |
11028 | value may not, of course, be truthful. | |
11029 | ||
9b371988 PH |
11030 | .vitem &$mime_$&&'xxx'& |
11031 | A number of variables whose names start with &$mime$& are | |
168e428f | 11032 | available when Exim is compiled with the content-scanning extension. For |
9b371988 | 11033 | details, see section &<<SECTscanmimepart>>&. |
168e428f | 11034 | |
9b371988 | 11035 | .vitem "&$n0$& &-- &$n9$&" |
168e428f | 11036 | These variables are counters that can be incremented by means |
9b371988 | 11037 | of the &%add%& command in filter files. |
168e428f | 11038 | |
9b371988 | 11039 | .vitem &$original_domain$& |
f89d2485 PH |
11040 | .vindex "&$domain$&" |
11041 | .vindex "&$original_domain$&" | |
068aaea8 | 11042 | When a top-level address is being processed for delivery, this contains the |
9b371988 PH |
11043 | same value as &$domain$&. However, if a &"child"& address (for example, |
11044 | generated by an alias, forward, or filter file) is being processed, this | |
3cb1b51e PH |
11045 | variable contains the domain of the original address (lower cased). This |
11046 | differs from &$parent_domain$& only when there is more than one level of | |
11047 | aliasing or forwarding. When more than one address is being delivered in a | |
11048 | single transport run, &$original_domain$& is not set. | |
9b371988 PH |
11049 | |
11050 | If a new address is created by means of a &%deliver%& command in a system | |
11051 | filter, it is set up with an artificial &"parent"& address. This has the local | |
11052 | part &'system-filter'& and the default qualify domain. | |
11053 | ||
11054 | .vitem &$original_local_part$& | |
f89d2485 PH |
11055 | .vindex "&$local_part$&" |
11056 | .vindex "&$original_local_part$&" | |
068aaea8 | 11057 | When a top-level address is being processed for delivery, this contains the |
9b371988 PH |
11058 | same value as &$local_part$&, unless a prefix or suffix was removed from the |
11059 | local part, because &$original_local_part$& always contains the full local | |
11060 | part. When a &"child"& address (for example, generated by an alias, forward, or | |
068aaea8 PH |
11061 | filter file) is being processed, this variable contains the full local part of |
11062 | the original address. | |
9b371988 | 11063 | |
168e428f | 11064 | If the router that did the redirection processed the local part |
9b371988 PH |
11065 | case-insensitively, the value in &$original_local_part$& is in lower case. |
11066 | This variable differs from &$parent_local_part$& only when there is more than | |
168e428f | 11067 | one level of aliasing or forwarding. When more than one address is being |
9b371988 PH |
11068 | delivered in a single transport run, &$original_local_part$& is not set. |
11069 | ||
11070 | If a new address is created by means of a &%deliver%& command in a system | |
11071 | filter, it is set up with an artificial &"parent"& address. This has the local | |
11072 | part &'system-filter'& and the default qualify domain. | |
11073 | ||
11074 | .vitem &$originator_gid$& | |
11075 | .cindex "gid (group id)" "of originating user" | |
11076 | .cindex "sender" "gid" | |
f89d2485 PH |
11077 | .vindex "&$caller_gid$&" |
11078 | .vindex "&$originator_gid$&" | |
9b371988 PH |
11079 | This variable contains the value of &$caller_gid$& that was set when the |
11080 | message was received. For messages received via the command line, this is the | |
11081 | gid of the sending user. For messages received by SMTP over TCP/IP, this is | |
11082 | normally the gid of the Exim user. | |
11083 | ||
11084 | .vitem &$originator_uid$& | |
11085 | .cindex "uid (user id)" "of originating user" | |
11086 | .cindex "sender" "uid" | |
f89d2485 PH |
11087 | .vindex "&$caller_uid$&" |
11088 | .vindex "&$originaltor_uid$&" | |
9b371988 | 11089 | The value of &$caller_uid$& that was set when the message was received. For |
068aaea8 PH |
11090 | messages received via the command line, this is the uid of the sending user. |
11091 | For messages received by SMTP over TCP/IP, this is normally the uid of the Exim | |
11092 | user. | |
168e428f | 11093 | |
9b371988 | 11094 | .vitem &$parent_domain$& |
f89d2485 | 11095 | .vindex "&$parent_domain$&" |
9b371988 | 11096 | This variable is similar to &$original_domain$& (see |
168e428f PH |
11097 | above), except that it refers to the immediately preceding parent address. |
11098 | ||
9b371988 | 11099 | .vitem &$parent_local_part$& |
f89d2485 | 11100 | .vindex "&$parent_local_part$&" |
9b371988 | 11101 | This variable is similar to &$original_local_part$& |
168e428f PH |
11102 | (see above), except that it refers to the immediately preceding parent address. |
11103 | ||
9b371988 PH |
11104 | .vitem &$pid$& |
11105 | .cindex "pid (process id)" "of current process" | |
f89d2485 | 11106 | .vindex "&$pid$&" |
168e428f PH |
11107 | This variable contains the current process id. |
11108 | ||
9b371988 PH |
11109 | .vitem &$pipe_addresses$& |
11110 | .cindex "filter" "transport filter" | |
11111 | .cindex "transport" "filter" | |
f89d2485 | 11112 | .vindex "&$pipe_addresses$&" |
068aaea8 | 11113 | This is not an expansion variable, but is mentioned here because the string |
c0712871 | 11114 | &`$pipe_addresses`& is handled specially in the command specification for the |
9b371988 PH |
11115 | &(pipe)& transport (chapter &<<CHAPpipetransport>>&) and in transport filters |
11116 | (described under &%transport_filter%& in chapter &<<CHAPtransportgeneric>>&). | |
11117 | It cannot be used in general expansion strings, and provokes an &"unknown | |
11118 | variable"& error if encountered. | |
11119 | ||
11120 | .vitem &$primary_hostname$& | |
f89d2485 | 11121 | .vindex "&$primary_hostname$&" |
9b371988 PH |
11122 | This variable contains the value set by &%primary_hostname%& in the |
11123 | configuration file, or read by the &[uname()]& function. If &[uname()]& returns | |
11124 | a single-component name, Exim calls &[gethostbyname()]& (or | |
11125 | &[getipnodebyname()]& where available) in an attempt to acquire a fully | |
11126 | qualified host name. See also &$smtp_active_hostname$&. | |
11127 | ||
11128 | ||
9b371988 PH |
11129 | .vitem &$prvscheck_address$& |
11130 | This variable is used in conjunction with the &%prvscheck%& expansion item, | |
11131 | which is described in sections &<<SECTexpansionitems>>& and | |
11132 | &<<SECTverifyPRVS>>&. | |
11133 | ||
11134 | .vitem &$prvscheck_keynum$& | |
11135 | This variable is used in conjunction with the &%prvscheck%& expansion item, | |
11136 | which is described in sections &<<SECTexpansionitems>>& and | |
11137 | &<<SECTverifyPRVS>>&. | |
11138 | ||
11139 | .vitem &$prvscheck_result$& | |
11140 | This variable is used in conjunction with the &%prvscheck%& expansion item, | |
11141 | which is described in sections &<<SECTexpansionitems>>& and | |
11142 | &<<SECTverifyPRVS>>&. | |
9b371988 PH |
11143 | |
11144 | .vitem &$qualify_domain$& | |
f89d2485 | 11145 | .vindex "&$qualify_domain$&" |
9b371988 PH |
11146 | The value set for the &%qualify_domain%& option in the configuration file. |
11147 | ||
11148 | .vitem &$qualify_recipient$& | |
f89d2485 | 11149 | .vindex "&$qualify_recipient$&" |
9b371988 PH |
11150 | The value set for the &%qualify_recipient%& option in the configuration file, |
11151 | or if not set, the value of &$qualify_domain$&. | |
11152 | ||
11153 | .vitem &$rcpt_count$& | |
f89d2485 | 11154 | .vindex "&$rcpt_count$&" |
068aaea8 PH |
11155 | When a message is being received by SMTP, this variable contains the number of |
11156 | RCPT commands received for the current message. If this variable is used in a | |
11157 | RCPT ACL, its value includes the current command. | |
168e428f | 11158 | |
9b371988 | 11159 | .vitem &$rcpt_defer_count$& |
f89d2485 | 11160 | .vindex "&$rcpt_defer_count$&" |
3cb1b51e | 11161 | .cindex "4&'xx'& responses" "count of" |
068aaea8 PH |
11162 | When a message is being received by SMTP, this variable contains the number of |
11163 | RCPT commands in the current message that have previously been rejected with a | |
9b371988 | 11164 | temporary (4&'xx'&) response. |
168e428f | 11165 | |
9b371988 | 11166 | .vitem &$rcpt_fail_count$& |
f89d2485 | 11167 | .vindex "&$rcpt_fail_count$&" |
068aaea8 PH |
11168 | When a message is being received by SMTP, this variable contains the number of |
11169 | RCPT commands in the current message that have previously been rejected with a | |
9b371988 | 11170 | permanent (5&'xx'&) response. |
168e428f | 11171 | |
9b371988 | 11172 | .vitem &$received_count$& |
f89d2485 | 11173 | .vindex "&$received_count$&" |
9b371988 | 11174 | This variable contains the number of &'Received:'& header lines in the message, |
068aaea8 PH |
11175 | including the one added by Exim (so its value is always greater than zero). It |
11176 | is available in the DATA ACL, the non-SMTP ACL, and while routing and | |
11177 | delivering. | |
168e428f | 11178 | |
9b371988 | 11179 | .vitem &$received_for$& |
f89d2485 | 11180 | .vindex "&$received_for$&" |
068aaea8 | 11181 | If there is only a single recipient address in an incoming message, this |
9b371988 PH |
11182 | variable contains that address when the &'Received:'& header line is being |
11183 | built. The value is copied after recipient rewriting has happened, but before | |
11184 | the &[local_scan()]& function is run. | |
168e428f | 11185 | |
3cb1b51e | 11186 | .vitem &$received_ip_address$& |
f89d2485 | 11187 | .vindex "&$received_ip_address$&" |
3cb1b51e PH |
11188 | As soon as an Exim server starts processing an incoming TCP/IP connection, this |
11189 | variable is set to the address of the local IP interface, and &$received_port$& | |
11190 | is set to the local port number. (The remote IP address and port are in | |
11191 | &$sender_host_address$& and &$sender_host_port$&.) When testing with &%-bh%&, | |
11192 | the port value is -1 unless it has been set using the &%-oMi%& command line | |
11193 | option. | |
11194 | ||
11195 | As well as being useful in ACLs (including the &"connect"& ACL), these variable | |
11196 | could be used, for example, to make the file name for a TLS certificate depend | |
11197 | on which interface and/or port is being used for the incoming connection. The | |
11198 | values of &$received_ip_address$& and &$received_port$& are saved with any | |
11199 | messages that are received, thus making these variables available at delivery | |
11200 | time. | |
11201 | ||
11202 | &*Note:*& There are no equivalent variables for outgoing connections, because | |
11203 | the values are unknown (unless they are explicitly set by options of the | |
11204 | &(smtp)& transport). | |
11205 | ||
11206 | .vitem &$received_port$& | |
f89d2485 | 11207 | .vindex "&$received_port$&" |
3cb1b51e | 11208 | See &$received_ip_address$&. |
3cb1b51e | 11209 | |
9b371988 | 11210 | .vitem &$received_protocol$& |
f89d2485 | 11211 | .vindex "&$received_protocol$&" |
068aaea8 PH |
11212 | When a message is being processed, this variable contains the name of the |
11213 | protocol by which it was received. Most of the names used by Exim are defined | |
9b371988 PH |
11214 | by RFCs 821, 2821, and 3848. They start with &"smtp"& (the client used HELO) or |
11215 | &"esmtp"& (the client used EHLO). This can be followed by &"s"& for secure | |
11216 | (encrypted) and/or &"a"& for authenticated. Thus, for example, if the protocol | |
11217 | is set to &"esmtpsa"&, the message was received over an encrypted SMTP | |
068aaea8 | 11218 | connection and the client was successfully authenticated. |
9b371988 PH |
11219 | |
11220 | Exim uses the protocol name &"smtps"& for the case when encryption is | |
168e428f | 11221 | automatically set up on connection without the use of STARTTLS (see |
9b371988 PH |
11222 | &%tls_on_connect_ports%&), and the client uses HELO to initiate the |
11223 | encrypted SMTP session. The name &"smtps"& is also used for the rare situation | |
168e428f PH |
11224 | where the client initially uses EHLO, sets up an encrypted connection using |
11225 | STARTTLS, and then uses HELO afterwards. | |
9b371988 PH |
11226 | |
11227 | The &%-oMr%& option provides a way of specifying a custom protocol name for | |
168e428f PH |
11228 | messages that are injected locally by trusted callers. This is commonly used to |
11229 | identify messages that are being re-injected after some kind of scanning. | |
11230 | ||
9b371988 | 11231 | .vitem &$received_time$& |
f89d2485 | 11232 | .vindex "&$received_time$&" |
068aaea8 PH |
11233 | This variable contains the date and time when the current message was received, |
11234 | as a number of seconds since the start of the Unix epoch. | |
168e428f | 11235 | |
9b371988 | 11236 | .vitem &$recipient_data$& |
f89d2485 | 11237 | .vindex "&$recipient_data$&" |
9b371988 | 11238 | This variable is set after an indexing lookup success in an ACL &%recipients%& |
068aaea8 | 11239 | condition. It contains the data from the lookup, and the value remains set |
9b371988 PH |
11240 | until the next &%recipients%& test. Thus, you can do things like this: |
11241 | .display | |
11242 | &`require recipients = cdb*@;/some/file`& | |
11243 | &`deny `&&'some further test involving'& &`$recipient_data`& | |
11244 | .endd | |
11245 | &*Warning*&: This variable is set only when a lookup is used as an indexing | |
168e428f PH |
11246 | method in the address list, using the semicolon syntax as in the example above. |
11247 | The variable is not set for a lookup that is used as part of the string | |
11248 | expansion that all such lists undergo before being interpreted. | |
11249 | ||
9b371988 | 11250 | .vitem &$recipient_verify_failure$& |
f89d2485 | 11251 | .vindex "&$recipient_verify_failure$&" |
068aaea8 PH |
11252 | In an ACL, when a recipient verification fails, this variable contains |
11253 | information about the failure. It is set to one of the following words: | |
9b371988 PH |
11254 | |
11255 | .ilist | |
11256 | &"qualify"&: The address was unqualified (no domain), and the message | |
168e428f PH |
11257 | was neither local nor came from an exempted host. |
11258 | ||
9b371988 PH |
11259 | .next |
11260 | &"route"&: Routing failed. | |
168e428f | 11261 | |
9b371988 PH |
11262 | .next |
11263 | &"mail"&: Routing succeeded, and a callout was attempted; rejection occurred at | |
168e428f PH |
11264 | or before the MAIL command (that is, on initial connection, HELO, or |
11265 | MAIL). | |
11266 | ||
9b371988 PH |
11267 | .next |
11268 | &"recipient"&: The RCPT command in a callout was rejected. | |
11269 | .next | |
11270 | ||
11271 | &"postmaster"&: The postmaster check in a callout was rejected. | |
11272 | .endlist | |
168e428f | 11273 | |
168e428f PH |
11274 | The main use of this variable is expected to be to distinguish between |
11275 | rejections of MAIL and rejections of RCPT. | |
11276 | ||
9b371988 | 11277 | .vitem &$recipients$& |
f89d2485 PH |
11278 | .vindex "&$recipients$&" |
11279 | This variable contains a list of envelope recipients for a message. A comma and | |
11280 | a space separate the addresses in the replacement text. However, the variable | |
11281 | is not generally available, to prevent exposure of Bcc recipients in | |
11282 | unprivileged users' filter files. You can use &$recipients$& only in these | |
11283 | cases: | |
168e428f | 11284 | |
9b371988 PH |
11285 | .olist |
11286 | In a system filter file. | |
11287 | .next | |
db9452a9 PH |
11288 | In the ACLs associated with the DATA command and with non-SMTP messages, that |
11289 | is, the ACLs defined by &%acl_smtp_predata%&, &%acl_smtp_data%&, | |
11290 | &%acl_smtp_mime%&, &%acl_not_smtp_start%&, &%acl_not_smtp%&, and | |
11291 | &%acl_not_smtp_mime%&. | |
f89d2485 | 11292 | .next |
f89d2485 | 11293 | From within a &[local_scan()]& function. |
9b371988 | 11294 | .endlist |
168e428f | 11295 | |
168e428f | 11296 | |
9b371988 | 11297 | .vitem &$recipients_count$& |
f89d2485 | 11298 | .vindex "&$recipients_count$&" |
068aaea8 PH |
11299 | When a message is being processed, this variable contains the number of |
11300 | envelope recipients that came with the message. Duplicates are not excluded | |
11301 | from the count. While a message is being received over SMTP, the number | |
11302 | increases for each accepted recipient. It can be referenced in an ACL. | |
168e428f | 11303 | |
db9452a9 | 11304 | |
db9452a9 | 11305 | .vitem &$regex_match_string$& |
f89d2485 | 11306 | .vindex "&$regex_match_string$&" |
db9452a9 PH |
11307 | This variable is set to contain the matching regular expression after a |
11308 | &%regex%& ACL condition has matched (see section &<<SECTscanregex>>&). | |
db9452a9 PH |
11309 | |
11310 | ||
9b371988 | 11311 | .vitem &$reply_address$& |
f89d2485 | 11312 | .vindex "&$reply_address$&" |
068aaea8 | 11313 | When a message is being processed, this variable contains the contents of the |
9b371988 | 11314 | &'Reply-To:'& header line if one exists and it is not empty, or otherwise the |
c0712871 | 11315 | contents of the &'From:'& header line. Apart from the removal of leading |
4f578862 | 11316 | white space, the value is not processed in any way. In particular, no RFC 2047 |
c0712871 | 11317 | decoding or character code translation takes place. |
168e428f | 11318 | |
9b371988 | 11319 | .vitem &$return_path$& |
f89d2485 | 11320 | .vindex "&$return_path$&" |
9b371988 | 11321 | When a message is being delivered, this variable contains the return path &-- |
168e428f | 11322 | the sender field that will be sent as part of the envelope. It is not enclosed |
9b371988 PH |
11323 | in <> characters. At the start of routing an address, &$return_path$& has the |
11324 | same value as &$sender_address$&, but if, for example, an incoming message to a | |
168e428f | 11325 | mailing list has been expanded by a router which specifies a different address |
9b371988 PH |
11326 | for bounce messages, &$return_path$& subsequently contains the new bounce |
11327 | address, whereas &$sender_address$& always contains the original sender address | |
11328 | that was received with the message. In other words, &$sender_address$& contains | |
11329 | the incoming envelope sender, and &$return_path$& contains the outgoing | |
11330 | envelope sender. | |
11331 | ||
11332 | .vitem &$return_size_limit$& | |
f89d2485 | 11333 | .vindex "&$return_size_limit$&" |
9b371988 PH |
11334 | This is an obsolete name for &$bounce_return_size_limit$&. |
11335 | ||
11336 | .vitem &$runrc$& | |
11337 | .cindex "return code" "from &%run%& expansion" | |
f89d2485 | 11338 | .vindex "&$runrc$&" |
168e428f | 11339 | This variable contains the return code from a command that is run by the |
9b371988 | 11340 | &%${run...}%& expansion item. &*Warning*&: In a router or transport, you cannot |
168e428f | 11341 | assume the order in which option values are expanded, except for those |
9b371988 PH |
11342 | preconditions whose order of testing is documented. Therefore, you cannot |
11343 | reliably expect to set &$runrc$& by the expansion of one option, and use it in | |
168e428f PH |
11344 | another. |
11345 | ||
9b371988 | 11346 | .vitem &$self_hostname$& |
0a4e3112 | 11347 | .oindex "&%self%&" "value of host name" |
f89d2485 | 11348 | .vindex "&$self_hostname$&" |
068aaea8 | 11349 | When an address is routed to a supposedly remote host that turns out to be the |
9b371988 PH |
11350 | local host, what happens is controlled by the &%self%& generic router option. |
11351 | One of its values causes the address to be passed to another router. When this | |
11352 | happens, &$self_hostname$& is set to the name of the local host that the | |
11353 | original router encountered. In other circumstances its contents are null. | |
168e428f | 11354 | |
9b371988 | 11355 | .vitem &$sender_address$& |
f89d2485 | 11356 | .vindex "&$sender_address$&" |
068aaea8 | 11357 | When a message is being processed, this variable contains the sender's address |
3cb1b51e PH |
11358 | that was received in the message's envelope. The case of letters in the address |
11359 | is retained, in both the local part and the domain. For bounce messages, the | |
11360 | value of this variable is the empty string. See also &$return_path$&. | |
168e428f | 11361 | |
9b371988 | 11362 | .vitem &$sender_address_data$& |
f89d2485 PH |
11363 | .vindex "&$address_data$&" |
11364 | .vindex "&$sender_address_data$&" | |
9b371988 PH |
11365 | If &$address_data$& is set when the routers are called from an ACL to verify a |
11366 | sender address, the final value is preserved in &$sender_address_data$&, to | |
168e428f PH |
11367 | distinguish it from data from a recipient address. The value does not persist |
11368 | after the end of the current ACL statement. If you want to preserve it for | |
11369 | longer, you can save it in an ACL variable. | |
11370 | ||
9b371988 | 11371 | .vitem &$sender_address_domain$& |
f89d2485 | 11372 | .vindex "&$sender_address_domain$&" |
9b371988 PH |
11373 | The domain portion of &$sender_address$&. |
11374 | ||
11375 | .vitem &$sender_address_local_part$& | |
f89d2485 | 11376 | .vindex "&$sender_address_local_part$&" |
9b371988 PH |
11377 | The local part portion of &$sender_address$&. |
11378 | ||
11379 | .vitem &$sender_data$& | |
f89d2485 | 11380 | .vindex "&$sender_data$&" |
9b371988 PH |
11381 | This variable is set after a lookup success in an ACL &%senders%& condition or |
11382 | in a router &%senders%& option. It contains the data from the lookup, and the | |
11383 | value remains set until the next &%senders%& test. Thus, you can do things like | |
11384 | this: | |
11385 | .display | |
11386 | &`require senders = cdb*@;/some/file`& | |
11387 | &`deny `&&'some further test involving'& &`$sender_data`& | |
11388 | .endd | |
11389 | &*Warning*&: This variable is set only when a lookup is used as an indexing | |
168e428f PH |
11390 | method in the address list, using the semicolon syntax as in the example above. |
11391 | The variable is not set for a lookup that is used as part of the string | |
11392 | expansion that all such lists undergo before being interpreted. | |
11393 | ||
9b371988 | 11394 | .vitem &$sender_fullhost$& |
f89d2485 | 11395 | .vindex "&$sender_fullhost$&" |
168e428f PH |
11396 | When a message is received from a remote host, this variable contains the host |
11397 | name and IP address in a single string. It ends with the IP address in square | |
11398 | brackets, followed by a colon and a port number if the logging of ports is | |
11399 | enabled. The format of the rest of the string depends on whether the host | |
11400 | issued a HELO or EHLO SMTP command, and whether the host name was verified by | |
11401 | looking up its IP address. (Looking up the IP address can be forced by the | |
9b371988 | 11402 | &%host_lookup%& option, independent of verification.) A plain host name at the |
168e428f PH |
11403 | start of the string is a verified host name; if this is not present, |
11404 | verification either failed or was not requested. A host name in parentheses is | |
11405 | the argument of a HELO or EHLO command. This is omitted if it is identical to | |
11406 | the verified host name or to the host's IP address in square brackets. | |
11407 | ||
9b371988 | 11408 | .vitem &$sender_helo_name$& |
f89d2485 | 11409 | .vindex "&$sender_helo_name$&" |
068aaea8 PH |
11410 | When a message is received from a remote host that has issued a HELO or EHLO |
11411 | command, the argument of that command is placed in this variable. It is also | |
11412 | set if HELO or EHLO is used when a message is received using SMTP locally via | |
9b371988 | 11413 | the &%-bs%& or &%-bS%& options. |
168e428f | 11414 | |
9b371988 | 11415 | .vitem &$sender_host_address$& |
f89d2485 | 11416 | .vindex "&$sender_host_address$&" |
068aaea8 PH |
11417 | When a message is received from a remote host, this variable contains that |
11418 | host's IP address. For locally submitted messages, it is empty. | |
168e428f | 11419 | |
9b371988 | 11420 | .vitem &$sender_host_authenticated$& |
f89d2485 | 11421 | .vindex "&$sender_host_authenticated$&" |
168e428f | 11422 | This variable contains the name (not the public name) of the authenticator |
068aaea8 PH |
11423 | driver that successfully authenticated the client from which the message was |
11424 | received. It is empty if there was no successful authentication. See also | |
9b371988 | 11425 | &$authenticated_id$&. |
168e428f | 11426 | |
9b371988 | 11427 | .vitem &$sender_host_name$& |
f89d2485 | 11428 | .vindex "&$sender_host_name$&" |
168e428f PH |
11429 | When a message is received from a remote host, this variable contains the |
11430 | host's name as obtained by looking up its IP address. For messages received by | |
11431 | other means, this variable is empty. | |
9b371988 | 11432 | |
f89d2485 | 11433 | .vindex "&$host_lookup_failed$&" |
168e428f | 11434 | If the host name has not previously been looked up, a reference to |
9b371988 | 11435 | &$sender_host_name$& triggers a lookup (for messages from remote hosts). |
168e428f PH |
11436 | A looked up name is accepted only if it leads back to the original IP address |
11437 | via a forward lookup. If either the reverse or the forward lookup fails to find | |
11438 | any data, or if the forward lookup does not yield the original IP address, | |
9b371988 PH |
11439 | &$sender_host_name$& remains empty, and &$host_lookup_failed$& is set to &"1"&. |
11440 | ||
f89d2485 | 11441 | .vindex "&$host_lookup_deferred$&" |
168e428f | 11442 | However, if either of the lookups cannot be completed (for example, there is a |
9b371988 PH |
11443 | DNS timeout), &$host_lookup_deferred$& is set to &"1"&, and |
11444 | &$host_lookup_failed$& remains set to &"0"&. | |
11445 | ||
11446 | Once &$host_lookup_failed$& is set to &"1"&, Exim does not try to look up the | |
11447 | host name again if there is a subsequent reference to &$sender_host_name$& | |
db9452a9 | 11448 | in the same Exim process, but it does try again if &$host_lookup_deferred$& |
9b371988 PH |
11449 | is set to &"1"&. |
11450 | ||
168e428f PH |
11451 | Exim does not automatically look up every calling host's name. If you want |
11452 | maximum efficiency, you should arrange your configuration so that it avoids | |
11453 | these lookups altogether. The lookup happens only if one or more of the | |
11454 | following are true: | |
11455 | ||
9b371988 PH |
11456 | .ilist |
11457 | A string containing &$sender_host_name$& is expanded. | |
11458 | .next | |
11459 | The calling host matches the list in &%host_lookup%&. In the default | |
11460 | configuration, this option is set to *, so it must be changed if lookups are | |
11461 | to be avoided. (In the code, the default for &%host_lookup%& is unset.) | |
11462 | .next | |
11463 | Exim needs the host name in order to test an item in a host list. The items | |
11464 | that require this are described in sections &<<SECThoslispatnam>>& and | |
11465 | &<<SECThoslispatnamsk>>&. | |
11466 | .next | |
11467 | The calling host matches &%helo_try_verify_hosts%& or &%helo_verify_hosts%&. | |
168e428f PH |
11468 | In this case, the host name is required to compare with the name quoted in any |
11469 | EHLO or HELO commands that the client issues. | |
9b371988 PH |
11470 | .next |
11471 | The remote host issues a EHLO or HELO command that quotes one of the | |
11472 | domains in &%helo_lookup_domains%&. The default value of this option is | |
11473 | . ==== As this is a nested list, any displays it contains must be indented | |
11474 | . ==== as otherwise they are too far to the left. | |
11475 | .code | |
11476 | helo_lookup_domains = @ : @[] | |
11477 | .endd | |
168e428f PH |
11478 | which causes a lookup if a remote host (incorrectly) gives the server's name or |
11479 | IP address in an EHLO or HELO command. | |
9b371988 | 11480 | .endlist |
168e428f PH |
11481 | |
11482 | ||
9b371988 | 11483 | .vitem &$sender_host_port$& |
f89d2485 | 11484 | .vindex "&$sender_host_port$&" |
068aaea8 PH |
11485 | When a message is received from a remote host, this variable contains the port |
11486 | number that was used on the remote host. | |
168e428f | 11487 | |
9b371988 | 11488 | .vitem &$sender_ident$& |
f89d2485 | 11489 | .vindex "&$sender_ident$&" |
168e428f PH |
11490 | When a message is received from a remote host, this variable contains the |
11491 | identification received in response to an RFC 1413 request. When a message has | |
11492 | been received locally, this variable contains the login name of the user that | |
11493 | called Exim. | |
11494 | ||
9b371988 PH |
11495 | .vitem &$sender_rate_$&&'xxx'& |
11496 | A number of variables whose names begin &$sender_rate_$& are set as part of the | |
11497 | &%ratelimit%& ACL condition. Details are given in section | |
11498 | &<<SECTratelimiting>>&. | |
9b371988 PH |
11499 | |
11500 | .vitem &$sender_rcvhost$& | |
11501 | .cindex "DNS" "reverse lookup" | |
11502 | .cindex "reverse DNS lookup" | |
f89d2485 | 11503 | .vindex "&$sender_rcvhost$&" |
9b371988 | 11504 | This is provided specifically for use in &'Received:'& headers. It starts with |
068aaea8 PH |
11505 | either the verified host name (as obtained from a reverse DNS lookup) or, if |
11506 | there is no verified host name, the IP address in square brackets. After that | |
11507 | there may be text in parentheses. When the first item is a verified host name, | |
11508 | the first thing in the parentheses is the IP address in square brackets, | |
11509 | followed by a colon and a port number if port logging is enabled. When the | |
9b371988 | 11510 | first item is an IP address, the port is recorded as &"port=&'xxxx'&"& inside |
068aaea8 | 11511 | the parentheses. |
9b371988 PH |
11512 | |
11513 | There may also be items of the form &"helo=&'xxxx'&"& if HELO or EHLO | |
168e428f | 11514 | was used and its argument was not identical to the real host name or IP |
9b371988 PH |
11515 | address, and &"ident=&'xxxx'&"& if an RFC 1413 ident string is available. If |
11516 | all three items are present in the parentheses, a newline and tab are inserted | |
11517 | into the string, to improve the formatting of the &'Received:'& header. | |
168e428f | 11518 | |
9b371988 | 11519 | .vitem &$sender_verify_failure$& |
f89d2485 | 11520 | .vindex "&$sender_verify_failure$&" |
168e428f | 11521 | In an ACL, when a sender verification fails, this variable contains information |
9b371988 PH |
11522 | about the failure. The details are the same as for |
11523 | &$recipient_verify_failure$&. | |
168e428f | 11524 | |
f89d2485 PH |
11525 | .vitem &$sending_ip_address$& |
11526 | .vindex "&$sending_ip_address$&" | |
11527 | This variable is set whenever an outgoing SMTP connection to another host has | |
11528 | been set up. It contains the IP address of the local interface that is being | |
11529 | used. This is useful if a host that has more than one IP address wants to take | |
11530 | on different personalities depending on which one is being used. For incoming | |
11531 | connections, see &$received_ip_address$&. | |
11532 | ||
11533 | .vitem &$sending_port$& | |
11534 | .vindex "&$sending_port$&" | |
11535 | This variable is set whenever an outgoing SMTP connection to another host has | |
11536 | been set up. It contains the local port that is being used. For incoming | |
11537 | connections, see &$received_port$&. | |
f89d2485 | 11538 | |
9b371988 | 11539 | .vitem &$smtp_active_hostname$& |
f89d2485 | 11540 | .vindex "&$smtp_active_hostname$&" |
3cb1b51e PH |
11541 | During an incoming SMTP session, this variable contains the value of the active |
11542 | host name, as specified by the &%smtp_active_hostname%& option. The value of | |
9b371988 PH |
11543 | &$smtp_active_hostname$& is saved with any message that is received, so its |
11544 | value can be consulted during routing and delivery. | |
11545 | ||
9b371988 | 11546 | .vitem &$smtp_command$& |
f89d2485 | 11547 | .vindex "&$smtp_command$&" |
068aaea8 PH |
11548 | During the processing of an incoming SMTP command, this variable contains the |
11549 | entire command. This makes it possible to distinguish between HELO and EHLO in | |
11550 | the HELO ACL, and also to distinguish between commands such as these: | |
9b371988 | 11551 | .code |
068aaea8 PH |
11552 | MAIL FROM:<> |
11553 | MAIL FROM: <> | |
9b371988 | 11554 | .endd |
068aaea8 | 11555 | For a MAIL command, extra parameters such as SIZE can be inspected. For a RCPT |
9b371988 PH |
11556 | command, the address in &$smtp_command$& is the original address before any |
11557 | rewriting, whereas the values in &$local_part$& and &$domain$& are taken from | |
11558 | the address after SMTP-time rewriting. | |
9b371988 PH |
11559 | |
11560 | .vitem &$smtp_command_argument$& | |
f89d2485 PH |
11561 | .cindex "SMTP" "command, argument for" |
11562 | .vindex "&$smtp_command_argument$&" | |
068aaea8 PH |
11563 | While an ACL is running to check an SMTP command, this variable contains the |
11564 | argument, that is, the text that follows the command name, with leading white | |
9b371988 | 11565 | space removed. Following the introduction of &$smtp_command$&, this variable is |
068aaea8 | 11566 | somewhat redundant, but is retained for backwards compatibility. |
168e428f | 11567 | |
f89d2485 PH |
11568 | .vitem &$smtp_count_at_connection_start$& |
11569 | .vindex "&$smtp_count_at_connection_start$&" | |
11570 | This variable is set greater than zero only in processes spawned by the Exim | |
11571 | daemon for handling incoming SMTP connections. The name is deliberately long, | |
11572 | in order to emphasize what the contents are. When the daemon accepts a new | |
11573 | connection, it increments this variable. A copy of the variable is passed to | |
11574 | the child process that handles the connection, but its value is fixed, and | |
11575 | never changes. It is only an approximation of how many incoming connections | |
11576 | there actually are, because many other connections may come and go while a | |
11577 | single connection is being processed. When a child process terminates, the | |
11578 | daemon decrements its copy of the variable. | |
f89d2485 | 11579 | |
9b371988 PH |
11580 | .vitem "&$sn0$& &-- &$sn9$&" |
11581 | These variables are copies of the values of the &$n0$& &-- &$n9$& accumulators | |
11582 | that were current at the end of the system filter file. This allows a system | |
11583 | filter file to set values that can be tested in users' filter files. For | |
11584 | example, a system filter could set a value indicating how likely it is that a | |
11585 | message is junk mail. | |
168e428f | 11586 | |
9b371988 PH |
11587 | .vitem &$spam_$&&'xxx'& |
11588 | A number of variables whose names start with &$spam$& are available when Exim | |
11589 | is compiled with the content-scanning extension. For details, see section | |
11590 | &<<SECTscanspamass>>&. | |
168e428f PH |
11591 | |
11592 | ||
9b371988 | 11593 | .vitem &$spool_directory$& |
f89d2485 | 11594 | .vindex "&$spool_directory$&" |
168e428f PH |
11595 | The name of Exim's spool directory. |
11596 | ||
9b371988 | 11597 | .vitem &$spool_inodes$& |
f89d2485 | 11598 | .vindex "&$spool_inodes$&" |
168e428f PH |
11599 | The number of free inodes in the disk partition where Exim's spool files are |
11600 | being written. The value is recalculated whenever the variable is referenced. | |
11601 | If the relevant file system does not have the concept of inodes, the value of | |
9b371988 | 11602 | is -1. See also the &%check_spool_inodes%& option. |
168e428f | 11603 | |
9b371988 | 11604 | .vitem &$spool_space$& |
f89d2485 | 11605 | .vindex "&$spool_space$&" |
168e428f PH |
11606 | The amount of free space (as a number of kilobytes) in the disk partition where |
11607 | Exim's spool files are being written. The value is recalculated whenever the | |
11608 | variable is referenced. If the operating system does not have the ability to | |
11609 | find the amount of free space (only true for experimental systems), the space | |
11610 | value is -1. For example, to check in an ACL that there is at least 50 | |
11611 | megabytes free on the spool, you could write: | |
9b371988 PH |
11612 | .code |
11613 | condition = ${if > {$spool_space}{50000}} | |
11614 | .endd | |
11615 | See also the &%check_spool_space%& option. | |
11616 | ||
11617 | ||
11618 | .vitem &$thisaddress$& | |
f89d2485 | 11619 | .vindex "&$thisaddress$&" |
9b371988 PH |
11620 | This variable is set only during the processing of the &%foranyaddress%& |
11621 | command in a filter file. Its use is explained in the description of that | |
11622 | command, which can be found in the separate document entitled &'Exim's | |
11623 | interfaces to mail filtering'&. | |
11624 | ||
11625 | .vitem &$tls_certificate_verified$& | |
f89d2485 | 11626 | .vindex "&$tls_certificate_verified$&" |
9b371988 PH |
11627 | This variable is set to &"1"& if a TLS certificate was verified when the |
11628 | message was received, and &"0"& otherwise. | |
11629 | ||
11630 | .vitem &$tls_cipher$& | |
f89d2485 | 11631 | .vindex "&$tls_cipher$&" |
168e428f PH |
11632 | When a message is received from a remote host over an encrypted SMTP |
11633 | connection, this variable is set to the cipher suite that was negotiated, for | |
11634 | example DES-CBC3-SHA. In other circumstances, in particular, for message | |
595028e4 PH |
11635 | received over unencrypted connections, the variable is empty. Testing |
11636 | &$tls_cipher$& for emptiness is one way of distinguishing between encrypted and | |
11637 | non-encrypted connections during ACL processing. | |
11638 | ||
11639 | The &$tls_cipher$& variable retains its value during message delivery, except | |
11640 | when an outward SMTP delivery takes place via the &(smtp)& transport. In this | |
11641 | case, &$tls_cipher$& is cleared before any outgoing SMTP connection is made, | |
11642 | and then set to the outgoing cipher suite if one is negotiated. See chapter | |
11643 | &<<CHAPTLS>>& for details of TLS support and chapter &<<CHAPsmtptrans>>& for | |
11644 | details of the &(smtp)& transport. | |
168e428f | 11645 | |
9b371988 | 11646 | .vitem &$tls_peerdn$& |
f89d2485 | 11647 | .vindex "&$tls_peerdn$&" |
068aaea8 | 11648 | When a message is received from a remote host over an encrypted SMTP |
168e428f PH |
11649 | connection, and Exim is configured to request a certificate from the client, |
11650 | the value of the Distinguished Name of the certificate is made available in the | |
7d0ab55c | 11651 | &$tls_peerdn$& during subsequent processing. Like &$tls_cipher$&, the |
595028e4 | 11652 | value is retained during message delivery, except during outbound SMTP |
7d0ab55c | 11653 | deliveries. |
168e428f | 11654 | |
9b371988 | 11655 | .vitem &$tod_bsdinbox$& |
f89d2485 | 11656 | .vindex "&$tod_bsdinbox$&" |
9b371988 PH |
11657 | The time of day and the date, in the format required for BSD-style mailbox |
11658 | files, for example: Thu Oct 17 17:14:09 1995. | |
168e428f | 11659 | |
9b371988 | 11660 | .vitem &$tod_epoch$& |
f89d2485 | 11661 | .vindex "&$tod_epoch$&" |
168e428f PH |
11662 | The time and date as a number of seconds since the start of the Unix epoch. |
11663 | ||
9b371988 | 11664 | .vitem &$tod_full$& |
f89d2485 | 11665 | .vindex "&$tod_full$&" |
168e428f PH |
11666 | A full version of the time and date, for example: Wed, 16 Oct 1995 09:51:40 |
11667 | +0100. The timezone is always given as a numerical offset from UTC, with | |
11668 | positive values used for timezones that are ahead (east) of UTC, and negative | |
11669 | values for those that are behind (west). | |
11670 | ||
9b371988 | 11671 | .vitem &$tod_log$& |
f89d2485 | 11672 | .vindex "&$tod_log$&" |
168e428f PH |
11673 | The time and date in the format used for writing Exim's log files, for example: |
11674 | 1995-10-12 15:32:29, but without a timezone. | |
11675 | ||
9b371988 | 11676 | .vitem &$tod_logfile$& |
f89d2485 | 11677 | .vindex "&$tod_logfile$&" |
168e428f | 11678 | This variable contains the date in the format yyyymmdd. This is the format that |
9b371988 | 11679 | is used for datestamping log files when &%log_file_path%& contains the &`%D`& |
168e428f PH |
11680 | flag. |
11681 | ||
9b371988 | 11682 | .vitem &$tod_zone$& |
f89d2485 | 11683 | .vindex "&$tod_zone$&" |
168e428f PH |
11684 | This variable contains the numerical value of the local timezone, for example: |
11685 | -0500. | |
11686 | ||
9b371988 | 11687 | .vitem &$tod_zulu$& |
f89d2485 | 11688 | .vindex "&$tod_zulu$&" |
9b371988 PH |
11689 | This variable contains the UTC date and time in &"Zulu"& format, as specified |
11690 | by ISO 8601, for example: 20030221154023Z. | |
168e428f | 11691 | |
9b371988 | 11692 | .vitem &$value$& |
f89d2485 | 11693 | .vindex "&$value$&" |
168e428f | 11694 | This variable contains the result of an expansion lookup, extraction operation, |
595028e4 PH |
11695 | or external command, as described above. It is also used during a |
11696 | &*reduce*& expansion. | |
168e428f | 11697 | |
9b371988 | 11698 | .vitem &$version_number$& |
f89d2485 | 11699 | .vindex "&$version_number$&" |
168e428f PH |
11700 | The version number of Exim. |
11701 | ||
9b371988 | 11702 | .vitem &$warn_message_delay$& |
f89d2485 | 11703 | .vindex "&$warn_message_delay$&" |
168e428f | 11704 | This variable is set only during the creation of a message warning about a |
9b371988 | 11705 | delivery delay. Details of its use are explained in section &<<SECTcustwarn>>&. |
168e428f | 11706 | |
9b371988 | 11707 | .vitem &$warn_message_recipients$& |
f89d2485 | 11708 | .vindex "&$warn_message_recipients$&" |
168e428f | 11709 | This variable is set only during the creation of a message warning about a |
9b371988 PH |
11710 | delivery delay. Details of its use are explained in section &<<SECTcustwarn>>&. |
11711 | .endlist | |
4f578862 | 11712 | .ecindex IIDstrexp |
168e428f PH |
11713 | |
11714 | ||
11715 | ||
9b371988 PH |
11716 | . //////////////////////////////////////////////////////////////////////////// |
11717 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 11718 | |
9b371988 | 11719 | .chapter "Embedded Perl" "CHAPperl" |
4f578862 | 11720 | .scindex IIDperl "Perl" "calling from Exim" |
168e428f PH |
11721 | Exim can be built to include an embedded Perl interpreter. When this is done, |
11722 | Perl subroutines can be called as part of the string expansion process. To make | |
11723 | use of the Perl support, you need version 5.004 or later of Perl installed on | |
11724 | your system. To include the embedded interpreter in the Exim binary, include | |
11725 | the line | |
9b371988 PH |
11726 | .code |
11727 | EXIM_PERL = perl.o | |
11728 | .endd | |
11729 | in your &_Local/Makefile_& and then build Exim in the normal way. | |
168e428f PH |
11730 | |
11731 | ||
f89d2485 | 11732 | .section "Setting up so Perl can be used" "SECID85" |
0a4e3112 | 11733 | .oindex "&%perl_startup%&" |
168e428f | 11734 | Access to Perl subroutines is via a global configuration option called |
9b371988 PH |
11735 | &%perl_startup%& and an expansion string operator &%${perl ...}%&. If there is |
11736 | no &%perl_startup%& option in the Exim configuration file then no Perl | |
168e428f | 11737 | interpreter is started and there is almost no overhead for Exim (since none of |
9b371988 | 11738 | the Perl library will be paged in unless used). If there is a &%perl_startup%& |
168e428f PH |
11739 | option then the associated value is taken to be Perl code which is executed in |
11740 | a newly created Perl interpreter. | |
11741 | ||
9b371988 | 11742 | The value of &%perl_startup%& is not expanded in the Exim sense, so you do not |
168e428f PH |
11743 | need backslashes before any characters to escape special meanings. The option |
11744 | should usually be something like | |
9b371988 PH |
11745 | .code |
11746 | perl_startup = do '/etc/exim.pl' | |
11747 | .endd | |
11748 | where &_/etc/exim.pl_& is Perl code which defines any subroutines you want to | |
168e428f PH |
11749 | use from Exim. Exim can be configured either to start up a Perl interpreter as |
11750 | soon as it is entered, or to wait until the first time it is needed. Starting | |
11751 | the interpreter at the beginning ensures that it is done while Exim still has | |
11752 | its setuid privilege, but can impose an unnecessary overhead if Perl is not in | |
11753 | fact used in a particular run. Also, note that this does not mean that Exim is | |
11754 | necessarily running as root when Perl is called at a later time. By default, | |
11755 | the interpreter is started only when it is needed, but this can be changed in | |
11756 | two ways: | |
11757 | ||
9b371988 | 11758 | .ilist |
0a4e3112 | 11759 | .oindex "&%perl_at_start%&" |
9b371988 | 11760 | Setting &%perl_at_start%& (a boolean option) in the configuration requests |
168e428f | 11761 | a startup when Exim is entered. |
9b371988 PH |
11762 | .next |
11763 | The command line option &%-ps%& also requests a startup when Exim is entered, | |
11764 | overriding the setting of &%perl_at_start%&. | |
11765 | .endlist | |
168e428f | 11766 | |
9b371988 PH |
11767 | There is also a command line option &%-pd%& (for delay) which suppresses the |
11768 | initial startup, even if &%perl_at_start%& is set. | |
168e428f | 11769 | |
168e428f | 11770 | |
f89d2485 | 11771 | .section "Calling Perl subroutines" "SECID86" |
9b371988 | 11772 | When the configuration file includes a &%perl_startup%& option you can make use |
168e428f | 11773 | of the string expansion item to call the Perl subroutines that are defined |
9b371988 | 11774 | by the &%perl_startup%& code. The operator is used in any of the following |
168e428f | 11775 | forms: |
9b371988 PH |
11776 | .code |
11777 | ${perl{foo}} | |
11778 | ${perl{foo}{argument}} | |
11779 | ${perl{foo}{argument1}{argument2} ... } | |
11780 | .endd | |
11781 | which calls the subroutine &%foo%& with the given arguments. A maximum of eight | |
168e428f PH |
11782 | arguments may be passed. Passing more than this results in an expansion failure |
11783 | with an error message of the form | |
9b371988 PH |
11784 | .code |
11785 | Too many arguments passed to Perl subroutine "foo" (max is 8) | |
11786 | .endd | |
168e428f PH |
11787 | The return value of the Perl subroutine is evaluated in a scalar context before |
11788 | it is passed back to Exim to be inserted into the expanded string. If the | |
9b371988 PH |
11789 | return value is &'undef'&, the expansion is forced to fail in the same way as |
11790 | an explicit &"fail"& on an &%if%& or &%lookup%& item. If the subroutine aborts | |
11791 | by obeying Perl's &%die%& function, the expansion fails with the error message | |
11792 | that was passed to &%die%&. | |
168e428f PH |
11793 | |
11794 | ||
f89d2485 | 11795 | .section "Calling Exim functions from Perl" "SECID87" |
9b371988 | 11796 | Within any Perl code called from Exim, the function &'Exim::expand_string()'& |
168e428f PH |
11797 | is available to call back into Exim's string expansion function. For example, |
11798 | the Perl code | |
9b371988 PH |
11799 | .code |
11800 | my $lp = Exim::expand_string('$local_part'); | |
11801 | .endd | |
11802 | makes the current Exim &$local_part$& available in the Perl variable &$lp$&. | |
168e428f | 11803 | Note those are single quotes and not double quotes to protect against |
9b371988 | 11804 | &$local_part$& being interpolated as a Perl variable. |
168e428f | 11805 | |
9b371988 PH |
11806 | If the string expansion is forced to fail by a &"fail"& item, the result of |
11807 | &'Exim::expand_string()'& is &%undef%&. If there is a syntax error in the | |
168e428f | 11808 | expansion string, the Perl call from the original expansion string fails with |
9b371988 | 11809 | an appropriate error message, in the same way as if &%die%& were used. |
168e428f | 11810 | |
9b371988 PH |
11811 | .cindex "debugging" "from embedded Perl" |
11812 | .cindex "log" "writing from embedded Perl" | |
168e428f | 11813 | Two other Exim functions are available for use from within Perl code. |
9b371988 PH |
11814 | &'Exim::debug_write()'& writes a string to the standard error stream if Exim's |
11815 | debugging is enabled. If you want a newline at the end, you must supply it. | |
11816 | &'Exim::log_write()'& writes a string to Exim's main log, adding a leading | |
11817 | timestamp. In this case, you should not supply a terminating newline. | |
168e428f PH |
11818 | |
11819 | ||
f89d2485 | 11820 | .section "Use of standard output and error by Perl" "SECID88" |
9b371988 | 11821 | .cindex "Perl" "standard output and error" |
168e428f PH |
11822 | You should not write to the standard error or output streams from within your |
11823 | Perl code, as it is not defined how these are set up. In versions of Exim | |
11824 | before 4.50, it is possible for the standard output or error to refer to the | |
11825 | SMTP connection during message reception via the daemon. Writing to this stream | |
11826 | is certain to cause chaos. From Exim 4.50 onwards, the standard output and | |
9b371988 | 11827 | error streams are connected to &_/dev/null_& in the daemon. The chaos is |
168e428f PH |
11828 | avoided, but the output is lost. |
11829 | ||
9b371988 PH |
11830 | .cindex "Perl" "use of &%warn%&" |
11831 | The Perl &%warn%& statement writes to the standard error stream by default. | |
11832 | Calls to &%warn%& may be embedded in Perl modules that you use, but over which | |
11833 | you have no control. When Exim starts up the Perl interpreter, it arranges for | |
11834 | output from the &%warn%& statement to be written to the Exim main log. You can | |
11835 | change this by including appropriate Perl magic somewhere in your Perl code. | |
11836 | For example, to discard &%warn%& output completely, you need this: | |
11837 | .code | |
11838 | $SIG{__WARN__} = sub { }; | |
11839 | .endd | |
11840 | Whenever a &%warn%& is obeyed, the anonymous subroutine is called. In this | |
168e428f | 11841 | example, the code for the subroutine is empty, so it does nothing, but you can |
9b371988 | 11842 | include any Perl code that you like. The text of the &%warn%& message is passed |
168e428f | 11843 | as the first subroutine argument. |
4f578862 | 11844 | .ecindex IIDperl |
168e428f PH |
11845 | |
11846 | ||
9b371988 PH |
11847 | . //////////////////////////////////////////////////////////////////////////// |
11848 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 11849 | |
9b371988 PH |
11850 | .chapter "Starting the daemon and the use of network interfaces" &&& |
11851 | "CHAPinterfaces" &&& | |
11852 | "Starting the daemon" | |
11853 | .cindex "daemon" "starting" | |
11854 | .cindex "interface" "listening" | |
11855 | .cindex "network interface" | |
11856 | .cindex "interface" "network" | |
11857 | .cindex "IP address" "for listening" | |
11858 | .cindex "daemon" "listening IP addresses" | |
11859 | .cindex "TCP/IP" "setting listening interfaces" | |
11860 | .cindex "TCP/IP" "setting listening ports" | |
168e428f PH |
11861 | A host that is connected to a TCP/IP network may have one or more physical |
11862 | hardware network interfaces. Each of these interfaces may be configured as one | |
9b371988 | 11863 | or more &"logical"& interfaces, which are the entities that a program actually |
168e428f | 11864 | works with. Each of these logical interfaces is associated with an IP address. |
9b371988 PH |
11865 | In addition, TCP/IP software supports &"loopback"& interfaces (127.0.0.1 in |
11866 | IPv4 and ::1 in IPv6), which do not use any physical hardware. Exim requires | |
168e428f PH |
11867 | knowledge about the host's interfaces for use in three different circumstances: |
11868 | ||
9b371988 PH |
11869 | .olist |
11870 | When a listening daemon is started, Exim needs to know which interfaces | |
168e428f | 11871 | and ports to listen on. |
9b371988 PH |
11872 | .next |
11873 | When Exim is routing an address, it needs to know which IP addresses | |
168e428f PH |
11874 | are associated with local interfaces. This is required for the correct |
11875 | processing of MX lists by removing the local host and others with the | |
11876 | same or higher priority values. Also, Exim needs to detect cases | |
11877 | when an address is routed to an IP address that in fact belongs to the | |
9b371988 | 11878 | local host. Unless the &%self%& router option or the &%allow_localhost%& |
168e428f PH |
11879 | option of the smtp transport is set (as appropriate), this is treated |
11880 | as an error situation. | |
9b371988 PH |
11881 | .next |
11882 | When Exim connects to a remote host, it may need to know which interface to use | |
168e428f | 11883 | for the outgoing connection. |
9b371988 | 11884 | .endlist |
168e428f PH |
11885 | |
11886 | ||
11887 | Exim's default behaviour is likely to be appropriate in the vast majority | |
11888 | of cases. If your host has only one interface, and you want all its IP | |
11889 | addresses to be treated in the same way, and you are using only the | |
11890 | standard SMTP port, you should not need to take any special action. The | |
11891 | rest of this chapter does not apply to you. | |
11892 | ||
11893 | In a more complicated situation you may want to listen only on certain | |
11894 | interfaces, or on different ports, and for this reason there are a number of | |
11895 | options that can be used to influence Exim's behaviour. The rest of this | |
11896 | chapter describes how they operate. | |
11897 | ||
11898 | When a message is received over TCP/IP, the interface and port that were | |
3cb1b51e | 11899 | actually used are set in &$received_ip_address$& and &$received_port$&. |
168e428f PH |
11900 | |
11901 | ||
11902 | ||
f89d2485 | 11903 | .section "Starting a listening daemon" "SECID89" |
9b371988 | 11904 | When a listening daemon is started (by means of the &%-bd%& command line |
168e428f PH |
11905 | option), the interfaces and ports on which it listens are controlled by the |
11906 | following options: | |
11907 | ||
9b371988 PH |
11908 | .ilist |
11909 | &%daemon_smtp_ports%& contains a list of default ports. (For backward | |
168e428f | 11910 | compatibility, this option can also be specified in the singular.) |
9b371988 PH |
11911 | .next |
11912 | &%local_interfaces%& contains list of interface IP addresses on which to | |
168e428f | 11913 | listen. Each item may optionally also specify a port. |
9b371988 | 11914 | .endlist |
168e428f PH |
11915 | |
11916 | The default list separator in both cases is a colon, but this can be changed as | |
9b371988 PH |
11917 | described in section &<<SECTlistconstruct>>&. When IPv6 addresses are involved, |
11918 | it is usually best to change the separator to avoid having to double all the | |
168e428f | 11919 | colons. For example: |
9b371988 | 11920 | .code |
168e428f PH |
11921 | local_interfaces = <; 127.0.0.1 ; \ |
11922 | 192.168.23.65 ; \ | |
11923 | ::1 ; \ | |
11924 | 3ffe:ffff:836f::fe86:a061 | |
9b371988 | 11925 | .endd |
168e428f | 11926 | There are two different formats for specifying a port along with an IP address |
9b371988 | 11927 | in &%local_interfaces%&: |
168e428f | 11928 | |
9b371988 PH |
11929 | .olist |
11930 | The port is added onto the address with a dot separator. For example, to listen | |
168e428f | 11931 | on port 1234 on two different IP addresses: |
9b371988 | 11932 | .code |
168e428f PH |
11933 | local_interfaces = <; 192.168.23.65.1234 ; \ |
11934 | 3ffe:ffff:836f::fe86:a061.1234 | |
9b371988 PH |
11935 | .endd |
11936 | .next | |
11937 | The IP address is enclosed in square brackets, and the port is added | |
168e428f | 11938 | with a colon separator, for example: |
9b371988 | 11939 | .code |
168e428f PH |
11940 | local_interfaces = <; [192.168.23.65]:1234 ; \ |
11941 | [3ffe:ffff:836f::fe86:a061]:1234 | |
9b371988 PH |
11942 | .endd |
11943 | .endlist | |
168e428f | 11944 | |
9b371988 | 11945 | When a port is not specified, the value of &%daemon_smtp_ports%& is used. The |
168e428f | 11946 | default setting contains just one port: |
9b371988 PH |
11947 | .code |
11948 | daemon_smtp_ports = smtp | |
11949 | .endd | |
168e428f PH |
11950 | If more than one port is listed, each interface that does not have its own port |
11951 | specified listens on all of them. Ports that are listed in | |
9b371988 PH |
11952 | &%daemon_smtp_ports%& can be identified either by name (defined in |
11953 | &_/etc/services_&) or by number. However, when ports are given with individual | |
11954 | IP addresses in &%local_interfaces%&, only numbers (not names) can be used. | |
168e428f PH |
11955 | |
11956 | ||
11957 | ||
f89d2485 | 11958 | .section "Special IP listening addresses" "SECID90" |
168e428f | 11959 | The addresses 0.0.0.0 and ::0 are treated specially. They are interpreted |
9b371988 PH |
11960 | as &"all IPv4 interfaces"& and &"all IPv6 interfaces"&, respectively. In each |
11961 | case, Exim tells the TCP/IP stack to &"listen on all IPv&'x'& interfaces"& | |
168e428f | 11962 | instead of setting up separate listening sockets for each interface. The |
9b371988 PH |
11963 | default value of &%local_interfaces%& is |
11964 | .code | |
11965 | local_interfaces = 0.0.0.0 | |
11966 | .endd | |
168e428f | 11967 | when Exim is built without IPv6 support; otherwise it is: |
9b371988 PH |
11968 | .code |
11969 | local_interfaces = <; ::0 ; 0.0.0.0 | |
11970 | .endd | |
168e428f PH |
11971 | Thus, by default, Exim listens on all available interfaces, on the SMTP port. |
11972 | ||
11973 | ||
11974 | ||
f89d2485 | 11975 | .section "Overriding local_interfaces and daemon_smtp_ports" "SECID91" |
9b371988 PH |
11976 | The &%-oX%& command line option can be used to override the values of |
11977 | &%daemon_smtp_ports%& and/or &%local_interfaces%& for a particular daemon | |
11978 | instance. Another way of doing this would be to use macros and the &%-D%& | |
11979 | option. However, &%-oX%& can be used by any admin user, whereas modification of | |
11980 | the runtime configuration by &%-D%& is allowed only when the caller is root or | |
168e428f PH |
11981 | exim. |
11982 | ||
9b371988 | 11983 | The value of &%-oX%& is a list of items. The default colon separator can be |
168e428f PH |
11984 | changed in the usual way if required. If there are any items that do not |
11985 | contain dots or colons (that is, are not IP addresses), the value of | |
9b371988 PH |
11986 | &%daemon_smtp_ports%& is replaced by the list of those items. If there are any |
11987 | items that do contain dots or colons, the value of &%local_interfaces%& is | |
168e428f | 11988 | replaced by those items. Thus, for example, |
9b371988 PH |
11989 | .code |
11990 | -oX 1225 | |
11991 | .endd | |
11992 | overrides &%daemon_smtp_ports%&, but leaves &%local_interfaces%& unchanged, | |
168e428f | 11993 | whereas |
9b371988 PH |
11994 | .code |
11995 | -oX 192.168.34.5.1125 | |
11996 | .endd | |
11997 | overrides &%local_interfaces%&, leaving &%daemon_smtp_ports%& unchanged. | |
11998 | (However, since &%local_interfaces%& now contains no items without ports, the | |
11999 | value of &%daemon_smtp_ports%& is no longer relevant in this example.) | |
168e428f PH |
12000 | |
12001 | ||
12002 | ||
9b371988 PH |
12003 | .section "Support for the obsolete SSMTP (or SMTPS) protocol" "SECTsupobssmt" |
12004 | .cindex "ssmtp protocol" | |
12005 | .cindex "smtps protocol" | |
12006 | .cindex "SMTP" "ssmtp protocol" | |
12007 | .cindex "SMTP" "smtps protocol" | |
168e428f PH |
12008 | Exim supports the obsolete SSMTP protocol (also known as SMTPS) that was used |
12009 | before the STARTTLS command was standardized for SMTP. Some legacy clients | |
9b371988 | 12010 | still use this protocol. If the &%tls_on_connect_ports%& option is set to a |
168e428f PH |
12011 | list of port numbers, connections to those ports must use SSMTP. The most |
12012 | common use of this option is expected to be | |
9b371988 PH |
12013 | .code |
12014 | tls_on_connect_ports = 465 | |
12015 | .endd | |
168e428f | 12016 | because 465 is the usual port number used by the legacy clients. There is also |
9b371988 | 12017 | a command line option &%-tls-on-connect%&, which forces all ports to behave in |
168e428f PH |
12018 | this way when a daemon is started. |
12019 | ||
9b371988 | 12020 | &*Warning*&: Setting &%tls_on_connect_ports%& does not of itself cause the |
168e428f | 12021 | daemon to listen on those ports. You must still specify them in |
9b371988 PH |
12022 | &%daemon_smtp_ports%&, &%local_interfaces%&, or the &%-oX%& option. (This is |
12023 | because &%tls_on_connect_ports%& applies to &%inetd%& connections as well as to | |
168e428f PH |
12024 | connections via the daemon.) |
12025 | ||
12026 | ||
12027 | ||
12028 | ||
f89d2485 | 12029 | .section "IPv6 address scopes" "SECID92" |
4f578862 | 12030 | .cindex "IPv6" "address scopes" |
9b371988 | 12031 | IPv6 addresses have &"scopes"&, and a host with multiple hardware interfaces |
168e428f PH |
12032 | can, in principle, have the same link-local IPv6 address on different |
12033 | interfaces. Thus, additional information is needed, over and above the IP | |
12034 | address, to distinguish individual interfaces. A convention of using a | |
12035 | percent sign followed by something (often the interface name) has been | |
12036 | adopted in some cases, leading to addresses like this: | |
9b371988 PH |
12037 | .code |
12038 | fe80::202:b3ff:fe03:45c1%eth0 | |
12039 | .endd | |
168e428f | 12040 | To accommodate this usage, a percent sign followed by an arbitrary string is |
9b371988 | 12041 | allowed at the end of an IPv6 address. By default, Exim calls &[getaddrinfo()]& |
168e428f PH |
12042 | to convert a textual IPv6 address for actual use. This function recognizes the |
12043 | percent convention in operating systems that support it, and it processes the | |
12044 | address appropriately. Unfortunately, some older libraries have problems with | |
9b371988 PH |
12045 | &[getaddrinfo()]&. If |
12046 | .code | |
12047 | IPV6_USE_INET_PTON=yes | |
12048 | .endd | |
12049 | is set in &_Local/Makefile_& (or an OS-dependent Makefile) when Exim is built, | |
12050 | Exim uses &'inet_pton()'& to convert a textual IPv6 address for actual use, | |
12051 | instead of &[getaddrinfo()]&. (Before version 4.14, it always used this | |
168e428f | 12052 | function.) Of course, this means that the additional functionality of |
9b371988 | 12053 | &[getaddrinfo()]& &-- recognizing scoped addresses &-- is lost. |
168e428f | 12054 | |
f89d2485 | 12055 | .section "Disabling IPv6" "SECID93" |
4f578862 PH |
12056 | .cindex "IPv6" "disabling" |
12057 | Sometimes it happens that an Exim binary that was compiled with IPv6 support is | |
12058 | run on a host whose kernel does not support IPv6. The binary will fall back to | |
12059 | using IPv4, but it may waste resources looking up AAAA records, and trying to | |
12060 | connect to IPv6 addresses, causing delays to mail delivery. If you set the | |
12061 | .oindex "&%disable_ipv6%&" | |
12062 | &%disable_ipv6%& option true, even if the Exim binary has IPv6 support, no IPv6 | |
12063 | activities take place. AAAA records are never looked up, and any IPv6 addresses | |
12064 | that are listed in &%local_interfaces%&, data for the &(manualroute)& router, | |
12065 | etc. are ignored. If IP literals are enabled, the &(ipliteral)& router declines | |
12066 | to handle IPv6 literal addresses. | |
12067 | ||
12068 | On the other hand, when IPv6 is in use, there may be times when you want to | |
12069 | disable it for certain hosts or domains. You can use the &%dns_ipv4_lookup%& | |
12070 | option to globally suppress the lookup of AAAA records for specified domains, | |
12071 | and you can use the &%ignore_target_hosts%& generic router option to ignore | |
12072 | IPv6 addresses in an individual router. | |
4f578862 | 12073 | |
168e428f PH |
12074 | |
12075 | ||
f89d2485 | 12076 | .section "Examples of starting a listening daemon" "SECID94" |
168e428f | 12077 | The default case in an IPv6 environment is |
9b371988 PH |
12078 | .code |
12079 | daemon_smtp_ports = smtp | |
12080 | local_interfaces = <; ::0 ; 0.0.0.0 | |
12081 | .endd | |
168e428f PH |
12082 | This specifies listening on the smtp port on all IPv6 and IPv4 interfaces. |
12083 | Either one or two sockets may be used, depending on the characteristics of | |
12084 | the TCP/IP stack. (This is complicated and messy; for more information, | |
9b371988 | 12085 | read the comments in the &_daemon.c_& source file.) |
168e428f PH |
12086 | |
12087 | To specify listening on ports 25 and 26 on all interfaces: | |
9b371988 PH |
12088 | .code |
12089 | daemon_smtp_ports = 25 : 26 | |
12090 | .endd | |
12091 | (leaving &%local_interfaces%& at the default setting) or, more explicitly: | |
12092 | .code | |
168e428f PH |
12093 | local_interfaces = <; ::0.25 ; ::0.26 \ |
12094 | 0.0.0.0.25 ; 0.0.0.0.26 | |
9b371988 | 12095 | .endd |
168e428f PH |
12096 | To listen on the default port on all IPv4 interfaces, and on port 26 on the |
12097 | IPv4 loopback address only: | |
9b371988 PH |
12098 | .code |
12099 | local_interfaces = 0.0.0.0 : 127.0.0.1.26 | |
12100 | .endd | |
168e428f | 12101 | To specify listening on the default port on specific interfaces only: |
9b371988 PH |
12102 | .code |
12103 | local_interfaces = 192.168.34.67 : 192.168.34.67 | |
12104 | .endd | |
12105 | &*Warning*&: Such a setting excludes listening on the loopback interfaces. | |
168e428f | 12106 | |
168e428f | 12107 | |
168e428f | 12108 | |
f89d2485 | 12109 | .section "Recognizing the local host" "SECTreclocipadd" |
9b371988 | 12110 | The &%local_interfaces%& option is also used when Exim needs to determine |
168e428f PH |
12111 | whether or not an IP address refers to the local host. That is, the IP |
12112 | addresses of all the interfaces on which a daemon is listening are always | |
12113 | treated as local. | |
12114 | ||
9b371988 | 12115 | For this usage, port numbers in &%local_interfaces%& are ignored. If either of |
168e428f PH |
12116 | the items 0.0.0.0 or ::0 are encountered, Exim gets a complete list of |
12117 | available interfaces from the operating system, and extracts the relevant | |
12118 | (that is, IPv4 or IPv6) addresses to use for checking. | |
12119 | ||
12120 | Some systems set up large numbers of virtual interfaces in order to provide | |
12121 | many virtual web servers. In this situation, you may want to listen for | |
12122 | email on only a few of the available interfaces, but nevertheless treat all | |
12123 | interfaces as local when routing. You can do this by setting | |
9b371988 PH |
12124 | &%extra_local_interfaces%& to a list of IP addresses, possibly including the |
12125 | &"all"& wildcard values. These addresses are recognized as local, but are not | |
168e428f | 12126 | used for listening. Consider this example: |
9b371988 | 12127 | .code |
168e428f PH |
12128 | local_interfaces = <; 127.0.0.1 ; ::1 ; \ |
12129 | 192.168.53.235 ; \ | |
12130 | 3ffe:2101:12:1:a00:20ff:fe86:a061 | |
12131 | ||
12132 | extra_local_interfaces = <; ::0 ; 0.0.0.0 | |
9b371988 | 12133 | .endd |
168e428f PH |
12134 | The daemon listens on the loopback interfaces and just one IPv4 and one IPv6 |
12135 | address, but all available interface addresses are treated as local when | |
12136 | Exim is routing. | |
12137 | ||
12138 | In some environments the local host name may be in an MX list, but with an IP | |
12139 | address that is not assigned to any local interface. In other cases it may be | |
12140 | desirable to treat other host names as if they referred to the local host. Both | |
9b371988 | 12141 | these cases can be handled by setting the &%hosts_treat_as_local%& option. |
168e428f PH |
12142 | This contains host names rather than IP addresses. When a host is referenced |
12143 | during routing, either via an MX record or directly, it is treated as the local | |
9b371988 PH |
12144 | host if its name matches &%hosts_treat_as_local%&, or if any of its IP |
12145 | addresses match &%local_interfaces%& or &%extra_local_interfaces%&. | |
168e428f PH |
12146 | |
12147 | ||
12148 | ||
f89d2485 | 12149 | .section "Delivering to a remote host" "SECID95" |
168e428f PH |
12150 | Delivery to a remote host is handled by the smtp transport. By default, it |
12151 | allows the system's TCP/IP functions to choose which interface to use (if | |
12152 | there is more than one) when connecting to a remote host. However, the | |
9b371988 PH |
12153 | &%interface%& option can be set to specify which interface is used. See the |
12154 | description of the smtp transport in chapter &<<CHAPsmtptrans>>& for more | |
12155 | details. | |
168e428f PH |
12156 | |
12157 | ||
12158 | ||
12159 | ||
9b371988 PH |
12160 | . //////////////////////////////////////////////////////////////////////////// |
12161 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 12162 | |
9b371988 | 12163 | .chapter "Main configuration" "CHAPmainconfig" |
4f578862 PH |
12164 | .scindex IIDconfima "configuration file" "main section" |
12165 | .scindex IIDmaiconf "main configuration" | |
168e428f PH |
12166 | The first part of the run time configuration file contains three types of item: |
12167 | ||
9b371988 PH |
12168 | .ilist |
12169 | Macro definitions: These lines start with an upper case letter. See section | |
12170 | &<<SECTmacrodefs>>& for details of macro processing. | |
12171 | .next | |
12172 | Named list definitions: These lines start with one of the words &"domainlist"&, | |
12173 | &"hostlist"&, &"addresslist"&, or &"localpartlist"&. Their use is described in | |
12174 | section &<<SECTnamedlists>>&. | |
12175 | .next | |
12176 | Main configuration settings: Each setting occupies one line of the file | |
168e428f | 12177 | (with possible continuations). If any setting is preceded by the word |
9b371988 PH |
12178 | &"hide"&, the &%-bP%& command line option displays its value to admin users |
12179 | only. See section &<<SECTcos>>& for a description of the syntax of these option | |
12180 | settings. | |
12181 | .endlist | |
168e428f PH |
12182 | |
12183 | This chapter specifies all the main configuration options, along with their | |
12184 | types and default values. For ease of finding a particular option, they appear | |
9b371988 PH |
12185 | in alphabetical order in section &<<SECTalomo>>& below. However, because there |
12186 | are now so many options, they are first listed briefly in functional groups, as | |
12187 | an aid to finding the name of the option you are looking for. Some options are | |
168e428f PH |
12188 | listed in more than one group. |
12189 | ||
f89d2485 | 12190 | .section "Miscellaneous" "SECID96" |
9b371988 PH |
12191 | .table2 |
12192 | .row &%bi_command%& "to run for &%-bi%& command line option" | |
4f578862 | 12193 | .row &%disable_ipv6%& "do no IPv6 processing" |
9b371988 PH |
12194 | .row &%keep_malformed%& "for broken files &-- should not happen" |
12195 | .row &%localhost_number%& "for unique message ids in clusters" | |
7d0ab55c | 12196 | .row &%message_body_newlines%& "retain newlines in &$message_body$&" |
9b371988 PH |
12197 | .row &%message_body_visible%& "how much to show in &$message_body$&" |
12198 | .row &%mua_wrapper%& "run in &""MUA wrapper""& mode" | |
12199 | .row &%print_topbitchars%& "top-bit characters are printing" | |
12200 | .row &%timezone%& "force time zone" | |
12201 | .endtable | |
12202 | ||
12203 | ||
f89d2485 | 12204 | .section "Exim parameters" "SECID97" |
9b371988 PH |
12205 | .table2 |
12206 | .row &%exim_group%& "override compiled-in value" | |
12207 | .row &%exim_path%& "override compiled-in value" | |
12208 | .row &%exim_user%& "override compiled-in value" | |
12209 | .row &%primary_hostname%& "default from &[uname()]&" | |
12210 | .row &%split_spool_directory%& "use multiple directories" | |
12211 | .row &%spool_directory%& "override compiled-in value" | |
12212 | .endtable | |
12213 | ||
12214 | ||
12215 | ||
f89d2485 | 12216 | .section "Privilege controls" "SECID98" |
9b371988 PH |
12217 | .table2 |
12218 | .row &%admin_groups%& "groups that are Exim admin users" | |
12219 | .row &%deliver_drop_privilege%& "drop root for delivery processes" | |
12220 | .row &%local_from_check%& "insert &'Sender:'& if necessary" | |
12221 | .row &%local_from_prefix%& "for testing &'From:'& for local sender" | |
12222 | .row &%local_from_suffix%& "for testing &'From:'& for local sender" | |
12223 | .row &%local_sender_retain%& "keep &'Sender:'& from untrusted user" | |
12224 | .row &%never_users%& "do not run deliveries as these" | |
12225 | .row &%prod_requires_admin%& "forced delivery requires admin user" | |
12226 | .row &%queue_list_requires_admin%& "queue listing requires admin user" | |
12227 | .row &%trusted_groups%& "groups that are trusted" | |
12228 | .row &%trusted_users%& "users that are trusted" | |
12229 | .endtable | |
12230 | ||
12231 | ||
12232 | ||
f89d2485 | 12233 | .section "Logging" "SECID99" |
9b371988 PH |
12234 | .table2 |
12235 | .row &%hosts_connection_nolog%& "exemption from connect logging" | |
12236 | .row &%log_file_path%& "override compiled-in value" | |
12237 | .row &%log_selector%& "set/unset optional logging" | |
12238 | .row &%log_timezone%& "add timezone to log lines" | |
12239 | .row &%message_logs%& "create per-message logs" | |
12240 | .row &%preserve_message_logs%& "after message completion" | |
12241 | .row &%process_log_path%& "for SIGUSR1 and &'exiwhat'&" | |
12242 | .row &%syslog_duplication%& "controls duplicate log lines on syslog" | |
12243 | .row &%syslog_facility%& "set syslog &""facility""& field" | |
12244 | .row &%syslog_processname%& "set syslog &""ident""& field" | |
12245 | .row &%syslog_timestamp%& "timestamp syslog lines" | |
12246 | .row &%write_rejectlog%& "control use of message log" | |
12247 | .endtable | |
12248 | ||
12249 | ||
12250 | ||
f89d2485 | 12251 | .section "Frozen messages" "SECID100" |
9b371988 PH |
12252 | .table2 |
12253 | .row &%auto_thaw%& "sets time for retrying frozen messages" | |
12254 | .row &%freeze_tell%& "send message when freezing" | |
12255 | .row &%move_frozen_messages%& "to another directory" | |
12256 | .row &%timeout_frozen_after%& "keep frozen messages only so long" | |
12257 | .endtable | |
12258 | ||
12259 | ||
12260 | ||
f89d2485 | 12261 | .section "Data lookups" "SECID101" |
9b371988 | 12262 | .table2 |
7d0ab55c | 12263 | .row &%ibase_servers%& "InterBase servers" |
9b371988 PH |
12264 | .row &%ldap_default_servers%& "used if no server in query" |
12265 | .row &%ldap_version%& "set protocol version" | |
12266 | .row &%lookup_open_max%& "lookup files held open" | |
7d0ab55c TF |
12267 | .row &%mysql_servers%& "default MySQL servers" |
12268 | .row &%oracle_servers%& "Oracle servers" | |
12269 | .row &%pgsql_servers%& "default PostgreSQL servers" | |
9b371988 PH |
12270 | .row &%sqlite_lock_timeout%& "as it says" |
12271 | .endtable | |
12272 | ||
12273 | ||
12274 | ||
f89d2485 | 12275 | .section "Message ids" "SECID102" |
9b371988 PH |
12276 | .table2 |
12277 | .row &%message_id_header_domain%& "used to build &'Message-ID:'& header" | |
12278 | .row &%message_id_header_text%& "ditto" | |
12279 | .endtable | |
12280 | ||
12281 | ||
12282 | ||
f89d2485 | 12283 | .section "Embedded Perl Startup" "SECID103" |
9b371988 PH |
12284 | .table2 |
12285 | .row &%perl_at_start%& "always start the interpreter" | |
12286 | .row &%perl_startup%& "code to obey when starting Perl" | |
12287 | .endtable | |
12288 | ||
12289 | ||
12290 | ||
f89d2485 | 12291 | .section "Daemon" "SECID104" |
9b371988 PH |
12292 | .table2 |
12293 | .row &%daemon_smtp_ports%& "default ports" | |
12294 | .row &%daemon_startup_retries%& "number of times to retry" | |
12295 | .row &%daemon_startup_sleep%& "time to sleep between tries" | |
12296 | .row &%extra_local_interfaces%& "not necessarily listened on" | |
12297 | .row &%local_interfaces%& "on which to listen, with optional ports" | |
12298 | .row &%pid_file_path%& "override compiled-in value" | |
12299 | .row &%queue_run_max%& "maximum simultaneous queue runners" | |
12300 | .endtable | |
12301 | ||
12302 | ||
12303 | ||
f89d2485 | 12304 | .section "Resource control" "SECID105" |
9b371988 PH |
12305 | .table2 |
12306 | .row &%check_log_inodes%& "before accepting a message" | |
12307 | .row &%check_log_space%& "before accepting a message" | |
12308 | .row &%check_spool_inodes%& "before accepting a message" | |
12309 | .row &%check_spool_space%& "before accepting a message" | |
12310 | .row &%deliver_queue_load_max%& "no queue deliveries if load high" | |
12311 | .row &%queue_only_load%& "queue incoming if load high" | |
7d0ab55c | 12312 | .row &%queue_only_load_latch%& "don't re-evaluate load for each message" |
9b371988 PH |
12313 | .row &%queue_run_max%& "maximum simultaneous queue runners" |
12314 | .row &%remote_max_parallel%& "parallel SMTP delivery per message" | |
12315 | .row &%smtp_accept_max%& "simultaneous incoming connections" | |
3cb1b51e | 12316 | .row &%smtp_accept_max_nonmail%& "non-mail commands" |
9b371988 PH |
12317 | .row &%smtp_accept_max_nonmail_hosts%& "hosts to which the limit applies" |
12318 | .row &%smtp_accept_max_per_connection%& "messages per connection" | |
12319 | .row &%smtp_accept_max_per_host%& "connections from one host" | |
12320 | .row &%smtp_accept_queue%& "queue mail if more connections" | |
12321 | .row &%smtp_accept_queue_per_connection%& "queue if more messages per &&& | |
12322 | connection" | |
12323 | .row &%smtp_accept_reserve%& "only reserve hosts if more connections" | |
12324 | .row &%smtp_check_spool_space%& "from SIZE on MAIL command" | |
12325 | .row &%smtp_connect_backlog%& "passed to TCP/IP stack" | |
12326 | .row &%smtp_load_reserve%& "SMTP from reserved hosts if load high" | |
12327 | .row &%smtp_reserve_hosts%& "these are the reserve hosts" | |
12328 | .endtable | |
12329 | ||
12330 | ||
12331 | ||
f89d2485 | 12332 | .section "Policy controls" "SECID106" |
9b371988 PH |
12333 | .table2 |
12334 | .row &%acl_not_smtp%& "ACL for non-SMTP messages" | |
12335 | .row &%acl_not_smtp_mime%& "ACL for non-SMTP MIME parts" | |
5d00f546 | 12336 | .row &%acl_not_smtp_start%& "ACL for start of non-SMTP message" |
9b371988 PH |
12337 | .row &%acl_smtp_auth%& "ACL for AUTH" |
12338 | .row &%acl_smtp_connect%& "ACL for connection" | |
12339 | .row &%acl_smtp_data%& "ACL for DATA" | |
12340 | .row &%acl_smtp_etrn%& "ACL for ETRN" | |
12341 | .row &%acl_smtp_expn%& "ACL for EXPN" | |
12342 | .row &%acl_smtp_helo%& "ACL for EHLO or HELO" | |
12343 | .row &%acl_smtp_mail%& "ACL for MAIL" | |
12344 | .row &%acl_smtp_mailauth%& "ACL for AUTH on MAIL command" | |
12345 | .row &%acl_smtp_mime%& "ACL for MIME parts" | |
12346 | .row &%acl_smtp_predata%& "ACL for start of data" | |
12347 | .row &%acl_smtp_quit%& "ACL for QUIT" | |
12348 | .row &%acl_smtp_rcpt%& "ACL for RCPT" | |
12349 | .row &%acl_smtp_starttls%& "ACL for STARTTLS" | |
12350 | .row &%acl_smtp_vrfy%& "ACL for VRFY" | |
12351 | .row &%av_scanner%& "specify virus scanner" | |
12352 | .row &%check_rfc2047_length%& "check length of RFC 2047 &""encoded &&& | |
12353 | words""&" | |
12354 | .row &%dns_csa_search_limit%& "control CSA parent search depth" | |
12355 | .row &%dns_csa_use_reverse%& "en/disable CSA IP reverse search" | |
12356 | .row &%header_maxsize%& "total size of message header" | |
12357 | .row &%header_line_maxsize%& "individual header line limit" | |
12358 | .row &%helo_accept_junk_hosts%& "allow syntactic junk from these hosts" | |
12359 | .row &%helo_allow_chars%& "allow illegal chars in HELO names" | |
12360 | .row &%helo_lookup_domains%& "lookup hostname for these HELO names" | |
12361 | .row &%helo_try_verify_hosts%& "HELO soft-checked for these hosts" | |
12362 | .row &%helo_verify_hosts%& "HELO hard-checked for these hosts" | |
12363 | .row &%host_lookup%& "host name looked up for these hosts" | |
12364 | .row &%host_lookup_order%& "order of DNS and local name lookups" | |
12365 | .row &%host_reject_connection%& "reject connection from these hosts" | |
12366 | .row &%hosts_treat_as_local%& "useful in some cluster configurations" | |
12367 | .row &%local_scan_timeout%& "timeout for &[local_scan()]&" | |
12368 | .row &%message_size_limit%& "for all messages" | |
12369 | .row &%percent_hack_domains%& "recognize %-hack for these domains" | |
12370 | .row &%spamd_address%& "set interface to SpamAssassin" | |
3cb1b51e | 12371 | .row &%strict_acl_vars%& "object to unset ACL variables" |
9b371988 PH |
12372 | .endtable |
12373 | ||
12374 | ||
12375 | ||
f89d2485 | 12376 | .section "Callout cache" "SECID107" |
9b371988 PH |
12377 | .table2 |
12378 | .row &%callout_domain_negative_expire%& "timeout for negative domain cache &&& | |
12379 | item" | |
12380 | .row &%callout_domain_positive_expire%& "timeout for positive domain cache &&& | |
12381 | item" | |
12382 | .row &%callout_negative_expire%& "timeout for negative address cache item" | |
12383 | .row &%callout_positive_expire%& "timeout for positive address cache item" | |
12384 | .row &%callout_random_local_part%& "string to use for &""random""& testing" | |
12385 | .endtable | |
12386 | ||
12387 | ||
12388 | ||
f89d2485 | 12389 | .section "TLS" "SECID108" |
9b371988 | 12390 | .table2 |
595028e4 PH |
12391 | .row &%gnutls_require_kx%& "control GnuTLS key exchanges" |
12392 | .row &%gnutls_require_mac%& "control GnuTLS MAC algorithms" | |
12393 | .row &%gnutls_require_protocols%& "control GnuTLS protocols" | |
e6060e2c | 12394 | .row &%gnutls_compat_mode%& "use GnuTLS compatibility mode" |
77bb000f | 12395 | .row &%openssl_options%& "adjust OpenSSL compatibility options" |
9b371988 PH |
12396 | .row &%tls_advertise_hosts%& "advertise TLS to these hosts" |
12397 | .row &%tls_certificate%& "location of server certificate" | |
12398 | .row &%tls_crl%& "certificate revocation list" | |
12399 | .row &%tls_dhparam%& "DH parameters for server" | |
12400 | .row &%tls_on_connect_ports%& "specify SSMTP (SMTPS) ports" | |
12401 | .row &%tls_privatekey%& "location of server private key" | |
12402 | .row &%tls_remember_esmtp%& "don't reset after starting TLS" | |
f89d2485 | 12403 | .row &%tls_require_ciphers%& "specify acceptable ciphers" |
9b371988 PH |
12404 | .row &%tls_try_verify_hosts%& "try to verify client certificate" |
12405 | .row &%tls_verify_certificates%& "expected client certificates" | |
12406 | .row &%tls_verify_hosts%& "insist on client certificate verify" | |
12407 | .endtable | |
12408 | ||
12409 | ||
12410 | ||
f89d2485 | 12411 | .section "Local user handling" "SECID109" |
9b371988 PH |
12412 | .table2 |
12413 | .row &%finduser_retries%& "useful in NIS environments" | |
12414 | .row &%gecos_name%& "used when creating &'Sender:'&" | |
12415 | .row &%gecos_pattern%& "ditto" | |
12416 | .row &%max_username_length%& "for systems that truncate" | |
12417 | .row &%unknown_login%& "used when no login name found" | |
12418 | .row &%unknown_username%& "ditto" | |
12419 | .row &%uucp_from_pattern%& "for recognizing &""From ""& lines" | |
12420 | .row &%uucp_from_sender%& "ditto" | |
12421 | .endtable | |
12422 | ||
12423 | ||
12424 | ||
f89d2485 | 12425 | .section "All incoming messages (SMTP and non-SMTP)" "SECID110" |
9b371988 PH |
12426 | .table2 |
12427 | .row &%header_maxsize%& "total size of message header" | |
12428 | .row &%header_line_maxsize%& "individual header line limit" | |
12429 | .row &%message_size_limit%& "applies to all messages" | |
12430 | .row &%percent_hack_domains%& "recognize %-hack for these domains" | |
12431 | .row &%received_header_text%& "expanded to make &'Received:'&" | |
12432 | .row &%received_headers_max%& "for mail loop detection" | |
12433 | .row &%recipients_max%& "limit per message" | |
f89d2485 | 12434 | .row &%recipients_max_reject%& "permanently reject excess recipients" |
9b371988 PH |
12435 | .endtable |
12436 | ||
12437 | ||
12438 | ||
12439 | ||
f89d2485 | 12440 | .section "Non-SMTP incoming messages" "SECID111" |
9b371988 PH |
12441 | .table2 |
12442 | .row &%receive_timeout%& "for non-SMTP messages" | |
12443 | .endtable | |
12444 | ||
12445 | ||
12446 | ||
12447 | ||
12448 | ||
f89d2485 | 12449 | .section "Incoming SMTP messages" "SECID112" |
9b371988 PH |
12450 | See also the &'Policy controls'& section above. |
12451 | ||
12452 | .table2 | |
12453 | .row &%host_lookup%& "host name looked up for these hosts" | |
12454 | .row &%host_lookup_order%& "order of DNS and local name lookups" | |
12455 | .row &%recipient_unqualified_hosts%& "may send unqualified recipients" | |
12456 | .row &%rfc1413_hosts%& "make ident calls to these hosts" | |
12457 | .row &%rfc1413_query_timeout%& "zero disables ident calls" | |
12458 | .row &%sender_unqualified_hosts%& "may send unqualified senders" | |
12459 | .row &%smtp_accept_keepalive%& "some TCP/IP magic" | |
12460 | .row &%smtp_accept_max%& "simultaneous incoming connections" | |
12461 | .row &%smtp_accept_max_nonmail%& "non-mail commands" | |
12462 | .row &%smtp_accept_max_nonmail_hosts%& "hosts to which the limit applies" | |
12463 | .row &%smtp_accept_max_per_connection%& "messages per connection" | |
12464 | .row &%smtp_accept_max_per_host%& "connections from one host" | |
12465 | .row &%smtp_accept_queue%& "queue mail if more connections" | |
12466 | .row &%smtp_accept_queue_per_connection%& "queue if more messages per &&& | |
12467 | connection" | |
12468 | .row &%smtp_accept_reserve%& "only reserve hosts if more connections" | |
12469 | .row &%smtp_active_hostname%& "host name to use in messages" | |
12470 | .row &%smtp_banner%& "text for welcome banner" | |
12471 | .row &%smtp_check_spool_space%& "from SIZE on MAIL command" | |
12472 | .row &%smtp_connect_backlog%& "passed to TCP/IP stack" | |
12473 | .row &%smtp_enforce_sync%& "of SMTP command/responses" | |
12474 | .row &%smtp_etrn_command%& "what to run for ETRN" | |
12475 | .row &%smtp_etrn_serialize%& "only one at once" | |
12476 | .row &%smtp_load_reserve%& "only reserve hosts if this load" | |
12477 | .row &%smtp_max_unknown_commands%& "before dropping connection" | |
12478 | .row &%smtp_ratelimit_hosts%& "apply ratelimiting to these hosts" | |
12479 | .row &%smtp_ratelimit_mail%& "ratelimit for MAIL commands" | |
12480 | .row &%smtp_ratelimit_rcpt%& "ratelimit for RCPT commands" | |
12481 | .row &%smtp_receive_timeout%& "per command or data line" | |
12482 | .row &%smtp_reserve_hosts%& "these are the reserve hosts" | |
12483 | .row &%smtp_return_error_details%& "give detail on rejections" | |
12484 | .endtable | |
12485 | ||
12486 | ||
12487 | ||
f89d2485 | 12488 | .section "SMTP extensions" "SECID113" |
9b371988 PH |
12489 | .table2 |
12490 | .row &%accept_8bitmime%& "advertise 8BITMIME" | |
12491 | .row &%auth_advertise_hosts%& "advertise AUTH to these hosts" | |
12492 | .row &%ignore_fromline_hosts%& "allow &""From ""& from these hosts" | |
12493 | .row &%ignore_fromline_local%& "allow &""From ""& from local SMTP" | |
12494 | .row &%pipelining_advertise_hosts%& "advertise pipelining to these hosts" | |
12495 | .row &%tls_advertise_hosts%& "advertise TLS to these hosts" | |
12496 | .endtable | |
12497 | ||
12498 | ||
12499 | ||
f89d2485 | 12500 | .section "Processing messages" "SECID114" |
9b371988 PH |
12501 | .table2 |
12502 | .row &%allow_domain_literals%& "recognize domain literal syntax" | |
12503 | .row &%allow_mx_to_ip%& "allow MX to point to IP address" | |
12504 | .row &%allow_utf8_domains%& "in addresses" | |
12505 | .row &%check_rfc2047_length%& "check length of RFC 2047 &""encoded &&& | |
12506 | words""&" | |
12507 | .row &%delivery_date_remove%& "from incoming messages" | |
db9452a9 | 12508 | .row &%envelope_to_remove%& "from incoming messages" |
9b371988 PH |
12509 | .row &%extract_addresses_remove_arguments%& "affects &%-t%& processing" |
12510 | .row &%headers_charset%& "default for translations" | |
12511 | .row &%qualify_domain%& "default for senders" | |
12512 | .row &%qualify_recipient%& "default for recipients" | |
12513 | .row &%return_path_remove%& "from incoming messages" | |
12514 | .row &%strip_excess_angle_brackets%& "in addresses" | |
12515 | .row &%strip_trailing_dot%& "at end of addresses" | |
12516 | .row &%untrusted_set_sender%& "untrusted can set envelope sender" | |
12517 | .endtable | |
12518 | ||
12519 | ||
12520 | ||
f89d2485 | 12521 | .section "System filter" "SECID115" |
9b371988 PH |
12522 | .table2 |
12523 | .row &%system_filter%& "locate system filter" | |
12524 | .row &%system_filter_directory_transport%& "transport for delivery to a &&& | |
12525 | directory" | |
12526 | .row &%system_filter_file_transport%& "transport for delivery to a file" | |
12527 | .row &%system_filter_group%& "group for filter running" | |
12528 | .row &%system_filter_pipe_transport%& "transport for delivery to a pipe" | |
12529 | .row &%system_filter_reply_transport%& "transport for autoreply delivery" | |
12530 | .row &%system_filter_user%& "user for filter running" | |
12531 | .endtable | |
12532 | ||
12533 | ||
12534 | ||
f89d2485 | 12535 | .section "Routing and delivery" "SECID116" |
9b371988 | 12536 | .table2 |
4f578862 | 12537 | .row &%disable_ipv6%& "do no IPv6 processing" |
9b371988 PH |
12538 | .row &%dns_again_means_nonexist%& "for broken domains" |
12539 | .row &%dns_check_names_pattern%& "pre-DNS syntax check" | |
12540 | .row &%dns_ipv4_lookup%& "only v4 lookup for these domains" | |
12541 | .row &%dns_retrans%& "parameter for resolver" | |
12542 | .row &%dns_retry%& "parameter for resolver" | |
12543 | .row &%hold_domains%& "hold delivery for these domains" | |
12544 | .row &%local_interfaces%& "for routing checks" | |
12545 | .row &%queue_domains%& "no immediate delivery for these" | |
12546 | .row &%queue_only%& "no immediate delivery at all" | |
12547 | .row &%queue_only_file%& "no immediate delivery if file exists" | |
12548 | .row &%queue_only_load%& "no immediate delivery if load is high" | |
7d0ab55c | 12549 | .row &%queue_only_load_latch%& "don't re-evaluate load for each message" |
9b371988 PH |
12550 | .row &%queue_only_override%& "allow command line to override" |
12551 | .row &%queue_run_in_order%& "order of arrival" | |
12552 | .row &%queue_run_max%& "of simultaneous queue runners" | |
12553 | .row &%queue_smtp_domains%& "no immediate SMTP delivery for these" | |
12554 | .row &%remote_max_parallel%& "parallel SMTP delivery per message" | |
12555 | .row &%remote_sort_domains%& "order of remote deliveries" | |
12556 | .row &%retry_data_expire%& "timeout for retry data" | |
12557 | .row &%retry_interval_max%& "safety net for retry rules" | |
12558 | .endtable | |
12559 | ||
12560 | ||
12561 | ||
f89d2485 | 12562 | .section "Bounce and warning messages" "SECID117" |
9b371988 PH |
12563 | .table2 |
12564 | .row &%bounce_message_file%& "content of bounce" | |
12565 | .row &%bounce_message_text%& "content of bounce" | |
12566 | .row &%bounce_return_body%& "include body if returning message" | |
12567 | .row &%bounce_return_message%& "include original message in bounce" | |
12568 | .row &%bounce_return_size_limit%& "limit on returned message" | |
12569 | .row &%bounce_sender_authentication%& "send authenticated sender with bounce" | |
595028e4 | 12570 | .row &%dsn_from%& "set &'From:'& contents in bounces" |
9b371988 PH |
12571 | .row &%errors_copy%& "copy bounce messages" |
12572 | .row &%errors_reply_to%& "&'Reply-to:'& in bounces" | |
12573 | .row &%delay_warning%& "time schedule" | |
12574 | .row &%delay_warning_condition%& "condition for warning messages" | |
12575 | .row &%ignore_bounce_errors_after%& "discard undeliverable bounces" | |
12576 | .row &%smtp_return_error_details%& "give detail on rejections" | |
12577 | .row &%warn_message_file%& "content of warning message" | |
12578 | .endtable | |
12579 | ||
12580 | ||
12581 | ||
12582 | .section "Alphabetical list of main options" "SECTalomo" | |
12583 | Those options that undergo string expansion before use are marked with | |
12584 | †. | |
12585 | ||
12586 | .option accept_8bitmime main boolean false | |
12587 | .cindex "8BITMIME" | |
12588 | .cindex "8-bit characters" | |
168e428f PH |
12589 | This option causes Exim to send 8BITMIME in its response to an SMTP |
12590 | EHLO command, and to accept the BODY= parameter on MAIL commands. | |
12591 | However, though Exim is 8-bit clean, it is not a protocol converter, and it | |
12592 | takes no steps to do anything special with messages received by this route. | |
12593 | Consequently, this option is turned off by default. | |
12594 | ||
9b371988 PH |
12595 | .option acl_not_smtp main string&!! unset |
12596 | .cindex "&ACL;" "for non-SMTP messages" | |
12597 | .cindex "non-SMTP messages" "ACLs for" | |
5d00f546 TF |
12598 | This option defines the ACL that is run when a non-SMTP message has been |
12599 | read and is on the point of being accepted. See chapter &<<CHAPACL>>& for | |
12600 | further details. | |
068aaea8 | 12601 | |
9b371988 | 12602 | .option acl_not_smtp_mime main string&!! unset |
068aaea8 | 12603 | This option defines the ACL that is run for individual MIME parts of non-SMTP |
9b371988 | 12604 | messages. It operates in exactly the same way as &%acl_smtp_mime%& operates for |
068aaea8 PH |
12605 | SMTP messages. |
12606 | ||
5d00f546 TF |
12607 | .option acl_not_smtp_start main string&!! unset |
12608 | .cindex "&ACL;" "at start of non-SMTP message" | |
12609 | .cindex "non-SMTP messages" "ACLs for" | |
12610 | This option defines the ACL that is run before Exim starts reading a | |
12611 | non-SMTP message. See chapter &<<CHAPACL>>& for further details. | |
12612 | ||
9b371988 PH |
12613 | .option acl_smtp_auth main string&!! unset |
12614 | .cindex "&ACL;" "setting up for SMTP commands" | |
12615 | .cindex "AUTH" "ACL for" | |
168e428f | 12616 | This option defines the ACL that is run when an SMTP AUTH command is |
9b371988 | 12617 | received. See chapter &<<CHAPACL>>& for further details. |
168e428f | 12618 | |
9b371988 PH |
12619 | .option acl_smtp_connect main string&!! unset |
12620 | .cindex "&ACL;" "on SMTP connection" | |
168e428f | 12621 | This option defines the ACL that is run when an SMTP connection is received. |
9b371988 | 12622 | See chapter &<<CHAPACL>>& for further details. |
168e428f | 12623 | |
9b371988 PH |
12624 | .option acl_smtp_data main string&!! unset |
12625 | .cindex "DATA" "ACL for" | |
168e428f PH |
12626 | This option defines the ACL that is run after an SMTP DATA command has been |
12627 | processed and the message itself has been received, but before the final | |
f89d2485 | 12628 | acknowledgment is sent. See chapter &<<CHAPACL>>& for further details. |
168e428f | 12629 | |
9b371988 PH |
12630 | .option acl_smtp_etrn main string&!! unset |
12631 | .cindex "ETRN" "ACL for" | |
168e428f | 12632 | This option defines the ACL that is run when an SMTP ETRN command is |
9b371988 | 12633 | received. See chapter &<<CHAPACL>>& for further details. |
168e428f | 12634 | |
9b371988 PH |
12635 | .option acl_smtp_expn main string&!! unset |
12636 | .cindex "EXPN" "ACL for" | |
168e428f | 12637 | This option defines the ACL that is run when an SMTP EXPN command is |
9b371988 | 12638 | received. See chapter &<<CHAPACL>>& for further details. |
168e428f | 12639 | |
9b371988 PH |
12640 | .option acl_smtp_helo main string&!! unset |
12641 | .cindex "EHLO" "ACL for" | |
12642 | .cindex "HELO" "ACL for" | |
168e428f | 12643 | This option defines the ACL that is run when an SMTP EHLO or HELO |
9b371988 | 12644 | command is received. See chapter &<<CHAPACL>>& for further details. |
168e428f | 12645 | |
168e428f | 12646 | |
9b371988 PH |
12647 | .option acl_smtp_mail main string&!! unset |
12648 | .cindex "MAIL" "ACL for" | |
168e428f | 12649 | This option defines the ACL that is run when an SMTP MAIL command is |
9b371988 | 12650 | received. See chapter &<<CHAPACL>>& for further details. |
168e428f | 12651 | |
9b371988 PH |
12652 | .option acl_smtp_mailauth main string&!! unset |
12653 | .cindex "AUTH" "on MAIL command" | |
168e428f | 12654 | This option defines the ACL that is run when there is an AUTH parameter on |
9b371988 PH |
12655 | a MAIL command. See chapter &<<CHAPACL>>& for details of ACLs, and chapter |
12656 | &<<CHAPSMTPAUTH>>& for details of authentication. | |
168e428f | 12657 | |
9b371988 PH |
12658 | .option acl_smtp_mime main string&!! unset |
12659 | .cindex "MIME content scanning" "ACL for" | |
168e428f PH |
12660 | This option is available when Exim is built with the content-scanning |
12661 | extension. It defines the ACL that is run for each MIME part in a message. See | |
9b371988 | 12662 | section &<<SECTscanmimepart>>& for details. |
168e428f | 12663 | |
9b371988 | 12664 | .option acl_smtp_predata main string&!! unset |
168e428f | 12665 | This option defines the ACL that is run when an SMTP DATA command is |
9b371988 | 12666 | received, before the message itself is received. See chapter &<<CHAPACL>>& for |
168e428f PH |
12667 | further details. |
12668 | ||
9b371988 | 12669 | .option acl_smtp_quit main string&!! unset |
f89d2485 | 12670 | .cindex "QUIT, ACL for" |
168e428f | 12671 | This option defines the ACL that is run when an SMTP QUIT command is |
9b371988 | 12672 | received. See chapter &<<CHAPACL>>& for further details. |
168e428f | 12673 | |
9b371988 PH |
12674 | .option acl_smtp_rcpt main string&!! unset |
12675 | .cindex "RCPT" "ACL for" | |
168e428f | 12676 | This option defines the ACL that is run when an SMTP RCPT command is |
9b371988 | 12677 | received. See chapter &<<CHAPACL>>& for further details. |
168e428f | 12678 | |
9b371988 | 12679 | .option acl_smtp_starttls main string&!! unset |
f89d2485 | 12680 | .cindex "STARTTLS, ACL for" |
168e428f | 12681 | This option defines the ACL that is run when an SMTP STARTTLS command is |
9b371988 | 12682 | received. See chapter &<<CHAPACL>>& for further details. |
168e428f | 12683 | |
9b371988 PH |
12684 | .option acl_smtp_vrfy main string&!! unset |
12685 | .cindex "VRFY" "ACL for" | |
168e428f | 12686 | This option defines the ACL that is run when an SMTP VRFY command is |
9b371988 | 12687 | received. See chapter &<<CHAPACL>>& for further details. |
168e428f | 12688 | |
9b371988 PH |
12689 | .option admin_groups main "string list&!!" unset |
12690 | .cindex "admin user" | |
068aaea8 PH |
12691 | This option is expanded just once, at the start of Exim's processing. If the |
12692 | current group or any of the supplementary groups of an Exim caller is in this | |
12693 | colon-separated list, the caller has admin privileges. If all your system | |
168e428f | 12694 | programmers are in a specific group, for example, you can give them all Exim |
9b371988 | 12695 | admin privileges by putting that group in &%admin_groups%&. However, this does |
168e428f PH |
12696 | not permit them to read Exim's spool files (whose group owner is the Exim gid). |
12697 | To permit this, you have to add individuals to the Exim group. | |
12698 | ||
9b371988 PH |
12699 | .option allow_domain_literals main boolean false |
12700 | .cindex "domain literal" | |
168e428f PH |
12701 | If this option is set, the RFC 2822 domain literal format is permitted in |
12702 | email addresses. The option is not set by default, because the domain literal | |
12703 | format is not normally required these days, and few people know about it. It | |
12704 | has, however, been exploited by mail abusers. | |
12705 | ||
12706 | Unfortunately, it seems that some DNS black list maintainers are using this | |
12707 | format to report black listing to postmasters. If you want to accept messages | |
12708 | addressed to your hosts by IP address, you need to set | |
9b371988 PH |
12709 | &%allow_domain_literals%& true, and also to add &`@[]`& to the list of local |
12710 | domains (defined in the named domain list &%local_domains%& in the default | |
12711 | configuration). This &"magic string"& matches the domain literal form of all | |
12712 | the local host's IP addresses. | |
168e428f | 12713 | |
168e428f | 12714 | |
9b371988 PH |
12715 | .option allow_mx_to_ip main boolean false |
12716 | .cindex "MX record" "pointing to IP address" | |
168e428f PH |
12717 | It appears that more and more DNS zone administrators are breaking the rules |
12718 | and putting domain names that look like IP addresses on the right hand side of | |
12719 | MX records. Exim follows the rules and rejects this, giving an error message | |
12720 | that explains the mis-configuration. However, some other MTAs support this | |
9b371988 PH |
12721 | practice, so to avoid &"Why can't Exim do this?"& complaints, |
12722 | &%allow_mx_to_ip%& exists, in order to enable this heinous activity. It is not | |
12723 | recommended, except when you have no other choice. | |
168e428f | 12724 | |
9b371988 PH |
12725 | .option allow_utf8_domains main boolean false |
12726 | .cindex "domain" "UTF-8 characters in" | |
12727 | .cindex "UTF-8" "in domain name" | |
168e428f PH |
12728 | Lots of discussion is going on about internationalized domain names. One |
12729 | camp is strongly in favour of just using UTF-8 characters, and it seems | |
12730 | that at least two other MTAs permit this. This option allows Exim users to | |
12731 | experiment if they wish. | |
12732 | ||
12733 | If it is set true, Exim's domain parsing function allows valid | |
12734 | UTF-8 multicharacters to appear in domain name components, in addition to | |
12735 | letters, digits, and hyphens. However, just setting this option is not | |
12736 | enough; if you want to look up these domain names in the DNS, you must also | |
9b371988 | 12737 | adjust the value of &%dns_check_names_pattern%& to match the extended form. A |
168e428f | 12738 | suitable setting is: |
9b371988 | 12739 | .code |
168e428f PH |
12740 | dns_check_names_pattern = (?i)^(?>(?(1)\.|())[a-z0-9\xc0-\xff]\ |
12741 | (?>[-a-z0-9\x80-\xff]*[a-z0-9\x80-\xbf])?)+$ | |
9b371988 | 12742 | .endd |
168e428f | 12743 | Alternatively, you can just disable this feature by setting |
9b371988 PH |
12744 | .code |
12745 | dns_check_names_pattern = | |
12746 | .endd | |
168e428f PH |
12747 | That is, set the option to an empty string so that no check is done. |
12748 | ||
12749 | ||
9b371988 PH |
12750 | .option auth_advertise_hosts main "host list&!!" * |
12751 | .cindex "authentication" "advertising" | |
12752 | .cindex "AUTH" "advertising" | |
168e428f PH |
12753 | If any server authentication mechanisms are configured, Exim advertises them in |
12754 | response to an EHLO command only if the calling host matches this list. | |
12755 | Otherwise, Exim does not advertise AUTH. | |
12756 | Exim does not accept AUTH commands from clients to which it has not | |
12757 | advertised the availability of AUTH. The advertising of individual | |
12758 | authentication mechanisms can be controlled by the use of the | |
9b371988 PH |
12759 | &%server_advertise_condition%& generic authenticator option on the individual |
12760 | authenticators. See chapter &<<CHAPSMTPAUTH>>& for further details. | |
168e428f PH |
12761 | |
12762 | Certain mail clients (for example, Netscape) require the user to provide a name | |
12763 | and password for authentication if AUTH is advertised, even though it may | |
12764 | not be needed (the host may accept messages from hosts on its local LAN without | |
9b371988 | 12765 | authentication, for example). The &%auth_advertise_hosts%& option can be used |
168e428f PH |
12766 | to make these clients more friendly by excluding them from the set of hosts to |
12767 | which Exim advertises AUTH. | |
12768 | ||
9b371988 | 12769 | .cindex "AUTH" "advertising when encrypted" |
168e428f PH |
12770 | If you want to advertise the availability of AUTH only when the connection |
12771 | is encrypted using TLS, you can make use of the fact that the value of this | |
12772 | option is expanded, with a setting like this: | |
9b371988 PH |
12773 | .code |
12774 | auth_advertise_hosts = ${if eq{$tls_cipher}{}{}{*}} | |
12775 | .endd | |
f89d2485 | 12776 | .vindex "&$tls_cipher$&" |
9b371988 | 12777 | If &$tls_cipher$& is empty, the session is not encrypted, and the result of |
168e428f | 12778 | the expansion is empty, thus matching no hosts. Otherwise, the result of the |
9b371988 | 12779 | expansion is *, which matches all hosts. |
168e428f | 12780 | |
168e428f | 12781 | |
9b371988 | 12782 | .option auto_thaw main time 0s |
9b371988 PH |
12783 | .cindex "thawing messages" |
12784 | .cindex "unfreezing messages" | |
168e428f | 12785 | If this option is set to a time greater than zero, a queue runner will try a |
068aaea8 PH |
12786 | new delivery attempt on any frozen message, other than a bounce message, if |
12787 | this much time has passed since it was frozen. This may result in the message | |
12788 | being re-frozen if nothing has changed since the last attempt. It is a way of | |
9b371988 | 12789 | saying &"keep on trying, even though there are big problems"&. |
068aaea8 | 12790 | |
9b371988 PH |
12791 | &*Note*&: This is an old option, which predates &%timeout_frozen_after%& and |
12792 | &%ignore_bounce_errors_after%&. It is retained for compatibility, but it is not | |
068aaea8 | 12793 | thought to be very useful any more, and its use should probably be avoided. |
168e428f | 12794 | |
9b371988 | 12795 | .option av_scanner main string "see below" |
168e428f PH |
12796 | This option is available if Exim is built with the content-scanning extension. |
12797 | It specifies which anti-virus scanner to use. The default value is: | |
9b371988 PH |
12798 | .code |
12799 | sophie:/var/run/sophie | |
12800 | .endd | |
12801 | If the value of &%av_scanner%& starts with dollar character, it is expanded | |
12802 | before use. See section &<<SECTscanvirus>>& for further details. | |
168e428f PH |
12803 | |
12804 | ||
168e428f | 12805 | |
9b371988 | 12806 | .option bi_command main string unset |
f89d2485 | 12807 | .oindex "&%-bi%&" |
168e428f | 12808 | This option supplies the name of a command that is run when Exim is called with |
9b371988 PH |
12809 | the &%-bi%& option (see chapter &<<CHAPcommandline>>&). The string value is |
12810 | just the command name, it is not a complete command line. If an argument is | |
12811 | required, it must come from the &%-oA%& command line option. | |
168e428f PH |
12812 | |
12813 | ||
9b371988 PH |
12814 | .option bounce_message_file main string unset |
12815 | .cindex "bounce message" "customizing" | |
12816 | .cindex "customizing" "bounce message" | |
168e428f PH |
12817 | This option defines a template file containing paragraphs of text to be used |
12818 | for constructing bounce messages. Details of the file's contents are given in | |
9b371988 | 12819 | chapter &<<CHAPemsgcust>>&. See also &%warn_message_file%&. |
168e428f | 12820 | |
168e428f | 12821 | |
9b371988 | 12822 | .option bounce_message_text main string unset |
168e428f | 12823 | When this option is set, its contents are included in the default bounce |
9b371988 PH |
12824 | message immediately after &"This message was created automatically by mail |
12825 | delivery software."& It is not used if &%bounce_message_file%& is set. | |
168e428f | 12826 | |
9b371988 PH |
12827 | .option bounce_return_body main boolean true |
12828 | .cindex "bounce message" "including body" | |
168e428f | 12829 | This option controls whether the body of an incoming message is included in a |
4f578862 PH |
12830 | bounce message when &%bounce_return_message%& is true. The default setting |
12831 | causes the entire message, both header and body, to be returned (subject to the | |
12832 | value of &%bounce_return_size_limit%&). If this option is false, only the | |
12833 | message header is included. In the case of a non-SMTP message containing an | |
12834 | error that is detected during reception, only those header lines preceding the | |
12835 | point at which the error was detected are returned. | |
9b371988 | 12836 | .cindex "bounce message" "including original" |
168e428f | 12837 | |
9b371988 | 12838 | .option bounce_return_message main boolean true |
4f578862 PH |
12839 | If this option is set false, none of the original message is included in |
12840 | bounce messages generated by Exim. See also &%bounce_return_size_limit%& and | |
12841 | &%bounce_return_body%&. | |
168e428f | 12842 | |
168e428f | 12843 | |
9b371988 | 12844 | .option bounce_return_size_limit main integer 100K |
f89d2485 | 12845 | .cindex "size" "of bounce, limit" |
9b371988 PH |
12846 | .cindex "bounce message" "size limit" |
12847 | .cindex "limit" "bounce message size" | |
168e428f | 12848 | This option sets a limit in bytes on the size of messages that are returned to |
9b371988 PH |
12849 | senders as part of bounce messages when &%bounce_return_message%& is true. The |
12850 | limit should be less than the value of the global &%message_size_limit%& and of | |
12851 | any &%message_size_limit%& settings on transports, to allow for the bounce text | |
168e428f PH |
12852 | that Exim generates. If this option is set to zero there is no limit. |
12853 | ||
12854 | When the body of any message that is to be included in a bounce message is | |
12855 | greater than the limit, it is truncated, and a comment pointing this out is | |
12856 | added at the top. The actual cutoff may be greater than the value given, owing | |
12857 | to the use of buffering for transferring the message in chunks (typically 8K in | |
12858 | size). The idea is to save bandwidth on those undeliverable 15-megabyte | |
12859 | messages. | |
12860 | ||
9b371988 PH |
12861 | .option bounce_sender_authentication main string unset |
12862 | .cindex "bounce message" "sender authentication" | |
12863 | .cindex "authentication" "bounce message" | |
12864 | .cindex "AUTH" "on bounce message" | |
168e428f PH |
12865 | This option provides an authenticated sender address that is sent with any |
12866 | bounce messages generated by Exim that are sent over an authenticated SMTP | |
12867 | connection. A typical setting might be: | |
9b371988 PH |
12868 | .code |
12869 | bounce_sender_authentication = mailer-daemon@my.domain.example | |
12870 | .endd | |
168e428f | 12871 | which would cause bounce messages to be sent using the SMTP command: |
9b371988 PH |
12872 | .code |
12873 | MAIL FROM:<> AUTH=mailer-daemon@my.domain.example | |
12874 | .endd | |
12875 | The value of &%bounce_sender_authentication%& must always be a complete email | |
168e428f PH |
12876 | address. |
12877 | ||
9b371988 PH |
12878 | .option callout_domain_negative_expire main time 3h |
12879 | .cindex "caching" "callout timeouts" | |
12880 | .cindex "callout" "caching timeouts" | |
168e428f | 12881 | This option specifies the expiry time for negative callout cache data for a |
9b371988 PH |
12882 | domain. See section &<<SECTcallver>>& for details of callout verification, and |
12883 | section &<<SECTcallvercache>>& for details of the caching. | |
168e428f | 12884 | |
168e428f | 12885 | |
9b371988 | 12886 | .option callout_domain_positive_expire main time 7d |
168e428f | 12887 | This option specifies the expiry time for positive callout cache data for a |
9b371988 PH |
12888 | domain. See section &<<SECTcallver>>& for details of callout verification, and |
12889 | section &<<SECTcallvercache>>& for details of the caching. | |
168e428f PH |
12890 | |
12891 | ||
9b371988 | 12892 | .option callout_negative_expire main time 2h |
168e428f | 12893 | This option specifies the expiry time for negative callout cache data for an |
9b371988 PH |
12894 | address. See section &<<SECTcallver>>& for details of callout verification, and |
12895 | section &<<SECTcallvercache>>& for details of the caching. | |
168e428f | 12896 | |
168e428f | 12897 | |
9b371988 | 12898 | .option callout_positive_expire main time 24h |
168e428f | 12899 | This option specifies the expiry time for positive callout cache data for an |
9b371988 PH |
12900 | address. See section &<<SECTcallver>>& for details of callout verification, and |
12901 | section &<<SECTcallvercache>>& for details of the caching. | |
168e428f | 12902 | |
168e428f | 12903 | |
9b371988 PH |
12904 | .option callout_random_local_part main string&!! "see below" |
12905 | This option defines the &"random"& local part that can be used as part of | |
12906 | callout verification. The default value is | |
12907 | .code | |
12908 | $primary_host_name-$tod_epoch-testing | |
12909 | .endd | |
12910 | See section &<<CALLaddparcall>>& for details of how this value is used. | |
168e428f | 12911 | |
168e428f | 12912 | |
9b371988 PH |
12913 | .option check_log_inodes main integer 0 |
12914 | See &%check_spool_space%& below. | |
168e428f PH |
12915 | |
12916 | ||
9b371988 PH |
12917 | .option check_log_space main integer 0 |
12918 | See &%check_spool_space%& below. | |
d1e83bff | 12919 | |
9b371988 PH |
12920 | .oindex "&%check_rfc2047_length%&" |
12921 | .cindex "RFC 2047" "disabling length check" | |
f89d2485 | 12922 | .option check_rfc2047_length main boolean true |
d1e83bff | 12923 | RFC 2047 defines a way of encoding non-ASCII characters in headers using a |
9b371988 | 12924 | system of &"encoded words"&. The RFC specifies a maximum length for an encoded |
d1e83bff PH |
12925 | word; strings to be encoded that exceed this length are supposed to use |
12926 | multiple encoded words. By default, Exim does not recognize encoded words that | |
12927 | exceed the maximum length. However, it seems that some software, in violation | |
9b371988 PH |
12928 | of the RFC, generates overlong encoded words. If &%check_rfc2047_length%& is |
12929 | set false, Exim recognizes encoded words of any length. | |
168e428f | 12930 | |
168e428f | 12931 | |
9b371988 PH |
12932 | .option check_spool_inodes main integer 0 |
12933 | See &%check_spool_space%& below. | |
168e428f PH |
12934 | |
12935 | ||
9b371988 PH |
12936 | .option check_spool_space main integer 0 |
12937 | .cindex "checking disk space" | |
f89d2485 | 12938 | .cindex "disk space, checking" |
9b371988 PH |
12939 | .cindex "spool directory" "checking space" |
12940 | The four &%check_...%& options allow for checking of disk resources before a | |
168e428f PH |
12941 | message is accepted. |
12942 | ||
f89d2485 PH |
12943 | .vindex "&$log_inodes$&" |
12944 | .vindex "&$log_space$&" | |
12945 | .vindex "&$spool_inodes$&" | |
12946 | .vindex "&$spool_space$&" | |
168e428f | 12947 | When any of these options are set, they apply to all incoming messages. If you |
068aaea8 | 12948 | want to apply different checks to different kinds of message, you can do so by |
3cb1b51e | 12949 | testing the variables &$log_inodes$&, &$log_space$&, &$spool_inodes$&, and |
9b371988 | 12950 | &$spool_space$& in an ACL with appropriate additional conditions. |
168e428f PH |
12951 | |
12952 | ||
9b371988 | 12953 | &%check_spool_space%& and &%check_spool_inodes%& check the spool partition if |
168e428f | 12954 | either value is greater than zero, for example: |
9b371988 PH |
12955 | .code |
12956 | check_spool_space = 10M | |
12957 | check_spool_inodes = 100 | |
12958 | .endd | |
168e428f | 12959 | The spool partition is the one that contains the directory defined by |
9b371988 | 12960 | SPOOL_DIRECTORY in &_Local/Makefile_&. It is used for holding messages in |
168e428f PH |
12961 | transit. |
12962 | ||
9b371988 | 12963 | &%check_log_space%& and &%check_log_inodes%& check the partition in which log |
168e428f | 12964 | files are written if either is greater than zero. These should be set only if |
9b371988 | 12965 | &%log_file_path%& and &%spool_directory%& refer to different partitions. |
168e428f PH |
12966 | |
12967 | If there is less space or fewer inodes than requested, Exim refuses to accept | |
12968 | incoming mail. In the case of SMTP input this is done by giving a 452 temporary | |
12969 | error response to the MAIL command. If ESMTP is in use and there was a | |
12970 | SIZE parameter on the MAIL command, its value is added to the | |
9b371988 PH |
12971 | &%check_spool_space%& value, and the check is performed even if |
12972 | &%check_spool_space%& is zero, unless &%no_smtp_check_spool_space%& is set. | |
168e428f | 12973 | |
9b371988 | 12974 | The values for &%check_spool_space%& and &%check_log_space%& are held as a |
168e428f PH |
12975 | number of kilobytes. If a non-multiple of 1024 is specified, it is rounded up. |
12976 | ||
12977 | For non-SMTP input and for batched SMTP input, the test is done at start-up; on | |
12978 | failure a message is written to stderr and Exim exits with a non-zero code, as | |
12979 | it obviously cannot send an error message of any kind. | |
12980 | ||
9b371988 PH |
12981 | .option daemon_smtp_ports main string &`smtp`& |
12982 | .cindex "port" "for daemon" | |
12983 | .cindex "TCP/IP" "setting listening ports" | |
168e428f | 12984 | This option specifies one or more default SMTP ports on which the Exim daemon |
9b371988 PH |
12985 | listens. See chapter &<<CHAPinterfaces>>& for details of how it is used. For |
12986 | backward compatibility, &%daemon_smtp_port%& (singular) is a synonym. | |
068aaea8 | 12987 | |
9b371988 | 12988 | .option daemon_startup_retries main integer 9 |
f89d2485 | 12989 | .cindex "daemon startup, retrying" |
9b371988 | 12990 | This option, along with &%daemon_startup_sleep%&, controls the retrying done by |
068aaea8 | 12991 | the daemon at startup when it cannot immediately bind a listening socket |
9b371988 | 12992 | (typically because the socket is already in use): &%daemon_startup_retries%& |
068aaea8 | 12993 | defines the number of retries after the first failure, and |
9b371988 | 12994 | &%daemon_startup_sleep%& defines the length of time to wait between retries. |
068aaea8 | 12995 | |
9b371988 PH |
12996 | .option daemon_startup_sleep main time 30s |
12997 | See &%daemon_startup_retries%&. | |
068aaea8 | 12998 | |
9b371988 PH |
12999 | .option delay_warning main "time list" 24h |
13000 | .cindex "warning of delay" | |
f89d2485 | 13001 | .cindex "delay warning, specifying" |
168e428f PH |
13002 | When a message is delayed, Exim sends a warning message to the sender at |
13003 | intervals specified by this option. The data is a colon-separated list of times | |
9b371988 PH |
13004 | after which to send warning messages. If the value of the option is an empty |
13005 | string or a zero time, no warnings are sent. Up to 10 times may be given. If a | |
13006 | message has been on the queue for longer than the last time, the last interval | |
13007 | between the times is used to compute subsequent warning times. For example, | |
13008 | with | |
13009 | .code | |
13010 | delay_warning = 4h:8h:24h | |
13011 | .endd | |
168e428f PH |
13012 | the first message is sent after 4 hours, the second after 8 hours, and |
13013 | the third one after 24 hours. After that, messages are sent every 16 hours, | |
13014 | because that is the interval between the last two times on the list. If you set | |
13015 | just one time, it specifies the repeat interval. For example, with: | |
9b371988 PH |
13016 | .code |
13017 | delay_warning = 6h | |
13018 | .endd | |
168e428f PH |
13019 | messages are repeated every six hours. To stop warnings after a given time, set |
13020 | a very large time at the end of the list. For example: | |
9b371988 PH |
13021 | .code |
13022 | delay_warning = 2h:12h:99d | |
13023 | .endd | |
168e428f | 13024 | |
9b371988 | 13025 | .option delay_warning_condition main string&!! "see below" |
f89d2485 | 13026 | .vindex "&$domain$&" |
168e428f | 13027 | The string is expanded at the time a warning message might be sent. If all the |
9b371988 PH |
13028 | deferred addresses have the same domain, it is set in &$domain$& during the |
13029 | expansion. Otherwise &$domain$& is empty. If the result of the expansion is a | |
13030 | forced failure, an empty string, or a string matching any of &"0"&, &"no"& or | |
13031 | &"false"& (the comparison being done caselessly) then the warning message is | |
db9452a9 | 13032 | not sent. The default is: |
9b371988 | 13033 | .code |
db9452a9 PH |
13034 | delay_warning_condition = ${if or {\ |
13035 | { !eq{$h_list-id:$h_list-post:$h_list-subscribe:}{} }\ | |
13036 | { match{$h_precedence:}{(?i)bulk|list|junk} }\ | |
13037 | { match{$h_auto-submitted:}{(?i)auto-generated|auto-replied} }\ | |
13038 | } {no}{yes}} | |
9b371988 | 13039 | .endd |
db9452a9 PH |
13040 | This suppresses the sending of warnings for messages that contain &'List-ID:'&, |
13041 | &'List-Post:'&, or &'List-Subscribe:'& headers, or have &"bulk"&, &"list"& or | |
13042 | &"junk"& in a &'Precedence:'& header, or have &"auto-generated"& or | |
13043 | &"auto-replied"& in an &'Auto-Submitted:'& header. | |
168e428f | 13044 | |
9b371988 PH |
13045 | .option deliver_drop_privilege main boolean false |
13046 | .cindex "unprivileged delivery" | |
13047 | .cindex "delivery" "unprivileged" | |
168e428f PH |
13048 | If this option is set true, Exim drops its root privilege at the start of a |
13049 | delivery process, and runs as the Exim user throughout. This severely restricts | |
13050 | the kinds of local delivery that are possible, but is viable in certain types | |
13051 | of configuration. There is a discussion about the use of root privilege in | |
9b371988 | 13052 | chapter &<<CHAPsecurity>>&. |
168e428f | 13053 | |
9b371988 PH |
13054 | .option deliver_queue_load_max main fixed-point unset |
13055 | .cindex "load average" | |
13056 | .cindex "queue runner" "abandoning" | |
168e428f PH |
13057 | When this option is set, a queue run is abandoned if the system load average |
13058 | becomes greater than the value of the option. The option has no effect on | |
13059 | ancient operating systems on which Exim cannot determine the load average. | |
9b371988 | 13060 | See also &%queue_only_load%& and &%smtp_load_reserve%&. |
168e428f | 13061 | |
168e428f | 13062 | |
9b371988 PH |
13063 | .option delivery_date_remove main boolean true |
13064 | .cindex "&'Delivery-date:'& header line" | |
13065 | Exim's transports have an option for adding a &'Delivery-date:'& header to a | |
13066 | message when it is delivered, in exactly the same way as &'Return-path:'& is | |
13067 | handled. &'Delivery-date:'& records the actual time of delivery. Such headers | |
168e428f PH |
13068 | should not be present in incoming messages, and this option causes them to be |
13069 | removed at the time the message is received, to avoid any problems that might | |
13070 | occur when a delivered message is subsequently sent on to some other recipient. | |
13071 | ||
a591010f | 13072 | .option disable_fsync main boolean false |
f89d2485 PH |
13073 | .cindex "&[fsync()]&, disabling" |
13074 | This option is available only if Exim was built with the compile-time option | |
13075 | ENABLE_DISABLE_FSYNC. When this is not set, a reference to &%disable_fsync%& in | |
13076 | a runtime configuration generates an &"unknown option"& error. You should not | |
13077 | build Exim with ENABLE_DISABLE_FSYNC or set &%disable_fsync%& unless you | |
13078 | really, really, really understand what you are doing. &'No pre-compiled | |
13079 | distributions of Exim should ever make this option available.'& | |
13080 | ||
13081 | When &%disable_fsync%& is set true, Exim no longer calls &[fsync()]& to force | |
13082 | updated files' data to be written to disc before continuing. Unexpected events | |
13083 | such as crashes and power outages may cause data to be lost or scrambled. | |
13084 | Here be Dragons. &*Beware.*& | |
f89d2485 | 13085 | |
4f578862 | 13086 | |
4f578862 PH |
13087 | .option disable_ipv6 main boolean false |
13088 | .cindex "IPv6" "disabling" | |
13089 | If this option is set true, even if the Exim binary has IPv6 support, no IPv6 | |
13090 | activities take place. AAAA records are never looked up, and any IPv6 addresses | |
13091 | that are listed in &%local_interfaces%&, data for the &%manualroute%& router, | |
13092 | etc. are ignored. If IP literals are enabled, the &(ipliteral)& router declines | |
13093 | to handle IPv6 literal addresses. | |
4f578862 PH |
13094 | |
13095 | ||
9b371988 PH |
13096 | .option dns_again_means_nonexist main "domain list&!!" unset |
13097 | .cindex "DNS" "&""try again""& response; overriding" | |
13098 | DNS lookups give a &"try again"& response for the DNS errors | |
13099 | &"non-authoritative host not found"& and &"SERVERFAIL"&. This can cause Exim to | |
13100 | keep trying to deliver a message, or to give repeated temporary errors to | |
13101 | incoming mail. Sometimes the effect is caused by a badly set up name server and | |
13102 | may persist for a long time. If a domain which exhibits this problem matches | |
13103 | anything in &%dns_again_means_nonexist%&, it is treated as if it did not exist. | |
13104 | This option should be used with care. You can make it apply to reverse lookups | |
13105 | by a setting such as this: | |
13106 | .code | |
13107 | dns_again_means_nonexist = *.in-addr.arpa | |
13108 | .endd | |
4f578862 PH |
13109 | This option applies to all DNS lookups that Exim does. It also applies when the |
13110 | &[gethostbyname()]& or &[getipnodebyname()]& functions give temporary errors, | |
13111 | since these are most likely to be caused by DNS lookup problems. The | |
13112 | &(dnslookup)& router has some options of its own for controlling what happens | |
13113 | when lookups for MX or SRV records give temporary errors. These more specific | |
13114 | options are applied after this global option. | |
168e428f | 13115 | |
9b371988 PH |
13116 | .option dns_check_names_pattern main string "see below" |
13117 | .cindex "DNS" "pre-check of name syntax" | |
168e428f | 13118 | When this option is set to a non-empty string, it causes Exim to check domain |
4f578862 PH |
13119 | names for characters that are not allowed in host names before handing them to |
13120 | the DNS resolver, because some resolvers give temporary errors for names that | |
13121 | contain unusual characters. If a domain name contains any unwanted characters, | |
13122 | a &"not found"& result is forced, and the resolver is not called. The check is | |
13123 | done by matching the domain name against a regular expression, which is the | |
13124 | value of this option. The default pattern is | |
9b371988 | 13125 | .code |
168e428f | 13126 | dns_check_names_pattern = \ |
4f578862 | 13127 | (?i)^(?>(?(1)\.|())[^\W_](?>[a-z0-9/-]*[^\W_])?)+$ |
9b371988 | 13128 | .endd |
4f578862 | 13129 | which permits only letters, digits, slashes, and hyphens in components, but |
7d0ab55c | 13130 | they must start and end with a letter or digit. Slashes are not, in fact, |
4f578862 PH |
13131 | permitted in host names, but they are found in certain NS records (which can be |
13132 | accessed in Exim by using a &%dnsdb%& lookup). If you set | |
13133 | &%allow_utf8_domains%&, you must modify this pattern, or set the option to an | |
13134 | empty string. | |
168e428f | 13135 | |
9b371988 | 13136 | .option dns_csa_search_limit main integer 5 |
068aaea8 | 13137 | This option controls the depth of parental searching for CSA SRV records in the |
9b371988 | 13138 | DNS, as described in more detail in section &<<SECTverifyCSA>>&. |
068aaea8 | 13139 | |
9b371988 | 13140 | .option dns_csa_use_reverse main boolean true |
068aaea8 PH |
13141 | This option controls whether or not an IP address, given as a CSA domain, is |
13142 | reversed and looked up in the reverse DNS, as described in more detail in | |
9b371988 | 13143 | section &<<SECTverifyCSA>>&. |
068aaea8 | 13144 | |
9b371988 PH |
13145 | .option dns_ipv4_lookup main "domain list&!!" unset |
13146 | .cindex "IPv6" "DNS lookup for AAAA records" | |
13147 | .cindex "DNS" "IPv6 lookup for AAAA records" | |
4f578862 PH |
13148 | When Exim is compiled with IPv6 support and &%disable_ipv6%& is not set, it |
13149 | looks for IPv6 address records (AAAA records) as well as IPv4 address records | |
13150 | (A records) when trying to find IP addresses for hosts, unless the host's | |
13151 | domain matches this list. | |
168e428f PH |
13152 | |
13153 | This is a fudge to help with name servers that give big delays or otherwise do | |
4f578862 PH |
13154 | not work for the AAAA record type. In due course, when the world's name |
13155 | servers have all been upgraded, there should be no need for this option. | |
168e428f PH |
13156 | |
13157 | ||
9b371988 PH |
13158 | .option dns_retrans main time 0s |
13159 | .cindex "DNS" "resolver options" | |
13160 | The options &%dns_retrans%& and &%dns_retry%& can be used to set the | |
168e428f PH |
13161 | retransmission and retry parameters for DNS lookups. Values of zero (the |
13162 | defaults) leave the system default settings unchanged. The first value is the | |
13163 | time between retries, and the second is the number of retries. It isn't | |
13164 | totally clear exactly how these settings affect the total time a DNS lookup may | |
13165 | take. I haven't found any documentation about timeouts on DNS lookups; these | |
13166 | parameter values are available in the external resolver interface structure, | |
13167 | but nowhere does it seem to describe how they are used or what you might want | |
13168 | to set in them. | |
13169 | ||
13170 | ||
9b371988 PH |
13171 | .option dns_retry main integer 0 |
13172 | See &%dns_retrans%& above. | |
168e428f | 13173 | |
168e428f | 13174 | |
9b371988 | 13175 | .option drop_cr main boolean false |
168e428f PH |
13176 | This is an obsolete option that is now a no-op. It used to affect the way Exim |
13177 | handled CR and LF characters in incoming messages. What happens now is | |
9b371988 | 13178 | described in section &<<SECTlineendings>>&. |
168e428f | 13179 | |
f89d2485 PH |
13180 | .option dsn_from main "string&!!" "see below" |
13181 | .cindex "&'From:'& header line" "in bounces" | |
13182 | .cindex "bounce messages" "&'From:'& line, specifying" | |
13183 | This option can be used to vary the contents of &'From:'& header lines in | |
13184 | bounces and other automatically generated messages (&"Delivery Status | |
13185 | Notifications"& &-- hence the name of the option). The default setting is: | |
13186 | .code | |
13187 | dsn_from = Mail Delivery System <Mailer-Daemon@$qualify_domain> | |
13188 | .endd | |
13189 | The value is expanded every time it is needed. If the expansion fails, a | |
13190 | panic is logged, and the default value is used. | |
168e428f | 13191 | |
9b371988 PH |
13192 | .option envelope_to_remove main boolean true |
13193 | .cindex "&'Envelope-to:'& header line" | |
13194 | Exim's transports have an option for adding an &'Envelope-to:'& header to a | |
13195 | message when it is delivered, in exactly the same way as &'Return-path:'& is | |
13196 | handled. &'Envelope-to:'& records the original recipient address from the | |
168e428f PH |
13197 | messages's envelope that caused the delivery to happen. Such headers should not |
13198 | be present in incoming messages, and this option causes them to be removed at | |
13199 | the time the message is received, to avoid any problems that might occur when a | |
13200 | delivered message is subsequently sent on to some other recipient. | |
13201 | ||
13202 | ||
9b371988 PH |
13203 | .option errors_copy main "string list&!!" unset |
13204 | .cindex "bounce message" "copy to other address" | |
13205 | .cindex "copy of bounce message" | |
168e428f | 13206 | Setting this option causes Exim to send bcc copies of bounce messages that it |
9b371988 | 13207 | generates to other addresses. &*Note*&: This does not apply to bounce messages |
168e428f PH |
13208 | coming from elsewhere. The value of the option is a colon-separated list of |
13209 | items. Each item consists of a pattern, terminated by white space, followed by | |
13210 | a comma-separated list of email addresses. If a pattern contains spaces, it | |
13211 | must be enclosed in double quotes. | |
13212 | ||
13213 | Each pattern is processed in the same way as a single item in an address list | |
9b371988 PH |
13214 | (see section &<<SECTaddresslist>>&). When a pattern matches the recipient of |
13215 | the bounce message, the message is copied to the addresses on the list. The | |
13216 | items are scanned in order, and once a matching one is found, no further items | |
13217 | are examined. For example: | |
13218 | .code | |
168e428f PH |
13219 | errors_copy = spqr@mydomain postmaster@mydomain.example :\ |
13220 | rqps@mydomain hostmaster@mydomain.example,\ | |
13221 | postmaster@mydomain.example | |
9b371988 | 13222 | .endd |
f89d2485 PH |
13223 | .vindex "&$domain$&" |
13224 | .vindex "&$local_part$&" | |
9b371988 PH |
13225 | The address list is expanded before use. The expansion variables &$local_part$& |
13226 | and &$domain$& are set from the original recipient of the error message, and if | |
13227 | there was any wildcard matching in the pattern, the expansion | |
13228 | .cindex "numerical variables (&$1$& &$2$& etc)" "in &%errors_copy%&" | |
13229 | variables &$0$&, &$1$&, etc. are set in the normal way. | |
13230 | ||
13231 | ||
13232 | .option errors_reply_to main string unset | |
13233 | .cindex "bounce message" "&'Reply-to:'& in" | |
4f578862 | 13234 | By default, Exim's bounce and delivery warning messages contain the header line |
9b371988 PH |
13235 | .display |
13236 | &`From: Mail Delivery System <Mailer-Daemon@`&&'qualify-domain'&&`>`& | |
13237 | .endd | |
4f578862 | 13238 | .oindex &%quota_warn_message%& |
9b371988 | 13239 | where &'qualify-domain'& is the value of the &%qualify_domain%& option. |
4f578862 PH |
13240 | A warning message that is generated by the &%quota_warn_message%& option in an |
13241 | &(appendfile)& transport may contain its own &'From:'& header line that | |
13242 | overrides the default. | |
13243 | ||
168e428f | 13244 | Experience shows that people reply to bounce messages. If the |
9b371988 PH |
13245 | &%errors_reply_to%& option is set, a &'Reply-To:'& header is added to bounce |
13246 | and warning messages. For example: | |
13247 | .code | |
13248 | errors_reply_to = postmaster@my.domain.example | |
13249 | .endd | |
168e428f | 13250 | The value of the option is not expanded. It must specify a valid RFC 2822 |
4f578862 PH |
13251 | address. However, if a warning message that is generated by the |
13252 | &%quota_warn_message%& option in an &(appendfile)& transport contain its | |
13253 | own &'Reply-To:'& header line, the value of the &%errors_reply_to%& option is | |
13254 | not used. | |
168e428f PH |
13255 | |
13256 | ||
9b371988 PH |
13257 | .option exim_group main string "compile-time configured" |
13258 | .cindex "gid (group id)" "Exim's own" | |
13259 | .cindex "Exim group" | |
168e428f PH |
13260 | This option changes the gid under which Exim runs when it gives up root |
13261 | privilege. The default value is compiled into the binary. The value of this | |
9b371988 PH |
13262 | option is used only when &%exim_user%& is also set. Unless it consists entirely |
13263 | of digits, the string is looked up using &[getgrnam()]&, and failure causes a | |
13264 | configuration error. See chapter &<<CHAPsecurity>>& for a discussion of | |
13265 | security issues. | |
168e428f | 13266 | |
168e428f | 13267 | |
9b371988 | 13268 | .option exim_path main string "see below" |
f89d2485 | 13269 | .cindex "Exim binary, path name" |
168e428f | 13270 | This option specifies the path name of the Exim binary, which is used when Exim |
9b371988 | 13271 | needs to re-exec itself. The default is set up to point to the file &'exim'& in |
168e428f | 13272 | the directory configured at compile time by the BIN_DIRECTORY setting. It |
9b371988 | 13273 | is necessary to change &%exim_path%& if, exceptionally, Exim is run from some |
168e428f | 13274 | other place. |
9b371988 | 13275 | &*Warning*&: Do not use a macro to define the value of this option, because |
168e428f | 13276 | you will break those Exim utilities that scan the configuration file to find |
9b371988 PH |
13277 | where the binary is. (They then use the &%-bP%& option to extract option |
13278 | settings such as the value of &%spool_directory%&.) | |
168e428f PH |
13279 | |
13280 | ||
9b371988 PH |
13281 | .option exim_user main string "compile-time configured" |
13282 | .cindex "uid (user id)" "Exim's own" | |
13283 | .cindex "Exim user" | |
168e428f PH |
13284 | This option changes the uid under which Exim runs when it gives up root |
13285 | privilege. The default value is compiled into the binary. Ownership of the run | |
9b371988 PH |
13286 | time configuration file and the use of the &%-C%& and &%-D%& command line |
13287 | options is checked against the values in the binary, not what is set here. | |
168e428f PH |
13288 | |
13289 | Unless it consists entirely of digits, the string is looked up using | |
9b371988 PH |
13290 | &[getpwnam()]&, and failure causes a configuration error. If &%exim_group%& is |
13291 | not also supplied, the gid is taken from the result of &[getpwnam()]& if it is | |
13292 | used. See chapter &<<CHAPsecurity>>& for a discussion of security issues. | |
168e428f | 13293 | |
168e428f | 13294 | |
9b371988 | 13295 | .option extra_local_interfaces main "string list" unset |
168e428f PH |
13296 | This option defines network interfaces that are to be considered local when |
13297 | routing, but which are not used for listening by the daemon. See section | |
9b371988 | 13298 | &<<SECTreclocipadd>>& for details. |
168e428f | 13299 | |
168e428f | 13300 | |
0a4e3112 PH |
13301 | . Allow this long option name to split; give it unsplit as a fifth argument |
13302 | . for the automatic .oindex that is generated by .option. | |
f89d2485 | 13303 | |
0a4e3112 PH |
13304 | .option "extract_addresses_remove_ &~&~arguments" main boolean true &&& |
13305 | extract_addresses_remove_arguments | |
f89d2485 | 13306 | .oindex "&%-t%&" |
9b371988 PH |
13307 | .cindex "command line" "addresses with &%-t%&" |
13308 | .cindex "Sendmail compatibility" "&%-t%& option" | |
168e428f | 13309 | According to some Sendmail documentation (Sun, IRIX, HP-UX), if any addresses |
9b371988 PH |
13310 | are present on the command line when the &%-t%& option is used to build an |
13311 | envelope from a message's &'To:'&, &'Cc:'& and &'Bcc:'& headers, the command | |
13312 | line addresses are removed from the recipients list. This is also how Smail | |
13313 | behaves. However, other Sendmail documentation (the O'Reilly book) states that | |
13314 | command line addresses are added to those obtained from the header lines. When | |
13315 | &%extract_addresses_remove_arguments%& is true (the default), Exim subtracts | |
168e428f PH |
13316 | argument headers. If it is set false, Exim adds rather than removes argument |
13317 | addresses. | |
13318 | ||
13319 | ||
9b371988 | 13320 | .option finduser_retries main integer 0 |
f89d2485 | 13321 | .cindex "NIS, retrying user lookups" |
168e428f | 13322 | On systems running NIS or other schemes in which user and group information is |
9b371988 | 13323 | distributed from a remote system, there can be times when &[getpwnam()]& and |
168e428f | 13324 | related functions fail, even when given valid data, because things time out. |
9b371988 PH |
13325 | Unfortunately these failures cannot be distinguished from genuine &"not found"& |
13326 | errors. If &%finduser_retries%& is set greater than zero, Exim will try that | |
168e428f PH |
13327 | many extra times to find a user or a group, waiting for one second between |
13328 | retries. | |
13329 | ||
9b371988 | 13330 | .cindex "&_/etc/passwd_&" "multiple reading of" |
168e428f | 13331 | You should not set this option greater than zero if your user information is in |
9b371988 | 13332 | a traditional &_/etc/passwd_& file, because it will cause Exim needlessly to |
168e428f PH |
13333 | search the file multiple times for non-existent users, and also cause delay. |
13334 | ||
13335 | ||
13336 | ||
9b371988 PH |
13337 | .option freeze_tell main "string list, comma separated" unset |
13338 | .cindex "freezing messages" "sending a message when freezing" | |
168e428f | 13339 | On encountering certain errors, or when configured to do so in a system filter, |
9b371988 PH |
13340 | ACL, or special router, Exim freezes a message. This means that no further |
13341 | delivery attempts take place until an administrator thaws the message, or the | |
13342 | &%auto_thaw%&, &%ignore_bounce_errors_after%&, or &%timeout_frozen_after%& | |
13343 | feature cause it to be processed. If &%freeze_tell%& is set, Exim generates a | |
13344 | warning message whenever it freezes something, unless the message it is | |
13345 | freezing is a locally-generated bounce message. (Without this exception there | |
13346 | is the possibility of looping.) The warning message is sent to the addresses | |
13347 | supplied as the comma-separated value of this option. If several of the | |
13348 | message's addresses cause freezing, only a single message is sent. If the | |
13349 | freezing was automatic, the reason(s) for freezing can be found in the message | |
13350 | log. If you configure freezing in a filter or ACL, you must arrange for any | |
13351 | logging that you require. | |
13352 | ||
13353 | ||
13354 | .option gecos_name main string&!! unset | |
13355 | .cindex "HP-UX" | |
f89d2485 | 13356 | .cindex "&""gecos""& field, parsing" |
9b371988 | 13357 | Some operating systems, notably HP-UX, use the &"gecos"& field in the system |
168e428f | 13358 | password file to hold other information in addition to users' real names. Exim |
9b371988 PH |
13359 | looks up this field for use when it is creating &'Sender:'& or &'From:'& |
13360 | headers. If either &%gecos_pattern%& or &%gecos_name%& are unset, the contents | |
13361 | of the field are used unchanged, except that, if an ampersand is encountered, | |
13362 | it is replaced by the user's login name with the first character forced to | |
168e428f PH |
13363 | upper case, since this is a convention that is observed on many systems. |
13364 | ||
9b371988 PH |
13365 | When these options are set, &%gecos_pattern%& is treated as a regular |
13366 | expression that is to be applied to the field (again with && replaced by the | |
13367 | login name), and if it matches, &%gecos_name%& is expanded and used as the | |
13368 | user's name. | |
168e428f | 13369 | |
9b371988 PH |
13370 | .cindex "numerical variables (&$1$& &$2$& etc)" "in &%gecos_name%&" |
13371 | Numeric variables such as &$1$&, &$2$&, etc. can be used in the expansion to | |
168e428f PH |
13372 | pick up sub-fields that were matched by the pattern. In HP-UX, where the user's |
13373 | name terminates at the first comma, the following can be used: | |
9b371988 PH |
13374 | .code |
13375 | gecos_pattern = ([^,]*) | |
13376 | gecos_name = $1 | |
13377 | .endd | |
168e428f | 13378 | |
9b371988 PH |
13379 | .option gecos_pattern main string unset |
13380 | See &%gecos_name%& above. | |
168e428f PH |
13381 | |
13382 | ||
f89d2485 PH |
13383 | .option gnutls_require_kx main string unset |
13384 | This option controls the key exchange mechanisms when GnuTLS is used in an Exim | |
13385 | server. For details, see section &<<SECTreqciphgnu>>&. | |
13386 | ||
13387 | .option gnutls_require_mac main string unset | |
13388 | This option controls the MAC algorithms when GnuTLS is used in an Exim | |
13389 | server. For details, see section &<<SECTreqciphgnu>>&. | |
13390 | ||
13391 | .option gnutls_require_protocols main string unset | |
13392 | This option controls the protocols when GnuTLS is used in an Exim | |
13393 | server. For details, see section &<<SECTreqciphgnu>>&. | |
f89d2485 | 13394 | |
e6060e2c NM |
13395 | .option gnutls_compat_mode main boolean unset |
13396 | This option controls whether GnuTLS is used in compatibility mode in an Exim | |
13397 | server. This reduces security slightly, but improves interworking with older | |
13398 | implementations of TLS. | |
f89d2485 | 13399 | |
9b371988 | 13400 | .option headers_charset main string "see below" |
168e428f | 13401 | This option sets a default character set for translating from encoded MIME |
9b371988 PH |
13402 | &"words"& in header lines, when referenced by an &$h_xxx$& expansion item. The |
13403 | default is the value of HEADERS_CHARSET in &_Local/Makefile_&. The | |
168e428f | 13404 | ultimate default is ISO-8859-1. For more details see the description of header |
9b371988 | 13405 | insertions in section &<<SECTexpansionitems>>&. |
168e428f PH |
13406 | |
13407 | ||
168e428f | 13408 | |
9b371988 PH |
13409 | .option header_maxsize main integer "see below" |
13410 | .cindex "header section" "maximum size of" | |
13411 | .cindex "limit" "size of message header section" | |
168e428f PH |
13412 | This option controls the overall maximum size of a message's header |
13413 | section. The default is the value of HEADER_MAXSIZE in | |
9b371988 | 13414 | &_Local/Makefile_&; the default for that is 1M. Messages with larger header |
168e428f PH |
13415 | sections are rejected. |
13416 | ||
13417 | ||
9b371988 PH |
13418 | .option header_line_maxsize main integer 0 |
13419 | .cindex "header lines" "maximum size of" | |
13420 | .cindex "limit" "size of one header line" | |
168e428f PH |
13421 | This option limits the length of any individual header line in a message, after |
13422 | all the continuations have been joined together. Messages with individual | |
13423 | header lines that are longer than the limit are rejected. The default value of | |
9b371988 | 13424 | zero means &"no limit"&. |
168e428f PH |
13425 | |
13426 | ||
13427 | ||
13428 | ||
9b371988 PH |
13429 | .option helo_accept_junk_hosts main "host list&!!" unset |
13430 | .cindex "HELO" "accepting junk data" | |
13431 | .cindex "EHLO" "accepting junk data" | |
168e428f PH |
13432 | Exim checks the syntax of HELO and EHLO commands for incoming SMTP |
13433 | mail, and gives an error response for invalid data. Unfortunately, there are | |
13434 | some SMTP clients that send syntactic junk. They can be accommodated by setting | |
9b371988 | 13435 | this option. Note that this is a syntax check only. See &%helo_verify_hosts%& |
168e428f | 13436 | if you want to do semantic checking. |
9b371988 | 13437 | See also &%helo_allow_chars%& for a way of extending the permitted character |
168e428f PH |
13438 | set. |
13439 | ||
13440 | ||
9b371988 PH |
13441 | .option helo_allow_chars main string unset |
13442 | .cindex "HELO" "underscores in" | |
13443 | .cindex "EHLO" "underscores in" | |
13444 | .cindex "underscore in EHLO/HELO" | |
168e428f PH |
13445 | This option can be set to a string of rogue characters that are permitted in |
13446 | all EHLO and HELO names in addition to the standard letters, digits, | |
13447 | hyphens, and dots. If you really must allow underscores, you can set | |
9b371988 PH |
13448 | .code |
13449 | helo_allow_chars = _ | |
13450 | .endd | |
168e428f PH |
13451 | Note that the value is one string, not a list. |
13452 | ||
13453 | ||
9b371988 PH |
13454 | .option helo_lookup_domains main "domain list&!!" &`@:@[]`& |
13455 | .cindex "HELO" "forcing reverse lookup" | |
13456 | .cindex "EHLO" "forcing reverse lookup" | |
168e428f PH |
13457 | If the domain given by a client in a HELO or EHLO command matches this |
13458 | list, a reverse lookup is done in order to establish the host's true name. The | |
13459 | default forces a lookup if the client host gives the server's name or any of | |
13460 | its IP addresses (in brackets), something that broken clients have been seen to | |
13461 | do. | |
13462 | ||
13463 | ||
9b371988 | 13464 | .option helo_try_verify_hosts main "host list&!!" unset |
9b371988 | 13465 | .cindex "HELO verifying" "optional" |
f89d2485 | 13466 | .cindex "EHLO" "verifying, optional" |
068aaea8 | 13467 | By default, Exim just checks the syntax of HELO and EHLO commands (see |
9b371988 PH |
13468 | &%helo_accept_junk_hosts%& and &%helo_allow_chars%&). However, some sites like |
13469 | to do more extensive checking of the data supplied by these commands. The ACL | |
400eda43 | 13470 | condition &`verify = helo`& is provided to make this possible. |
9b371988 PH |
13471 | Formerly, it was necessary also to set this option (&%helo_try_verify_hosts%&) |
13472 | to force the check to occur. From release 4.53 onwards, this is no longer | |
9c2b45c9 | 13473 | necessary. If the check has not been done before &`verify = helo`& is |
9b371988 PH |
13474 | encountered, it is done at that time. Consequently, this option is obsolete. |
13475 | Its specification is retained here for backwards compatibility. | |
13476 | ||
068aaea8 | 13477 | When an EHLO or HELO command is received, if the calling host matches |
9b371988 | 13478 | &%helo_try_verify_hosts%&, Exim checks that the host name given in the HELO or |
068aaea8 | 13479 | EHLO command either: |
168e428f | 13480 | |
9b371988 PH |
13481 | .ilist |
13482 | is an IP literal matching the calling address of the host, or | |
13483 | .next | |
13484 | .cindex "DNS" "reverse lookup" | |
13485 | .cindex "reverse DNS lookup" | |
168e428f PH |
13486 | matches the host name that Exim obtains by doing a reverse lookup of the |
13487 | calling host address, or | |
9b371988 PH |
13488 | .next |
13489 | when looked up using &[gethostbyname()]& (or &[getipnodebyname()]& when | |
168e428f | 13490 | available) yields the calling host address. |
9b371988 | 13491 | .endlist |
168e428f PH |
13492 | |
13493 | However, the EHLO or HELO command is not rejected if any of the checks | |
13494 | fail. Processing continues, but the result of the check is remembered, and can | |
9c2b45c9 | 13495 | be detected later in an ACL by the &`verify = helo`& condition. |
168e428f | 13496 | |
9b371988 PH |
13497 | .option helo_verify_hosts main "host list&!!" unset |
13498 | .cindex "HELO verifying" "mandatory" | |
f89d2485 | 13499 | .cindex "EHLO" "verifying, mandatory" |
9b371988 | 13500 | Like &%helo_try_verify_hosts%&, this option is obsolete, and retained only for |
068aaea8 | 13501 | backwards compatibility. For hosts that match this option, Exim checks the host |
9b371988 PH |
13502 | name given in the HELO or EHLO in the same way as for |
13503 | &%helo_try_verify_hosts%&. If the check fails, the HELO or EHLO command is | |
13504 | rejected with a 550 error, and entries are written to the main and reject logs. | |
13505 | If a MAIL command is received before EHLO or HELO, it is rejected with a 503 | |
13506 | error. | |
168e428f | 13507 | |
9b371988 PH |
13508 | .option hold_domains main "domain list&!!" unset |
13509 | .cindex "domain" "delaying delivery" | |
13510 | .cindex "delivery" "delaying certain domains" | |
168e428f PH |
13511 | This option allows mail for particular domains to be held on the queue |
13512 | manually. The option is overridden if a message delivery is forced with the | |
9b371988 PH |
13513 | &%-M%&, &%-qf%&, &%-Rf%& or &%-Sf%& options, and also while testing or |
13514 | verifying addresses using &%-bt%& or &%-bv%&. Otherwise, if a domain matches an | |
13515 | item in &%hold_domains%&, no routing or delivery for that address is done, and | |
13516 | it is deferred every time the message is looked at. | |
168e428f PH |
13517 | |
13518 | This option is intended as a temporary operational measure for delaying the | |
13519 | delivery of mail while some problem is being sorted out, or some new | |
13520 | configuration tested. If you just want to delay the processing of some | |
9b371988 PH |
13521 | domains until a queue run occurs, you should use &%queue_domains%& or |
13522 | &%queue_smtp_domains%&, not &%hold_domains%&. | |
168e428f | 13523 | |
9b371988 | 13524 | A setting of &%hold_domains%& does not override Exim's code for removing |
168e428f PH |
13525 | messages from the queue if they have been there longer than the longest retry |
13526 | time in any retry rule. If you want to hold messages for longer than the normal | |
13527 | retry times, insert a dummy retry rule with a long retry time. | |
13528 | ||
13529 | ||
9b371988 | 13530 | .option host_lookup main "host list&!!" unset |
f89d2485 | 13531 | .cindex "host name" "lookup, forcing" |
168e428f PH |
13532 | Exim does not look up the name of a calling host from its IP address unless it |
13533 | is required to compare against some host list, or the host matches | |
9b371988 | 13534 | &%helo_try_verify_hosts%& or &%helo_verify_hosts%&, or the host matches this |
168e428f PH |
13535 | option (which normally contains IP addresses rather than host names). The |
13536 | default configuration file contains | |
9b371988 PH |
13537 | .code |
13538 | host_lookup = * | |
13539 | .endd | |
168e428f PH |
13540 | which causes a lookup to happen for all hosts. If the expense of these lookups |
13541 | is felt to be too great, the setting can be changed or removed. | |
13542 | ||
13543 | After a successful reverse lookup, Exim does a forward lookup on the name it | |
13544 | has obtained, to verify that it yields the IP address that it started with. If | |
13545 | this check fails, Exim behaves as if the name lookup failed. | |
13546 | ||
f89d2485 PH |
13547 | .vindex "&$host_lookup_failed$&" |
13548 | .vindex "&$sender_host_name$&" | |
9b371988 PH |
13549 | After any kind of failure, the host name (in &$sender_host_name$&) remains |
13550 | unset, and &$host_lookup_failed$& is set to the string &"1"&. See also | |
9c2b45c9 NM |
13551 | &%dns_again_means_nonexist%&, &%helo_lookup_domains%&, and |
13552 | &`verify = reverse_host_lookup`& in ACLs. | |
168e428f PH |
13553 | |
13554 | ||
9b371988 | 13555 | .option host_lookup_order main "string list" &`bydns:byaddr`& |
168e428f PH |
13556 | This option specifies the order of different lookup methods when Exim is trying |
13557 | to find a host name from an IP address. The default is to do a DNS lookup | |
9b371988 | 13558 | first, and then to try a local lookup (using &[gethostbyaddr()]& or equivalent) |
168e428f PH |
13559 | if that fails. You can change the order of these lookups, or omit one entirely, |
13560 | if you want. | |
13561 | ||
9b371988 | 13562 | &*Warning*&: The &"byaddr"& method does not always yield aliases when there are |
168e428f | 13563 | multiple PTR records in the DNS and the IP address is not listed in |
9b371988 | 13564 | &_/etc/hosts_&. Different operating systems give different results in this |
168e428f PH |
13565 | case. That is why the default tries a DNS lookup first. |
13566 | ||
13567 | ||
13568 | ||
9b371988 PH |
13569 | .option host_reject_connection main "host list&!!" unset |
13570 | .cindex "host" "rejecting connections from" | |
168e428f PH |
13571 | If this option is set, incoming SMTP calls from the hosts listed are rejected |
13572 | as soon as the connection is made. | |
13573 | This option is obsolete, and retained only for backward compatibility, because | |
9b371988 | 13574 | nowadays the ACL specified by &%acl_smtp_connect%& can also reject incoming |
168e428f PH |
13575 | connections immediately. |
13576 | ||
13577 | The ability to give an immediate rejection (either by this option or using an | |
13578 | ACL) is provided for use in unusual cases. Many hosts will just try again, | |
13579 | sometimes without much delay. Normally, it is better to use an ACL to reject | |
13580 | incoming messages at a later stage, such as after RCPT commands. See | |
9b371988 | 13581 | chapter &<<CHAPACL>>&. |
168e428f PH |
13582 | |
13583 | ||
9b371988 PH |
13584 | .option hosts_connection_nolog main "host list&!!" unset |
13585 | .cindex "host" "not logging connections from" | |
168e428f | 13586 | This option defines a list of hosts for which connection logging does not |
9b371988 | 13587 | happen, even though the &%smtp_connection%& log selector is set. For example, |
168e428f PH |
13588 | you might want not to log SMTP connections from local processes, or from |
13589 | 127.0.0.1, or from your local LAN. This option is consulted in the main loop of | |
13590 | the daemon; you should therefore strive to restrict its value to a short inline | |
13591 | list of IP addresses and networks. To disable logging SMTP connections from | |
13592 | local processes, you must create a host list with an empty item. For example: | |
9b371988 PH |
13593 | .code |
13594 | hosts_connection_nolog = : | |
13595 | .endd | |
13596 | If the &%smtp_connection%& log selector is not set, this option has no effect. | |
168e428f PH |
13597 | |
13598 | ||
13599 | ||
9b371988 PH |
13600 | .option hosts_treat_as_local main "domain list&!!" unset |
13601 | .cindex "local host" "domains treated as" | |
13602 | .cindex "host" "treated as local" | |
168e428f PH |
13603 | If this option is set, any host names that match the domain list are treated as |
13604 | if they were the local host when Exim is scanning host lists obtained from MX | |
13605 | records | |
13606 | or other sources. Note that the value of this option is a domain list, not a | |
13607 | host list, because it is always used to check host names, not IP addresses. | |
13608 | ||
13609 | This option also applies when Exim is matching the special items | |
9b371988 PH |
13610 | &`@mx_any`&, &`@mx_primary`&, and &`@mx_secondary`& in a domain list (see |
13611 | section &<<SECTdomainlist>>&), and when checking the &%hosts%& option in the | |
13612 | &(smtp)& transport for the local host (see the &%allow_localhost%& option in | |
13613 | that transport). See also &%local_interfaces%&, &%extra_local_interfaces%&, and | |
13614 | chapter &<<CHAPinterfaces>>&, which contains a discussion about local network | |
f89d2485 | 13615 | interfaces and recognizing the local host. |
9b371988 PH |
13616 | |
13617 | ||
595028e4 PH |
13618 | .option ibase_servers main "string list" unset |
13619 | .cindex "InterBase" "server list" | |
13620 | This option provides a list of InterBase servers and associated connection data, | |
13621 | to be used in conjunction with &(ibase)& lookups (see section &<<SECID72>>&). | |
13622 | The option is available only if Exim has been built with InterBase support. | |
595028e4 PH |
13623 | |
13624 | ||
13625 | ||
9b371988 PH |
13626 | .option ignore_bounce_errors_after main time 10w |
13627 | .cindex "bounce message" "discarding" | |
13628 | .cindex "discarding bounce message" | |
168e428f PH |
13629 | This option affects the processing of bounce messages that cannot be delivered, |
13630 | that is, those that suffer a permanent delivery failure. (Bounce messages that | |
13631 | suffer temporary delivery failures are of course retried in the usual way.) | |
13632 | ||
13633 | After a permanent delivery failure, bounce messages are frozen, | |
13634 | because there is no sender to whom they can be returned. When a frozen bounce | |
13635 | message has been on the queue for more than the given time, it is unfrozen at | |
13636 | the next queue run, and a further delivery is attempted. If delivery fails | |
13637 | again, the bounce message is discarded. This makes it possible to keep failed | |
13638 | bounce messages around for a shorter time than the normal maximum retry time | |
13639 | for frozen messages. For example, | |
9b371988 PH |
13640 | .code |
13641 | ignore_bounce_errors_after = 12h | |
13642 | .endd | |
168e428f PH |
13643 | retries failed bounce message deliveries after 12 hours, discarding any further |
13644 | failures. If the value of this option is set to a zero time period, bounce | |
13645 | failures are discarded immediately. Setting a very long time (as in the default | |
13646 | value) has the effect of disabling this option. For ways of automatically | |
9b371988 PH |
13647 | dealing with other kinds of frozen message, see &%auto_thaw%& and |
13648 | &%timeout_frozen_after%&. | |
168e428f PH |
13649 | |
13650 | ||
9b371988 PH |
13651 | .option ignore_fromline_hosts main "host list&!!" unset |
13652 | .cindex "&""From""& line" | |
13653 | .cindex "UUCP" "&""From""& line" | |
13654 | Some broken SMTP clients insist on sending a UUCP-like &"From&~"& line before | |
13655 | the headers of a message. By default this is treated as the start of the | |
13656 | message's body, which means that any following headers are not recognized as | |
13657 | such. Exim can be made to ignore it by setting &%ignore_fromline_hosts%& to | |
13658 | match those hosts that insist on sending it. If the sender is actually a local | |
13659 | process rather than a remote host, and is using &%-bs%& to inject the messages, | |
13660 | &%ignore_fromline_local%& must be set to achieve this effect. | |
168e428f | 13661 | |
168e428f | 13662 | |
9b371988 PH |
13663 | .option ignore_fromline_local main boolean false |
13664 | See &%ignore_fromline_hosts%& above. | |
168e428f | 13665 | |
168e428f | 13666 | |
9b371988 | 13667 | .option keep_malformed main time 4d |
168e428f PH |
13668 | This option specifies the length of time to keep messages whose spool files |
13669 | have been corrupted in some way. This should, of course, never happen. At the | |
13670 | next attempt to deliver such a message, it gets removed. The incident is | |
13671 | logged. | |
13672 | ||
13673 | ||
9b371988 PH |
13674 | .option ldap_default_servers main "string list" unset |
13675 | .cindex "LDAP" "default servers" | |
168e428f | 13676 | This option provides a list of LDAP servers which are tried in turn when an |
9b371988 PH |
13677 | LDAP query does not contain a server. See section &<<SECTforldaque>>& for |
13678 | details of LDAP queries. This option is available only when Exim has been built | |
13679 | with LDAP support. | |
168e428f | 13680 | |
168e428f | 13681 | |
9b371988 | 13682 | .option ldap_version main integer unset |
f89d2485 | 13683 | .cindex "LDAP" "protocol version, forcing" |
168e428f | 13684 | This option can be used to force Exim to set a specific protocol version for |
9b371988 | 13685 | LDAP. If it option is unset, it is shown by the &%-bP%& command line option as |
168e428f PH |
13686 | -1. When this is the case, the default is 3 if LDAP_VERSION3 is defined in |
13687 | the LDAP headers; otherwise it is 2. This option is available only when Exim | |
13688 | has been built with LDAP support. | |
13689 | ||
13690 | ||
13691 | ||
9b371988 PH |
13692 | .option local_from_check main boolean true |
13693 | .cindex "&'Sender:'& header line" "disabling addition of" | |
13694 | .cindex "&'From:'& header line" "disabling checking of" | |
168e428f | 13695 | When a message is submitted locally (that is, not over a TCP/IP connection) by |
9b371988 PH |
13696 | an untrusted user, Exim removes any existing &'Sender:'& header line, and |
13697 | checks that the &'From:'& header line matches the login of the calling user and | |
13698 | the domain specified by &%qualify_domain%&. | |
168e428f | 13699 | |
9b371988 | 13700 | &*Note*&: An unqualified address (no domain) in the &'From:'& header in a |
168e428f | 13701 | locally submitted message is automatically qualified by Exim, unless the |
9b371988 | 13702 | &%-bnq%& command line option is used. |
168e428f | 13703 | |
9b371988 PH |
13704 | You can use &%local_from_prefix%& and &%local_from_suffix%& to permit affixes |
13705 | on the local part. If the &'From:'& header line does not match, Exim adds a | |
13706 | &'Sender:'& header with an address constructed from the calling user's login | |
13707 | and the default qualify domain. | |
168e428f | 13708 | |
9b371988 PH |
13709 | If &%local_from_check%& is set false, the &'From:'& header check is disabled, |
13710 | and no &'Sender:'& header is ever added. If, in addition, you want to retain | |
13711 | &'Sender:'& header lines supplied by untrusted users, you must also set | |
13712 | &%local_sender_retain%& to be true. | |
168e428f | 13713 | |
9b371988 | 13714 | .cindex "envelope sender" |
168e428f PH |
13715 | These options affect only the header lines in the message. The envelope sender |
13716 | is still forced to be the login id at the qualify domain unless | |
9b371988 | 13717 | &%untrusted_set_sender%& permits the user to supply an envelope sender. |
168e428f | 13718 | |
9b371988 PH |
13719 | For messages received over TCP/IP, an ACL can specify &"submission mode"& to |
13720 | request similar header line checking. See section &<<SECTthesenhea>>&, which | |
13721 | has more details about &'Sender:'& processing. | |
168e428f PH |
13722 | |
13723 | ||
13724 | ||
13725 | ||
9b371988 PH |
13726 | .option local_from_prefix main string unset |
13727 | When Exim checks the &'From:'& header line of locally submitted messages for | |
13728 | matching the login id (see &%local_from_check%& above), it can be configured to | |
168e428f | 13729 | ignore certain prefixes and suffixes in the local part of the address. This is |
9b371988 PH |
13730 | done by setting &%local_from_prefix%& and/or &%local_from_suffix%& to |
13731 | appropriate lists, in the same form as the &%local_part_prefix%& and | |
13732 | &%local_part_suffix%& router options (see chapter &<<CHAProutergeneric>>&). For | |
168e428f | 13733 | example, if |
9b371988 PH |
13734 | .code |
13735 | local_from_prefix = *- | |
13736 | .endd | |
13737 | is set, a &'From:'& line containing | |
13738 | .code | |
13739 | From: anything-user@your.domain.example | |
13740 | .endd | |
13741 | will not cause a &'Sender:'& header to be added if &'user@your.domain.example'& | |
168e428f PH |
13742 | matches the actual sender address that is constructed from the login name and |
13743 | qualify domain. | |
13744 | ||
13745 | ||
9b371988 PH |
13746 | .option local_from_suffix main string unset |
13747 | See &%local_from_prefix%& above. | |
168e428f PH |
13748 | |
13749 | ||
9b371988 | 13750 | .option local_interfaces main "string list" "see below" |
168e428f PH |
13751 | This option controls which network interfaces are used by the daemon for |
13752 | listening; they are also used to identify the local host when routing. Chapter | |
9b371988 PH |
13753 | &<<CHAPinterfaces>>& contains a full description of this option and the related |
13754 | options &%daemon_smtp_ports%&, &%extra_local_interfaces%&, | |
13755 | &%hosts_treat_as_local%&, and &%tls_on_connect_ports%&. The default value for | |
13756 | &%local_interfaces%& is | |
13757 | .code | |
13758 | local_interfaces = 0.0.0.0 | |
13759 | .endd | |
168e428f | 13760 | when Exim is built without IPv6 support; otherwise it is |
9b371988 PH |
13761 | .code |
13762 | local_interfaces = <; ::0 ; 0.0.0.0 | |
13763 | .endd | |
168e428f | 13764 | |
9b371988 PH |
13765 | .option local_scan_timeout main time 5m |
13766 | .cindex "timeout" "for &[local_scan()]& function" | |
13767 | .cindex "&[local_scan()]& function" "timeout" | |
13768 | This timeout applies to the &[local_scan()]& function (see chapter | |
13769 | &<<CHAPlocalscan>>&). Zero means &"no timeout"&. If the timeout is exceeded, | |
13770 | the incoming message is rejected with a temporary error if it is an SMTP | |
13771 | message. For a non-SMTP message, the message is dropped and Exim ends with a | |
13772 | non-zero code. The incident is logged on the main and reject logs. | |
168e428f PH |
13773 | |
13774 | ||
168e428f | 13775 | |
9b371988 PH |
13776 | .option local_sender_retain main boolean false |
13777 | .cindex "&'Sender:'& header line" "retaining from local submission" | |
168e428f | 13778 | When a message is submitted locally (that is, not over a TCP/IP connection) by |
9b371988 PH |
13779 | an untrusted user, Exim removes any existing &'Sender:'& header line. If you |
13780 | do not want this to happen, you must set &%local_sender_retain%&, and you must | |
13781 | also set &%local_from_check%& to be false (Exim will complain if you do not). | |
13782 | See also the ACL modifier &`control = suppress_local_fixups`&. Section | |
13783 | &<<SECTthesenhea>>& has more details about &'Sender:'& processing. | |
168e428f PH |
13784 | |
13785 | ||
13786 | ||
168e428f | 13787 | |
9b371988 PH |
13788 | .option localhost_number main string&!! unset |
13789 | .cindex "host" "locally unique number for" | |
13790 | .cindex "message ids" "with multiple hosts" | |
f89d2485 | 13791 | .vindex "&$localhost_number$&" |
168e428f PH |
13792 | Exim's message ids are normally unique only within the local host. If |
13793 | uniqueness among a set of hosts is required, each host must set a different | |
9b371988 | 13794 | value for the &%localhost_number%& option. The string is expanded immediately |
168e428f PH |
13795 | after reading the configuration file (so that a number can be computed from the |
13796 | host name, for example) and the result of the expansion must be a number in the | |
9b371988 PH |
13797 | range 0&--16 (or 0&--10 on operating systems with case-insensitive file |
13798 | systems). This is available in subsequent string expansions via the variable | |
13799 | &$localhost_number$&. When &%localhost_number is set%&, the final two | |
168e428f PH |
13800 | characters of the message id, instead of just being a fractional part of the |
13801 | time, are computed from the time and the local host number as described in | |
9b371988 | 13802 | section &<<SECTmessiden>>&. |
168e428f PH |
13803 | |
13804 | ||
13805 | ||
9b371988 PH |
13806 | .option log_file_path main "string list&!!" "set at compile time" |
13807 | .cindex "log" "file path for" | |
168e428f PH |
13808 | This option sets the path which is used to determine the names of Exim's log |
13809 | files, or indicates that logging is to be to syslog, or both. It is expanded | |
13810 | when Exim is entered, so it can, for example, contain a reference to the host | |
13811 | name. If no specific path is set for the log files at compile or run time, they | |
9b371988 PH |
13812 | are written in a sub-directory called &_log_& in Exim's spool directory. |
13813 | Chapter &<<CHAPlog>>& contains further details about Exim's logging, and | |
13814 | section &<<SECTwhelogwri>>& describes how the contents of &%log_file_path%& are | |
13815 | used. If this string is fixed at your installation (contains no expansion | |
13816 | variables) it is recommended that you do not set this option in the | |
13817 | configuration file, but instead supply the path using LOG_FILE_PATH in | |
13818 | &_Local/Makefile_& so that it is available to Exim for logging errors detected | |
13819 | early on &-- in particular, failure to read the configuration file. | |
13820 | ||
13821 | ||
13822 | .option log_selector main string unset | |
13823 | .cindex "log" "selectors" | |
168e428f PH |
13824 | This option can be used to reduce or increase the number of things that Exim |
13825 | writes to its log files. Its argument is made up of names preceded by plus or | |
13826 | minus characters. For example: | |
9b371988 PH |
13827 | .code |
13828 | log_selector = +arguments -retry_defer | |
13829 | .endd | |
168e428f | 13830 | A list of possible names and what they control is given in the chapter on |
9b371988 | 13831 | logging, in section &<<SECTlogselector>>&. |
168e428f PH |
13832 | |
13833 | ||
9b371988 PH |
13834 | .option log_timezone main boolean false |
13835 | .cindex "log" "timezone for entries" | |
f89d2485 PH |
13836 | .vindex "&$tod_log$&" |
13837 | .vindex "&$tod_zone$&" | |
168e428f PH |
13838 | By default, the timestamps on log lines are in local time without the |
13839 | timezone. This means that if your timezone changes twice a year, the timestamps | |
13840 | in log lines are ambiguous for an hour when the clocks go back. One way of | |
13841 | avoiding this problem is to set the timezone to UTC. An alternative is to set | |
9b371988 | 13842 | &%log_timezone%& true. This turns on the addition of the timezone offset to |
168e428f PH |
13843 | timestamps in log lines. Turning on this option can add quite a lot to the size |
13844 | of log files because each line is extended by 6 characters. Note that the | |
9b371988 PH |
13845 | &$tod_log$& variable contains the log timestamp without the zone, but there is |
13846 | another variable called &$tod_zone$& that contains just the timezone offset. | |
168e428f | 13847 | |
168e428f | 13848 | |
9b371988 PH |
13849 | .option lookup_open_max main integer 25 |
13850 | .cindex "too many open files" | |
f89d2485 | 13851 | .cindex "open files, too many" |
9b371988 PH |
13852 | .cindex "file" "too many open" |
13853 | .cindex "lookup" "maximum open files" | |
13854 | .cindex "limit" "open files for lookups" | |
168e428f | 13855 | This option limits the number of simultaneously open files for single-key |
9b371988 PH |
13856 | lookups that use regular files (that is, &(lsearch)&, &(dbm)&, and &(cdb)&). |
13857 | Exim normally keeps these files open during routing, because often the same | |
13858 | file is required several times. If the limit is reached, Exim closes the least | |
13859 | recently used file. Note that if you are using the &'ndbm'& library, it | |
13860 | actually opens two files for each logical DBM database, though it still counts | |
13861 | as one for the purposes of &%lookup_open_max%&. If you are getting &"too many | |
13862 | open files"& errors with NDBM, you need to reduce the value of | |
13863 | &%lookup_open_max%&. | |
13864 | ||
13865 | ||
13866 | .option max_username_length main integer 0 | |
f89d2485 | 13867 | .cindex "length of login name" |
9b371988 PH |
13868 | .cindex "user name" "maximum length" |
13869 | .cindex "limit" "user name length" | |
168e428f | 13870 | Some operating systems are broken in that they truncate long arguments to |
9b371988 PH |
13871 | &[getpwnam()]& to eight characters, instead of returning &"no such user"&. If |
13872 | this option is set greater than zero, any attempt to call &[getpwnam()]& with | |
13873 | an argument that is longer behaves as if &[getpwnam()]& failed. | |
168e428f PH |
13874 | |
13875 | ||
595028e4 PH |
13876 | .option message_body_newlines main bool false |
13877 | .cindex "message body" "newlines in variables" | |
13878 | .cindex "newline" "in message body variables" | |
13879 | .vindex "&$message_body$&" | |
13880 | .vindex "&$message_body_end$&" | |
13881 | By default, newlines in the message body are replaced by spaces when setting | |
13882 | the &$message_body$& and &$message_body_end$& expansion variables. If this | |
13883 | option is set true, this no longer happens. | |
595028e4 | 13884 | |
168e428f | 13885 | |
9b371988 PH |
13886 | .option message_body_visible main integer 500 |
13887 | .cindex "body of message" "visible size" | |
13888 | .cindex "message body" "visible size" | |
f89d2485 PH |
13889 | .vindex "&$message_body$&" |
13890 | .vindex "&$message_body_end$&" | |
168e428f | 13891 | This option specifies how much of a message's body is to be included in the |
9b371988 | 13892 | &$message_body$& and &$message_body_end$& expansion variables. |
168e428f PH |
13893 | |
13894 | ||
9b371988 PH |
13895 | .option message_id_header_domain main string&!! unset |
13896 | .cindex "&'Message-ID:'& header line" | |
168e428f | 13897 | If this option is set, the string is expanded and used as the right hand side |
9b371988 PH |
13898 | (domain) of the &'Message-ID:'& header that Exim creates if a |
13899 | locally-originated incoming message does not have one. &"Locally-originated"& | |
13900 | means &"not received over TCP/IP."& | |
168e428f PH |
13901 | Otherwise, the primary host name is used. |
13902 | Only letters, digits, dot and hyphen are accepted; any other characters are | |
13903 | replaced by hyphens. If the expansion is forced to fail, or if the result is an | |
13904 | empty string, the option is ignored. | |
13905 | ||
13906 | ||
9b371988 | 13907 | .option message_id_header_text main string&!! unset |
168e428f | 13908 | If this variable is set, the string is expanded and used to augment the text of |
9b371988 | 13909 | the &'Message-id:'& header that Exim creates if a locally-originated incoming |
068aaea8 PH |
13910 | message does not have one. The text of this header is required by RFC 2822 to |
13911 | take the form of an address. By default, Exim uses its internal message id as | |
13912 | the local part, and the primary host name as the domain. If this option is set, | |
13913 | it is expanded, and provided the expansion is not forced to fail, and does not | |
13914 | yield an empty string, the result is inserted into the header immediately | |
13915 | before the @, separated from the internal message id by a dot. Any characters | |
13916 | that are illegal in an address are automatically converted into hyphens. This | |
9b371988 | 13917 | means that variables such as &$tod_log$& can be used, because the spaces and |
068aaea8 | 13918 | colons will become hyphens. |
168e428f PH |
13919 | |
13920 | ||
9b371988 | 13921 | .option message_logs main boolean true |
f89d2485 | 13922 | .cindex "message logs" "disabling" |
9b371988 | 13923 | .cindex "log" "message log; disabling" |
168e428f | 13924 | If this option is turned off, per-message log files are not created in the |
9b371988 | 13925 | &_msglog_& spool sub-directory. This reduces the amount of disk I/O required by |
168e428f PH |
13926 | Exim, by reducing the number of files involved in handling a message from a |
13927 | minimum of four (header spool file, body spool file, delivery journal, and | |
13928 | per-message log) to three. The other major I/O activity is Exim's main log, | |
13929 | which is not affected by this option. | |
13930 | ||
13931 | ||
9b371988 PH |
13932 | .option message_size_limit main string&!! 50M |
13933 | .cindex "message" "size limit" | |
13934 | .cindex "limit" "message size" | |
f89d2485 | 13935 | .cindex "size" "of message, limit" |
168e428f | 13936 | This option limits the maximum size of message that Exim will process. The |
ad268134 PH |
13937 | value is expanded for each incoming connection so, for example, it can be made |
13938 | to depend on the IP address of the remote host for messages arriving via | |
f89d2485 PH |
13939 | TCP/IP. After expansion, the value must be a sequence of decimal digits, |
13940 | optionally followed by K or M. | |
ad268134 PH |
13941 | |
13942 | &*Note*&: This limit cannot be made to depend on a message's sender or any | |
13943 | other properties of an individual message, because it has to be advertised in | |
13944 | the server's response to EHLO. String expansion failure causes a temporary | |
13945 | error. A value of zero means no limit, but its use is not recommended. See also | |
13946 | &%bounce_return_size_limit%&. | |
168e428f PH |
13947 | |
13948 | Incoming SMTP messages are failed with a 552 error if the limit is | |
13949 | exceeded; locally-generated messages either get a stderr message or a delivery | |
9b371988 PH |
13950 | failure message to the sender, depending on the &%-oe%& setting. Rejection of |
13951 | an oversized message is logged in both the main and the reject logs. See also | |
13952 | the generic transport option &%message_size_limit%&, which limits the size of | |
168e428f PH |
13953 | message that an individual transport can process. |
13954 | ||
13955 | ||
9b371988 PH |
13956 | .option move_frozen_messages main boolean false |
13957 | .cindex "frozen messages" "moving" | |
168e428f | 13958 | This option, which is available only if Exim has been built with the setting |
9b371988 PH |
13959 | .code |
13960 | SUPPORT_MOVE_FROZEN_MESSAGES=yes | |
13961 | .endd | |
13962 | in &_Local/Makefile_&, causes frozen messages and their message logs to be | |
13963 | moved from the &_input_& and &_msglog_& directories on the spool to &_Finput_& | |
13964 | and &_Fmsglog_&, respectively. There is currently no support in Exim or the | |
168e428f | 13965 | standard utilities for handling such moved messages, and they do not show up in |
9b371988 | 13966 | lists generated by &%-bp%& or by the Exim monitor. |
168e428f | 13967 | |
168e428f | 13968 | |
9b371988 | 13969 | .option mua_wrapper main boolean false |
168e428f | 13970 | Setting this option true causes Exim to run in a very restrictive mode in which |
9b371988 | 13971 | it passes messages synchronously to a smart host. Chapter &<<CHAPnonqueueing>>& |
168e428f PH |
13972 | contains a full description of this facility. |
13973 | ||
13974 | ||
13975 | ||
9b371988 PH |
13976 | .option mysql_servers main "string list" unset |
13977 | .cindex "MySQL" "server list" | |
168e428f | 13978 | This option provides a list of MySQL servers and associated connection data, to |
595028e4 | 13979 | be used in conjunction with &(mysql)& lookups (see section &<<SECID72>>&). The |
168e428f PH |
13980 | option is available only if Exim has been built with MySQL support. |
13981 | ||
13982 | ||
9b371988 | 13983 | .option never_users main "string list&!!" unset |
068aaea8 PH |
13984 | This option is expanded just once, at the start of Exim's processing. Local |
13985 | message deliveries are normally run in processes that are setuid to the | |
168e428f PH |
13986 | recipient, and remote deliveries are normally run under Exim's own uid and gid. |
13987 | It is usually desirable to prevent any deliveries from running as root, as a | |
13988 | safety precaution. | |
13989 | ||
13990 | When Exim is built, an option called FIXED_NEVER_USERS can be set to a | |
13991 | list of users that must not be used for local deliveries. This list is fixed in | |
13992 | the binary and cannot be overridden by the configuration file. By default, it | |
9b371988 | 13993 | contains just the single user name &"root"&. The &%never_users%& runtime option |
168e428f PH |
13994 | can be used to add more users to the fixed list. |
13995 | ||
13996 | If a message is to be delivered as one of the users on the fixed list or the | |
9b371988 | 13997 | &%never_users%& list, an error occurs, and delivery is deferred. A common |
168e428f | 13998 | example is |
9b371988 PH |
13999 | .code |
14000 | never_users = root:daemon:bin | |
14001 | .endd | |
168e428f | 14002 | Including root is redundant if it is also on the fixed list, but it does no |
9b371988 | 14003 | harm. This option overrides the &%pipe_as_creator%& option of the &(pipe)& |
168e428f PH |
14004 | transport driver. |
14005 | ||
14006 | ||
77bb000f PP |
14007 | .option openssl_options main "string list" +dont_insert_empty_fragments |
14008 | .cindex "OpenSSL "compatibility options" | |
14009 | This option allows an administrator to adjust the SSL options applied | |
14010 | by OpenSSL to connections. It is given as a space-separated list of items, | |
14011 | each one to be +added or -subtracted from the current value. The default | |
14012 | value is one option which happens to have been set historically. You can | |
14013 | remove all options with: | |
14014 | .code | |
14015 | openssl_options = -all | |
14016 | .endd | |
14017 | This option is only available if Exim is built against OpenSSL. The values | |
14018 | available for this option vary according to the age of your OpenSSL install. | |
14019 | The &"all"& value controls a subset of flags which are available, typically | |
14020 | the bug workaround options. The &'SSL_CTX_set_options'& man page will | |
14021 | list the values known on your system and Exim should support all the | |
14022 | &"bug workaround"& options and many of the &"modifying"& options. The Exim | |
14023 | names lose the leading &"SSL_OP_"& and are lower-cased. | |
14024 | ||
14025 | Note that adjusting the options can have severe impact upon the security of | |
14026 | SSL as used by Exim. It is possible to disable safety checks and shoot | |
14027 | yourself in the foot in various unpleasant ways. This option should not be | |
14028 | adjusted lightly. An unrecognised item will be detected at by invoking Exim | |
14029 | with the &%-bV%& flag. | |
14030 | ||
14031 | An example: | |
14032 | .code | |
14033 | openssl_options = -all +microsoft_big_sslv3_buffer | |
14034 | .endd | |
14035 | ||
14036 | ||
9b371988 PH |
14037 | .option oracle_servers main "string list" unset |
14038 | .cindex "Oracle" "server list" | |
168e428f | 14039 | This option provides a list of Oracle servers and associated connection data, |
595028e4 | 14040 | to be used in conjunction with &(oracle)& lookups (see section &<<SECID72>>&). |
9b371988 PH |
14041 | The option is available only if Exim has been built with Oracle support. |
14042 | ||
14043 | ||
14044 | .option percent_hack_domains main "domain list&!!" unset | |
14045 | .cindex "&""percent hack""&" | |
14046 | .cindex "source routing" "in email address" | |
14047 | .cindex "address" "source-routed" | |
14048 | The &"percent hack"& is the convention whereby a local part containing a | |
14049 | percent sign is re-interpreted as a new email address, with the percent | |
14050 | replaced by @. This is sometimes called &"source routing"&, though that term is | |
14051 | also applied to RFC 2822 addresses that begin with an @ character. If this | |
14052 | option is set, Exim implements the percent facility for those domains listed, | |
14053 | but no others. This happens before an incoming SMTP address is tested against | |
14054 | an ACL. | |
14055 | ||
14056 | &*Warning*&: The &"percent hack"& has often been abused by people who are | |
168e428f PH |
14057 | trying to get round relaying restrictions. For this reason, it is best avoided |
14058 | if at all possible. Unfortunately, a number of less security-conscious MTAs | |
14059 | implement it unconditionally. If you are running Exim on a gateway host, and | |
14060 | routing mail through to internal MTAs without processing the local parts, it is | |
14061 | a good idea to reject recipient addresses with percent characters in their | |
14062 | local parts. Exim's default configuration does this. | |
14063 | ||
14064 | ||
9b371988 | 14065 | .option perl_at_start main boolean false |
168e428f | 14066 | This option is available only when Exim is built with an embedded Perl |
9b371988 | 14067 | interpreter. See chapter &<<CHAPperl>>& for details of its use. |
168e428f | 14068 | |
168e428f | 14069 | |
9b371988 | 14070 | .option perl_startup main string unset |
168e428f | 14071 | This option is available only when Exim is built with an embedded Perl |
9b371988 | 14072 | interpreter. See chapter &<<CHAPperl>>& for details of its use. |
168e428f PH |
14073 | |
14074 | ||
9b371988 PH |
14075 | .option pgsql_servers main "string list" unset |
14076 | .cindex "PostgreSQL lookup type" "server list" | |
168e428f | 14077 | This option provides a list of PostgreSQL servers and associated connection |
9b371988 | 14078 | data, to be used in conjunction with &(pgsql)& lookups (see section |
595028e4 | 14079 | &<<SECID72>>&). The option is available only if Exim has been built with |
9b371988 | 14080 | PostgreSQL support. |
168e428f | 14081 | |
168e428f | 14082 | |
9b371988 PH |
14083 | .option pid_file_path main string&!! "set at compile time" |
14084 | .cindex "daemon" "pid file path" | |
f89d2485 | 14085 | .cindex "pid file, path for" |
168e428f PH |
14086 | This option sets the name of the file to which the Exim daemon writes its |
14087 | process id. The string is expanded, so it can contain, for example, references | |
14088 | to the host name: | |
9b371988 PH |
14089 | .code |
14090 | pid_file_path = /var/log/$primary_hostname/exim.pid | |
14091 | .endd | |
14092 | If no path is set, the pid is written to the file &_exim-daemon.pid_& in Exim's | |
168e428f | 14093 | spool directory. |
9b371988 PH |
14094 | The value set by the option can be overridden by the &%-oP%& command line |
14095 | option. A pid file is not written if a &"non-standard"& daemon is run by means | |
14096 | of the &%-oX%& option, unless a path is explicitly supplied by &%-oP%&. | |
168e428f | 14097 | |
168e428f | 14098 | |
9b371988 | 14099 | .option pipelining_advertise_hosts main "host list&!!" * |
f89d2485 | 14100 | .cindex "PIPELINING" "suppressing advertising" |
168e428f | 14101 | This option can be used to suppress the advertisement of the SMTP |
595028e4 PH |
14102 | PIPELINING extension to specific hosts. See also the &*no_pipelining*& |
14103 | control in section &<<SECTcontrols>>&. When PIPELINING is not advertised and | |
f89d2485 PH |
14104 | &%smtp_enforce_sync%& is true, an Exim server enforces strict synchronization |
14105 | for each SMTP command and response. When PIPELINING is advertised, Exim assumes | |
14106 | that clients will use it; &"out of order"& commands that are &"expected"& do | |
14107 | not count as protocol errors (see &%smtp_max_synprot_errors%&). | |
168e428f PH |
14108 | |
14109 | ||
9b371988 PH |
14110 | .option preserve_message_logs main boolean false |
14111 | .cindex "message logs" "preserving" | |
168e428f PH |
14112 | If this option is set, message log files are not deleted when messages are |
14113 | completed. Instead, they are moved to a sub-directory of the spool directory | |
9b371988 | 14114 | called &_msglog.OLD_&, where they remain available for statistical or debugging |
168e428f PH |
14115 | purposes. This is a dangerous option to set on systems with any appreciable |
14116 | volume of mail. Use with care! | |
14117 | ||
14118 | ||
9b371988 PH |
14119 | .option primary_hostname main string "see below" |
14120 | .cindex "name" "of local host" | |
14121 | .cindex "host" "name of local" | |
14122 | .cindex "local host" "name of" | |
f89d2485 | 14123 | .vindex "&$primary_hostname$&" |
068aaea8 | 14124 | This specifies the name of the current host. It is used in the default EHLO or |
9b371988 PH |
14125 | HELO command for outgoing SMTP messages (changeable via the &%helo_data%& |
14126 | option in the &(smtp)& transport), and as the default for &%qualify_domain%&. | |
14127 | The value is also used by default in some SMTP response messages from an Exim | |
14128 | server. This can be changed dynamically by setting &%smtp_active_hostname%&. | |
14129 | ||
14130 | If &%primary_hostname%& is not set, Exim calls &[uname()]& to find the host | |
14131 | name. If this fails, Exim panics and dies. If the name returned by &[uname()]& | |
14132 | contains only one component, Exim passes it to &[gethostbyname()]& (or | |
14133 | &[getipnodebyname()]& when available) in order to obtain the fully qualified | |
14134 | version. The variable &$primary_hostname$& contains the host name, whether set | |
14135 | explicitly by this option, or defaulted. | |
14136 | ||
14137 | ||
14138 | .option print_topbitchars main boolean false | |
14139 | .cindex "printing characters" | |
14140 | .cindex "8-bit characters" | |
168e428f | 14141 | By default, Exim considers only those characters whose codes lie in the range |
9b371988 | 14142 | 32&--126 to be printing characters. In a number of circumstances (for example, |
168e428f | 14143 | when writing log entries) non-printing characters are converted into escape |
9b371988 PH |
14144 | sequences, primarily to avoid messing up the layout. If &%print_topbitchars%& |
14145 | is set, code values of 128 and above are also considered to be printing | |
168e428f PH |
14146 | characters. |
14147 | ||
8c44ad5f TF |
14148 | This option also affects the header syntax checks performed by the |
14149 | &(autoreply)& transport, and whether Exim uses RFC 2047 encoding of | |
14150 | the user's full name when constructing From: and Sender: addresses (as | |
14151 | described in section &<<SECTconstr>>&). Setting this option can cause | |
14152 | Exim to generate eight bit message headers that do not conform to the | |
14153 | standards. | |
14154 | ||
168e428f | 14155 | |
9b371988 PH |
14156 | .option process_log_path main string unset |
14157 | .cindex "process log path" | |
14158 | .cindex "log" "process log" | |
14159 | .cindex "&'exiwhat'&" | |
168e428f | 14160 | This option sets the name of the file to which an Exim process writes its |
9b371988 PH |
14161 | &"process log"& when sent a USR1 signal. This is used by the &'exiwhat'& |
14162 | utility script. If this option is unset, the file called &_exim-process.info_& | |
14163 | in Exim's spool directory is used. The ability to specify the name explicitly | |
14164 | can be useful in environments where two different Exims are running, using | |
168e428f PH |
14165 | different spool directories. |
14166 | ||
14167 | ||
9b371988 | 14168 | .option prod_requires_admin main boolean true |
f89d2485 PH |
14169 | .oindex "&%-M%&" |
14170 | .oindex "&%-R%&" | |
14171 | .oindex "&%-q%&" | |
9b371988 PH |
14172 | The &%-M%&, &%-R%&, and &%-q%& command-line options require the caller to be an |
14173 | admin user unless &%prod_requires_admin%& is set false. See also | |
14174 | &%queue_list_requires_admin%&. | |
168e428f | 14175 | |
168e428f | 14176 | |
9b371988 PH |
14177 | .option qualify_domain main string "see below" |
14178 | .cindex "domain" "for qualifying addresses" | |
14179 | .cindex "address" "qualification" | |
168e428f PH |
14180 | This option specifies the domain name that is added to any envelope sender |
14181 | addresses that do not have a domain qualification. It also applies to | |
9b371988 PH |
14182 | recipient addresses if &%qualify_recipient%& is not set. Unqualified addresses |
14183 | are accepted by default only for locally-generated messages. Qualification is | |
14184 | also applied to addresses in header lines such as &'From:'& and &'To:'& for | |
14185 | locally-generated messages, unless the &%-bnq%& command line option is used. | |
168e428f PH |
14186 | |
14187 | Messages from external sources must always contain fully qualified addresses, | |
9b371988 PH |
14188 | unless the sending host matches &%sender_unqualified_hosts%& or |
14189 | &%recipient_unqualified_hosts%& (as appropriate), in which case incoming | |
14190 | addresses are qualified with &%qualify_domain%& or &%qualify_recipient%& as | |
168e428f | 14191 | necessary. Internally, Exim always works with fully qualified envelope |
9b371988 PH |
14192 | addresses. If &%qualify_domain%& is not set, it defaults to the |
14193 | &%primary_hostname%& value. | |
168e428f PH |
14194 | |
14195 | ||
9b371988 | 14196 | .option qualify_recipient main string "see below" |
168e428f | 14197 | This option allows you to specify a different domain for qualifying recipient |
9b371988 | 14198 | addresses to the one that is used for senders. See &%qualify_domain%& above. |
168e428f PH |
14199 | |
14200 | ||
168e428f | 14201 | |
9b371988 PH |
14202 | .option queue_domains main "domain list&!!" unset |
14203 | .cindex "domain" "specifying non-immediate delivery" | |
14204 | .cindex "queueing incoming messages" | |
14205 | .cindex "message" "queueing certain domains" | |
168e428f PH |
14206 | This option lists domains for which immediate delivery is not required. |
14207 | A delivery process is started whenever a message is received, but only those | |
14208 | domains that do not match are processed. All other deliveries wait until the | |
9b371988 | 14209 | next queue run. See also &%hold_domains%& and &%queue_smtp_domains%&. |
168e428f | 14210 | |
168e428f | 14211 | |
9b371988 | 14212 | .option queue_list_requires_admin main boolean true |
f89d2485 | 14213 | .oindex "&%-bp%&" |
9b371988 PH |
14214 | The &%-bp%& command-line option, which lists the messages that are on the |
14215 | queue, requires the caller to be an admin user unless | |
14216 | &%queue_list_requires_admin%& is set false. See also &%prod_requires_admin%&. | |
168e428f PH |
14217 | |
14218 | ||
9b371988 PH |
14219 | .option queue_only main boolean false |
14220 | .cindex "queueing incoming messages" | |
14221 | .cindex "message" "queueing unconditionally" | |
14222 | If &%queue_only%& is set, a delivery process is not automatically started | |
168e428f | 14223 | whenever a message is received. Instead, the message waits on the queue for the |
9b371988 | 14224 | next queue run. Even if &%queue_only%& is false, incoming messages may not get |
168e428f PH |
14225 | delivered immediately when certain conditions (such as heavy load) occur. |
14226 | ||
9b371988 PH |
14227 | The &%-odq%& command line has the same effect as &%queue_only%&. The &%-odb%& |
14228 | and &%-odi%& command line options override &%queue_only%& unless | |
14229 | &%queue_only_override%& is set false. See also &%queue_only_file%&, | |
14230 | &%queue_only_load%&, and &%smtp_accept_queue%&. | |
168e428f | 14231 | |
168e428f | 14232 | |
9b371988 PH |
14233 | .option queue_only_file main string unset |
14234 | .cindex "queueing incoming messages" | |
14235 | .cindex "message" "queueing by file existence" | |
168e428f | 14236 | This option can be set to a colon-separated list of absolute path names, each |
9b371988 PH |
14237 | one optionally preceded by &"smtp"&. When Exim is receiving a message, |
14238 | it tests for the existence of each listed path using a call to &[stat()]&. For | |
f89d2485 | 14239 | each path that exists, the corresponding queueing option is set. |
9b371988 PH |
14240 | For paths with no prefix, &%queue_only%& is set; for paths prefixed by |
14241 | &"smtp"&, &%queue_smtp_domains%& is set to match all domains. So, for example, | |
14242 | .code | |
14243 | queue_only_file = smtp/some/file | |
14244 | .endd | |
14245 | causes Exim to behave as if &%queue_smtp_domains%& were set to &"*"& whenever | |
14246 | &_/some/file_& exists. | |
14247 | ||
14248 | ||
14249 | .option queue_only_load main fixed-point unset | |
14250 | .cindex "load average" | |
14251 | .cindex "queueing incoming messages" | |
14252 | .cindex "message" "queueing by load" | |
168e428f PH |
14253 | If the system load average is higher than this value, incoming messages from |
14254 | all sources are queued, and no automatic deliveries are started. If this | |
595028e4 PH |
14255 | happens during local or remote SMTP input, all subsequent messages received on |
14256 | the same SMTP connection are queued by default, whatever happens to the load in | |
14257 | the meantime, but this can be changed by setting &%queue_only_load_latch%& | |
14258 | false. | |
595028e4 PH |
14259 | |
14260 | Deliveries will subsequently be performed by queue runner processes. This | |
14261 | option has no effect on ancient operating systems on which Exim cannot | |
14262 | determine the load average. See also &%deliver_queue_load_max%& and | |
14263 | &%smtp_load_reserve%&. | |
14264 | ||
14265 | ||
595028e4 PH |
14266 | .option queue_only_load_latch main boolean true |
14267 | .cindex "load average" "re-evaluating per message" | |
14268 | When this option is true (the default), once one message has been queued | |
14269 | because the load average is higher than the value set by &%queue_only_load%&, | |
14270 | all subsequent messages received on the same SMTP connection are also queued. | |
14271 | This is a deliberate choice; even though the load average may fall below the | |
14272 | threshold, it doesn't seem right to deliver later messages on the same | |
14273 | connection when not delivering earlier ones. However, there are special | |
14274 | circumstances such as very long-lived connections from scanning appliances | |
14275 | where this is not the best strategy. In such cases, &%queue_only_load_latch%& | |
14276 | should be set false. This causes the value of the load average to be | |
14277 | re-evaluated for each message. | |
168e428f | 14278 | |
168e428f | 14279 | |
9b371988 PH |
14280 | .option queue_only_override main boolean true |
14281 | .cindex "queueing incoming messages" | |
14282 | When this option is true, the &%-od%&&'x'& command line options override the | |
14283 | setting of &%queue_only%& or &%queue_only_file%& in the configuration file. If | |
14284 | &%queue_only_override%& is set false, the &%-od%&&'x'& options cannot be used | |
14285 | to override; they are accepted, but ignored. | |
168e428f PH |
14286 | |
14287 | ||
9b371988 PH |
14288 | .option queue_run_in_order main boolean false |
14289 | .cindex "queue runner" "processing messages in order" | |
168e428f PH |
14290 | If this option is set, queue runs happen in order of message arrival instead of |
14291 | in an arbitrary order. For this to happen, a complete list of the entire queue | |
14292 | must be set up before the deliveries start. When the queue is all held in a | |
c0712871 PH |
14293 | single directory (the default), a single list is created for both the ordered |
14294 | and the non-ordered cases. However, if &%split_spool_directory%& is set, a | |
14295 | single list is not created when &%queue_run_in_order%& is false. In this case, | |
14296 | the sub-directories are processed one at a time (in a random order), and this | |
14297 | avoids setting up one huge list for the whole queue. Thus, setting | |
14298 | &%queue_run_in_order%& with &%split_spool_directory%& may degrade performance | |
14299 | when the queue is large, because of the extra work in setting up the single, | |
14300 | large list. In most situations, &%queue_run_in_order%& should not be set. | |
168e428f PH |
14301 | |
14302 | ||
168e428f | 14303 | |
9b371988 PH |
14304 | .option queue_run_max main integer 5 |
14305 | .cindex "queue runner" "maximum number of" | |
168e428f PH |
14306 | This controls the maximum number of queue runner processes that an Exim daemon |
14307 | can run simultaneously. This does not mean that it starts them all at once, | |
14308 | but rather that if the maximum number are still running when the time comes to | |
14309 | start another one, it refrains from starting another one. This can happen with | |
14310 | very large queues and/or very sluggish deliveries. This option does not, | |
14311 | however, interlock with other processes, so additional queue runners can be | |
14312 | started by other means, or by killing and restarting the daemon. | |
14313 | ||
068aaea8 PH |
14314 | Setting this option to zero does not suppress queue runs; rather, it disables |
14315 | the limit, allowing any number of simultaneous queue runner processes to be | |
9b371988 PH |
14316 | run. If you do not want queue runs to occur, omit the &%-q%&&'xx'& setting on |
14317 | the daemon's command line. | |
168e428f | 14318 | |
9b371988 PH |
14319 | .option queue_smtp_domains main "domain list&!!" unset |
14320 | .cindex "queueing incoming messages" | |
14321 | .cindex "message" "queueing remote deliveries" | |
168e428f PH |
14322 | When this option is set, a delivery process is started whenever a message is |
14323 | received, routing is performed, and local deliveries take place. | |
14324 | However, if any SMTP deliveries are required for domains that match | |
9b371988 | 14325 | &%queue_smtp_domains%&, they are not immediately delivered, but instead the |
168e428f PH |
14326 | message waits on the queue for the next queue run. Since routing of the message |
14327 | has taken place, Exim knows to which remote hosts it must be delivered, and so | |
14328 | when the queue run happens, multiple messages for the same host are delivered | |
9b371988 PH |
14329 | over a single SMTP connection. The &%-odqs%& command line option causes all |
14330 | SMTP deliveries to be queued in this way, and is equivalent to setting | |
14331 | &%queue_smtp_domains%& to &"*"&. See also &%hold_domains%& and | |
14332 | &%queue_domains%&. | |
168e428f | 14333 | |
168e428f | 14334 | |
9b371988 PH |
14335 | .option receive_timeout main time 0s |
14336 | .cindex "timeout" "for non-SMTP input" | |
168e428f PH |
14337 | This option sets the timeout for accepting a non-SMTP message, that is, the |
14338 | maximum time that Exim waits when reading a message on the standard input. If | |
14339 | the value is zero, it will wait for ever. This setting is overridden by the | |
9b371988 PH |
14340 | &%-or%& command line option. The timeout for incoming SMTP messages is |
14341 | controlled by &%smtp_receive_timeout%&. | |
168e428f | 14342 | |
9b371988 PH |
14343 | .option received_header_text main string&!! "see below" |
14344 | .cindex "customizing" "&'Received:'& header" | |
14345 | .cindex "&'Received:'& header line" "customizing" | |
14346 | This string defines the contents of the &'Received:'& message header that is | |
168e428f PH |
14347 | added to each message, except for the timestamp, which is automatically added |
14348 | on at the end (preceded by a semicolon). The string is expanded each time it is | |
9b371988 | 14349 | used. If the expansion yields an empty string, no &'Received:'& header line is |
168e428f | 14350 | added to the message. Otherwise, the string should start with the text |
9b371988 PH |
14351 | &"Received:"& and conform to the RFC 2822 specification for &'Received:'& |
14352 | header lines. The default setting is: | |
168e428f | 14353 | |
9b371988 | 14354 | .code |
168e428f | 14355 | received_header_text = Received: \ |
d1e83bff | 14356 | ${if def:sender_rcvhost {from $sender_rcvhost\n\t}\ |
9b371988 | 14357 | {${if def:sender_ident \ |
4f578862 | 14358 | {from ${quote_local_part:$sender_ident} }}\ |
d1e83bff PH |
14359 | ${if def:sender_helo_name {(helo=$sender_helo_name)\n\t}}}}\ |
14360 | by $primary_hostname \ | |
14361 | ${if def:received_protocol {with $received_protocol}} \ | |
14362 | ${if def:tls_cipher {($tls_cipher)\n\t}}\ | |
14363 | (Exim $version_number)\n\t\ | |
9b371988 PH |
14364 | ${if def:sender_address \ |
14365 | {(envelope-from <$sender_address>)\n\t}}\ | |
d1e83bff PH |
14366 | id $message_exim_id\ |
14367 | ${if def:received_for {\n\tfor $received_for}} | |
9b371988 | 14368 | .endd |
168e428f | 14369 | |
d1e83bff PH |
14370 | The reference to the TLS cipher is omitted when Exim is built without TLS |
14371 | support. The use of conditional expansions ensures that this works for both | |
14372 | locally generated messages and messages received from remote hosts, giving | |
14373 | header lines such as the following: | |
9b371988 PH |
14374 | .code |
14375 | Received: from scrooge.carol.example ([192.168.12.25] ident=root) | |
14376 | by marley.carol.example with esmtp (Exim 4.00) | |
14377 | (envelope-from <bob@carol.example>) | |
14378 | id 16IOWa-00019l-00 | |
14379 | for chas@dickens.example; Tue, 25 Dec 2001 14:43:44 +0000 | |
14380 | Received: by scrooge.carol.example with local (Exim 4.00) | |
14381 | id 16IOWW-000083-00; Tue, 25 Dec 2001 14:43:41 +0000 | |
14382 | .endd | |
168e428f PH |
14383 | Until the body of the message has been received, the timestamp is the time when |
14384 | the message started to be received. Once the body has arrived, and all policy | |
14385 | checks have taken place, the timestamp is updated to the time at which the | |
14386 | message was accepted. | |
14387 | ||
14388 | ||
9b371988 PH |
14389 | .option received_headers_max main integer 30 |
14390 | .cindex "loop" "prevention" | |
14391 | .cindex "mail loop prevention" | |
14392 | .cindex "&'Received:'& header line" "counting" | |
14393 | When a message is to be delivered, the number of &'Received:'& headers is | |
168e428f PH |
14394 | counted, and if it is greater than this parameter, a mail loop is assumed to |
14395 | have occurred, the delivery is abandoned, and an error message is generated. | |
14396 | This applies to both local and remote deliveries. | |
14397 | ||
14398 | ||
9b371988 PH |
14399 | .option recipient_unqualified_hosts main "host list&!!" unset |
14400 | .cindex "unqualified addresses" | |
14401 | .cindex "host" "unqualified addresses from" | |
168e428f PH |
14402 | This option lists those hosts from which Exim is prepared to accept unqualified |
14403 | recipient addresses in message envelopes. The addresses are made fully | |
9b371988 | 14404 | qualified by the addition of the &%qualify_recipient%& value. This option also |
168e428f PH |
14405 | affects message header lines. Exim does not reject unqualified recipient |
14406 | addresses in headers, but it qualifies them only if the message came from a | |
9b371988 PH |
14407 | host that matches &%recipient_unqualified_hosts%&, |
14408 | or if the message was submitted locally (not using TCP/IP), and the &%-bnq%& | |
168e428f PH |
14409 | option was not set. |
14410 | ||
14411 | ||
9b371988 PH |
14412 | .option recipients_max main integer 0 |
14413 | .cindex "limit" "number of recipients" | |
14414 | .cindex "recipient" "maximum number" | |
168e428f PH |
14415 | If this option is set greater than zero, it specifies the maximum number of |
14416 | original recipients for any message. Additional recipients that are generated | |
14417 | by aliasing or forwarding do not count. SMTP messages get a 452 response for | |
14418 | all recipients over the limit; earlier recipients are delivered as normal. | |
14419 | Non-SMTP messages with too many recipients are failed, and no deliveries are | |
14420 | done. | |
14421 | ||
9b371988 PH |
14422 | .cindex "RCPT" "maximum number of incoming" |
14423 | &*Note*&: The RFCs specify that an SMTP server should accept at least 100 | |
168e428f PH |
14424 | RCPT commands in a single message. |
14425 | ||
14426 | ||
9b371988 | 14427 | .option recipients_max_reject main boolean false |
168e428f PH |
14428 | If this option is set true, Exim rejects SMTP messages containing too many |
14429 | recipients by giving 552 errors to the surplus RCPT commands, and a 554 | |
14430 | error to the eventual DATA command. Otherwise (the default) it gives a 452 | |
14431 | error to the surplus RCPT commands and accepts the message on behalf of the | |
14432 | initial set of recipients. The remote server should then re-send the message | |
14433 | for the remaining recipients at a later time. | |
14434 | ||
14435 | ||
9b371988 PH |
14436 | .option remote_max_parallel main integer 2 |
14437 | .cindex "delivery" "parallelism for remote" | |
168e428f PH |
14438 | This option controls parallel delivery of one message to a number of remote |
14439 | hosts. If the value is less than 2, parallel delivery is disabled, and Exim | |
14440 | does all the remote deliveries for a message one by one. Otherwise, if a single | |
14441 | message has to be delivered to more than one remote host, or if several copies | |
9b371988 PH |
14442 | have to be sent to the same remote host, up to &%remote_max_parallel%& |
14443 | deliveries are done simultaneously. If more than &%remote_max_parallel%& | |
168e428f PH |
14444 | deliveries are required, the maximum number of processes are started, and as |
14445 | each one finishes, another is begun. The order of starting processes is the | |
14446 | same as if sequential delivery were being done, and can be controlled by the | |
9b371988 | 14447 | &%remote_sort_domains%& option. If parallel delivery takes place while running |
168e428f PH |
14448 | with debugging turned on, the debugging output from each delivery process is |
14449 | tagged with its process id. | |
14450 | ||
14451 | This option controls only the maximum number of parallel deliveries for one | |
14452 | message in one Exim delivery process. Because Exim has no central queue | |
14453 | manager, there is no way of controlling the total number of simultaneous | |
14454 | deliveries if the configuration allows a delivery attempt as soon as a message | |
14455 | is received. | |
14456 | ||
9b371988 PH |
14457 | .cindex "number of deliveries" |
14458 | .cindex "delivery" "maximum number of" | |
168e428f | 14459 | If you want to control the total number of deliveries on the system, you |
9b371988 | 14460 | need to set the &%queue_only%& option. This ensures that all incoming messages |
168e428f PH |
14461 | are added to the queue without starting a delivery process. Then set up an Exim |
14462 | daemon to start queue runner processes at appropriate intervals (probably | |
14463 | fairly often, for example, every minute), and limit the total number of queue | |
9b371988 | 14464 | runners by setting the &%queue_run_max%& parameter. Because each queue runner |
168e428f | 14465 | delivers only one message at a time, the maximum number of deliveries that can |
9b371988 PH |
14466 | then take place at once is &%queue_run_max%& multiplied by |
14467 | &%remote_max_parallel%&. | |
168e428f PH |
14468 | |
14469 | If it is purely remote deliveries you want to control, use | |
9b371988 | 14470 | &%queue_smtp_domains%& instead of &%queue_only%&. This has the added benefit of |
f89d2485 | 14471 | doing the SMTP routing before queueing, so that several messages for the same |
168e428f PH |
14472 | host will eventually get delivered down the same connection. |
14473 | ||
14474 | ||
9b371988 PH |
14475 | .option remote_sort_domains main "domain list&!!" unset |
14476 | .cindex "sorting remote deliveries" | |
14477 | .cindex "delivery" "sorting remote" | |
168e428f PH |
14478 | When there are a number of remote deliveries for a message, they are sorted by |
14479 | domain into the order given by this list. For example, | |
9b371988 PH |
14480 | .code |
14481 | remote_sort_domains = *.cam.ac.uk:*.uk | |
14482 | .endd | |
14483 | would attempt to deliver to all addresses in the &'cam.ac.uk'& domain first, | |
14484 | then to those in the &%uk%& domain, then to any others. | |
168e428f | 14485 | |
168e428f | 14486 | |
9b371988 PH |
14487 | .option retry_data_expire main time 7d |
14488 | .cindex "hints database" "data expiry" | |
14489 | This option sets a &"use before"& time on retry information in Exim's hints | |
168e428f PH |
14490 | database. Any older retry data is ignored. This means that, for example, once a |
14491 | host has not been tried for 7 days, Exim behaves as if it has no knowledge of | |
14492 | past failures. | |
14493 | ||
14494 | ||
9b371988 PH |
14495 | .option retry_interval_max main time 24h |
14496 | .cindex "retry" "limit on interval" | |
14497 | .cindex "limit" "on retry interval" | |
14498 | Chapter &<<CHAPretry>>& describes Exim's mechanisms for controlling the | |
14499 | intervals between delivery attempts for messages that cannot be delivered | |
14500 | straight away. This option sets an overall limit to the length of time between | |
4f578862 PH |
14501 | retries. It cannot be set greater than 24 hours; any attempt to do so forces |
14502 | the default value. | |
168e428f PH |
14503 | |
14504 | ||
9b371988 PH |
14505 | .option return_path_remove main boolean true |
14506 | .cindex "&'Return-path:'& header line" "removing" | |
14507 | RFC 2821, section 4.4, states that an SMTP server must insert a | |
14508 | &'Return-path:'& header line into a message when it makes a &"final delivery"&. | |
14509 | The &'Return-path:'& header preserves the sender address as received in the | |
14510 | MAIL command. This description implies that this header should not be present | |
14511 | in an incoming message. If &%return_path_remove%& is true, any existing | |
14512 | &'Return-path:'& headers are removed from messages at the time they are | |
14513 | received. Exim's transports have options for adding &'Return-path:'& headers at | |
14514 | the time of delivery. They are normally used only for final local deliveries. | |
168e428f | 14515 | |
168e428f | 14516 | |
9b371988 PH |
14517 | .option return_size_limit main integer 100K |
14518 | This option is an obsolete synonym for &%bounce_return_size_limit%&. | |
168e428f | 14519 | |
168e428f | 14520 | |
9b371988 PH |
14521 | .option rfc1413_hosts main "host list&!!" * |
14522 | .cindex "RFC 1413" | |
14523 | .cindex "host" "for RFC 1413 calls" | |
168e428f PH |
14524 | RFC 1413 identification calls are made to any client host which matches an item |
14525 | in the list. | |
14526 | ||
4f578862 | 14527 | .option rfc1413_query_timeout main time 5s |
9b371988 PH |
14528 | .cindex "RFC 1413" "query timeout" |
14529 | .cindex "timeout" "for RFC 1413 call" | |
168e428f PH |
14530 | This sets the timeout on RFC 1413 identification calls. If it is set to zero, |
14531 | no RFC 1413 calls are ever made. | |
14532 | ||
14533 | ||
9b371988 PH |
14534 | .option sender_unqualified_hosts main "host list&!!" unset |
14535 | .cindex "unqualified addresses" | |
14536 | .cindex "host" "unqualified addresses from" | |
168e428f PH |
14537 | This option lists those hosts from which Exim is prepared to accept unqualified |
14538 | sender addresses. The addresses are made fully qualified by the addition of | |
9b371988 PH |
14539 | &%qualify_domain%&. This option also affects message header lines. Exim does |
14540 | not reject unqualified addresses in headers that contain sender addresses, but | |
14541 | it qualifies them only if the message came from a host that matches | |
14542 | &%sender_unqualified_hosts%&, or if the message was submitted locally (not | |
14543 | using TCP/IP), and the &%-bnq%& option was not set. | |
168e428f PH |
14544 | |
14545 | ||
9b371988 PH |
14546 | .option smtp_accept_keepalive main boolean true |
14547 | .cindex "keepalive" "on incoming connection" | |
168e428f PH |
14548 | This option controls the setting of the SO_KEEPALIVE option on incoming |
14549 | TCP/IP socket connections. When set, it causes the kernel to probe idle | |
9b371988 | 14550 | connections periodically, by sending packets with &"old"& sequence numbers. The |
f89d2485 | 14551 | other end of the connection should send an acknowledgment if the connection is |
168e428f PH |
14552 | still okay or a reset if the connection has been aborted. The reason for doing |
14553 | this is that it has the beneficial effect of freeing up certain types of | |
14554 | connection that can get stuck when the remote host is disconnected without | |
14555 | tidying up the TCP/IP call properly. The keepalive mechanism takes several | |
14556 | hours to detect unreachable hosts. | |
14557 | ||
14558 | ||
14559 | ||
9b371988 PH |
14560 | .option smtp_accept_max main integer 20 |
14561 | .cindex "limit" "incoming SMTP connections" | |
14562 | .cindex "SMTP" "incoming connection count" | |
14563 | .cindex "inetd" | |
168e428f PH |
14564 | This option specifies the maximum number of simultaneous incoming SMTP calls |
14565 | that Exim will accept. It applies only to the listening daemon; there is no | |
9b371988 PH |
14566 | control (in Exim) when incoming SMTP is being handled by &'inetd'&. If the |
14567 | value is set to zero, no limit is applied. However, it is required to be | |
14568 | non-zero if either &%smtp_accept_max_per_host%& or &%smtp_accept_queue%& is | |
f89d2485 | 14569 | set. See also &%smtp_accept_reserve%& and &%smtp_load_reserve%&. |
168e428f | 14570 | |
f89d2485 PH |
14571 | A new SMTP connection is immediately rejected if the &%smtp_accept_max%& limit |
14572 | has been reached. If not, Exim first checks &%smtp_accept_max_per_host%&. If | |
14573 | that limit has not been reached for the client host, &%smtp_accept_reserve%& | |
14574 | and &%smtp_load_reserve%& are then checked before accepting the connection. | |
168e428f | 14575 | |
168e428f | 14576 | |
9b371988 PH |
14577 | .option smtp_accept_max_nonmail main integer 10 |
14578 | .cindex "limit" "non-mail SMTP commands" | |
14579 | .cindex "SMTP" "limiting non-mail commands" | |
14580 | Exim counts the number of &"non-mail"& commands in an SMTP session, and drops | |
14581 | the connection if there are too many. This option defines &"too many"&. The | |
14582 | check catches some denial-of-service attacks, repeated failing AUTHs, or a mad | |
168e428f | 14583 | client looping sending EHLO, for example. The check is applied only if the |
9b371988 | 14584 | client host matches &%smtp_accept_max_nonmail_hosts%&. |
168e428f PH |
14585 | |
14586 | When a new message is expected, one occurrence of RSET is not counted. This | |
14587 | allows a client to send one RSET between messages (this is not necessary, | |
f89d2485 | 14588 | but some clients do it). Exim also allows one uncounted occurrence of HELO |
168e428f PH |
14589 | or EHLO, and one occurrence of STARTTLS between messages. After |
14590 | starting up a TLS session, another EHLO is expected, and so it too is not | |
14591 | counted. The first occurrence of AUTH in a connection, or immediately | |
14592 | following STARTTLS is not counted. Otherwise, all commands other than | |
14593 | MAIL, RCPT, DATA, and QUIT are counted. | |
14594 | ||
14595 | ||
9b371988 PH |
14596 | .option smtp_accept_max_nonmail_hosts main "host list&!!" * |
14597 | You can control which hosts are subject to the &%smtp_accept_max_nonmail%& | |
168e428f PH |
14598 | check by setting this option. The default value makes it apply to all hosts. By |
14599 | changing the value, you can exclude any badly-behaved hosts that you have to | |
14600 | live with. | |
14601 | ||
14602 | ||
0a4e3112 PH |
14603 | . Allow this long option name to split; give it unsplit as a fifth argument |
14604 | . for the automatic .oindex that is generated by .option. | |
168e428f | 14605 | |
0a4e3112 PH |
14606 | .option "smtp_accept_max_per_ &~&~connection" main integer 1000 &&& |
14607 | smtp_accept_max_per_connection | |
f89d2485 | 14608 | .cindex "SMTP" "limiting incoming message count" |
9b371988 | 14609 | .cindex "limit" "messages per SMTP connection" |
168e428f PH |
14610 | The value of this option limits the number of MAIL commands that Exim is |
14611 | prepared to accept over a single SMTP connection, whether or not each command | |
14612 | results in the transfer of a message. After the limit is reached, a 421 | |
14613 | response is given to subsequent MAIL commands. This limit is a safety | |
14614 | precaution against a client that goes mad (incidents of this type have been | |
14615 | seen). | |
14616 | ||
14617 | ||
9b371988 PH |
14618 | .option smtp_accept_max_per_host main string&!! unset |
14619 | .cindex "limit" "SMTP connections from one host" | |
14620 | .cindex "host" "limiting SMTP connections from" | |
168e428f PH |
14621 | This option restricts the number of simultaneous IP connections from a single |
14622 | host (strictly, from a single IP address) to the Exim daemon. The option is | |
14623 | expanded, to enable different limits to be applied to different hosts by | |
9b371988 | 14624 | reference to &$sender_host_address$&. Once the limit is reached, additional |
f89d2485 PH |
14625 | connection attempts from the same host are rejected with error code 421. This |
14626 | is entirely independent of &%smtp_accept_reserve%&. The option's default value | |
14627 | of zero imposes no limit. If this option is set greater than zero, it is | |
14628 | required that &%smtp_accept_max%& be non-zero. | |
168e428f | 14629 | |
9b371988 | 14630 | &*Warning*&: When setting this option you should not use any expansion |
168e428f PH |
14631 | constructions that take an appreciable amount of time. The expansion and test |
14632 | happen in the main daemon loop, in order to reject additional connections | |
14633 | without forking additional processes (otherwise a denial-of-service attack | |
14634 | could cause a vast number or processes to be created). While the daemon is | |
14635 | doing this processing, it cannot accept any other incoming connections. | |
14636 | ||
14637 | ||
14638 | ||
9b371988 PH |
14639 | .option smtp_accept_queue main integer 0 |
14640 | .cindex "SMTP" "incoming connection count" | |
14641 | .cindex "queueing incoming messages" | |
14642 | .cindex "message" "queueing by SMTP connection count" | |
595028e4 PH |
14643 | If the number of simultaneous incoming SMTP connections being handled via the |
14644 | listening daemon exceeds this value, messages received by SMTP are just placed | |
14645 | on the queue; no delivery processes are started automatically. The count is | |
14646 | fixed at the start of an SMTP connection. It cannot be updated in the | |
14647 | subprocess that receives messages, and so the queueing or not queueing applies | |
14648 | to all messages received in the same connection. | |
595028e4 PH |
14649 | |
14650 | A value of zero implies no limit, and clearly any non-zero value is useful only | |
14651 | if it is less than the &%smtp_accept_max%& value (unless that is zero). See | |
14652 | also &%queue_only%&, &%queue_only_load%&, &%queue_smtp_domains%&, and the | |
14653 | various &%-od%&&'x'& command line options. | |
168e428f | 14654 | |
168e428f | 14655 | |
0a4e3112 PH |
14656 | . Allow this long option name to split; give it unsplit as a fifth argument |
14657 | . for the automatic .oindex that is generated by .option. | |
f89d2485 | 14658 | |
0a4e3112 PH |
14659 | .option "smtp_accept_queue_per_ &~&~connection" main integer 10 &&& |
14660 | smtp_accept_queue_per_connection | |
9b371988 PH |
14661 | .cindex "queueing incoming messages" |
14662 | .cindex "message" "queueing by message count" | |
168e428f PH |
14663 | This option limits the number of delivery processes that Exim starts |
14664 | automatically when receiving messages via SMTP, whether via the daemon or by | |
9b371988 | 14665 | the use of &%-bs%& or &%-bS%&. If the value of the option is greater than zero, |
168e428f PH |
14666 | and the number of messages received in a single SMTP session exceeds this |
14667 | number, subsequent messages are placed on the queue, but no delivery processes | |
14668 | are started. This helps to limit the number of Exim processes when a server | |
14669 | restarts after downtime and there is a lot of mail waiting for it on other | |
14670 | systems. On large systems, the default should probably be increased, and on | |
14671 | dial-in client systems it should probably be set to zero (that is, disabled). | |
14672 | ||
14673 | ||
9b371988 PH |
14674 | .option smtp_accept_reserve main integer 0 |
14675 | .cindex "SMTP" "incoming call count" | |
14676 | .cindex "host" "reserved" | |
14677 | When &%smtp_accept_max%& is set greater than zero, this option specifies a | |
168e428f | 14678 | number of SMTP connections that are reserved for connections from the hosts |
9b371988 PH |
14679 | that are specified in &%smtp_reserve_hosts%&. The value set in |
14680 | &%smtp_accept_max%& includes this reserve pool. The specified hosts are not | |
168e428f | 14681 | restricted to this number of connections; the option specifies a minimum number |
f89d2485 | 14682 | of connection slots for them, not a maximum. It is a guarantee that this group |
595028e4 PH |
14683 | of hosts can always get at least &%smtp_accept_reserve%& connections. However, |
14684 | the limit specified by &%smtp_accept_max_per_host%& is still applied to each | |
14685 | individual host. | |
168e428f | 14686 | |
9b371988 | 14687 | For example, if &%smtp_accept_max%& is set to 50 and &%smtp_accept_reserve%& is |
168e428f | 14688 | set to 5, once there are 45 active connections (from any hosts), new |
f89d2485 | 14689 | connections are accepted only from hosts listed in &%smtp_reserve_hosts%&, |
595028e4 | 14690 | provided the other criteria for acceptance are met. |
168e428f PH |
14691 | |
14692 | ||
9b371988 PH |
14693 | .option smtp_active_hostname main string&!! unset |
14694 | .cindex "host" "name in SMTP responses" | |
14695 | .cindex "SMTP" "host name in responses" | |
f89d2485 | 14696 | .vindex "&$primary_hostname$&" |
168e428f | 14697 | This option is provided for multi-homed servers that want to masquerade as |
3cb1b51e PH |
14698 | several different hosts. At the start of an incoming SMTP connection, its value |
14699 | is expanded and used instead of the value of &$primary_hostname$& in SMTP | |
168e428f PH |
14700 | responses. For example, it is used as domain name in the response to an |
14701 | incoming HELO or EHLO command. | |
14702 | ||
f89d2485 | 14703 | .vindex "&$smtp_active_hostname$&" |
3cb1b51e PH |
14704 | The active hostname is placed in the &$smtp_active_hostname$& variable, which |
14705 | is saved with any messages that are received. It is therefore available for use | |
14706 | in routers and transports when the message is later delivered. | |
168e428f PH |
14707 | |
14708 | If this option is unset, or if its expansion is forced to fail, or if the | |
9b371988 | 14709 | expansion results in an empty string, the value of &$primary_hostname$& is |
168e428f PH |
14710 | used. Other expansion failures cause a message to be written to the main and |
14711 | panic logs, and the SMTP command receives a temporary error. Typically, the | |
9b371988 | 14712 | value of &%smtp_active_hostname%& depends on the incoming interface address. |
168e428f | 14713 | For example: |
9b371988 | 14714 | .code |
3cb1b51e | 14715 | smtp_active_hostname = ${if eq{$received_ip_address}{10.0.0.1}\ |
168e428f | 14716 | {cox.mydomain}{box.mydomain}} |
9b371988 | 14717 | .endd |
168e428f | 14718 | |
3cb1b51e PH |
14719 | Although &$smtp_active_hostname$& is primarily concerned with incoming |
14720 | messages, it is also used as the default for HELO commands in callout | |
14721 | verification if there is no remote transport from which to obtain a | |
14722 | &%helo_data%& value. | |
3cb1b51e | 14723 | |
9b371988 PH |
14724 | .option smtp_banner main string&!! "see below" |
14725 | .cindex "SMTP" "welcome banner" | |
14726 | .cindex "banner for SMTP" | |
14727 | .cindex "welcome banner for SMTP" | |
14728 | .cindex "customizing" "SMTP banner" | |
168e428f PH |
14729 | This string, which is expanded every time it is used, is output as the initial |
14730 | positive response to an SMTP connection. The default setting is: | |
9b371988 | 14731 | .code |
168e428f PH |
14732 | smtp_banner = $smtp_active_hostname ESMTP Exim \ |
14733 | $version_number $tod_full | |
9b371988 | 14734 | .endd |
168e428f | 14735 | Failure to expand the string causes a panic error. If you want to create a |
9b371988 | 14736 | multiline response to the initial SMTP connection, use &"\n"& in the string at |
168e428f PH |
14737 | appropriate points, but not at the end. Note that the 220 code is not included |
14738 | in this string. Exim adds it automatically (several times in the case of a | |
14739 | multiline response). | |
14740 | ||
14741 | ||
9b371988 PH |
14742 | .option smtp_check_spool_space main boolean true |
14743 | .cindex "checking disk space" | |
f89d2485 | 14744 | .cindex "disk space, checking" |
9b371988 | 14745 | .cindex "spool directory" "checking space" |
168e428f PH |
14746 | When this option is set, if an incoming SMTP session encounters the SIZE |
14747 | option on a MAIL command, it checks that there is enough space in the | |
14748 | spool directory's partition to accept a message of that size, while still | |
9b371988 | 14749 | leaving free the amount specified by &%check_spool_space%& (even if that value |
168e428f PH |
14750 | is zero). If there isn't enough space, a temporary error code is returned. |
14751 | ||
14752 | ||
9b371988 PH |
14753 | .option smtp_connect_backlog main integer 20 |
14754 | .cindex "connection backlog" | |
14755 | .cindex "SMTP" "connection backlog" | |
14756 | .cindex "backlog of connections" | |
168e428f PH |
14757 | This option specifies a maximum number of waiting SMTP connections. Exim passes |
14758 | this value to the TCP/IP system when it sets up its listener. Once this number | |
14759 | of connections are waiting for the daemon's attention, subsequent connection | |
14760 | attempts are refused at the TCP/IP level. At least, that is what the manuals | |
14761 | say; in some circumstances such connection attempts have been observed to time | |
14762 | out instead. For large systems it is probably a good idea to increase the | |
14763 | value (to 50, say). It also gives some protection against denial-of-service | |
14764 | attacks by SYN flooding. | |
14765 | ||
14766 | ||
9b371988 PH |
14767 | .option smtp_enforce_sync main boolean true |
14768 | .cindex "SMTP" "synchronization checking" | |
14769 | .cindex "synchronization checking in SMTP" | |
168e428f PH |
14770 | The SMTP protocol specification requires the client to wait for a response from |
14771 | the server at certain points in the dialogue. Without PIPELINING these | |
14772 | synchronization points are after every command; with PIPELINING they are | |
14773 | fewer, but they still exist. | |
14774 | ||
14775 | Some spamming sites send out a complete set of SMTP commands without waiting | |
14776 | for any response. Exim protects against this by rejecting a message if the | |
9b371988 PH |
14777 | client has sent further input when it should not have. The error response &"554 |
14778 | SMTP synchronization error"& is sent, and the connection is dropped. Testing | |
14779 | for this error cannot be perfect because of transmission delays (unexpected | |
14780 | input may be on its way but not yet received when Exim checks). However, it | |
14781 | does detect many instances. | |
168e428f | 14782 | |
9b371988 | 14783 | The check can be globally disabled by setting &%smtp_enforce_sync%& false. |
168e428f | 14784 | If you want to disable the check selectively (for example, only for certain |
9b371988 PH |
14785 | hosts), you can do so by an appropriate use of a &%control%& modifier in an ACL |
14786 | (see section &<<SECTcontrols>>&). See also &%pipelining_advertise_hosts%&. | |
168e428f PH |
14787 | |
14788 | ||
14789 | ||
9b371988 PH |
14790 | .option smtp_etrn_command main string&!! unset |
14791 | .cindex "ETRN" "command to be run" | |
f89d2485 | 14792 | .vindex "&$domain$&" |
168e428f PH |
14793 | If this option is set, the given command is run whenever an SMTP ETRN |
14794 | command is received from a host that is permitted to issue such commands (see | |
9b371988 PH |
14795 | chapter &<<CHAPACL>>&). The string is split up into separate arguments which |
14796 | are independently expanded. The expansion variable &$domain$& is set to the | |
168e428f PH |
14797 | argument of the ETRN command, and no syntax checking is done on it. For |
14798 | example: | |
9b371988 PH |
14799 | .code |
14800 | smtp_etrn_command = /etc/etrn_command $domain \ | |
14801 | $sender_host_address | |
14802 | .endd | |
168e428f PH |
14803 | A new process is created to run the command, but Exim does not wait for it to |
14804 | complete. Consequently, its status cannot be checked. If the command cannot be | |
14805 | run, a line is written to the panic log, but the ETRN caller still receives | |
14806 | a 250 success response. Exim is normally running under its own uid when | |
14807 | receiving SMTP, so it is not possible for it to change the uid before running | |
14808 | the command. | |
14809 | ||
14810 | ||
9b371988 PH |
14811 | .option smtp_etrn_serialize main boolean true |
14812 | .cindex "ETRN" "serializing" | |
168e428f PH |
14813 | When this option is set, it prevents the simultaneous execution of more than |
14814 | one identical command as a result of ETRN in an SMTP connection. See | |
9b371988 | 14815 | section &<<SECTETRN>>& for details. |
168e428f | 14816 | |
168e428f | 14817 | |
9b371988 PH |
14818 | .option smtp_load_reserve main fixed-point unset |
14819 | .cindex "load average" | |
168e428f | 14820 | If the system load average ever gets higher than this, incoming SMTP calls are |
9b371988 PH |
14821 | accepted only from those hosts that match an entry in &%smtp_reserve_hosts%&. |
14822 | If &%smtp_reserve_hosts%& is not set, no incoming SMTP calls are accepted when | |
168e428f PH |
14823 | the load is over the limit. The option has no effect on ancient operating |
14824 | systems on which Exim cannot determine the load average. See also | |
9b371988 | 14825 | &%deliver_queue_load_max%& and &%queue_only_load%&. |
168e428f PH |
14826 | |
14827 | ||
14828 | ||
9b371988 PH |
14829 | .option smtp_max_synprot_errors main integer 3 |
14830 | .cindex "SMTP" "limiting syntax and protocol errors" | |
14831 | .cindex "limit" "SMTP syntax and protocol errors" | |
168e428f PH |
14832 | Exim rejects SMTP commands that contain syntax or protocol errors. In |
14833 | particular, a syntactically invalid email address, as in this command: | |
9b371988 PH |
14834 | .code |
14835 | RCPT TO:<abc xyz@a.b.c> | |
14836 | .endd | |
168e428f PH |
14837 | causes immediate rejection of the command, before any other tests are done. |
14838 | (The ACL cannot be run if there is no valid address to set up for it.) An | |
14839 | example of a protocol error is receiving RCPT before MAIL. If there are | |
14840 | too many syntax or protocol errors in one SMTP session, the connection is | |
14841 | dropped. The limit is set by this option. | |
14842 | ||
9b371988 | 14843 | .cindex "PIPELINING" "expected errors" |
168e428f | 14844 | When the PIPELINING extension to SMTP is in use, some protocol errors are |
9b371988 | 14845 | &"expected"&, for instance, a RCPT command after a rejected MAIL command. |
168e428f | 14846 | Exim assumes that PIPELINING will be used if it advertises it (see |
9b371988 | 14847 | &%pipelining_advertise_hosts%&), and in this situation, &"expected"& errors do |
168e428f PH |
14848 | not count towards the limit. |
14849 | ||
14850 | ||
14851 | ||
9b371988 PH |
14852 | .option smtp_max_unknown_commands main integer 3 |
14853 | .cindex "SMTP" "limiting unknown commands" | |
14854 | .cindex "limit" "unknown SMTP commands" | |
168e428f PH |
14855 | If there are too many unrecognized commands in an incoming SMTP session, an |
14856 | Exim server drops the connection. This is a defence against some kinds of abuse | |
14857 | that subvert web | |
14858 | clients | |
14859 | into making connections to SMTP ports; in these circumstances, a number of | |
14860 | non-SMTP command lines are sent first. | |
14861 | ||
14862 | ||
14863 | ||
9b371988 PH |
14864 | .option smtp_ratelimit_hosts main "host list&!!" unset |
14865 | .cindex "SMTP" "rate limiting" | |
14866 | .cindex "limit" "rate of message arrival" | |
14867 | .cindex "RCPT" "rate limiting" | |
168e428f PH |
14868 | Some sites find it helpful to be able to limit the rate at which certain hosts |
14869 | can send them messages, and the rate at which an individual message can specify | |
9b371988 PH |
14870 | recipients. |
14871 | ||
9b371988 PH |
14872 | Exim has two rate-limiting facilities. This section describes the older |
14873 | facility, which can limit rates within a single connection. The newer | |
14874 | &%ratelimit%& ACL condition can limit rates across all connections. See section | |
14875 | &<<SECTratelimiting>>& for details of the newer facility. | |
9b371988 PH |
14876 | |
14877 | When a host matches &%smtp_ratelimit_hosts%&, the values of | |
14878 | &%smtp_ratelimit_mail%& and &%smtp_ratelimit_rcpt%& are used to control the | |
168e428f PH |
14879 | rate of acceptance of MAIL and RCPT commands in a single SMTP session, |
14880 | respectively. Each option, if set, must contain a set of four comma-separated | |
14881 | values: | |
14882 | ||
9b371988 PH |
14883 | .ilist |
14884 | A threshold, before which there is no rate limiting. | |
14885 | .next | |
14886 | An initial time delay. Unlike other times in Exim, numbers with decimal | |
168e428f | 14887 | fractional parts are allowed here. |
9b371988 PH |
14888 | .next |
14889 | A factor by which to increase the delay each time. | |
14890 | .next | |
14891 | A maximum value for the delay. This should normally be less than 5 minutes, | |
168e428f | 14892 | because after that time, the client is liable to timeout the SMTP command. |
9b371988 | 14893 | .endlist |
168e428f PH |
14894 | |
14895 | For example, these settings have been used successfully at the site which | |
14896 | first suggested this feature, for controlling mail from their customers: | |
9b371988 PH |
14897 | .code |
14898 | smtp_ratelimit_mail = 2,0.5s,1.05,4m | |
14899 | smtp_ratelimit_rcpt = 4,0.25s,1.015,4m | |
14900 | .endd | |
168e428f PH |
14901 | The first setting specifies delays that are applied to MAIL commands after |
14902 | two have been received over a single connection. The initial delay is 0.5 | |
14903 | seconds, increasing by a factor of 1.05 each time. The second setting applies | |
14904 | delays to RCPT commands when more than four occur in a single message. | |
14905 | ||
168e428f | 14906 | |
9b371988 PH |
14907 | .option smtp_ratelimit_mail main string unset |
14908 | See &%smtp_ratelimit_hosts%& above. | |
168e428f PH |
14909 | |
14910 | ||
9b371988 PH |
14911 | .option smtp_ratelimit_rcpt main string unset |
14912 | See &%smtp_ratelimit_hosts%& above. | |
168e428f | 14913 | |
168e428f | 14914 | |
9b371988 PH |
14915 | .option smtp_receive_timeout main time 5m |
14916 | .cindex "timeout" "for SMTP input" | |
f89d2485 | 14917 | .cindex "SMTP" "input timeout" |
168e428f PH |
14918 | This sets a timeout value for SMTP reception. It applies to all forms of SMTP |
14919 | input, including batch SMTP. If a line of input (either an SMTP command or a | |
14920 | data line) is not received within this time, the SMTP connection is dropped and | |
14921 | the message is abandoned. | |
14922 | A line is written to the log containing one of the following messages: | |
9b371988 PH |
14923 | .code |
14924 | SMTP command timeout on connection from... | |
14925 | SMTP data timeout on connection from... | |
14926 | .endd | |
168e428f PH |
14927 | The former means that Exim was expecting to read an SMTP command; the latter |
14928 | means that it was in the DATA phase, reading the contents of a message. | |
14929 | ||
14930 | ||
f89d2485 | 14931 | .oindex "&%-os%&" |
168e428f | 14932 | The value set by this option can be overridden by the |
9b371988 | 14933 | &%-os%& command-line option. A setting of zero time disables the timeout, but |
168e428f | 14934 | this should never be used for SMTP over TCP/IP. (It can be useful in some cases |
9b371988 PH |
14935 | of local input using &%-bs%& or &%-bS%&.) For non-SMTP input, the reception |
14936 | timeout is controlled by &%receive_timeout%& and &%-or%&. | |
168e428f | 14937 | |
168e428f | 14938 | |
9b371988 | 14939 | .option smtp_reserve_hosts main "host list&!!" unset |
168e428f | 14940 | This option defines hosts for which SMTP connections are reserved; see |
9b371988 | 14941 | &%smtp_accept_reserve%& and &%smtp_load_reserve%& above. |
168e428f PH |
14942 | |
14943 | ||
9b371988 PH |
14944 | .option smtp_return_error_details main boolean false |
14945 | .cindex "SMTP" "details policy failures" | |
f89d2485 | 14946 | .cindex "policy control" "rejection, returning details" |
168e428f | 14947 | In the default state, Exim uses bland messages such as |
9b371988 | 14948 | &"Administrative prohibition"& when it rejects SMTP commands for policy |
168e428f | 14949 | reasons. Many sysadmins like this because it gives away little information |
f89d2485 | 14950 | to spammers. However, some other sysadmins who are applying strict checking |
168e428f | 14951 | policies want to give out much fuller information about failures. Setting |
9b371988 PH |
14952 | &%smtp_return_error_details%& true causes Exim to be more forthcoming. For |
14953 | example, instead of &"Administrative prohibition"&, it might give: | |
14954 | .code | |
14955 | 550-Rejected after DATA: '>' missing at end of address: | |
14956 | 550 failing address in "From" header is: <user@dom.ain | |
14957 | .endd | |
14958 | ||
14959 | .option spamd_address main string "see below" | |
168e428f | 14960 | This option is available when Exim is compiled with the content-scanning |
9b371988 PH |
14961 | extension. It specifies how Exim connects to SpamAssassin's &%spamd%& daemon. |
14962 | The default value is | |
14963 | .code | |
14964 | 127.0.0.1 783 | |
14965 | .endd | |
14966 | See section &<<SECTscanspamass>>& for more details. | |
168e428f PH |
14967 | |
14968 | ||
14969 | ||
9b371988 PH |
14970 | .option split_spool_directory main boolean false |
14971 | .cindex "multiple spool directories" | |
14972 | .cindex "spool directory" "split" | |
f89d2485 | 14973 | .cindex "directories, multiple" |
168e428f PH |
14974 | If this option is set, it causes Exim to split its input directory into 62 |
14975 | subdirectories, each with a single alphanumeric character as its name. The | |
14976 | sixth character of the message id is used to allocate messages to | |
14977 | subdirectories; this is the least significant base-62 digit of the time of | |
14978 | arrival of the message. | |
14979 | ||
14980 | Splitting up the spool in this way may provide better performance on systems | |
14981 | where there are long mail queues, by reducing the number of files in any one | |
14982 | directory. The msglog directory is also split up in a similar way to the input | |
9b371988 PH |
14983 | directory; however, if &%preserve_message_logs%& is set, all old msglog files |
14984 | are still placed in the single directory &_msglog.OLD_&. | |
168e428f PH |
14985 | |
14986 | It is not necessary to take any special action for existing messages when | |
9b371988 PH |
14987 | changing &%split_spool_directory%&. Exim notices messages that are in the |
14988 | &"wrong"& place, and continues to process them. If the option is turned off | |
14989 | after a period of being on, the subdirectories will eventually empty and be | |
168e428f PH |
14990 | automatically deleted. |
14991 | ||
9b371988 | 14992 | When &%split_spool_directory%& is set, the behaviour of queue runner processes |
168e428f PH |
14993 | changes. Instead of creating a list of all messages in the queue, and then |
14994 | trying to deliver each one in turn, it constructs a list of those in one | |
14995 | sub-directory and tries to deliver them, before moving on to the next | |
14996 | sub-directory. The sub-directories are processed in a random order. This | |
14997 | spreads out the scanning of the input directories, and uses less memory. It is | |
14998 | particularly beneficial when there are lots of messages on the queue. However, | |
9b371988 | 14999 | if &%queue_run_in_order%& is set, none of this new processing happens. The |
168e428f PH |
15000 | entire queue has to be scanned and sorted before any deliveries can start. |
15001 | ||
15002 | ||
9b371988 PH |
15003 | .option spool_directory main string&!! "set at compile time" |
15004 | .cindex "spool directory" "path to" | |
168e428f PH |
15005 | This defines the directory in which Exim keeps its spool, that is, the messages |
15006 | it is waiting to deliver. The default value is taken from the compile-time | |
15007 | configuration setting, if there is one. If not, this option must be set. The | |
15008 | string is expanded, so it can contain, for example, a reference to | |
9b371988 | 15009 | &$primary_hostname$&. |
168e428f PH |
15010 | |
15011 | If the spool directory name is fixed on your installation, it is recommended | |
15012 | that you set it at build time rather than from this option, particularly if the | |
9b371988 | 15013 | log files are being written to the spool directory (see &%log_file_path%&). |
168e428f PH |
15014 | Otherwise log files cannot be used for errors that are detected early on, such |
15015 | as failures in the configuration file. | |
15016 | ||
15017 | By using this option to override the compiled-in path, it is possible to run | |
15018 | tests of Exim without using the standard spool. | |
15019 | ||
9b371988 | 15020 | .option sqlite_lock_timeout main time 5s |
f89d2485 | 15021 | .cindex "sqlite lookup type" "lock timeout" |
9b371988 PH |
15022 | This option controls the timeout that the &(sqlite)& lookup uses when trying to |
15023 | access an SQLite database. See section &<<SECTsqlite>>& for more details. | |
9b371988 | 15024 | |
3cb1b51e | 15025 | .option strict_acl_vars main boolean false |
f89d2485 | 15026 | .cindex "&ACL;" "variables, handling unset" |
3cb1b51e PH |
15027 | This option controls what happens if a syntactically valid but undefined ACL |
15028 | variable is referenced. If it is false (the default), an empty string | |
15029 | is substituted; if it is true, an error is generated. See section | |
15030 | &<<SECTaclvariables>>& for details of ACL variables. | |
3cb1b51e | 15031 | |
9b371988 | 15032 | .option strip_excess_angle_brackets main boolean false |
f89d2485 | 15033 | .cindex "angle brackets, excess" |
9b371988 PH |
15034 | If this option is set, redundant pairs of angle brackets round &"route-addr"& |
15035 | items in addresses are stripped. For example, &'<<xxx@a.b.c.d>>'& is | |
15036 | treated as &'<xxx@a.b.c.d>'&. If this is in the envelope and the message is | |
15037 | passed on to another MTA, the excess angle brackets are not passed on. If this | |
15038 | option is not set, multiple pairs of angle brackets cause a syntax error. | |
15039 | ||
15040 | ||
15041 | .option strip_trailing_dot main boolean false | |
15042 | .cindex "trailing dot on domain" | |
15043 | .cindex "dot" "trailing on domain" | |
168e428f PH |
15044 | If this option is set, a trailing dot at the end of a domain in an address is |
15045 | ignored. If this is in the envelope and the message is passed on to another | |
15046 | MTA, the dot is not passed on. If this option is not set, a dot at the end of a | |
15047 | domain causes a syntax error. | |
15048 | However, addresses in header lines are checked only when an ACL requests header | |
15049 | syntax checking. | |
15050 | ||
15051 | ||
9b371988 PH |
15052 | .option syslog_duplication main boolean true |
15053 | .cindex "syslog" "duplicate log lines; suppressing" | |
168e428f PH |
15054 | When Exim is logging to syslog, it writes the log lines for its three |
15055 | separate logs at different syslog priorities so that they can in principle | |
15056 | be separated on the logging hosts. Some installations do not require this | |
15057 | separation, and in those cases, the duplication of certain log lines is a | |
9b371988 | 15058 | nuisance. If &%syslog_duplication%& is set false, only one copy of any |
168e428f PH |
15059 | particular log line is written to syslog. For lines that normally go to |
15060 | both the main log and the reject log, the reject log version (possibly | |
15061 | containing message header lines) is written, at LOG_NOTICE priority. | |
15062 | Lines that normally go to both the main and the panic log are written at | |
15063 | the LOG_ALERT priority. | |
15064 | ||
15065 | ||
9b371988 PH |
15066 | .option syslog_facility main string unset |
15067 | .cindex "syslog" "facility; setting" | |
15068 | This option sets the syslog &"facility"& name, used when Exim is logging to | |
15069 | syslog. The value must be one of the strings &"mail"&, &"user"&, &"news"&, | |
15070 | &"uucp"&, &"daemon"&, or &"local&'x'&"& where &'x'& is a digit between 0 and 7. | |
15071 | If this option is unset, &"mail"& is used. See chapter &<<CHAPlog>>& for | |
15072 | details of Exim's logging. | |
168e428f | 15073 | |
168e428f | 15074 | |
168e428f | 15075 | |
9b371988 PH |
15076 | .option syslog_processname main string &`exim`& |
15077 | .cindex "syslog" "process name; setting" | |
15078 | This option sets the syslog &"ident"& name, used when Exim is logging to | |
15079 | syslog. The value must be no longer than 32 characters. See chapter | |
15080 | &<<CHAPlog>>& for details of Exim's logging. | |
168e428f PH |
15081 | |
15082 | ||
168e428f | 15083 | |
9b371988 PH |
15084 | .option syslog_timestamp main boolean true |
15085 | .cindex "syslog" "timestamps" | |
15086 | If &%syslog_timestamp%& is set false, the timestamps on Exim's log lines are | |
15087 | omitted when these lines are sent to syslog. See chapter &<<CHAPlog>>& for | |
168e428f PH |
15088 | details of Exim's logging. |
15089 | ||
15090 | ||
9b371988 PH |
15091 | .option system_filter main string&!! unset |
15092 | .cindex "filter" "system filter" | |
15093 | .cindex "system filter" "specifying" | |
15094 | .cindex "Sieve filter" "not available for system filter" | |
168e428f PH |
15095 | This option specifies an Exim filter file that is applied to all messages at |
15096 | the start of each delivery attempt, before any routing is done. System filters | |
15097 | must be Exim filters; they cannot be Sieve filters. If the system filter | |
15098 | generates any deliveries to files or pipes, or any new mail messages, the | |
9b371988 | 15099 | appropriate &%system_filter_..._transport%& option(s) must be set, to define |
168e428f | 15100 | which transports are to be used. Details of this facility are given in chapter |
9b371988 | 15101 | &<<CHAPsystemfilter>>&. |
168e428f | 15102 | |
168e428f | 15103 | |
9b371988 | 15104 | .option system_filter_directory_transport main string&!! unset |
f89d2485 | 15105 | .vindex "&$address_file$&" |
168e428f | 15106 | This sets the name of the transport driver that is to be used when the |
9b371988 | 15107 | &%save%& command in a system message filter specifies a path ending in &"/"&, |
168e428f | 15108 | implying delivery of each message into a separate file in some directory. |
9b371988 | 15109 | During the delivery, the variable &$address_file$& contains the path name. |
168e428f PH |
15110 | |
15111 | ||
9b371988 PH |
15112 | .option system_filter_file_transport main string&!! unset |
15113 | .cindex "file" "transport for system filter" | |
15114 | This sets the name of the transport driver that is to be used when the &%save%& | |
15115 | command in a system message filter specifies a path not ending in &"/"&. During | |
15116 | the delivery, the variable &$address_file$& contains the path name. | |
168e428f | 15117 | |
9b371988 PH |
15118 | .option system_filter_group main string unset |
15119 | .cindex "gid (group id)" "system filter" | |
15120 | This option is used only when &%system_filter_user%& is also set. It sets the | |
168e428f PH |
15121 | gid under which the system filter is run, overriding any gid that is associated |
15122 | with the user. The value may be numerical or symbolic. | |
15123 | ||
9b371988 PH |
15124 | .option system_filter_pipe_transport main string&!! unset |
15125 | .cindex "&(pipe)& transport" "for system filter" | |
f89d2485 | 15126 | .vindex "&$address_pipe$&" |
9b371988 PH |
15127 | This specifies the transport driver that is to be used when a &%pipe%& command |
15128 | is used in a system filter. During the delivery, the variable &$address_pipe$& | |
168e428f PH |
15129 | contains the pipe command. |
15130 | ||
15131 | ||
9b371988 PH |
15132 | .option system_filter_reply_transport main string&!! unset |
15133 | .cindex "&(autoreply)& transport" "for system filter" | |
15134 | This specifies the transport driver that is to be used when a &%mail%& command | |
15135 | is used in a system filter. | |
168e428f | 15136 | |
9b371988 PH |
15137 | .option system_filter_user main string unset |
15138 | .cindex "uid (user id)" "system filter" | |
168e428f PH |
15139 | If this option is not set, the system filter is run in the main Exim delivery |
15140 | process, as root. When the option is set, the system filter runs in a separate | |
15141 | process, as the given user. Unless the string consists entirely of digits, it | |
15142 | is looked up in the password data. Failure to find the named user causes a | |
15143 | configuration error. The gid is either taken from the password data, or | |
9b371988 PH |
15144 | specified by &%system_filter_group%&. When the uid is specified numerically, |
15145 | &%system_filter_group%& is required to be set. | |
168e428f PH |
15146 | |
15147 | If the system filter generates any pipe, file, or reply deliveries, the uid | |
15148 | under which the filter is run is used when transporting them, unless a | |
9b371988 | 15149 | transport option overrides. Normally you should set &%system_filter_user%& if |
168e428f PH |
15150 | your system filter generates these kinds of delivery. |
15151 | ||
15152 | ||
9b371988 PH |
15153 | .option tcp_nodelay main boolean true |
15154 | .cindex "daemon" "TCP_NODELAY on sockets" | |
15155 | .cindex "Nagle algorithm" | |
15156 | .cindex "TCP_NODELAY on listening sockets" | |
168e428f PH |
15157 | If this option is set false, it stops the Exim daemon setting the |
15158 | TCP_NODELAY option on its listening sockets. Setting TCP_NODELAY | |
9b371988 | 15159 | turns off the &"Nagle algorithm"&, which is a way of improving network |
168e428f PH |
15160 | performance in interactive (character-by-character) situations. Turning it off |
15161 | should improve Exim's performance a bit, so that is what happens by default. | |
15162 | However, it appears that some broken clients cannot cope, and time out. Hence | |
15163 | this option. It affects only those sockets that are set up for listening by the | |
15164 | daemon. Sockets created by the smtp transport for delivering mail always set | |
15165 | TCP_NODELAY. | |
15166 | ||
15167 | ||
9b371988 PH |
15168 | .option timeout_frozen_after main time 0s |
15169 | .cindex "frozen messages" "timing out" | |
15170 | .cindex "timeout" "frozen messages" | |
15171 | If &%timeout_frozen_after%& is set to a time greater than zero, a frozen | |
3cb1b51e PH |
15172 | message of any kind that has been on the queue for longer than the given time |
15173 | is automatically cancelled at the next queue run. If the frozen message is a | |
15174 | bounce message, it is just discarded; otherwise, a bounce is sent to the | |
15175 | sender, in a similar manner to cancellation by the &%-Mg%& command line option. | |
15176 | If you want to timeout frozen bounce messages earlier than other kinds of | |
15177 | frozen message, see &%ignore_bounce_errors_after%&. | |
15178 | ||
3cb1b51e PH |
15179 | &*Note:*& the default value of zero means no timeouts; with this setting, |
15180 | frozen messages remain on the queue forever (except for any frozen bounce | |
15181 | messages that are released by &%ignore_bounce_errors_after%&). | |
168e428f | 15182 | |
168e428f | 15183 | |
9b371988 | 15184 | .option timezone main string unset |
f89d2485 | 15185 | .cindex "timezone, setting" |
9b371988 | 15186 | The value of &%timezone%& is used to set the environment variable TZ while |
168e428f PH |
15187 | running Exim (if it is different on entry). This ensures that all timestamps |
15188 | created by Exim are in the required timezone. If you want all your timestamps | |
15189 | to be in UTC (aka GMT) you should set | |
9b371988 PH |
15190 | .code |
15191 | timezone = UTC | |
15192 | .endd | |
15193 | The default value is taken from TIMEZONE_DEFAULT in &_Local/Makefile_&, | |
168e428f | 15194 | or, if that is not set, from the value of the TZ environment variable when Exim |
9b371988 | 15195 | is built. If &%timezone%& is set to the empty string, either at build or run |
168e428f PH |
15196 | time, any existing TZ variable is removed from the environment when Exim |
15197 | runs. This is appropriate behaviour for obtaining wall-clock time on some, but | |
15198 | unfortunately not all, operating systems. | |
15199 | ||
15200 | ||
9b371988 PH |
15201 | .option tls_advertise_hosts main "host list&!!" unset |
15202 | .cindex "TLS" "advertising" | |
15203 | .cindex "encryption" "on SMTP connection" | |
15204 | .cindex "SMTP" "encrypted connection" | |
168e428f PH |
15205 | When Exim is built with support for TLS encrypted connections, the availability |
15206 | of the STARTTLS command to set up an encrypted session is advertised in | |
15207 | response to EHLO only to those client hosts that match this option. See | |
9b371988 | 15208 | chapter &<<CHAPTLS>>& for details of Exim's support for TLS. |
168e428f PH |
15209 | |
15210 | ||
9b371988 PH |
15211 | .option tls_certificate main string&!! unset |
15212 | .cindex "TLS" "server certificate; location of" | |
f89d2485 | 15213 | .cindex "certificate" "server, location of" |
168e428f PH |
15214 | The value of this option is expanded, and must then be the absolute path to a |
15215 | file which contains the server's certificates. The server's private key is also | |
9b371988 PH |
15216 | assumed to be in this file if &%tls_privatekey%& is unset. See chapter |
15217 | &<<CHAPTLS>>& for further details. | |
168e428f | 15218 | |
9b371988 | 15219 | &*Note*&: The certificates defined by this option are used only when Exim is |
168e428f | 15220 | receiving incoming messages as a server. If you want to supply certificates for |
9b371988 PH |
15221 | use when sending messages as a client, you must set the &%tls_certificate%& |
15222 | option in the relevant &(smtp)& transport. | |
168e428f | 15223 | |
168e428f | 15224 | |
9b371988 PH |
15225 | .option tls_crl main string&!! unset |
15226 | .cindex "TLS" "server certificate revocation list" | |
15227 | .cindex "certificate" "revocation list for server" | |
168e428f PH |
15228 | This option specifies a certificate revocation list. The expanded value must |
15229 | be the name of a file that contains a CRL in PEM format. | |
15230 | ||
15231 | ||
9b371988 PH |
15232 | .option tls_dhparam main string&!! unset |
15233 | .cindex "TLS" "D-H parameters for server" | |
168e428f PH |
15234 | The value of this option is expanded, and must then be the absolute path to |
15235 | a file which contains the server's DH parameter values. | |
15236 | This is used only for OpenSSL. When Exim is linked with GnuTLS, this option is | |
9b371988 | 15237 | ignored. See section &<<SECTopenvsgnu>>& for further details. |
168e428f PH |
15238 | |
15239 | ||
9b371988 | 15240 | .option tls_on_connect_ports main "string list" unset |
168e428f PH |
15241 | This option specifies a list of incoming SSMTP (aka SMTPS) ports that should |
15242 | operate the obsolete SSMTP (SMTPS) protocol, where a TLS session is immediately | |
15243 | set up without waiting for the client to issue a STARTTLS command. For | |
9b371988 | 15244 | further details, see section &<<SECTsupobssmt>>&. |
168e428f PH |
15245 | |
15246 | ||
168e428f | 15247 | |
9b371988 PH |
15248 | .option tls_privatekey main string&!! unset |
15249 | .cindex "TLS" "server private key; location of" | |
168e428f | 15250 | The value of this option is expanded, and must then be the absolute path to a |
4f578862 PH |
15251 | file which contains the server's private key. If this option is unset, or if |
15252 | the expansion is forced to fail, or the result is an empty string, the private | |
15253 | key is assumed to be in the same file as the server's certificates. See chapter | |
15254 | &<<CHAPTLS>>& for further details. | |
168e428f | 15255 | |
168e428f | 15256 | |
9b371988 PH |
15257 | .option tls_remember_esmtp main boolean false |
15258 | .cindex "TLS" "esmtp state; remembering" | |
15259 | .cindex "TLS" "broken clients" | |
168e428f | 15260 | If this option is set true, Exim violates the RFCs by remembering that it is in |
9b371988 | 15261 | &"esmtp"& state after successfully negotiating a TLS session. This provides |
168e428f PH |
15262 | support for broken clients that fail to send a new EHLO after starting a |
15263 | TLS session. | |
15264 | ||
15265 | ||
9b371988 PH |
15266 | .option tls_require_ciphers main string&!! unset |
15267 | .cindex "TLS" "requiring specific ciphers" | |
15268 | .cindex "cipher" "requiring specific" | |
168e428f | 15269 | This option controls which ciphers can be used for incoming TLS connections. |
9b371988 | 15270 | The &(smtp)& transport has an option of the same name for controlling outgoing |
168e428f PH |
15271 | connections. This option is expanded for each connection, so can be varied for |
15272 | different clients if required. The value of this option must be a list of | |
15273 | permitted cipher suites. The OpenSSL and GnuTLS libraries handle cipher control | |
9b371988 PH |
15274 | in somewhat different ways. If GnuTLS is being used, the client controls the |
15275 | preference order of the available ciphers. Details are given in sections | |
15276 | &<<SECTreqciphssl>>& and &<<SECTreqciphgnu>>&. | |
168e428f | 15277 | |
168e428f | 15278 | |
9b371988 PH |
15279 | .option tls_try_verify_hosts main "host list&!!" unset |
15280 | .cindex "TLS" "client certificate verification" | |
15281 | .cindex "certificate" "verification of client" | |
15282 | See &%tls_verify_hosts%& below. | |
168e428f | 15283 | |
168e428f | 15284 | |
9b371988 PH |
15285 | .option tls_verify_certificates main string&!! unset |
15286 | .cindex "TLS" "client certificate verification" | |
15287 | .cindex "certificate" "verification of client" | |
168e428f PH |
15288 | The value of this option is expanded, and must then be the absolute path to |
15289 | a file containing permitted certificates for clients that | |
9b371988 PH |
15290 | match &%tls_verify_hosts%& or &%tls_try_verify_hosts%&. Alternatively, if you |
15291 | are using OpenSSL, you can set &%tls_verify_certificates%& to the name of a | |
168e428f PH |
15292 | directory containing certificate files. This does not work with GnuTLS; the |
15293 | option must be set to the name of a single file if you are using GnuTLS. | |
15294 | ||
15295 | ||
9b371988 PH |
15296 | .option tls_verify_hosts main "host list&!!" unset |
15297 | .cindex "TLS" "client certificate verification" | |
15298 | .cindex "certificate" "verification of client" | |
15299 | This option, along with &%tls_try_verify_hosts%&, controls the checking of | |
595028e4 PH |
15300 | certificates from clients. The expected certificates are defined by |
15301 | &%tls_verify_certificates%&, which must be set. A configuration error occurs if | |
15302 | either &%tls_verify_hosts%& or &%tls_try_verify_hosts%& is set and | |
15303 | &%tls_verify_certificates%& is not set. | |
168e428f | 15304 | |
9b371988 | 15305 | Any client that matches &%tls_verify_hosts%& is constrained by |
595028e4 PH |
15306 | &%tls_verify_certificates%&. When the client initiates a TLS session, it must |
15307 | present one of the listed certificates. If it does not, the connection is | |
15308 | aborted. &*Warning*&: Including a host in &%tls_verify_hosts%& does not require | |
15309 | the host to use TLS. It can still send SMTP commands through unencrypted | |
15310 | connections. Forcing a client to use TLS has to be done separately using an | |
15311 | ACL to reject inappropriate commands when the connection is not encrypted. | |
168e428f | 15312 | |
9b371988 PH |
15313 | A weaker form of checking is provided by &%tls_try_verify_hosts%&. If a client |
15314 | matches this option (but not &%tls_verify_hosts%&), Exim requests a | |
15315 | certificate and checks it against &%tls_verify_certificates%&, but does not | |
168e428f PH |
15316 | abort the connection if there is no certificate or if it does not match. This |
15317 | state can be detected in an ACL, which makes it possible to implement policies | |
9b371988 PH |
15318 | such as &"accept for relay only if a verified certificate has been received, |
15319 | but accept for local delivery if encrypted, even without a verified | |
15320 | certificate"&. | |
168e428f PH |
15321 | |
15322 | Client hosts that match neither of these lists are not asked to present | |
15323 | certificates. | |
15324 | ||
15325 | ||
9b371988 | 15326 | .option trusted_groups main "string list&!!" unset |
f89d2485 PH |
15327 | .cindex "trusted groups" |
15328 | .cindex "groups" "trusted" | |
068aaea8 PH |
15329 | This option is expanded just once, at the start of Exim's processing. If this |
15330 | option is set, any process that is running in one of the listed groups, or | |
15331 | which has one of them as a supplementary group, is trusted. The groups can be | |
9b371988 PH |
15332 | specified numerically or by name. See section &<<SECTtrustedadmin>>& for |
15333 | details of what trusted callers are permitted to do. If neither | |
15334 | &%trusted_groups%& nor &%trusted_users%& is set, only root and the Exim user | |
15335 | are trusted. | |
9b371988 PH |
15336 | |
15337 | .option trusted_users main "string list&!!" unset | |
f89d2485 | 15338 | .cindex "trusted users" |
9b371988 | 15339 | .cindex "user" "trusted" |
068aaea8 PH |
15340 | This option is expanded just once, at the start of Exim's processing. If this |
15341 | option is set, any process that is running as one of the listed users is | |
15342 | trusted. The users can be specified numerically or by name. See section | |
9b371988 PH |
15343 | &<<SECTtrustedadmin>>& for details of what trusted callers are permitted to do. |
15344 | If neither &%trusted_groups%& nor &%trusted_users%& is set, only root and the | |
15345 | Exim user are trusted. | |
9b371988 PH |
15346 | |
15347 | .option unknown_login main string&!! unset | |
15348 | .cindex "uid (user id)" "unknown caller" | |
f89d2485 | 15349 | .vindex "&$caller_uid$&" |
168e428f | 15350 | This is a specialized feature for use in unusual configurations. By default, if |
9b371988 PH |
15351 | the uid of the caller of Exim cannot be looked up using &[getpwuid()]&, Exim |
15352 | gives up. The &%unknown_login%& option can be used to set a login name to be | |
15353 | used in this circumstance. It is expanded, so values like &%user$caller_uid%& | |
15354 | can be set. When &%unknown_login%& is used, the value of &%unknown_username%& | |
15355 | is used for the user's real name (gecos field), unless this has been set by the | |
15356 | &%-F%& option. | |
15357 | ||
15358 | .option unknown_username main string unset | |
15359 | See &%unknown_login%&. | |
15360 | ||
15361 | .option untrusted_set_sender main "address list&!!" unset | |
f89d2485 | 15362 | .cindex "trusted users" |
9b371988 | 15363 | .cindex "sender" "setting by untrusted user" |
f89d2485 | 15364 | .cindex "untrusted user setting sender" |
9b371988 PH |
15365 | .cindex "user" "untrusted setting sender" |
15366 | .cindex "envelope sender" | |
168e428f PH |
15367 | When an untrusted user submits a message to Exim using the standard input, Exim |
15368 | normally creates an envelope sender address from the user's login and the | |
9b371988 PH |
15369 | default qualification domain. Data from the &%-f%& option (for setting envelope |
15370 | senders on non-SMTP messages) or the SMTP MAIL command (if &%-bs%& or &%-bS%& | |
168e428f PH |
15371 | is used) is ignored. |
15372 | ||
15373 | However, untrusted users are permitted to set an empty envelope sender address, | |
15374 | to declare that a message should never generate any bounces. For example: | |
9b371988 PH |
15375 | .code |
15376 | exim -f '<>' user@domain.example | |
15377 | .endd | |
f89d2485 | 15378 | .vindex "&$sender_ident$&" |
9b371988 | 15379 | The &%untrusted_set_sender%& option allows you to permit untrusted users to set |
168e428f PH |
15380 | other envelope sender addresses in a controlled way. When it is set, untrusted |
15381 | users are allowed to set envelope sender addresses that match any of the | |
15382 | patterns in the list. Like all address lists, the string is expanded. The | |
9b371988 | 15383 | identity of the user is in &$sender_ident$&, so you can, for example, restrict |
168e428f PH |
15384 | users to setting senders that start with their login ids |
15385 | followed by a hyphen | |
15386 | by a setting like this: | |
9b371988 PH |
15387 | .code |
15388 | untrusted_set_sender = ^$sender_ident- | |
15389 | .endd | |
168e428f PH |
15390 | If you want to allow untrusted users to set envelope sender addresses without |
15391 | restriction, you can use | |
9b371988 PH |
15392 | .code |
15393 | untrusted_set_sender = * | |
15394 | .endd | |
15395 | The &%untrusted_set_sender%& option applies to all forms of local input, but | |
168e428f PH |
15396 | only to the setting of the envelope sender. It does not permit untrusted users |
15397 | to use the other options which trusted user can use to override message | |
15398 | parameters. Furthermore, it does not stop Exim from removing an existing | |
9b371988 PH |
15399 | &'Sender:'& header in the message, or from adding a &'Sender:'& header if |
15400 | necessary. See &%local_sender_retain%& and &%local_from_check%& for ways of | |
15401 | overriding these actions. The handling of the &'Sender:'& header is also | |
15402 | described in section &<<SECTthesenhea>>&. | |
168e428f | 15403 | |
9b371988 PH |
15404 | The log line for a message's arrival shows the envelope sender following |
15405 | &"<="&. For local messages, the user's login always follows, after &"U="&. In | |
15406 | &%-bp%& displays, and in the Exim monitor, if an untrusted user sets an | |
15407 | envelope sender address, the user's login is shown in parentheses after the | |
15408 | sender address. | |
168e428f | 15409 | |
168e428f | 15410 | |
9b371988 PH |
15411 | .option uucp_from_pattern main string "see below" |
15412 | .cindex "&""From""& line" | |
15413 | .cindex "UUCP" "&""From""& line" | |
168e428f | 15414 | Some applications that pass messages to an MTA via a command line interface use |
9b371988 | 15415 | an initial line starting with &"From&~"& to pass the envelope sender. In |
168e428f | 15416 | particular, this is used by UUCP software. Exim recognizes such a line by means |
9b371988 | 15417 | of a regular expression that is set in &%uucp_from_pattern%&. When the pattern |
168e428f | 15418 | matches, the sender address is constructed by expanding the contents of |
9b371988 | 15419 | &%uucp_from_sender%&, provided that the caller of Exim is a trusted user. The |
168e428f | 15420 | default pattern recognizes lines in the following two forms: |
9b371988 PH |
15421 | .code |
15422 | From ph10 Fri Jan 5 12:35 GMT 1996 | |
15423 | From ph10 Fri, 7 Jan 97 14:00:00 GMT | |
15424 | .endd | |
168e428f | 15425 | The pattern can be seen by running |
9b371988 PH |
15426 | .code |
15427 | exim -bP uucp_from_pattern | |
15428 | .endd | |
168e428f | 15429 | It checks only up to the hours and minutes, and allows for a 2-digit or 4-digit |
9b371988 PH |
15430 | year in the second case. The first word after &"From&~"& is matched in the |
15431 | regular expression by a parenthesized subpattern. The default value for | |
15432 | &%uucp_from_sender%& is &"$1"&, which therefore just uses this first word | |
15433 | (&"ph10"& in the example above) as the message's sender. See also | |
15434 | &%ignore_fromline_hosts%&. | |
168e428f PH |
15435 | |
15436 | ||
9b371988 PH |
15437 | .option uucp_from_sender main string&!! &`$1`& |
15438 | See &%uucp_from_pattern%& above. | |
168e428f | 15439 | |
168e428f | 15440 | |
9b371988 PH |
15441 | .option warn_message_file main string unset |
15442 | .cindex "warning of delay" "customizing the message" | |
15443 | .cindex "customizing" "warning message" | |
168e428f PH |
15444 | This option defines a template file containing paragraphs of text to be used |
15445 | for constructing the warning message which is sent by Exim when a message has | |
15446 | been on the queue for a specified amount of time, as specified by | |
9b371988 PH |
15447 | &%delay_warning%&. Details of the file's contents are given in chapter |
15448 | &<<CHAPemsgcust>>&. See also &%bounce_message_file%&. | |
168e428f PH |
15449 | |
15450 | ||
9b371988 PH |
15451 | .option write_rejectlog main boolean true |
15452 | .cindex "reject log" "disabling" | |
168e428f | 15453 | If this option is set false, Exim no longer writes anything to the reject log. |
9b371988 | 15454 | See chapter &<<CHAPlog>>& for details of what Exim writes to its logs. |
4f578862 PH |
15455 | .ecindex IIDconfima |
15456 | .ecindex IIDmaiconf | |
168e428f PH |
15457 | |
15458 | ||
15459 | ||
15460 | ||
9b371988 PH |
15461 | . //////////////////////////////////////////////////////////////////////////// |
15462 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 15463 | |
9b371988 | 15464 | .chapter "Generic options for routers" "CHAProutergeneric" |
4f578862 PH |
15465 | .scindex IIDgenoprou1 "options" "generic; for routers" |
15466 | .scindex IIDgenoprou2 "generic options" "router" | |
168e428f | 15467 | This chapter describes the generic options that apply to all routers. |
9b371988 | 15468 | Those that are preconditions are marked with ‡ in the &"use"& field. |
168e428f PH |
15469 | |
15470 | For a general description of how a router operates, see sections | |
9b371988 | 15471 | &<<SECTrunindrou>>& and &<<SECTrouprecon>>&. The latter specifies the order in |
168e428f | 15472 | which the preconditions are tested. The order of expansion of the options that |
9b371988 PH |
15473 | provide data for a transport is: &%errors_to%&, &%headers_add%&, |
15474 | &%headers_remove%&, &%transport%&. | |
168e428f PH |
15475 | |
15476 | ||
168e428f | 15477 | |
9b371988 PH |
15478 | .option address_data routers string&!! unset |
15479 | .cindex "router" "data attached to address" | |
168e428f PH |
15480 | The string is expanded just before the router is run, that is, after all the |
15481 | precondition tests have succeeded. If the expansion is forced to fail, the | |
9b371988 PH |
15482 | router declines, the value of &%address_data%& remains unchanged, and the |
15483 | &%more%& option controls what happens next. Other expansion failures cause | |
15484 | delivery of the address to be deferred. | |
168e428f | 15485 | |
f89d2485 | 15486 | .vindex "&$address_data$&" |
168e428f | 15487 | When the expansion succeeds, the value is retained with the address, and can be |
9b371988 | 15488 | accessed using the variable &$address_data$& in the current router, subsequent |
168e428f PH |
15489 | routers, and the eventual transport. |
15490 | ||
9b371988 PH |
15491 | &*Warning*&: If the current or any subsequent router is a &(redirect)& router |
15492 | that runs a user's filter file, the contents of &$address_data$& are accessible | |
068aaea8 | 15493 | in the filter. This is not normally a problem, because such data is usually |
9b371988 PH |
15494 | either not confidential or it &"belongs"& to the current user, but if you do |
15495 | put confidential data into &$address_data$& you need to remember this point. | |
168e428f | 15496 | |
9b371988 PH |
15497 | Even if the router declines or passes, the value of &$address_data$& remains |
15498 | with the address, though it can be changed by another &%address_data%& setting | |
168e428f | 15499 | on a subsequent router. If a router generates child addresses, the value of |
9b371988 PH |
15500 | &$address_data$& propagates to them. This also applies to the special kind of |
15501 | &"child"& that is generated by a router with the &%unseen%& option. | |
15502 | ||
15503 | The idea of &%address_data%& is that you can use it to look up a lot of data | |
15504 | for the address once, and then pick out parts of the data later. For example, | |
15505 | you could use a single LDAP lookup to return a string of the form | |
15506 | .code | |
15507 | uid=1234 gid=5678 mailbox=/mail/xyz forward=/home/xyz/.forward | |
15508 | .endd | |
168e428f | 15509 | In the transport you could pick out the mailbox by a setting such as |
9b371988 PH |
15510 | .code |
15511 | file = ${extract{mailbox}{$address_data}} | |
15512 | .endd | |
168e428f PH |
15513 | This makes the configuration file less messy, and also reduces the number of |
15514 | lookups (though Exim does cache lookups). | |
15515 | ||
f89d2485 PH |
15516 | .vindex "&$sender_address_data$&" |
15517 | .vindex "&$address_data$&" | |
595028e4 PH |
15518 | The &%address_data%& facility is also useful as a means of passing information |
15519 | from one router to another, and from a router to a transport. In addition, if | |
15520 | &$address_data$& is set by a router when verifying a recipient address from an | |
15521 | ACL, it remains available for use in the rest of the ACL statement. After | |
15522 | verifying a sender, the value is transferred to &$sender_address_data$&. | |
168e428f PH |
15523 | |
15524 | ||
168e428f | 15525 | |
9b371988 | 15526 | .option address_test routers&!? boolean true |
f89d2485 | 15527 | .oindex "&%-bt%&" |
9b371988 | 15528 | .cindex "router" "skipping when address testing" |
168e428f | 15529 | If this option is set false, the router is skipped when routing is being tested |
9b371988 PH |
15530 | by means of the &%-bt%& command line option. This can be a convenience when |
15531 | your first router sends messages to an external scanner, because it saves you | |
15532 | having to set the &"already scanned"& indicator when testing real address | |
168e428f PH |
15533 | routing. |
15534 | ||
15535 | ||
15536 | ||
9b371988 PH |
15537 | .option cannot_route_message routers string&!! unset |
15538 | .cindex "router" "customizing &""cannot route""& message" | |
15539 | .cindex "customizing" "&""cannot route""& message" | |
168e428f | 15540 | This option specifies a text message that is used when an address cannot be |
9b371988 PH |
15541 | routed because Exim has run out of routers. The default message is |
15542 | &"Unrouteable address"&. This option is useful only on routers that have | |
15543 | &%more%& set false, or on the very last router in a configuration, because the | |
4f578862 | 15544 | value that is used is taken from the last router that is considered. This |
9b371988 | 15545 | includes a router that is skipped because its preconditions are not met, as |
4f578862 | 15546 | well as a router that declines. For example, using the default configuration, |
9b371988 PH |
15547 | you could put: |
15548 | .code | |
15549 | cannot_route_message = Remote domain not found in DNS | |
15550 | .endd | |
15551 | on the first router, which is a &(dnslookup)& router with &%more%& set false, | |
15552 | and | |
15553 | .code | |
15554 | cannot_route_message = Unknown local user | |
15555 | .endd | |
15556 | on the final router that checks for local users. If string expansion fails for | |
15557 | this option, the default message is used. Unless the expansion failure was | |
15558 | explicitly forced, a message about the failure is written to the main and panic | |
15559 | logs, in addition to the normal message about the routing failure. | |
15560 | ||
15561 | ||
15562 | .option caseful_local_part routers boolean false | |
15563 | .cindex "case of local parts" | |
15564 | .cindex "router" "case of local parts" | |
168e428f PH |
15565 | By default, routers handle the local parts of addresses in a case-insensitive |
15566 | manner, though the actual case is preserved for transmission with the message. | |
15567 | If you want the case of letters to be significant in a router, you must set | |
15568 | this option true. For individual router options that contain address or local | |
9b371988 PH |
15569 | part lists (for example, &%local_parts%&), case-sensitive matching can be |
15570 | turned on by &"+caseful"& as a list item. See section &<<SECTcasletadd>>& for | |
15571 | more details. | |
15572 | ||
f89d2485 PH |
15573 | .vindex "&$local_part$&" |
15574 | .vindex "&$original_local_part$&" | |
15575 | .vindex "&$parent_local_part$&" | |
9b371988 PH |
15576 | The value of the &$local_part$& variable is forced to lower case while a |
15577 | router is running unless &%caseful_local_part%& is set. When a router assigns | |
15578 | an address to a transport, the value of &$local_part$& when the transport runs | |
168e428f | 15579 | is the same as it was in the router. Similarly, when a router generates child |
9b371988 PH |
15580 | addresses by aliasing or forwarding, the values of &$original_local_part$& |
15581 | and &$parent_local_part$& are those that were used by the redirecting router. | |
168e428f PH |
15582 | |
15583 | This option applies to the processing of an address by a router. When a | |
9b371988 | 15584 | recipient address is being processed in an ACL, there is a separate &%control%& |
168e428f | 15585 | modifier that can be used to specify case-sensitive processing within the ACL |
9b371988 | 15586 | (see section &<<SECTcontrols>>&). |
168e428f PH |
15587 | |
15588 | ||
15589 | ||
9b371988 | 15590 | .option check_local_user routers&!? boolean false |
f89d2485 | 15591 | .cindex "local user, checking in router" |
9b371988 PH |
15592 | .cindex "router" "checking for local user" |
15593 | .cindex "&_/etc/passwd_&" | |
f89d2485 | 15594 | .vindex "&$home$&" |
168e428f PH |
15595 | When this option is true, Exim checks that the local part of the recipient |
15596 | address (with affixes removed if relevant) is the name of an account on the | |
9b371988 PH |
15597 | local system. The check is done by calling the &[getpwnam()]& function rather |
15598 | than trying to read &_/etc/passwd_& directly. This means that other methods of | |
168e428f | 15599 | holding password data (such as NIS) are supported. If the local part is a local |
9b371988 | 15600 | user, &$home$& is set from the password data, and can be tested in other |
168e428f | 15601 | preconditions that are evaluated after this one (the order of evaluation is |
9b371988 PH |
15602 | given in section &<<SECTrouprecon>>&). However, the value of &$home$& can be |
15603 | overridden by &%router_home_directory%&. If the local part is not a local user, | |
168e428f PH |
15604 | the router is skipped. |
15605 | ||
15606 | If you want to check that the local part is either the name of a local user | |
9b371988 PH |
15607 | or matches something else, you cannot combine &%check_local_user%& with a |
15608 | setting of &%local_parts%&, because that specifies the logical &'and'& of the | |
15609 | two conditions. However, you can use a &(passwd)& lookup in a &%local_parts%& | |
168e428f | 15610 | setting to achieve this. For example: |
9b371988 PH |
15611 | .code |
15612 | local_parts = passwd;$local_part : lsearch;/etc/other/users | |
15613 | .endd | |
15614 | Note, however, that the side effects of &%check_local_user%& (such as setting | |
15615 | up a home directory) do not occur when a &(passwd)& lookup is used in a | |
15616 | &%local_parts%& (or any other) precondition. | |
168e428f | 15617 | |
168e428f PH |
15618 | |
15619 | ||
9b371988 PH |
15620 | .option condition routers&!? string&!! unset |
15621 | .cindex "router" "customized precondition" | |
168e428f | 15622 | This option specifies a general precondition test that has to succeed for the |
9b371988 PH |
15623 | router to be called. The &%condition%& option is the last precondition to be |
15624 | evaluated (see section &<<SECTrouprecon>>&). The string is expanded, and if the | |
15625 | result is a forced failure, or an empty string, or one of the strings &"0"& or | |
15626 | &"no"& or &"false"& (checked without regard to the case of the letters), the | |
15627 | router is skipped, and the address is offered to the next one. | |
168e428f PH |
15628 | |
15629 | If the result is any other value, the router is run (as this is the last | |
15630 | precondition to be evaluated, all the other preconditions must be true). | |
15631 | ||
9b371988 | 15632 | The &%condition%& option provides a means of applying custom conditions to the |
168e428f PH |
15633 | running of routers. Note that in the case of a simple conditional expansion, |
15634 | the default expansion values are exactly what is wanted. For example: | |
9b371988 PH |
15635 | .code |
15636 | condition = ${if >{$message_age}{600}} | |
15637 | .endd | |
168e428f | 15638 | Because of the default behaviour of the string expansion, this is equivalent to |
9b371988 PH |
15639 | .code |
15640 | condition = ${if >{$message_age}{600}{true}{}} | |
15641 | .endd | |
168e428f PH |
15642 | If the expansion fails (other than forced failure) delivery is deferred. Some |
15643 | of the other precondition options are common special cases that could in fact | |
9b371988 | 15644 | be specified using &%condition%&. |
168e428f PH |
15645 | |
15646 | ||
168e428f | 15647 | |
9b371988 PH |
15648 | .option debug_print routers string&!! unset |
15649 | .cindex "testing" "variables in drivers" | |
15650 | If this option is set and debugging is enabled (see the &%-d%& command line | |
168e428f PH |
15651 | option), the string is expanded and included in the debugging output. |
15652 | If expansion of the string fails, the error message is written to the debugging | |
15653 | output, and Exim carries on processing. | |
15654 | This option is provided to help with checking out the values of variables and | |
9b371988 PH |
15655 | so on when debugging router configurations. For example, if a &%condition%& |
15656 | option appears not to be working, &%debug_print%& can be used to output the | |
15657 | variables it references. The output happens after checks for &%domains%&, | |
15658 | &%local_parts%&, and &%check_local_user%& but before any other preconditions | |
15659 | are tested. A newline is added to the text if it does not end with one. | |
168e428f PH |
15660 | |
15661 | ||
15662 | ||
9b371988 | 15663 | .option disable_logging routers boolean false |
168e428f PH |
15664 | If this option is set true, nothing is logged for any routing errors |
15665 | or for any deliveries caused by this router. You should not set this option | |
15666 | unless you really, really know what you are doing. See also the generic | |
15667 | transport option of the same name. | |
15668 | ||
15669 | ||
9b371988 PH |
15670 | .option domains routers&!? "domain list&!!" unset |
15671 | .cindex "router" "restricting to specific domains" | |
f89d2485 | 15672 | .vindex "&$domain_data$&" |
168e428f PH |
15673 | If this option is set, the router is skipped unless the current domain matches |
15674 | the list. If the match is achieved by means of a file lookup, the data that the | |
9b371988 PH |
15675 | lookup returned for the domain is placed in &$domain_data$& for use in string |
15676 | expansions of the driver's private options. See section &<<SECTrouprecon>>& for | |
15677 | a list of the order in which preconditions are evaluated. | |
168e428f PH |
15678 | |
15679 | ||
15680 | ||
9b371988 | 15681 | .option driver routers string unset |
168e428f PH |
15682 | This option must always be set. It specifies which of the available routers is |
15683 | to be used. | |
15684 | ||
15685 | ||
15686 | ||
9b371988 PH |
15687 | .option errors_to routers string&!! unset |
15688 | .cindex "envelope sender" | |
15689 | .cindex "router" "changing address for errors" | |
4f578862 PH |
15690 | If a router successfully handles an address, it may assign the address to a |
15691 | transport for delivery or it may generate child addresses. In both cases, if | |
15692 | there is a delivery problem during later processing, the resulting bounce | |
15693 | message is sent to the address that results from expanding this string, | |
15694 | provided that the address verifies successfully. The &%errors_to%& option is | |
15695 | expanded before &%headers_add%&, &%headers_remove%&, and &%transport%&. | |
15696 | ||
15697 | The &%errors_to%& setting associated with an address can be overridden if it | |
15698 | subsequently passes through other routers that have their own &%errors_to%& | |
15699 | settings, or if the message is delivered by a transport with a &%return_path%& | |
15700 | setting. | |
15701 | ||
15702 | If &%errors_to%& is unset, or the expansion is forced to fail, or the result of | |
168e428f PH |
15703 | the expansion fails to verify, the errors address associated with the incoming |
15704 | address is used. At top level, this is the envelope sender. A non-forced | |
15705 | expansion failure causes delivery to be deferred. | |
15706 | ||
9b371988 PH |
15707 | If an address for which &%errors_to%& has been set ends up being delivered over |
15708 | SMTP, the envelope sender for that delivery is the &%errors_to%& value, so that | |
168e428f | 15709 | any bounces that are generated by other MTAs on the delivery route are also |
4f578862 PH |
15710 | sent there. You can set &%errors_to%& to the empty string by either of these |
15711 | settings: | |
9b371988 PH |
15712 | .code |
15713 | errors_to = | |
4f578862 | 15714 | errors_to = "" |
9b371988 | 15715 | .endd |
168e428f PH |
15716 | An expansion item that yields an empty string has the same effect. If you do |
15717 | this, a locally detected delivery error for addresses processed by this router | |
15718 | no longer gives rise to a bounce message; the error is discarded. If the | |
9b371988 PH |
15719 | address is delivered to a remote host, the return path is set to &`<>`&, unless |
15720 | overridden by the &%return_path%& option on the transport. | |
168e428f | 15721 | |
f89d2485 | 15722 | .vindex "&$address_data$&" |
168e428f PH |
15723 | If for some reason you want to discard local errors, but use a non-empty |
15724 | MAIL command for remote delivery, you can preserve the original return | |
9b371988 PH |
15725 | path in &$address_data$& in the router, and reinstate it in the transport by |
15726 | setting &%return_path%&. | |
168e428f | 15727 | |
4f578862 PH |
15728 | The most common use of &%errors_to%& is to direct mailing list bounces to the |
15729 | manager of the list, as described in section &<<SECTmailinglists>>&, or to | |
15730 | implement VERP (Variable Envelope Return Paths) (see section &<<SECTverp>>&). | |
15731 | ||
168e428f PH |
15732 | |
15733 | ||
9b371988 PH |
15734 | .option expn routers&!? boolean true |
15735 | .cindex "address" "testing" | |
15736 | .cindex "testing" "addresses" | |
15737 | .cindex "EXPN" "router skipping" | |
15738 | .cindex "router" "skipping for EXPN" | |
168e428f PH |
15739 | If this option is turned off, the router is skipped when testing an address |
15740 | as a result of processing an SMTP EXPN command. You might, for example, | |
9b371988 | 15741 | want to turn it off on a router for users' &_.forward_& files, while leaving it |
168e428f | 15742 | on for the system alias file. |
9b371988 | 15743 | See section &<<SECTrouprecon>>& for a list of the order in which preconditions |
168e428f PH |
15744 | are evaluated. |
15745 | ||
15746 | The use of the SMTP EXPN command is controlled by an ACL (see chapter | |
9b371988 PH |
15747 | &<<CHAPACL>>&). When Exim is running an EXPN command, it is similar to testing |
15748 | an address with &%-bt%&. Compare VRFY, whose counterpart is &%-bv%&. | |
168e428f PH |
15749 | |
15750 | ||
168e428f | 15751 | |
9b371988 PH |
15752 | .option fail_verify routers boolean false |
15753 | .cindex "router" "forcing verification failure" | |
15754 | Setting this option has the effect of setting both &%fail_verify_sender%& and | |
15755 | &%fail_verify_recipient%& to the same value. | |
168e428f PH |
15756 | |
15757 | ||
15758 | ||
9b371988 | 15759 | .option fail_verify_recipient routers boolean false |
168e428f PH |
15760 | If this option is true and an address is accepted by this router when |
15761 | verifying a recipient, verification fails. | |
15762 | ||
15763 | ||
15764 | ||
9b371988 | 15765 | .option fail_verify_sender routers boolean false |
168e428f PH |
15766 | If this option is true and an address is accepted by this router when |
15767 | verifying a sender, verification fails. | |
15768 | ||
15769 | ||
15770 | ||
9b371988 | 15771 | .option fallback_hosts routers "string list" unset |
9b371988 PH |
15772 | .cindex "router" "fallback hosts" |
15773 | .cindex "fallback" "hosts specified on router" | |
168e428f | 15774 | String expansion is not applied to this option. The argument must be a |
068aaea8 | 15775 | colon-separated list of host names or IP addresses. The list separator can be |
9b371988 | 15776 | changed (see section &<<SECTlistconstruct>>&), and a port can be specified with |
068aaea8 | 15777 | each name or address. In fact, the format of each item is exactly the same as |
9b371988 PH |
15778 | defined for the list of hosts in a &(manualroute)& router (see section |
15779 | &<<SECTformatonehostitem>>&). | |
068aaea8 PH |
15780 | |
15781 | If a router queues an address for a remote transport, this host list is | |
15782 | associated with the address, and used instead of the transport's fallback host | |
9b371988 PH |
15783 | list. If &%hosts_randomize%& is set on the transport, the order of the list is |
15784 | randomized for each use. See the &%fallback_hosts%& option of the &(smtp)& | |
068aaea8 | 15785 | transport for further details. |
168e428f PH |
15786 | |
15787 | ||
9b371988 PH |
15788 | .option group routers string&!! "see below" |
15789 | .cindex "gid (group id)" "local delivery" | |
15790 | .cindex "local transports" "uid and gid" | |
15791 | .cindex "transport" "local" | |
15792 | .cindex "router" "setting group" | |
168e428f PH |
15793 | When a router queues an address for a transport, and the transport does not |
15794 | specify a group, the group given here is used when running the delivery | |
15795 | process. | |
15796 | The group may be specified numerically or by name. If expansion fails, the | |
15797 | error is logged and delivery is deferred. | |
9b371988 PH |
15798 | The default is unset, unless &%check_local_user%& is set, when the default |
15799 | is taken from the password information. See also &%initgroups%& and &%user%& | |
15800 | and the discussion in chapter &<<CHAPenvironment>>&. | |
168e428f PH |
15801 | |
15802 | ||
15803 | ||
9b371988 | 15804 | .option headers_add routers string&!! unset |
9b371988 PH |
15805 | .cindex "header lines" "adding" |
15806 | .cindex "router" "adding header lines" | |
168e428f PH |
15807 | This option specifies a string of text that is expanded at routing time, and |
15808 | associated with any addresses that are accepted by the router. However, this | |
15809 | option has no effect when an address is just being verified. The way in which | |
15810 | the text is used to add header lines at transport time is described in section | |
9b371988 | 15811 | &<<SECTheadersaddrem>>&. New header lines are not actually added until the |
d1e83bff PH |
15812 | message is in the process of being transported. This means that references to |
15813 | header lines in string expansions in the transport's configuration do not | |
9b371988 | 15814 | &"see"& the added header lines. |
168e428f | 15815 | |
9b371988 PH |
15816 | The &%headers_add%& option is expanded after &%errors_to%&, but before |
15817 | &%headers_remove%& and &%transport%&. If the expanded string is empty, or if | |
15818 | the expansion is forced to fail, the option has no effect. Other expansion | |
15819 | failures are treated as configuration errors. | |
168e428f | 15820 | |
9b371988 PH |
15821 | &*Warning 1*&: The &%headers_add%& option cannot be used for a &(redirect)& |
15822 | router that has the &%one_time%& option set. | |
068aaea8 | 15823 | |
0a4e3112 PH |
15824 | .cindex "duplicate addresses" |
15825 | .oindex "&%unseen%&" | |
9b371988 PH |
15826 | &*Warning 2*&: If the &%unseen%& option is set on the router, all header |
15827 | additions are deleted when the address is passed on to subsequent routers. | |
0a4e3112 PH |
15828 | For a &%redirect%& router, if a generated address is the same as the incoming |
15829 | address, this can lead to duplicate addresses with different header | |
15830 | modifications. Exim does not do duplicate deliveries (except, in certain | |
15831 | circumstances, to pipes -- see section &<<SECTdupaddr>>&), but it is undefined | |
15832 | which of the duplicates is discarded, so this ambiguous situation should be | |
15833 | avoided. The &%repeat_use%& option of the &%redirect%& router may be of help. | |
168e428f PH |
15834 | |
15835 | ||
15836 | ||
9b371988 | 15837 | .option headers_remove routers string&!! unset |
9b371988 PH |
15838 | .cindex "header lines" "removing" |
15839 | .cindex "router" "removing header lines" | |
168e428f PH |
15840 | This option specifies a string of text that is expanded at routing time, and |
15841 | associated with any addresses that are accepted by the router. However, this | |
15842 | option has no effect when an address is just being verified. The way in which | |
15843 | the text is used to remove header lines at transport time is described in | |
9b371988 PH |
15844 | section &<<SECTheadersaddrem>>&. Header lines are not actually removed until |
15845 | the message is in the process of being transported. This means that references | |
15846 | to header lines in string expansions in the transport's configuration still | |
15847 | &"see"& the original header lines. | |
9b371988 PH |
15848 | |
15849 | The &%headers_remove%& option is expanded after &%errors_to%& and | |
15850 | &%headers_add%&, but before &%transport%&. If the expansion is forced to fail, | |
15851 | the option has no effect. Other expansion failures are treated as configuration | |
15852 | errors. | |
168e428f | 15853 | |
9b371988 PH |
15854 | &*Warning 1*&: The &%headers_remove%& option cannot be used for a &(redirect)& |
15855 | router that has the &%one_time%& option set. | |
168e428f | 15856 | |
9b371988 PH |
15857 | &*Warning 2*&: If the &%unseen%& option is set on the router, all header |
15858 | removal requests are deleted when the address is passed on to subsequent | |
0a4e3112 PH |
15859 | routers, and this can lead to problems with duplicates -- see the similar |
15860 | warning for &%headers_add%& above. | |
168e428f | 15861 | |
168e428f | 15862 | |
9b371988 PH |
15863 | .option ignore_target_hosts routers "host list&!!" unset |
15864 | .cindex "IP address" "discarding" | |
15865 | .cindex "router" "discarding IP addresses" | |
168e428f PH |
15866 | Although this option is a host list, it should normally contain IP address |
15867 | entries rather than names. If any host that is looked up by the router has an | |
15868 | IP address that matches an item in this list, Exim behaves as if that IP | |
15869 | address did not exist. This option allows you to cope with rogue DNS entries | |
15870 | like | |
9b371988 PH |
15871 | .code |
15872 | remote.domain.example. A 127.0.0.1 | |
15873 | .endd | |
168e428f | 15874 | by setting |
9b371988 PH |
15875 | .code |
15876 | ignore_target_hosts = 127.0.0.1 | |
15877 | .endd | |
15878 | on the relevant router. If all the hosts found by a &(dnslookup)& router are | |
168e428f | 15879 | discarded in this way, the router declines. In a conventional configuration, an |
9b371988 PH |
15880 | attempt to mail to such a domain would normally provoke the &"unrouteable |
15881 | domain"& error, and an attempt to verify an address in the domain would fail. | |
15882 | Similarly, if &%ignore_target_hosts%& is set on an &(ipliteral)& router, the | |
168e428f PH |
15883 | router declines if presented with one of the listed addresses. |
15884 | ||
9b371988 PH |
15885 | You can use this option to disable the use of IPv4 or IPv6 for mail delivery by |
15886 | means of the first or the second of the following settings, respectively: | |
15887 | .code | |
15888 | ignore_target_hosts = 0.0.0.0/0 | |
15889 | ignore_target_hosts = <; 0::0/0 | |
15890 | .endd | |
15891 | The pattern in the first line matches all IPv4 addresses, whereas the pattern | |
15892 | in the second line matches all IPv6 addresses. | |
9b371988 | 15893 | |
168e428f | 15894 | This option may also be useful for ignoring link-local and site-local IPv6 |
9b371988 | 15895 | addresses. Because, like all host lists, the value of &%ignore_target_hosts%& |
168e428f PH |
15896 | is expanded before use as a list, it is possible to make it dependent on the |
15897 | domain that is being routed. | |
15898 | ||
f89d2485 | 15899 | .vindex "&$host_address$&" |
9b371988 | 15900 | During its expansion, &$host_address$& is set to the IP address that is being |
168e428f PH |
15901 | checked. |
15902 | ||
9b371988 PH |
15903 | .option initgroups routers boolean false |
15904 | .cindex "additional groups" | |
15905 | .cindex "groups" "additional" | |
15906 | .cindex "local transports" "uid and gid" | |
15907 | .cindex "transport" "local" | |
168e428f PH |
15908 | If the router queues an address for a transport, and this option is true, and |
15909 | the uid supplied by the router is not overridden by the transport, the | |
9b371988 PH |
15910 | &[initgroups()]& function is called when running the transport to ensure that |
15911 | any additional groups associated with the uid are set up. See also &%group%& | |
15912 | and &%user%& and the discussion in chapter &<<CHAPenvironment>>&. | |
168e428f PH |
15913 | |
15914 | ||
168e428f | 15915 | |
9b371988 PH |
15916 | .option local_part_prefix routers&!? "string list" unset |
15917 | .cindex "router" "prefix for local part" | |
f89d2485 | 15918 | .cindex "prefix" "for local part, used in router" |
068aaea8 | 15919 | If this option is set, the router is skipped unless the local part starts with |
9b371988 PH |
15920 | one of the given strings, or &%local_part_prefix_optional%& is true. See |
15921 | section &<<SECTrouprecon>>& for a list of the order in which preconditions are | |
15922 | evaluated. | |
168e428f PH |
15923 | |
15924 | The list is scanned from left to right, and the first prefix that matches is | |
15925 | used. A limited form of wildcard is available; if the prefix begins with an | |
15926 | asterisk, it matches the longest possible sequence of arbitrary characters at | |
15927 | the start of the local part. An asterisk should therefore always be followed by | |
15928 | some character that does not occur in normal local parts. | |
9b371988 PH |
15929 | .cindex "multiple mailboxes" |
15930 | .cindex "mailbox" "multiple" | |
168e428f | 15931 | Wildcarding can be used to set up multiple user mailboxes, as described in |
9b371988 | 15932 | section &<<SECTmulbox>>&. |
168e428f | 15933 | |
f89d2485 PH |
15934 | .vindex "&$local_part$&" |
15935 | .vindex "&$local_part_prefix$&" | |
9b371988 | 15936 | During the testing of the &%local_parts%& option, and while the router is |
168e428f | 15937 | running, the prefix is removed from the local part, and is available in the |
9b371988 | 15938 | expansion variable &$local_part_prefix$&. When a message is being delivered, if |
068aaea8 PH |
15939 | the router accepts the address, this remains true during subsequent delivery by |
15940 | a transport. In particular, the local part that is transmitted in the RCPT | |
15941 | command for LMTP, SMTP, and BSMTP deliveries has the prefix removed by default. | |
9b371988 PH |
15942 | This behaviour can be overridden by setting &%rcpt_include_affixes%& true on |
15943 | the relevant transport. | |
168e428f | 15944 | |
9b371988 | 15945 | When an address is being verified, &%local_part_prefix%& affects only the |
068aaea8 PH |
15946 | behaviour of the router. If the callout feature of verification is in use, this |
15947 | means that the full address, including the prefix, will be used during the | |
15948 | callout. | |
15949 | ||
168e428f | 15950 | The prefix facility is commonly used to handle local parts of the form |
9b371988 PH |
15951 | &%owner-something%&. Another common use is to support local parts of the form |
15952 | &%real-username%& to bypass a user's &_.forward_& file &-- helpful when trying | |
15953 | to tell a user their forwarding is broken &-- by placing a router like this one | |
15954 | immediately before the router that handles &_.forward_& files: | |
15955 | .code | |
15956 | real_localuser: | |
15957 | driver = accept | |
15958 | local_part_prefix = real- | |
15959 | check_local_user | |
15960 | transport = local_delivery | |
15961 | .endd | |
595028e4 PH |
15962 | For security, it would probably be a good idea to restrict the use of this |
15963 | router to locally-generated messages, using a condition such as this: | |
15964 | .code | |
15965 | condition = ${if match {$sender_host_address}\ | |
15966 | {\N^(|127\.0\.0\.1)$\N}} | |
15967 | .endd | |
595028e4 | 15968 | |
9b371988 | 15969 | If both &%local_part_prefix%& and &%local_part_suffix%& are set for a router, |
168e428f PH |
15970 | both conditions must be met if not optional. Care must be taken if wildcards |
15971 | are used in both a prefix and a suffix on the same router. Different | |
15972 | separator characters must be used to avoid ambiguity. | |
15973 | ||
15974 | ||
9b371988 PH |
15975 | .option local_part_prefix_optional routers boolean false |
15976 | See &%local_part_prefix%& above. | |
168e428f PH |
15977 | |
15978 | ||
168e428f | 15979 | |
9b371988 PH |
15980 | .option local_part_suffix routers&!? "string list" unset |
15981 | .cindex "router" "suffix for local part" | |
15982 | .cindex "suffix for local part" "used in router" | |
15983 | This option operates in the same way as &%local_part_prefix%&, except that the | |
168e428f | 15984 | local part must end (rather than start) with the given string, the |
9b371988 PH |
15985 | &%local_part_suffix_optional%& option determines whether the suffix is |
15986 | mandatory, and the wildcard * character, if present, must be the last | |
168e428f | 15987 | character of the suffix. This option facility is commonly used to handle local |
9b371988 PH |
15988 | parts of the form &%something-request%& and multiple user mailboxes of the form |
15989 | &%username-foo%&. | |
168e428f PH |
15990 | |
15991 | ||
9b371988 PH |
15992 | .option local_part_suffix_optional routers boolean false |
15993 | See &%local_part_suffix%& above. | |
168e428f | 15994 | |
168e428f PH |
15995 | |
15996 | ||
9b371988 PH |
15997 | .option local_parts routers&!? "local part list&!!" unset |
15998 | .cindex "router" "restricting to specific local parts" | |
15999 | .cindex "local part" "checking in router" | |
168e428f | 16000 | The router is run only if the local part of the address matches the list. |
9b371988 | 16001 | See section &<<SECTrouprecon>>& for a list of the order in which preconditions |
168e428f | 16002 | are evaluated, and |
9b371988 | 16003 | section &<<SECTlocparlis>>& for a discussion of local part lists. Because the |
168e428f PH |
16004 | string is expanded, it is possible to make it depend on the domain, for |
16005 | example: | |
9b371988 PH |
16006 | .code |
16007 | local_parts = dbm;/usr/local/specials/$domain | |
16008 | .endd | |
f89d2485 | 16009 | .vindex "&$local_part_data$&" |
168e428f | 16010 | If the match is achieved by a lookup, the data that the lookup returned |
9b371988 | 16011 | for the local part is placed in the variable &$local_part_data$& for use in |
168e428f PH |
16012 | expansions of the router's private options. You might use this option, for |
16013 | example, if you have a large number of local virtual domains, and you want to | |
16014 | send all postmaster mail to the same place without having to set up an alias in | |
16015 | each virtual domain: | |
9b371988 PH |
16016 | .code |
16017 | postmaster: | |
16018 | driver = redirect | |
16019 | local_parts = postmaster | |
16020 | data = postmaster@real.domain.example | |
16021 | .endd | |
168e428f | 16022 | |
168e428f | 16023 | |
9b371988 PH |
16024 | .option log_as_local routers boolean "see below" |
16025 | .cindex "log" "delivery line" | |
16026 | .cindex "delivery" "log line format" | |
168e428f | 16027 | Exim has two logging styles for delivery, the idea being to make local |
9b371988 | 16028 | deliveries stand out more visibly from remote ones. In the &"local"& style, the |
168e428f | 16029 | recipient address is given just as the local part, without a domain. The use of |
9b371988 | 16030 | this style is controlled by this option. It defaults to true for the &(accept)& |
4f578862 | 16031 | router, and false for all the others. This option applies only when a |
9b371988 | 16032 | router assigns an address to a transport. It has no effect on routers that |
4f578862 | 16033 | redirect addresses. |
168e428f PH |
16034 | |
16035 | ||
168e428f | 16036 | |
9b371988 | 16037 | .option more routers boolean&!! true |
168e428f | 16038 | The result of string expansion for this option must be a valid boolean value, |
9b371988 | 16039 | that is, one of the strings &"yes"&, &"no"&, &"true"&, or &"false"&. Any other |
168e428f PH |
16040 | result causes an error, and delivery is deferred. If the expansion is forced to |
16041 | fail, the default value for the option (true) is used. Other failures cause | |
16042 | delivery to be deferred. | |
16043 | ||
068aaea8 PH |
16044 | If this option is set false, and the router declines to handle the address, no |
16045 | further routers are tried, routing fails, and the address is bounced. | |
0a4e3112 | 16046 | .oindex "&%self%&" |
9b371988 PH |
16047 | However, if the router explicitly passes an address to the following router by |
16048 | means of the setting | |
16049 | .code | |
16050 | self = pass | |
16051 | .endd | |
16052 | or otherwise, the setting of &%more%& is ignored. Also, the setting of &%more%& | |
168e428f PH |
16053 | does not affect the behaviour if one of the precondition tests fails. In that |
16054 | case, the address is always passed to the next router. | |
16055 | ||
9b371988 PH |
16056 | Note that &%address_data%& is not considered to be a precondition. If its |
16057 | expansion is forced to fail, the router declines, and the value of &%more%& | |
068aaea8 PH |
16058 | controls what happens next. |
16059 | ||
168e428f | 16060 | |
9b371988 PH |
16061 | .option pass_on_timeout routers boolean false |
16062 | .cindex "timeout" "of router" | |
16063 | .cindex "router" "timeout" | |
168e428f | 16064 | If a router times out during a host lookup, it normally causes deferral of the |
9b371988 PH |
16065 | address. If &%pass_on_timeout%& is set, the address is passed on to the next |
16066 | router, overriding &%no_more%&. This may be helpful for systems that are | |
168e428f PH |
16067 | intermittently connected to the Internet, or those that want to pass to a smart |
16068 | host any messages that cannot immediately be delivered. | |
16069 | ||
16070 | There are occasional other temporary errors that can occur while doing DNS | |
16071 | lookups. They are treated in the same way as a timeout, and this option | |
16072 | applies to all of them. | |
16073 | ||
16074 | ||
16075 | ||
9b371988 PH |
16076 | .option pass_router routers string unset |
16077 | .cindex "router" "go to after &""pass""&" | |
595028e4 PH |
16078 | Routers that recognize the generic &%self%& option (&(dnslookup)&, |
16079 | &(ipliteral)&, and &(manualroute)&) are able to return &"pass"&, forcing | |
16080 | routing to continue, and overriding a false setting of &%more%&. When one of | |
16081 | these routers returns &"pass"&, the address is normally handed on to the next | |
9b371988 PH |
16082 | router in sequence. This can be changed by setting &%pass_router%& to the name |
16083 | of another router. However (unlike &%redirect_router%&) the named router must | |
16084 | be below the current router, to avoid loops. Note that this option applies only | |
16085 | to the special case of &"pass"&. It does not apply when a router returns | |
595028e4 | 16086 | &"decline"& because it cannot handle an address. |
168e428f PH |
16087 | |
16088 | ||
168e428f | 16089 | |
9b371988 PH |
16090 | .option redirect_router routers string unset |
16091 | .cindex "router" "start at after redirection" | |
168e428f PH |
16092 | Sometimes an administrator knows that it is pointless to reprocess addresses |
16093 | generated from alias or forward files with the same router again. For | |
16094 | example, if an alias file translates real names into login ids there is no | |
16095 | point searching the alias file a second time, especially if it is a large file. | |
16096 | ||
9b371988 PH |
16097 | The &%redirect_router%& option can be set to the name of any router instance. |
16098 | It causes the routing of any generated addresses to start at the named router | |
168e428f PH |
16099 | instead of at the first router. This option has no effect if the router in |
16100 | which it is set does not generate new addresses. | |
16101 | ||
16102 | ||
16103 | ||
9b371988 PH |
16104 | .option require_files routers&!? "string list&!!" unset |
16105 | .cindex "file" "requiring for router" | |
16106 | .cindex "router" "requiring file existence" | |
168e428f PH |
16107 | This option provides a general mechanism for predicating the running of a |
16108 | router on the existence or non-existence of certain files or directories. | |
16109 | Before running a router, as one of its precondition tests, Exim works its way | |
9b371988 | 16110 | through the &%require_files%& list, expanding each item separately. |
168e428f PH |
16111 | |
16112 | Because the list is split before expansion, any colons in expansion items must | |
16113 | be doubled, or the facility for using a different list separator must be used. | |
16114 | If any expansion is forced to fail, the item is ignored. Other expansion | |
16115 | failures cause routing of the address to be deferred. | |
16116 | ||
16117 | If any expanded string is empty, it is ignored. Otherwise, except as described | |
16118 | below, each string must be a fully qualified file path, optionally preceded by | |
9b371988 PH |
16119 | &"!"&. The paths are passed to the &[stat()]& function to test for the |
16120 | existence of the files or directories. The router is skipped if any paths not | |
16121 | preceded by &"!"& do not exist, or if any paths preceded by &"!"& do exist. | |
168e428f | 16122 | |
9b371988 PH |
16123 | .cindex "NFS" |
16124 | If &[stat()]& cannot determine whether a file exists or not, delivery of | |
168e428f PH |
16125 | the message is deferred. This can happen when NFS-mounted filesystems are |
16126 | unavailable. | |
16127 | ||
9b371988 | 16128 | This option is checked after the &%domains%&, &%local_parts%&, and &%senders%& |
168e428f | 16129 | options, so you cannot use it to check for the existence of a file in which to |
9b371988 | 16130 | look up a domain, local part, or sender. (See section &<<SECTrouprecon>>& for a |
168e428f | 16131 | full list of the order in which preconditions are evaluated.) However, as |
9b371988 PH |
16132 | these options are all expanded, you can use the &%exists%& expansion condition |
16133 | to make such tests. The &%require_files%& option is intended for checking files | |
168e428f | 16134 | that the router may be going to use internally, or which are needed by a |
9b371988 | 16135 | transport (for example &_.procmailrc_&). |
168e428f | 16136 | |
9b371988 | 16137 | During delivery, the &[stat()]& function is run as root, but there is a |
168e428f | 16138 | facility for some checking of the accessibility of a file by another user. |
9b371988 | 16139 | This is not a proper permissions check, but just a &"rough"& check that |
168e428f PH |
16140 | operates as follows: |
16141 | ||
9b371988 | 16142 | If an item in a &%require_files%& list does not contain any forward slash |
168e428f PH |
16143 | characters, it is taken to be the user (and optional group, separated by a |
16144 | comma) to be checked for subsequent files in the list. If no group is specified | |
16145 | but the user is specified symbolically, the gid associated with the uid is | |
16146 | used. For example: | |
9b371988 PH |
16147 | .code |
16148 | require_files = mail:/some/file | |
16149 | require_files = $local_part:$home/.procmailrc | |
16150 | .endd | |
16151 | If a user or group name in a &%require_files%& list does not exist, the | |
16152 | &%require_files%& condition fails. | |
168e428f PH |
16153 | |
16154 | Exim performs the check by scanning along the components of the file path, and | |
9b371988 PH |
16155 | checking the access for the given uid and gid. It checks for &"x"& access on |
16156 | directories, and &"r"& access on the final file. Note that this means that file | |
168e428f PH |
16157 | access control lists, if the operating system has them, are ignored. |
16158 | ||
9b371988 | 16159 | &*Warning 1*&: When the router is being run to verify addresses for an |
168e428f | 16160 | incoming SMTP message, Exim is not running as root, but under its own uid. This |
9b371988 PH |
16161 | may affect the result of a &%require_files%& check. In particular, &[stat()]& |
16162 | may yield the error EACCES (&"Permission denied"&). This means that the Exim | |
168e428f PH |
16163 | user is not permitted to read one of the directories on the file's path. |
16164 | ||
9b371988 PH |
16165 | &*Warning 2*&: Even when Exim is running as root while delivering a message, |
16166 | &[stat()]& can yield EACCES for a file in an NFS directory that is mounted | |
16167 | without root access. In this case, if a check for access by a particular user | |
16168 | is requested, Exim creates a subprocess that runs as that user, and tries the | |
16169 | check again in that process. | |
168e428f PH |
16170 | |
16171 | The default action for handling an unresolved EACCES is to consider it to | |
9b371988 PH |
16172 | be caused by a configuration error, and routing is deferred because the |
16173 | existence or non-existence of the file cannot be determined. However, in some | |
16174 | circumstances it may be desirable to treat this condition as if the file did | |
16175 | not exist. If the file name (or the exclamation mark that precedes the file | |
16176 | name for non-existence) is preceded by a plus sign, the EACCES error is treated | |
16177 | as if the file did not exist. For example: | |
16178 | .code | |
16179 | require_files = +/some/file | |
16180 | .endd | |
168e428f | 16181 | If the router is not an essential part of verification (for example, it |
9b371988 | 16182 | handles users' &_.forward_& files), another solution is to set the &%verify%& |
168e428f PH |
16183 | option false so that the router is skipped when verifying. |
16184 | ||
16185 | ||
16186 | ||
9b371988 PH |
16187 | .option retry_use_local_part routers boolean "see below" |
16188 | .cindex "hints database" "retry keys" | |
16189 | .cindex "local part" "in retry keys" | |
168e428f PH |
16190 | When a delivery suffers a temporary routing failure, a retry record is created |
16191 | in Exim's hints database. For addresses whose routing depends only on the | |
16192 | domain, the key for the retry record should not involve the local part, but for | |
16193 | other addresses, both the domain and the local part should be included. | |
16194 | Usually, remote routing is of the former kind, and local routing is of the | |
16195 | latter kind. | |
16196 | ||
16197 | This option controls whether the local part is used to form the key for retry | |
16198 | hints for addresses that suffer temporary errors while being handled by this | |
9b371988 | 16199 | router. The default value is true for any router that has &%check_local_user%& |
168e428f PH |
16200 | set, and false otherwise. Note that this option does not apply to hints keys |
16201 | for transport delays; they are controlled by a generic transport option of the | |
16202 | same name. | |
16203 | ||
9b371988 | 16204 | The setting of &%retry_use_local_part%& applies only to the router on which it |
168e428f PH |
16205 | appears. If the router generates child addresses, they are routed |
16206 | independently; this setting does not become attached to them. | |
16207 | ||
16208 | ||
16209 | ||
9b371988 PH |
16210 | .option router_home_directory routers string&!! unset |
16211 | .cindex "router" "home directory for" | |
16212 | .cindex "home directory" "for router" | |
f89d2485 | 16213 | .vindex "&$home$&" |
168e428f | 16214 | This option sets a home directory for use while the router is running. (Compare |
9b371988 PH |
16215 | &%transport_home_directory%&, which sets a home directory for later |
16216 | transporting.) In particular, if used on a &(redirect)& router, this option | |
16217 | sets a value for &$home$& while a filter is running. The value is expanded; | |
16218 | forced expansion failure causes the option to be ignored &-- other failures | |
168e428f PH |
16219 | cause the router to defer. |
16220 | ||
9b371988 PH |
16221 | Expansion of &%router_home_directory%& happens immediately after the |
16222 | &%check_local_user%& test (if configured), before any further expansions take | |
168e428f | 16223 | place. |
9b371988 | 16224 | (See section &<<SECTrouprecon>>& for a list of the order in which preconditions |
168e428f | 16225 | are evaluated.) |
9b371988 PH |
16226 | While the router is running, &%router_home_directory%& overrides the value of |
16227 | &$home$& that came from &%check_local_user%&. | |
168e428f | 16228 | |
4f578862 PH |
16229 | When a router accepts an address and assigns it to a local transport (including |
16230 | the cases when a &(redirect)& router generates a pipe, file, or autoreply | |
16231 | delivery), the home directory setting for the transport is taken from the first | |
16232 | of these values that is set: | |
168e428f | 16233 | |
9b371988 PH |
16234 | .ilist |
16235 | The &%home_directory%& option on the transport; | |
16236 | .next | |
16237 | The &%transport_home_directory%& option on the router; | |
16238 | .next | |
16239 | The password data if &%check_local_user%& is set on the router; | |
16240 | .next | |
16241 | The &%router_home_directory%& option on the router. | |
16242 | .endlist | |
16243 | ||
16244 | In other words, &%router_home_directory%& overrides the password data for the | |
168e428f PH |
16245 | router, but not for the transport. |
16246 | ||
16247 | ||
16248 | ||
9b371988 PH |
16249 | .option self routers string freeze |
16250 | .cindex "MX record" "pointing to local host" | |
16251 | .cindex "local host" "MX pointing to" | |
168e428f | 16252 | This option applies to those routers that use a recipient address to find a |
9b371988 PH |
16253 | list of remote hosts. Currently, these are the &(dnslookup)&, &(ipliteral)&, |
16254 | and &(manualroute)& routers. | |
16255 | Certain configurations of the &(queryprogram)& router can also specify a list | |
168e428f PH |
16256 | of remote hosts. |
16257 | Usually such routers are configured to send the message to a remote host via an | |
9b371988 | 16258 | &(smtp)& transport. The &%self%& option specifies what happens when the first |
168e428f PH |
16259 | host on the list turns out to be the local host. |
16260 | The way in which Exim checks for the local host is described in section | |
9b371988 | 16261 | &<<SECTreclocipadd>>&. |
168e428f PH |
16262 | |
16263 | Normally this situation indicates either an error in Exim's configuration (for | |
16264 | example, the router should be configured not to process this domain), or an | |
16265 | error in the DNS (for example, the MX should not point to this host). For this | |
16266 | reason, the default action is to log the incident, defer the address, and | |
16267 | freeze the message. The following alternatives are provided for use in special | |
16268 | cases: | |
16269 | ||
9b371988 PH |
16270 | .vlist |
16271 | .vitem &%defer%& | |
168e428f PH |
16272 | Delivery of the message is tried again later, but the message is not frozen. |
16273 | ||
9b371988 | 16274 | .vitem "&%reroute%&: <&'domain'&>" |
168e428f PH |
16275 | The domain is changed to the given domain, and the address is passed back to |
16276 | be reprocessed by the routers. No rewriting of headers takes place. This | |
16277 | behaviour is essentially a redirection. | |
16278 | ||
9b371988 | 16279 | .vitem "&%reroute: rewrite:%& <&'domain'&>" |
168e428f PH |
16280 | The domain is changed to the given domain, and the address is passed back to be |
16281 | reprocessed by the routers. Any headers that contain the original domain are | |
16282 | rewritten. | |
16283 | ||
9b371988 | 16284 | .vitem &%pass%& |
0a4e3112 | 16285 | .oindex "&%more%&" |
f89d2485 | 16286 | .vindex "&$self_hostname$&" |
168e428f | 16287 | The router passes the address to the next router, or to the router named in the |
9b371988 PH |
16288 | &%pass_router%& option if it is set. This overrides &%no_more%&. During |
16289 | subsequent routing and delivery, the variable &$self_hostname$& contains the | |
16290 | name of the local host that the router encountered. This can be used to | |
168e428f PH |
16291 | distinguish between different cases for hosts with multiple names. The |
16292 | combination | |
9b371988 PH |
16293 | .code |
16294 | self = pass | |
16295 | no_more | |
16296 | .endd | |
168e428f | 16297 | ensures that only those addresses that routed to the local host are passed on. |
9b371988 | 16298 | Without &%no_more%&, addresses that were declined for other reasons would also |
168e428f PH |
16299 | be passed to the next router. |
16300 | ||
9b371988 | 16301 | .vitem &%fail%& |
168e428f PH |
16302 | Delivery fails and an error report is generated. |
16303 | ||
9b371988 PH |
16304 | .vitem &%send%& |
16305 | .cindex "local host" "sending to" | |
168e428f | 16306 | The anomaly is ignored and the address is queued for the transport. This |
9b371988 PH |
16307 | setting should be used with extreme caution. For an &(smtp)& transport, it |
16308 | makes sense only in cases where the program that is listening on the SMTP port | |
16309 | is not this version of Exim. That is, it must be some other MTA, or Exim with a | |
168e428f | 16310 | different configuration file that handles the domain in another way. |
9b371988 | 16311 | .endlist |
168e428f PH |
16312 | |
16313 | ||
16314 | ||
9b371988 PH |
16315 | .option senders routers&!? "address list&!!" unset |
16316 | .cindex "router" "checking senders" | |
168e428f PH |
16317 | If this option is set, the router is skipped unless the message's sender |
16318 | address matches something on the list. | |
9b371988 | 16319 | See section &<<SECTrouprecon>>& for a list of the order in which preconditions |
168e428f PH |
16320 | are evaluated. |
16321 | ||
16322 | There are issues concerning verification when the running of routers is | |
9b371988 PH |
16323 | dependent on the sender. When Exim is verifying the address in an &%errors_to%& |
16324 | setting, it sets the sender to the null string. When using the &%-bt%& option | |
16325 | to check a configuration file, it is necessary also to use the &%-f%& option to | |
16326 | set an appropriate sender. For incoming mail, the sender is unset when | |
16327 | verifying the sender, but is available when verifying any recipients. If the | |
16328 | SMTP VRFY command is enabled, it must be used after MAIL if the sender address | |
16329 | matters. | |
16330 | ||
16331 | ||
16332 | .option translate_ip_address routers string&!! unset | |
16333 | .cindex "IP address" "translating" | |
16334 | .cindex "packet radio" | |
16335 | .cindex "router" "IP address translation" | |
168e428f PH |
16336 | There exist some rare networking situations (for example, packet radio) where |
16337 | it is helpful to be able to translate IP addresses generated by normal routing | |
16338 | mechanisms into other IP addresses, thus performing a kind of manual IP | |
16339 | routing. This should be done only if the normal IP routing of the TCP/IP stack | |
16340 | is inadequate or broken. Because this is an extremely uncommon requirement, the | |
16341 | code to support this option is not included in the Exim binary unless | |
9b371988 | 16342 | SUPPORT_TRANSLATE_IP_ADDRESS=yes is set in &_Local/Makefile_&. |
168e428f | 16343 | |
f89d2485 | 16344 | .vindex "&$host_address$&" |
9b371988 PH |
16345 | The &%translate_ip_address%& string is expanded for every IP address generated |
16346 | by the router, with the generated address set in &$host_address$&. If the | |
168e428f PH |
16347 | expansion is forced to fail, no action is taken. |
16348 | For any other expansion error, delivery of the message is deferred. | |
16349 | If the result of the expansion is an IP address, that replaces the original | |
9b371988 PH |
16350 | address; otherwise the result is assumed to be a host name &-- this is looked |
16351 | up using &[gethostbyname()]& (or &[getipnodebyname()]& when available) to | |
16352 | produce one or more replacement IP addresses. For example, to subvert all IP | |
16353 | addresses in some specific networks, this could be added to a router: | |
16354 | .code | |
168e428f | 16355 | translate_ip_address = \ |
9b371988 PH |
16356 | ${lookup{${mask:$host_address/26}}lsearch{/some/file}\ |
16357 | {$value}fail}} | |
16358 | .endd | |
168e428f | 16359 | The file would contain lines like |
9b371988 PH |
16360 | .code |
16361 | 10.2.3.128/26 some.host | |
16362 | 10.8.4.34/26 10.44.8.15 | |
16363 | .endd | |
168e428f PH |
16364 | You should not make use of this facility unless you really understand what you |
16365 | are doing. | |
16366 | ||
16367 | ||
16368 | ||
9b371988 | 16369 | .option transport routers string&!! unset |
168e428f PH |
16370 | This option specifies the transport to be used when a router accepts an address |
16371 | and sets it up for delivery. A transport is never needed if a router is used | |
16372 | only for verification. The value of the option is expanded at routing time, | |
9b371988 PH |
16373 | after the expansion of &%errors_to%&, &%headers_add%&, and &%headers_remove%&, |
16374 | and result must be the name of one of the configured transports. If it is not, | |
168e428f PH |
16375 | delivery is deferred. |
16376 | ||
9b371988 PH |
16377 | The &%transport%& option is not used by the &(redirect)& router, but it does |
16378 | have some private options that set up transports for pipe and file deliveries | |
16379 | (see chapter &<<CHAPredirect>>&). | |
168e428f PH |
16380 | |
16381 | ||
16382 | ||
9b371988 PH |
16383 | .option transport_current_directory routers string&!! unset |
16384 | .cindex "current directory for local transport" | |
168e428f PH |
16385 | This option associates a current directory with any address that is routed |
16386 | to a local transport. This can happen either because a transport is | |
16387 | explicitly configured for the router, or because it generates a delivery to a | |
16388 | file or a pipe. During the delivery process (that is, at transport time), this | |
16389 | option string is expanded and is set as the current directory, unless | |
16390 | overridden by a setting on the transport. | |
16391 | If the expansion fails for any reason, including forced failure, an error is | |
16392 | logged, and delivery is deferred. | |
9b371988 PH |
16393 | See chapter &<<CHAPenvironment>>& for details of the local delivery |
16394 | environment. | |
168e428f PH |
16395 | |
16396 | ||
16397 | ||
168e428f | 16398 | |
9b371988 PH |
16399 | .option transport_home_directory routers string&!! "see below" |
16400 | .cindex "home directory" "for local transport" | |
168e428f PH |
16401 | This option associates a home directory with any address that is routed to a |
16402 | local transport. This can happen either because a transport is explicitly | |
16403 | configured for the router, or because it generates a delivery to a file or a | |
16404 | pipe. During the delivery process (that is, at transport time), the option | |
16405 | string is expanded and is set as the home directory, unless overridden by a | |
9b371988 | 16406 | setting of &%home_directory%& on the transport. |
168e428f PH |
16407 | If the expansion fails for any reason, including forced failure, an error is |
16408 | logged, and delivery is deferred. | |
16409 | ||
16410 | If the transport does not specify a home directory, and | |
9b371988 | 16411 | &%transport_home_directory%& is not set for the router, the home directory for |
f89d2485 | 16412 | the transport is taken from the password data if &%check_local_user%& is set for |
9b371988 | 16413 | the router. Otherwise it is taken from &%router_home_directory%& if that option |
168e428f PH |
16414 | is set; if not, no home directory is set for the transport. |
16415 | ||
9b371988 | 16416 | See chapter &<<CHAPenvironment>>& for further details of the local delivery |
168e428f PH |
16417 | environment. |
16418 | ||
16419 | ||
16420 | ||
16421 | ||
9b371988 PH |
16422 | .option unseen routers boolean&!! false |
16423 | .cindex "router" "carrying on after success" | |
168e428f | 16424 | The result of string expansion for this option must be a valid boolean value, |
9b371988 | 16425 | that is, one of the strings &"yes"&, &"no"&, &"true"&, or &"false"&. Any other |
068aaea8 PH |
16426 | result causes an error, and delivery is deferred. If the expansion is forced to |
16427 | fail, the default value for the option (false) is used. Other failures cause | |
16428 | delivery to be deferred. | |
16429 | ||
168e428f PH |
16430 | When this option is set true, routing does not cease if the router accepts the |
16431 | address. Instead, a copy of the incoming address is passed to the next router, | |
9b371988 PH |
16432 | overriding a false setting of &%more%&. There is little point in setting |
16433 | &%more%& false if &%unseen%& is always true, but it may be useful in cases when | |
16434 | the value of &%unseen%& contains expansion items (and therefore, presumably, is | |
16435 | sometimes true and sometimes false). | |
16436 | ||
9b371988 | 16437 | .cindex "copy of message (&%unseen%& option)" |
0a4e3112 PH |
16438 | Setting the &%unseen%& option has a similar effect to the &%unseen%& command |
16439 | qualifier in filter files. It can be used to cause copies of messages to be | |
16440 | delivered to some other destination, while also carrying out a normal delivery. | |
16441 | In effect, the current address is made into a &"parent"& that has two children | |
16442 | &-- one that is delivered as specified by this router, and a clone that goes on | |
16443 | to be routed further. For this reason, &%unseen%& may not be combined with the | |
9b371988 | 16444 | &%one_time%& option in a &(redirect)& router. |
9b371988 PH |
16445 | |
16446 | &*Warning*&: Header lines added to the address (or specified for removal) by | |
16447 | this router or by previous routers affect the &"unseen"& copy of the message | |
16448 | only. The clone that continues to be processed by further routers starts with | |
0a4e3112 PH |
16449 | no added headers and none specified for removal. For a &%redirect%& router, if |
16450 | a generated address is the same as the incoming address, this can lead to | |
16451 | duplicate addresses with different header modifications. Exim does not do | |
16452 | duplicate deliveries (except, in certain circumstances, to pipes -- see section | |
16453 | &<<SECTdupaddr>>&), but it is undefined which of the duplicates is discarded, | |
16454 | so this ambiguous situation should be avoided. The &%repeat_use%& option of the | |
16455 | &%redirect%& router may be of help. | |
16456 | ||
16457 | Unlike the handling of header modifications, any data that was set by the | |
16458 | &%address_data%& option in the current or previous routers &'is'& passed on to | |
16459 | subsequent routers. | |
168e428f PH |
16460 | |
16461 | ||
9b371988 PH |
16462 | .option user routers string&!! "see below" |
16463 | .cindex "uid (user id)" "local delivery" | |
16464 | .cindex "local transports" "uid and gid" | |
16465 | .cindex "transport" "local" | |
16466 | .cindex "router" "user for filter processing" | |
16467 | .cindex "filter" "user for processing" | |
168e428f PH |
16468 | When a router queues an address for a transport, and the transport does not |
16469 | specify a user, the user given here is used when running the delivery process. | |
16470 | The user may be specified numerically or by name. If expansion fails, the | |
16471 | error is logged and delivery is deferred. | |
9b371988 PH |
16472 | This user is also used by the &(redirect)& router when running a filter file. |
16473 | The default is unset, except when &%check_local_user%& is set. In this case, | |
168e428f | 16474 | the default is taken from the password information. If the user is specified as |
9b371988 PH |
16475 | a name, and &%group%& is not set, the group associated with the user is used. |
16476 | See also &%initgroups%& and &%group%& and the discussion in chapter | |
16477 | &<<CHAPenvironment>>&. | |
168e428f PH |
16478 | |
16479 | ||
168e428f | 16480 | |
9b371988 PH |
16481 | .option verify routers&!? boolean true |
16482 | Setting this option has the effect of setting &%verify_sender%& and | |
16483 | &%verify_recipient%& to the same value. | |
168e428f PH |
16484 | |
16485 | ||
9b371988 PH |
16486 | .option verify_only routers&!? boolean false |
16487 | .cindex "EXPN" "with &%verify_only%&" | |
f89d2485 | 16488 | .oindex "&%-bv%&" |
9b371988 | 16489 | .cindex "router" "used only when verifying" |
168e428f | 16490 | If this option is set, the router is used only when verifying an address or |
9b371988 PH |
16491 | testing with the &%-bv%& option, not when actually doing a delivery, testing |
16492 | with the &%-bt%& option, or running the SMTP EXPN command. It can be further | |
16493 | restricted to verifying only senders or recipients by means of | |
16494 | &%verify_sender%& and &%verify_recipient%&. | |
168e428f | 16495 | |
9b371988 | 16496 | &*Warning*&: When the router is being run to verify addresses for an incoming |
168e428f PH |
16497 | SMTP message, Exim is not running as root, but under its own uid. If the router |
16498 | accesses any files, you need to make sure that they are accessible to the Exim | |
16499 | user or group. | |
16500 | ||
16501 | ||
9b371988 | 16502 | .option verify_recipient routers&!? boolean true |
168e428f PH |
16503 | If this option is false, the router is skipped when verifying recipient |
16504 | addresses | |
9b371988 PH |
16505 | or testing recipient verification using &%-bv%&. |
16506 | See section &<<SECTrouprecon>>& for a list of the order in which preconditions | |
168e428f PH |
16507 | are evaluated. |
16508 | ||
16509 | ||
9b371988 | 16510 | .option verify_sender routers&!? boolean true |
168e428f | 16511 | If this option is false, the router is skipped when verifying sender addresses |
9b371988 PH |
16512 | or testing sender verification using &%-bvs%&. |
16513 | See section &<<SECTrouprecon>>& for a list of the order in which preconditions | |
168e428f | 16514 | are evaluated. |
4f578862 PH |
16515 | .ecindex IIDgenoprou1 |
16516 | .ecindex IIDgenoprou2 | |
168e428f PH |
16517 | |
16518 | ||
16519 | ||
16520 | ||
16521 | ||
16522 | ||
9b371988 PH |
16523 | . //////////////////////////////////////////////////////////////////////////// |
16524 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 16525 | |
f89d2485 | 16526 | .chapter "The accept router" "CHID4" |
9b371988 PH |
16527 | .cindex "&(accept)& router" |
16528 | .cindex "routers" "&(accept)&" | |
16529 | The &(accept)& router has no private options of its own. Unless it is being | |
16530 | used purely for verification (see &%verify_only%&) a transport is required to | |
16531 | be defined by the generic &%transport%& option. If the preconditions that are | |
168e428f PH |
16532 | specified by generic options are met, the router accepts the address and queues |
16533 | it for the given transport. The most common use of this router is for setting | |
16534 | up deliveries to local mailboxes. For example: | |
9b371988 PH |
16535 | .code |
16536 | localusers: | |
16537 | driver = accept | |
16538 | domains = mydomain.example | |
16539 | check_local_user | |
16540 | transport = local_delivery | |
16541 | .endd | |
16542 | The &%domains%& condition in this example checks the domain of the address, and | |
16543 | &%check_local_user%& checks that the local part is the login of a local user. | |
16544 | When both preconditions are met, the &(accept)& router runs, and queues the | |
16545 | address for the &(local_delivery)& transport. | |
168e428f PH |
16546 | |
16547 | ||
16548 | ||
16549 | ||
16550 | ||
16551 | ||
9b371988 PH |
16552 | . //////////////////////////////////////////////////////////////////////////// |
16553 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 16554 | |
9b371988 | 16555 | .chapter "The dnslookup router" "CHAPdnslookup" |
4f578862 PH |
16556 | .scindex IIDdnsrou1 "&(dnslookup)& router" |
16557 | .scindex IIDdnsrou2 "routers" "&(dnslookup)&" | |
9b371988 | 16558 | The &(dnslookup)& router looks up the hosts that handle mail for the |
168e428f | 16559 | recipient's domain in the DNS. A transport must always be set for this router, |
9b371988 | 16560 | unless &%verify_only%& is set. |
168e428f | 16561 | |
9b371988 | 16562 | If SRV support is configured (see &%check_srv%& below), Exim first searches for |
168e428f PH |
16563 | SRV records. If none are found, or if SRV support is not configured, |
16564 | MX records are looked up. If no MX records exist, address records are sought. | |
9b371988 PH |
16565 | However, &%mx_domains%& can be set to disable the direct use of address |
16566 | records. | |
168e428f PH |
16567 | |
16568 | MX records of equal priority are sorted by Exim into a random order. Exim then | |
16569 | looks for address records for the host names obtained from MX or SRV records. | |
16570 | When a host has more than one IP address, they are sorted into a random order, | |
16571 | except that IPv6 addresses are always sorted before IPv4 addresses. If all the | |
9b371988 | 16572 | IP addresses found are discarded by a setting of the &%ignore_target_hosts%& |
168e428f PH |
16573 | generic option, the router declines. |
16574 | ||
16575 | Unless they have the highest priority (lowest MX value), MX records that point | |
9b371988 | 16576 | to the local host, or to any host name that matches &%hosts_treat_as_local%&, |
168e428f PH |
16577 | are discarded, together with any other MX records of equal or lower priority. |
16578 | ||
9b371988 PH |
16579 | .cindex "MX record" "pointing to local host" |
16580 | .cindex "local host" "MX pointing to" | |
0a4e3112 | 16581 | .oindex "&%self%&" "in &(dnslookup)& router" |
168e428f | 16582 | If the host pointed to by the highest priority MX record, or looked up as an |
9b371988 PH |
16583 | address record, is the local host, or matches &%hosts_treat_as_local%&, what |
16584 | happens is controlled by the generic &%self%& option. | |
168e428f PH |
16585 | |
16586 | ||
9b371988 | 16587 | .section "Problems with DNS lookups" "SECTprowitdnsloo" |
168e428f PH |
16588 | There have been problems with DNS servers when SRV records are looked up. |
16589 | Some mis-behaving servers return a DNS error or timeout when a non-existent | |
16590 | SRV record is sought. Similar problems have in the past been reported for | |
9b371988 | 16591 | MX records. The global &%dns_again_means_nonexist%& option can help with this |
168e428f PH |
16592 | problem, but it is heavy-handed because it is a global option. |
16593 | ||
9b371988 PH |
16594 | For this reason, there are two options, &%srv_fail_domains%& and |
16595 | &%mx_fail_domains%&, that control what happens when a DNS lookup in a | |
16596 | &(dnslookup)& router results in a DNS failure or a &"try again"& response. If | |
16597 | an attempt to look up an SRV or MX record causes one of these results, and the | |
16598 | domain matches the relevant list, Exim behaves as if the DNS had responded &"no | |
16599 | such record"&. In the case of an SRV lookup, this means that the router | |
16600 | proceeds to look for MX records; in the case of an MX lookup, it proceeds to | |
16601 | look for A or AAAA records, unless the domain matches &%mx_domains%&, in which | |
16602 | case routing fails. | |
168e428f PH |
16603 | |
16604 | ||
16605 | ||
168e428f | 16606 | |
f89d2485 | 16607 | .section "Private options for dnslookup" "SECID118" |
9b371988 PH |
16608 | .cindex "options" "&(dnslookup)& router" |
16609 | The private options for the &(dnslookup)& router are as follows: | |
168e428f | 16610 | |
9b371988 PH |
16611 | .option check_secondary_mx dnslookup boolean false |
16612 | .cindex "MX record" "checking for secondary" | |
168e428f PH |
16613 | If this option is set, the router declines unless the local host is found in |
16614 | (and removed from) the list of hosts obtained by MX lookup. This can be used to | |
16615 | process domains for which the local host is a secondary mail exchanger | |
16616 | differently to other domains. The way in which Exim decides whether a host is | |
9b371988 | 16617 | the local host is described in section &<<SECTreclocipadd>>&. |
168e428f PH |
16618 | |
16619 | ||
9b371988 PH |
16620 | .option check_srv dnslookup string&!! unset |
16621 | .cindex "SRV record" "enabling use of" | |
16622 | The &(dnslookup)& router supports the use of SRV records (see RFC 2782) in | |
168e428f | 16623 | addition to MX and address records. The support is disabled by default. To |
9b371988 | 16624 | enable SRV support, set the &%check_srv%& option to the name of the service |
168e428f | 16625 | required. For example, |
9b371988 PH |
16626 | .code |
16627 | check_srv = smtp | |
16628 | .endd | |
168e428f PH |
16629 | looks for SRV records that refer to the normal smtp service. The option is |
16630 | expanded, so the service name can vary from message to message or address | |
16631 | to address. This might be helpful if SRV records are being used for a | |
9b371988 | 16632 | submission service. If the expansion is forced to fail, the &%check_srv%& |
168e428f PH |
16633 | option is ignored, and the router proceeds to look for MX records in the |
16634 | normal way. | |
16635 | ||
16636 | When the expansion succeeds, the router searches first for SRV records for | |
16637 | the given service (it assumes TCP protocol). A single SRV record with a | |
9b371988 PH |
16638 | host name that consists of just a single dot indicates &"no such service for |
16639 | this domain"&; if this is encountered, the router declines. If other kinds of | |
168e428f PH |
16640 | SRV record are found, they are used to construct a host list for delivery |
16641 | according to the rules of RFC 2782. MX records are not sought in this case. | |
16642 | ||
16643 | When no SRV records are found, MX records (and address records) are sought in | |
16644 | the traditional way. In other words, SRV records take precedence over MX | |
16645 | records, just as MX records take precedence over address records. Note that | |
16646 | this behaviour is not sanctioned by RFC 2782, though a previous draft RFC | |
16647 | defined it. It is apparently believed that MX records are sufficient for email | |
16648 | and that SRV records should not be used for this purpose. However, SRV records | |
9b371988 | 16649 | have an additional &"weight"& feature which some people might find useful when |
168e428f PH |
16650 | trying to split an SMTP load between hosts of different power. |
16651 | ||
9b371988 PH |
16652 | See section &<<SECTprowitdnsloo>>& above for a discussion of Exim's behaviour |
16653 | when there is a DNS lookup error. | |
168e428f PH |
16654 | |
16655 | ||
168e428f | 16656 | |
9b371988 PH |
16657 | .option mx_domains dnslookup "domain list&!!" unset |
16658 | .cindex "MX record" "required to exist" | |
16659 | .cindex "SRV record" "required to exist" | |
16660 | A domain that matches &%mx_domains%& is required to have either an MX or an SRV | |
f89d2485 | 16661 | record in order to be recognized. (The name of this option could be improved.) |
9b371988 PH |
16662 | For example, if all the mail hosts in &'fict.example'& are known to have MX |
16663 | records, except for those in &'discworld.fict.example'&, you could use this | |
168e428f | 16664 | setting: |
9b371988 PH |
16665 | .code |
16666 | mx_domains = ! *.discworld.fict.example : *.fict.example | |
16667 | .endd | |
168e428f PH |
16668 | This specifies that messages addressed to a domain that matches the list but |
16669 | has no MX record should be bounced immediately instead of being routed using | |
16670 | the address record. | |
16671 | ||
16672 | ||
9b371988 | 16673 | .option mx_fail_domains dnslookup "domain list&!!" unset |
168e428f PH |
16674 | If the DNS lookup for MX records for one of the domains in this list causes a |
16675 | DNS lookup error, Exim behaves as if no MX records were found. See section | |
9b371988 | 16676 | &<<SECTprowitdnsloo>>& for more discussion. |
168e428f PH |
16677 | |
16678 | ||
16679 | ||
168e428f | 16680 | |
9b371988 PH |
16681 | .option qualify_single dnslookup boolean true |
16682 | .cindex "DNS" "resolver options" | |
16683 | .cindex "DNS" "qualifying single-component names" | |
168e428f PH |
16684 | When this option is true, the resolver option RES_DEFNAMES is set for DNS |
16685 | lookups. Typically, but not standardly, this causes the resolver to qualify | |
16686 | single-component names with the default domain. For example, on a machine | |
9b371988 PH |
16687 | called &'dictionary.ref.example'&, the domain &'thesaurus'& would be changed to |
16688 | &'thesaurus.ref.example'& inside the resolver. For details of what your | |
16689 | resolver actually does, consult your man pages for &'resolver'& and | |
16690 | &'resolv.conf'&. | |
168e428f PH |
16691 | |
16692 | ||
16693 | ||
9b371988 PH |
16694 | .option rewrite_headers dnslookup boolean true |
16695 | .cindex "rewriting" "header lines" | |
16696 | .cindex "header lines" "rewriting" | |
168e428f PH |
16697 | If the domain name in the address that is being processed is not fully |
16698 | qualified, it may be expanded to its full form by a DNS lookup. For example, if | |
9b371988 PH |
16699 | an address is specified as &'dormouse@teaparty'&, the domain might be |
16700 | expanded to &'teaparty.wonderland.fict.example'&. Domain expansion can also | |
16701 | occur as a result of setting the &%widen_domains%& option. If | |
16702 | &%rewrite_headers%& is true, all occurrences of the abbreviated domain name in | |
16703 | any &'Bcc:'&, &'Cc:'&, &'From:'&, &'Reply-to:'&, &'Sender:'&, and &'To:'& | |
16704 | header lines of the message are rewritten with the full domain name. | |
168e428f PH |
16705 | |
16706 | This option should be turned off only when it is known that no message is | |
16707 | ever going to be sent outside an environment where the abbreviation makes | |
16708 | sense. | |
16709 | ||
16710 | When an MX record is looked up in the DNS and matches a wildcard record, name | |
16711 | servers normally return a record containing the name that has been looked up, | |
16712 | making it impossible to detect whether a wildcard was present or not. However, | |
16713 | some name servers have recently been seen to return the wildcard entry. If the | |
16714 | name returned by a DNS lookup begins with an asterisk, it is not used for | |
16715 | header rewriting. | |
16716 | ||
16717 | ||
9b371988 PH |
16718 | .option same_domain_copy_routing dnslookup boolean false |
16719 | .cindex "address" "copying routing" | |
16720 | Addresses with the same domain are normally routed by the &(dnslookup)& router | |
168e428f PH |
16721 | to the same list of hosts. However, this cannot be presumed, because the router |
16722 | options and preconditions may refer to the local part of the address. By | |
16723 | default, therefore, Exim routes each address in a message independently. DNS | |
16724 | servers run caches, so repeated DNS lookups are not normally expensive, and in | |
16725 | any case, personal messages rarely have more than a few recipients. | |
16726 | ||
16727 | If you are running mailing lists with large numbers of subscribers at the same | |
9b371988 PH |
16728 | domain, and you are using a &(dnslookup)& router which is independent of the |
16729 | local part, you can set &%same_domain_copy_routing%& to bypass repeated DNS | |
16730 | lookups for identical domains in one message. In this case, when &(dnslookup)& | |
168e428f PH |
16731 | routes an address to a remote transport, any other unrouted addresses in the |
16732 | message that have the same domain are automatically given the same routing | |
16733 | without processing them independently, | |
16734 | provided the following conditions are met: | |
16735 | ||
9b371988 PH |
16736 | .ilist |
16737 | No router that processed the address specified &%headers_add%& or | |
16738 | &%headers_remove%&. | |
16739 | .next | |
16740 | The router did not change the address in any way, for example, by &"widening"& | |
168e428f | 16741 | the domain. |
9b371988 | 16742 | .endlist |
168e428f PH |
16743 | |
16744 | ||
16745 | ||
16746 | ||
9b371988 PH |
16747 | .option search_parents dnslookup boolean false |
16748 | .cindex "DNS" "resolver options" | |
168e428f | 16749 | When this option is true, the resolver option RES_DNSRCH is set for DNS |
9b371988 PH |
16750 | lookups. This is different from the &%qualify_single%& option in that it |
16751 | applies to domains containing dots. Typically, but not standardly, it causes | |
16752 | the resolver to search for the name in the current domain and in parent | |
16753 | domains. For example, on a machine in the &'fict.example'& domain, if looking | |
16754 | up &'teaparty.wonderland'& failed, the resolver would try | |
16755 | &'teaparty.wonderland.fict.example'&. For details of what your resolver | |
16756 | actually does, consult your man pages for &'resolver'& and &'resolv.conf'&. | |
168e428f PH |
16757 | |
16758 | Setting this option true can cause problems in domains that have a wildcard MX | |
16759 | record, because any domain that does not have its own MX record matches the | |
16760 | local wildcard. | |
16761 | ||
16762 | ||
16763 | ||
9b371988 | 16764 | .option srv_fail_domains dnslookup "domain list&!!" unset |
168e428f PH |
16765 | If the DNS lookup for SRV records for one of the domains in this list causes a |
16766 | DNS lookup error, Exim behaves as if no SRV records were found. See section | |
9b371988 | 16767 | &<<SECTprowitdnsloo>>& for more discussion. |
168e428f PH |
16768 | |
16769 | ||
16770 | ||
168e428f | 16771 | |
9b371988 PH |
16772 | .option widen_domains dnslookup "string list" unset |
16773 | .cindex "domain" "partial; widening" | |
168e428f PH |
16774 | If a DNS lookup fails and this option is set, each of its strings in turn is |
16775 | added onto the end of the domain, and the lookup is tried again. For example, | |
16776 | if | |
9b371988 PH |
16777 | .code |
16778 | widen_domains = fict.example:ref.example | |
16779 | .endd | |
16780 | is set and a lookup of &'klingon.dictionary'& fails, | |
16781 | &'klingon.dictionary.fict.example'& is looked up, and if this fails, | |
16782 | &'klingon.dictionary.ref.example'& is tried. Note that the &%qualify_single%& | |
16783 | and &%search_parents%& options can cause some widening to be undertaken inside | |
4f578862 PH |
16784 | the DNS resolver. &%widen_domains%& is not applied to sender addresses |
16785 | when verifying, unless &%rewrite_headers%& is false (not the default). | |
9b371988 PH |
16786 | |
16787 | ||
f89d2485 | 16788 | .section "Effect of qualify_single and search_parents" "SECID119" |
168e428f | 16789 | When a domain from an envelope recipient is changed by the resolver as a result |
9b371988 PH |
16790 | of the &%qualify_single%& or &%search_parents%& options, Exim rewrites the |
16791 | corresponding address in the message's header lines unless &%rewrite_headers%& | |
168e428f PH |
16792 | is set false. Exim then re-routes the address, using the full domain. |
16793 | ||
16794 | These two options affect only the DNS lookup that takes place inside the router | |
16795 | for the domain of the address that is being routed. They do not affect lookups | |
16796 | such as that implied by | |
9b371988 PH |
16797 | .code |
16798 | domains = @mx_any | |
16799 | .endd | |
168e428f PH |
16800 | that may happen while processing a router precondition before the router is |
16801 | entered. No widening ever takes place for these lookups. | |
4f578862 PH |
16802 | .ecindex IIDdnsrou1 |
16803 | .ecindex IIDdnsrou2 | |
168e428f PH |
16804 | |
16805 | ||
16806 | ||
16807 | ||
16808 | ||
16809 | ||
16810 | ||
16811 | ||
16812 | ||
9b371988 PH |
16813 | . //////////////////////////////////////////////////////////////////////////// |
16814 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 16815 | |
f89d2485 | 16816 | .chapter "The ipliteral router" "CHID5" |
9b371988 PH |
16817 | .cindex "&(ipliteral)& router" |
16818 | .cindex "domain literal" "routing" | |
16819 | .cindex "routers" "&(ipliteral)&" | |
168e428f | 16820 | This router has no private options. Unless it is being used purely for |
9b371988 PH |
16821 | verification (see &%verify_only%&) a transport is required to be defined by the |
16822 | generic &%transport%& option. The router accepts the address if its domain part | |
4f578862 PH |
16823 | takes the form of an RFC 2822 domain literal. For example, the &(ipliteral)& |
16824 | router handles the address | |
9b371988 PH |
16825 | .code |
16826 | root@[192.168.1.1] | |
16827 | .endd | |
4f578862 PH |
16828 | by setting up delivery to the host with that IP address. IPv4 domain literals |
16829 | consist of an IPv4 address enclosed in square brackets. IPv6 domain literals | |
16830 | are similar, but the address is preceded by &`ipv6:`&. For example: | |
16831 | .code | |
16832 | postmaster@[ipv6:fe80::a00:20ff:fe86:a061.5678] | |
16833 | .endd | |
16834 | Exim allows &`ipv4:`& before IPv4 addresses, for consistency, and on the | |
16835 | grounds that sooner or later somebody will try it. | |
168e428f | 16836 | |
0a4e3112 | 16837 | .oindex "&%self%&" "in &(ipliteral)& router" |
9b371988 | 16838 | If the IP address matches something in &%ignore_target_hosts%&, the router |
168e428f | 16839 | declines. If an IP literal turns out to refer to the local host, the generic |
9b371988 | 16840 | &%self%& option determines what happens. |
168e428f PH |
16841 | |
16842 | The RFCs require support for domain literals; however, their use is | |
16843 | controversial in today's Internet. If you want to use this router, you must | |
9b371988 | 16844 | also set the main configuration option &%allow_domain_literals%&. Otherwise, |
168e428f PH |
16845 | Exim will not recognize the domain literal syntax in addresses. |
16846 | ||
16847 | ||
16848 | ||
9b371988 PH |
16849 | . //////////////////////////////////////////////////////////////////////////// |
16850 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 16851 | |
f89d2485 | 16852 | .chapter "The iplookup router" "CHID6" |
9b371988 PH |
16853 | .cindex "&(iplookup)& router" |
16854 | .cindex "routers" "&(iplookup)&" | |
16855 | The &(iplookup)& router was written to fulfil a specific requirement in | |
168e428f PH |
16856 | Cambridge University (which in fact no longer exists). For this reason, it is |
16857 | not included in the binary of Exim by default. If you want to include it, you | |
16858 | must set | |
9b371988 PH |
16859 | .code |
16860 | ROUTER_IPLOOKUP=yes | |
16861 | .endd | |
16862 | in your &_Local/Makefile_& configuration file. | |
168e428f | 16863 | |
9b371988 | 16864 | The &(iplookup)& router routes an address by sending it over a TCP or UDP |
168e428f | 16865 | connection to one or more specific hosts. The host can then return the same or |
9b371988 | 16866 | a different address &-- in effect rewriting the recipient address in the |
168e428f PH |
16867 | message's envelope. The new address is then passed on to subsequent routers. If |
16868 | this process fails, the address can be passed on to other routers, or delivery | |
9b371988 PH |
16869 | can be deferred. Since &(iplookup)& is just a rewriting router, a transport |
16870 | must not be specified for it. | |
168e428f | 16871 | |
9b371988 PH |
16872 | .cindex "options" "&(iplookup)& router" |
16873 | .option hosts iplookup string unset | |
168e428f | 16874 | This option must be supplied. Its value is a colon-separated list of host |
9b371988 PH |
16875 | names. The hosts are looked up using &[gethostbyname()]& |
16876 | (or &[getipnodebyname()]& when available) | |
168e428f | 16877 | and are tried in order until one responds to the query. If none respond, what |
9b371988 | 16878 | happens is controlled by &%optional%&. |
168e428f PH |
16879 | |
16880 | ||
9b371988 PH |
16881 | .option optional iplookup boolean false |
16882 | If &%optional%& is true, if no response is obtained from any host, the address | |
16883 | is passed to the next router, overriding &%no_more%&. If &%optional%& is false, | |
168e428f PH |
16884 | delivery to the address is deferred. |
16885 | ||
16886 | ||
9b371988 PH |
16887 | .option port iplookup integer 0 |
16888 | .cindex "port" "&(iplookup)& router" | |
168e428f PH |
16889 | This option must be supplied. It specifies the port number for the TCP or UDP |
16890 | call. | |
16891 | ||
16892 | ||
9b371988 PH |
16893 | .option protocol iplookup string udp |
16894 | This option can be set to &"udp"& or &"tcp"& to specify which of the two | |
16895 | protocols is to be used. | |
168e428f | 16896 | |
168e428f | 16897 | |
f89d2485 | 16898 | .option query iplookup string&!! "see below" |
168e428f | 16899 | This defines the content of the query that is sent to the remote hosts. The |
f89d2485 PH |
16900 | default value is: |
16901 | .code | |
16902 | $local_part@$domain $local_part@$domain | |
16903 | .endd | |
16904 | The repetition serves as a way of checking that a response is to the correct | |
16905 | query in the default case (see &%response_pattern%& below). | |
168e428f PH |
16906 | |
16907 | ||
9b371988 | 16908 | .option reroute iplookup string&!! unset |
168e428f PH |
16909 | If this option is not set, the rerouted address is precisely the byte string |
16910 | returned by the remote host, up to the first white space, if any. If set, the | |
16911 | string is expanded to form the rerouted address. It can include parts matched | |
9b371988 PH |
16912 | in the response by &%response_pattern%& by means of numeric variables such as |
16913 | &$1$&, &$2$&, etc. The variable &$0$& refers to the entire input string, | |
168e428f | 16914 | whether or not a pattern is in use. In all cases, the rerouted address must end |
9b371988 | 16915 | up in the form &'local_part@domain'&. |
168e428f | 16916 | |
168e428f | 16917 | |
9b371988 | 16918 | .option response_pattern iplookup string unset |
168e428f PH |
16919 | This option can be set to a regular expression that is applied to the string |
16920 | returned from the remote host. If the pattern does not match the response, the | |
9b371988 PH |
16921 | router declines. If &%response_pattern%& is not set, no checking of the |
16922 | response is done, unless the query was defaulted, in which case there is a | |
16923 | check that the text returned after the first white space is the original | |
16924 | address. This checks that the answer that has been received is in response to | |
16925 | the correct question. For example, if the response is just a new domain, the | |
16926 | following could be used: | |
16927 | .code | |
16928 | response_pattern = ^([^@]+)$ | |
16929 | reroute = $local_part@$1 | |
16930 | .endd | |
16931 | ||
16932 | .option timeout iplookup time 5s | |
168e428f | 16933 | This specifies the amount of time to wait for a response from the remote |
9b371988 | 16934 | machine. The same timeout is used for the &[connect()]& function for a TCP |
168e428f PH |
16935 | call. It does not apply to UDP. |
16936 | ||
16937 | ||
16938 | ||
16939 | ||
9b371988 PH |
16940 | . //////////////////////////////////////////////////////////////////////////// |
16941 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 16942 | |
f89d2485 | 16943 | .chapter "The manualroute router" "CHID7" |
4f578862 PH |
16944 | .scindex IIDmanrou1 "&(manualroute)& router" |
16945 | .scindex IIDmanrou2 "routers" "&(manualroute)&" | |
9b371988 PH |
16946 | .cindex "domain" "manually routing" |
16947 | The &(manualroute)& router is so-called because it provides a way of manually | |
168e428f PH |
16948 | routing an address according to its domain. It is mainly used when you want to |
16949 | route addresses to remote hosts according to your own rules, bypassing the | |
9b371988 | 16950 | normal DNS routing that looks up MX records. However, &(manualroute)& can also |
168e428f PH |
16951 | route to local transports, a facility that may be useful if you want to save |
16952 | messages for dial-in hosts in local files. | |
16953 | ||
9b371988 PH |
16954 | The &(manualroute)& router compares a list of domain patterns with the domain |
16955 | it is trying to route. If there is no match, the router declines. Each pattern | |
16956 | has associated with it a list of hosts and some other optional data, which may | |
168e428f | 16957 | include a transport. The combination of a pattern and its data is called a |
9b371988 PH |
16958 | &"routing rule"&. For patterns that do not have an associated transport, the |
16959 | generic &%transport%& option must specify a transport, unless the router is | |
16960 | being used purely for verification (see &%verify_only%&). | |
168e428f | 16961 | |
f89d2485 | 16962 | .vindex "&$host$&" |
168e428f PH |
16963 | In the case of verification, matching the domain pattern is sufficient for the |
16964 | router to accept the address. When actually routing an address for delivery, | |
16965 | an address that matches a domain pattern is queued for the associated | |
16966 | transport. If the transport is not a local one, a host list must be associated | |
16967 | with the pattern; IP addresses are looked up for the hosts, and these are | |
16968 | passed to the transport along with the mail address. For local transports, a | |
9b371988 | 16969 | host list is optional. If it is present, it is passed in &$host$& as a single |
168e428f PH |
16970 | text string. |
16971 | ||
9b371988 PH |
16972 | The list of routing rules can be provided as an inline string in |
16973 | &%route_list%&, or the data can be obtained by looking up the domain in a file | |
16974 | or database by setting &%route_data%&. Only one of these settings may appear in | |
16975 | any one instance of &(manualroute)&. The format of routing rules is described | |
16976 | below, following the list of private options. | |
168e428f | 16977 | |
168e428f | 16978 | |
9b371988 | 16979 | .section "Private options for manualroute" "SECTprioptman" |
168e428f | 16980 | |
9b371988 PH |
16981 | .cindex "options" "&(manualroute)& router" |
16982 | The private options for the &(manualroute)& router are as follows: | |
168e428f | 16983 | |
f89d2485 PH |
16984 | .option host_all_ignored manualroute string defer |
16985 | See &%host_find_failed%&. | |
168e428f | 16986 | |
9b371988 PH |
16987 | .option host_find_failed manualroute string freeze |
16988 | This option controls what happens when &(manualroute)& tries to find an IP | |
168e428f | 16989 | address for a host, and the host does not exist. The option can be set to one |
f89d2485 | 16990 | of the following values: |
9b371988 PH |
16991 | .code |
16992 | decline | |
16993 | defer | |
16994 | fail | |
16995 | freeze | |
f89d2485 | 16996 | ignore |
9b371988 PH |
16997 | pass |
16998 | .endd | |
f89d2485 PH |
16999 | The default (&"freeze"&) assumes that this state is a serious configuration |
17000 | error. The difference between &"pass"& and &"decline"& is that the former | |
17001 | forces the address to be passed to the next router (or the router defined by | |
9b371988 | 17002 | &%pass_router%&), |
0a4e3112 | 17003 | .oindex "&%more%&" |
9b371988 PH |
17004 | overriding &%no_more%&, whereas the latter passes the address to the next |
17005 | router only if &%more%& is true. | |
168e428f | 17006 | |
f89d2485 PH |
17007 | The value &"ignore"& causes Exim to completely ignore a host whose IP address |
17008 | cannot be found. If all the hosts in the list are ignored, the behaviour is | |
17009 | controlled by the &%host_all_ignored%& option. This takes the same values | |
17010 | as &%host_find_failed%&, except that it cannot be set to &"ignore"&. | |
17011 | ||
17012 | The &%host_find_failed%& option applies only to a definite &"does not exist"& | |
17013 | state; if a host lookup gets a temporary error, delivery is deferred unless the | |
17014 | generic &%pass_on_timeout%& option is set. | |
168e428f | 17015 | |
168e428f | 17016 | |
9b371988 PH |
17017 | .option hosts_randomize manualroute boolean false |
17018 | .cindex "randomized host list" | |
17019 | .cindex "host" "list of; randomized" | |
168e428f PH |
17020 | If this option is set, the order of the items in a host list in a routing rule |
17021 | is randomized each time the list is used, unless an option in the routing rule | |
17022 | overrides (see below). Randomizing the order of a host list can be used to do | |
17023 | crude load sharing. However, if more than one mail address is routed by the | |
17024 | same router to the same host list, the host lists are considered to be the same | |
17025 | (even though they may be randomized into different orders) for the purpose of | |
17026 | deciding whether to batch the deliveries into a single SMTP transaction. | |
17027 | ||
9b371988 | 17028 | When &%hosts_randomize%& is true, a host list may be split |
168e428f PH |
17029 | into groups whose order is separately randomized. This makes it possible to |
17030 | set up MX-like behaviour. The boundaries between groups are indicated by an | |
9b371988 PH |
17031 | item that is just &`+`& in the host list. For example: |
17032 | .code | |
17033 | route_list = * host1:host2:host3:+:host4:host5 | |
17034 | .endd | |
168e428f PH |
17035 | The order of the first three hosts and the order of the last two hosts is |
17036 | randomized for each use, but the first three always end up before the last two. | |
9b371988 PH |
17037 | If &%hosts_randomize%& is not set, a &`+`& item in the list is ignored. If a |
17038 | randomized host list is passed to an &(smtp)& transport that also has | |
17039 | &%hosts_randomize set%&, the list is not re-randomized. | |
168e428f PH |
17040 | |
17041 | ||
9b371988 | 17042 | .option route_data manualroute string&!! unset |
168e428f PH |
17043 | If this option is set, it must expand to yield the data part of a routing rule. |
17044 | Typically, the expansion string includes a lookup based on the domain. For | |
17045 | example: | |
9b371988 PH |
17046 | .code |
17047 | route_data = ${lookup{$domain}dbm{/etc/routes}} | |
17048 | .endd | |
168e428f PH |
17049 | If the expansion is forced to fail, or the result is an empty string, the |
17050 | router declines. Other kinds of expansion failure cause delivery to be | |
17051 | deferred. | |
17052 | ||
17053 | ||
0a4e3112 | 17054 | .option route_list manualroute "string list" unset |
168e428f PH |
17055 | This string is a list of routing rules, in the form defined below. Note that, |
17056 | unlike most string lists, the items are separated by semicolons. This is so | |
17057 | that they may contain colon-separated host lists. | |
17058 | ||
17059 | ||
9b371988 PH |
17060 | .option same_domain_copy_routing manualroute boolean false |
17061 | .cindex "address" "copying routing" | |
17062 | Addresses with the same domain are normally routed by the &(manualroute)& | |
17063 | router to the same list of hosts. However, this cannot be presumed, because the | |
17064 | router options and preconditions may refer to the local part of the address. By | |
168e428f PH |
17065 | default, therefore, Exim routes each address in a message independently. DNS |
17066 | servers run caches, so repeated DNS lookups are not normally expensive, and in | |
17067 | any case, personal messages rarely have more than a few recipients. | |
17068 | ||
17069 | If you are running mailing lists with large numbers of subscribers at the same | |
9b371988 PH |
17070 | domain, and you are using a &(manualroute)& router which is independent of the |
17071 | local part, you can set &%same_domain_copy_routing%& to bypass repeated DNS | |
17072 | lookups for identical domains in one message. In this case, when | |
17073 | &(manualroute)& routes an address to a remote transport, any other unrouted | |
17074 | addresses in the message that have the same domain are automatically given the | |
17075 | same routing without processing them independently. However, this is only done | |
17076 | if &%headers_add%& and &%headers_remove%& are unset. | |
168e428f PH |
17077 | |
17078 | ||
17079 | ||
17080 | ||
f89d2485 | 17081 | .section "Routing rules in route_list" "SECID120" |
9b371988 | 17082 | The value of &%route_list%& is a string consisting of a sequence of routing |
168e428f | 17083 | rules, separated by semicolons. If a semicolon is needed in a rule, it can be |
068aaea8 | 17084 | entered as two semicolons. Alternatively, the list separator can be changed as |
9b371988 | 17085 | described (for colon-separated lists) in section &<<SECTlistconstruct>>&. |
068aaea8 | 17086 | Empty rules are ignored. The format of each rule is |
9b371988 PH |
17087 | .display |
17088 | <&'domain pattern'&> <&'list of hosts'&> <&'options'&> | |
17089 | .endd | |
168e428f PH |
17090 | The following example contains two rules, each with a simple domain pattern and |
17091 | no options: | |
9b371988 | 17092 | .code |
168e428f PH |
17093 | route_list = \ |
17094 | dict.ref.example mail-1.ref.example:mail-2.ref.example ; \ | |
17095 | thes.ref.example mail-3.ref.example:mail-4.ref.example | |
9b371988 | 17096 | .endd |
168e428f PH |
17097 | The three parts of a rule are separated by white space. The pattern and the |
17098 | list of hosts can be enclosed in quotes if necessary, and if they are, the | |
9b371988 | 17099 | usual quoting rules apply. Each rule in a &%route_list%& must start with a |
168e428f PH |
17100 | single domain pattern, which is the only mandatory item in the rule. The |
17101 | pattern is in the same format as one item in a domain list (see section | |
9b371988 | 17102 | &<<SECTdomainlist>>&), |
168e428f PH |
17103 | except that it may not be the name of an interpolated file. |
17104 | That is, it may be wildcarded, or a regular expression, or a file or database | |
17105 | lookup (with semicolons doubled, because of the use of semicolon as a separator | |
9b371988 | 17106 | in a &%route_list%&). |
168e428f | 17107 | |
9b371988 | 17108 | The rules in &%route_list%& are searched in order until one of the patterns |
168e428f PH |
17109 | matches the domain that is being routed. The list of hosts and then options are |
17110 | then used as described below. If there is no match, the router declines. When | |
9b371988 | 17111 | &%route_list%& is set, &%route_data%& must not be set. |
168e428f PH |
17112 | |
17113 | ||
17114 | ||
f89d2485 | 17115 | .section "Routing rules in route_data" "SECID121" |
9b371988 | 17116 | The use of &%route_list%& is convenient when there are only a small number of |
168e428f | 17117 | routing rules. For larger numbers, it is easier to use a file or database to |
9b371988 PH |
17118 | hold the routing information, and use the &%route_data%& option instead. |
17119 | The value of &%route_data%& is a list of hosts, followed by (optional) options. | |
17120 | Most commonly, &%route_data%& is set as a string that contains an | |
168e428f PH |
17121 | expansion lookup. For example, suppose we place two routing rules in a file |
17122 | like this: | |
9b371988 PH |
17123 | .code |
17124 | dict.ref.example: mail-1.ref.example:mail-2.ref.example | |
17125 | thes.ref.example: mail-3.ref.example:mail-4.ref.example | |
17126 | .endd | |
168e428f | 17127 | This data can be accessed by setting |
9b371988 PH |
17128 | .code |
17129 | route_data = ${lookup{$domain}lsearch{/the/file/name}} | |
17130 | .endd | |
168e428f | 17131 | Failure of the lookup results in an empty string, causing the router to |
9b371988 | 17132 | decline. However, you do not have to use a lookup in &%route_data%&. The only |
168e428f PH |
17133 | requirement is that the result of expanding the string is a list of hosts, |
17134 | possibly followed by options, separated by white space. The list of hosts must | |
17135 | be enclosed in quotes if it contains white space. | |
17136 | ||
17137 | ||
17138 | ||
17139 | ||
f89d2485 | 17140 | .section "Format of the list of hosts" "SECID122" |
9b371988 PH |
17141 | A list of hosts, whether obtained via &%route_data%& or &%route_list%&, is |
17142 | always separately expanded before use. If the expansion fails, the router | |
17143 | declines. The result of the expansion must be a colon-separated list of names | |
17144 | and/or IP addresses, optionally also including ports. The format of each item | |
17145 | in the list is described in the next section. The list separator can be changed | |
17146 | as described in section &<<SECTlistconstruct>>&. | |
168e428f | 17147 | |
9b371988 | 17148 | If the list of hosts was obtained from a &%route_list%& item, the following |
168e428f PH |
17149 | variables are set during its expansion: |
17150 | ||
9b371988 PH |
17151 | .ilist |
17152 | .cindex "numerical variables (&$1$& &$2$& etc)" "in &(manualroute)& router" | |
168e428f | 17153 | If the domain was matched against a regular expression, the numeric variables |
9b371988 PH |
17154 | &$1$&, &$2$&, etc. may be set. For example: |
17155 | .code | |
17156 | route_list = ^domain(\d+) host-$1.text.example | |
17157 | .endd | |
17158 | .next | |
17159 | &$0$& is always set to the entire domain. | |
17160 | .next | |
17161 | &$1$& is also set when partial matching is done in a file lookup. | |
17162 | ||
17163 | .next | |
f89d2485 | 17164 | .vindex "&$value$&" |
168e428f | 17165 | If the pattern that matched the domain was a lookup item, the data that was |
9b371988 PH |
17166 | looked up is available in the expansion variable &$value$&. For example: |
17167 | .code | |
17168 | route_list = lsearch;;/some/file.routes $value | |
17169 | .endd | |
17170 | .endlist | |
068aaea8 PH |
17171 | |
17172 | Note the doubling of the semicolon in the pattern that is necessary because | |
17173 | semicolon is the default route list separator. | |
17174 | ||
17175 | ||
17176 | ||
9b371988 | 17177 | .section "Format of one host item" "SECTformatonehostitem" |
068aaea8 PH |
17178 | Each item in the list of hosts is either a host name or an IP address, |
17179 | optionally with an attached port number. When no port is given, an IP address | |
17180 | is not enclosed in brackets. When a port is specified, it overrides the port | |
17181 | specification on the transport. The port is separated from the name or address | |
17182 | by a colon. This leads to some complications: | |
168e428f | 17183 | |
9b371988 PH |
17184 | .ilist |
17185 | Because colon is the default separator for the list of hosts, either | |
068aaea8 PH |
17186 | the colon that specifies a port must be doubled, or the list separator must |
17187 | be changed. The following two examples have the same effect: | |
9b371988 PH |
17188 | .code |
17189 | route_list = * "host1.tld::1225 : host2.tld::1226" | |
17190 | route_list = * "<+ host1.tld:1225 + host2.tld:1226" | |
17191 | .endd | |
17192 | .next | |
17193 | When IPv6 addresses are involved, it gets worse, because they contain | |
068aaea8 PH |
17194 | colons of their own. To make this case easier, it is permitted to |
17195 | enclose an IP address (either v4 or v6) in square brackets if a port | |
17196 | number follows. For example: | |
9b371988 PH |
17197 | .code |
17198 | route_list = * "</ [10.1.1.1]:1225 / [::1]:1226" | |
17199 | .endd | |
17200 | .endlist | |
9b371988 PH |
17201 | |
17202 | .section "How the list of hosts is used" "SECThostshowused" | |
17203 | When an address is routed to an &(smtp)& transport by &(manualroute)&, each of | |
168e428f | 17204 | the hosts is tried, in the order specified, when carrying out the SMTP |
9b371988 PH |
17205 | delivery. However, the order can be changed by setting the &%hosts_randomize%& |
17206 | option, either on the router (see section &<<SECTprioptman>>& above), or on the | |
168e428f PH |
17207 | transport. |
17208 | ||
17209 | Hosts may be listed by name or by IP address. An unadorned name in the list of | |
9b371988 | 17210 | hosts is interpreted as a host name. A name that is followed by &`/MX`& is |
168e428f PH |
17211 | interpreted as an indirection to a sublist of hosts obtained by looking up MX |
17212 | records in the DNS. For example: | |
9b371988 PH |
17213 | .code |
17214 | route_list = * x.y.z:p.q.r/MX:e.f.g | |
17215 | .endd | |
068aaea8 PH |
17216 | If this feature is used with a port specifier, the port must come last. For |
17217 | example: | |
9b371988 PH |
17218 | .code |
17219 | route_list = * dom1.tld/mx::1225 | |
17220 | .endd | |
9b371988 | 17221 | If the &%hosts_randomize%& option is set, the order of the items in the list is |
168e428f | 17222 | randomized before any lookups are done. Exim then scans the list; for any name |
9b371988 | 17223 | that is not followed by &`/MX`& it looks up an IP address. If this turns out to |
168e428f PH |
17224 | be an interface on the local host and the item is not the first in the list, |
17225 | Exim discards it and any subsequent items. If it is the first item, what | |
17226 | happens is controlled by the | |
0a4e3112 | 17227 | .oindex "&%self%&" "in &(manualroute)& router" |
9b371988 | 17228 | &%self%& option of the router. |
168e428f | 17229 | |
9b371988 | 17230 | A name on the list that is followed by &`/MX`& is replaced with the list of |
168e428f | 17231 | hosts obtained by looking up MX records for the name. This is always a DNS |
9b371988 PH |
17232 | lookup; the &%bydns%& and &%byname%& options (see section &<<SECThowoptused>>& |
17233 | below) are not relevant here. The order of these hosts is determined by the | |
17234 | preference values in the MX records, according to the usual rules. Because | |
17235 | randomizing happens before the MX lookup, it does not affect the order that is | |
17236 | defined by MX preferences. | |
168e428f PH |
17237 | |
17238 | If the local host is present in the sublist obtained from MX records, but is | |
17239 | not the most preferred host in that list, it and any equally or less | |
17240 | preferred hosts are removed before the sublist is inserted into the main list. | |
17241 | ||
17242 | If the local host is the most preferred host in the MX list, what happens | |
9b371988 | 17243 | depends on where in the original list of hosts the &`/MX`& item appears. If it |
168e428f PH |
17244 | is not the first item (that is, there are previous hosts in the main list), |
17245 | Exim discards this name and any subsequent items in the main list. | |
17246 | ||
17247 | If the MX item is first in the list of hosts, and the local host is the | |
9b371988 | 17248 | most preferred host, what happens is controlled by the &%self%& option of the |
168e428f PH |
17249 | router. |
17250 | ||
17251 | DNS failures when lookup up the MX records are treated in the same way as DNS | |
9b371988 PH |
17252 | failures when looking up IP addresses: &%pass_on_timeout%& and |
17253 | &%host_find_failed%& are used when relevant. | |
168e428f | 17254 | |
9b371988 | 17255 | The generic &%ignore_target_hosts%& option applies to all hosts in the list, |
168e428f PH |
17256 | whether obtained from an MX lookup or not. |
17257 | ||
17258 | ||
17259 | ||
9b371988 | 17260 | .section "How the options are used" "SECThowoptused" |
168e428f PH |
17261 | The options are a sequence of words; in practice no more than three are ever |
17262 | present. One of the words can be the name of a transport; this overrides the | |
9b371988 | 17263 | &%transport%& option on the router for this particular routing rule only. The |
168e428f PH |
17264 | other words (if present) control randomization of the list of hosts on a |
17265 | per-rule basis, and how the IP addresses of the hosts are to be found when | |
17266 | routing to a remote transport. These options are as follows: | |
17267 | ||
9b371988 PH |
17268 | .ilist |
17269 | &%randomize%&: randomize the order of the hosts in this list, overriding the | |
17270 | setting of &%hosts_randomize%& for this routing rule only. | |
17271 | .next | |
17272 | &%no_randomize%&: do not randomize the order of the hosts in this list, | |
17273 | overriding the setting of &%hosts_randomize%& for this routing rule only. | |
17274 | .next | |
17275 | &%byname%&: use &[getipnodebyname()]& (&[gethostbyname()]& on older systems) to | |
168e428f | 17276 | find IP addresses. This function may ultimately cause a DNS lookup, but it may |
9b371988 PH |
17277 | also look in &_/etc/hosts_& or other sources of information. |
17278 | .next | |
17279 | &%bydns%&: look up address records for the hosts directly in the DNS; fail if | |
168e428f PH |
17280 | no address records are found. If there is a temporary DNS error (such as a |
17281 | timeout), delivery is deferred. | |
9b371988 | 17282 | .endlist |
168e428f PH |
17283 | |
17284 | For example: | |
9b371988 | 17285 | .code |
168e428f PH |
17286 | route_list = domain1 host1:host2:host3 randomize bydns;\ |
17287 | domain2 host4:host5 | |
9b371988 PH |
17288 | .endd |
17289 | If neither &%byname%& nor &%bydns%& is given, Exim behaves as follows: First, a | |
17290 | DNS lookup is done. If this yields anything other than HOST_NOT_FOUND, that | |
17291 | result is used. Otherwise, Exim goes on to try a call to &[getipnodebyname()]& | |
17292 | or &[gethostbyname()]&, and the result of the lookup is the result of that | |
168e428f PH |
17293 | call. |
17294 | ||
9b371988 PH |
17295 | &*Warning*&: It has been discovered that on some systems, if a DNS lookup |
17296 | called via &[getipnodebyname()]& times out, HOST_NOT_FOUND is returned | |
168e428f | 17297 | instead of TRY_AGAIN. That is why the default action is to try a DNS |
9b371988 | 17298 | lookup first. Only if that gives a definite &"no such host"& is the local |
168e428f PH |
17299 | function called. |
17300 | ||
17301 | ||
17302 | ||
17303 | If no IP address for a host can be found, what happens is controlled by the | |
9b371988 | 17304 | &%host_find_failed%& option. |
168e428f | 17305 | |
f89d2485 | 17306 | .vindex "&$host$&" |
168e428f | 17307 | When an address is routed to a local transport, IP addresses are not looked up. |
9b371988 | 17308 | The host list is passed to the transport in the &$host$& variable. |
168e428f PH |
17309 | |
17310 | ||
17311 | ||
f89d2485 | 17312 | .section "Manualroute examples" "SECID123" |
9b371988 | 17313 | In some of the examples that follow, the presence of the &%remote_smtp%& |
168e428f PH |
17314 | transport, as defined in the default configuration file, is assumed: |
17315 | ||
9b371988 PH |
17316 | .ilist |
17317 | .cindex "smart host" "example router" | |
17318 | The &(manualroute)& router can be used to forward all external mail to a | |
17319 | &'smart host'&. If you have set up, in the main part of the configuration, a | |
17320 | named domain list that contains your local domains, for example: | |
17321 | .code | |
17322 | domainlist local_domains = my.domain.example | |
17323 | .endd | |
17324 | You can arrange for all other domains to be routed to a smart host by making | |
168e428f | 17325 | your first router something like this: |
9b371988 PH |
17326 | .code |
17327 | smart_route: | |
17328 | driver = manualroute | |
17329 | domains = !+local_domains | |
17330 | transport = remote_smtp | |
17331 | route_list = * smarthost.ref.example | |
17332 | .endd | |
168e428f | 17333 | This causes all non-local addresses to be sent to the single host |
9b371988 | 17334 | &'smarthost.ref.example'&. If a colon-separated list of smart hosts is given, |
168e428f | 17335 | they are tried in order |
9b371988 | 17336 | (but you can use &%hosts_randomize%& to vary the order each time). |
168e428f | 17337 | Another way of configuring the same thing is this: |
9b371988 PH |
17338 | .code |
17339 | smart_route: | |
17340 | driver = manualroute | |
17341 | transport = remote_smtp | |
17342 | route_list = !+local_domains smarthost.ref.example | |
17343 | .endd | |
168e428f | 17344 | There is no difference in behaviour between these two routers as they stand. |
9b371988 PH |
17345 | However, they behave differently if &%no_more%& is added to them. In the first |
17346 | example, the router is skipped if the domain does not match the &%domains%& | |
168e428f | 17347 | precondition; the following router is always tried. If the router runs, it |
9b371988 PH |
17348 | always matches the domain and so can never decline. Therefore, &%no_more%& |
17349 | would have no effect. In the second case, the router is never skipped; it | |
17350 | always runs. However, if it doesn't match the domain, it declines. In this case | |
17351 | &%no_more%& would prevent subsequent routers from running. | |
17352 | ||
17353 | .next | |
17354 | .cindex "mail hub example" | |
17355 | A &'mail hub'& is a host which receives mail for a number of domains via MX | |
168e428f PH |
17356 | records in the DNS and delivers it via its own private routing mechanism. Often |
17357 | the final destinations are behind a firewall, with the mail hub being the one | |
17358 | machine that can connect to machines both inside and outside the firewall. The | |
9b371988 | 17359 | &(manualroute)& router is usually used on a mail hub to route incoming messages |
168e428f | 17360 | to the correct hosts. For a small number of domains, the routing can be inline, |
9b371988 | 17361 | using the &%route_list%& option, but for a larger number a file or database |
168e428f | 17362 | lookup is easier to manage. |
9b371988 | 17363 | |
168e428f PH |
17364 | If the domain names are in fact the names of the machines to which the mail is |
17365 | to be sent by the mail hub, the configuration can be quite simple. For | |
9b371988 PH |
17366 | example: |
17367 | .code | |
17368 | hub_route: | |
17369 | driver = manualroute | |
17370 | transport = remote_smtp | |
17371 | route_list = *.rhodes.tvs.example $domain | |
17372 | .endd | |
17373 | This configuration routes domains that match &`*.rhodes.tvs.example`& to hosts | |
168e428f PH |
17374 | whose names are the same as the mail domains. A similar approach can be taken |
17375 | if the host name can be obtained from the domain name by a string manipulation | |
17376 | that the expansion facilities can handle. Otherwise, a lookup based on the | |
17377 | domain can be used to find the host: | |
9b371988 PH |
17378 | .code |
17379 | through_firewall: | |
17380 | driver = manualroute | |
17381 | transport = remote_smtp | |
17382 | route_data = ${lookup {$domain} cdb {/internal/host/routes}} | |
17383 | .endd | |
168e428f PH |
17384 | The result of the lookup must be the name or IP address of the host (or |
17385 | hosts) to which the address is to be routed. If the lookup fails, the route | |
17386 | data is empty, causing the router to decline. The address then passes to the | |
17387 | next router. | |
17388 | ||
9b371988 PH |
17389 | .next |
17390 | .cindex "batched SMTP output example" | |
17391 | .cindex "SMTP" "batched outgoing; example" | |
17392 | You can use &(manualroute)& to deliver messages to pipes or files in batched | |
168e428f PH |
17393 | SMTP format for onward transportation by some other means. This is one way of |
17394 | storing mail for a dial-up host when it is not connected. The route list entry | |
17395 | can be as simple as a single domain name in a configuration like this: | |
9b371988 PH |
17396 | .code |
17397 | save_in_file: | |
17398 | driver = manualroute | |
17399 | transport = batchsmtp_appendfile | |
17400 | route_list = saved.domain.example | |
17401 | .endd | |
168e428f PH |
17402 | though often a pattern is used to pick up more than one domain. If there are |
17403 | several domains or groups of domains with different transport requirements, | |
17404 | different transports can be listed in the routing information: | |
9b371988 | 17405 | .code |
168e428f PH |
17406 | save_in_file: |
17407 | driver = manualroute | |
17408 | route_list = \ | |
17409 | *.saved.domain1.example $domain batch_appendfile; \ | |
17410 | *.saved.domain2.example \ | |
17411 | ${lookup{$domain}dbm{/domain2/hosts}{$value}fail} \ | |
17412 | batch_pipe | |
9b371988 | 17413 | .endd |
f89d2485 PH |
17414 | .vindex "&$domain$&" |
17415 | .vindex "&$host$&" | |
9b371988 PH |
17416 | The first of these just passes the domain in the &$host$& variable, which |
17417 | doesn't achieve much (since it is also in &$domain$&), but the second does a | |
168e428f PH |
17418 | file lookup to find a value to pass, causing the router to decline to handle |
17419 | the address if the lookup fails. | |
17420 | ||
9b371988 PH |
17421 | .next |
17422 | .cindex "UUCP" "example of router for" | |
168e428f | 17423 | Routing mail directly to UUCP software is a specific case of the use of |
9b371988 | 17424 | &(manualroute)& in a gateway to another mail environment. This is an example of |
168e428f | 17425 | one way it can be done: |
9b371988 | 17426 | .code |
168e428f PH |
17427 | # Transport |
17428 | uucp: | |
17429 | driver = pipe | |
17430 | user = nobody | |
17431 | command = /usr/local/bin/uux -r - \ | |
17432 | ${substr_-5:$host}!rmail ${local_part} | |
17433 | return_fail_output = true | |
17434 | ||
17435 | # Router | |
17436 | uucphost: | |
17437 | transport = uucp | |
17438 | driver = manualroute | |
17439 | route_data = \ | |
17440 | ${lookup{$domain}lsearch{/usr/local/exim/uucphosts}} | |
9b371988 PH |
17441 | .endd |
17442 | The file &_/usr/local/exim/uucphosts_& contains entries like | |
17443 | .code | |
17444 | darksite.ethereal.example: darksite.UUCP | |
17445 | .endd | |
17446 | It can be set up more simply without adding and removing &".UUCP"& but this way | |
168e428f | 17447 | makes clear the distinction between the domain name |
9b371988 PH |
17448 | &'darksite.ethereal.example'& and the UUCP host name &'darksite'&. |
17449 | .endlist | |
4f578862 PH |
17450 | .ecindex IIDmanrou1 |
17451 | .ecindex IIDmanrou2 | |
168e428f PH |
17452 | |
17453 | ||
17454 | ||
17455 | ||
17456 | ||
17457 | ||
17458 | ||
17459 | ||
9b371988 PH |
17460 | . //////////////////////////////////////////////////////////////////////////// |
17461 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 17462 | |
9b371988 | 17463 | .chapter "The queryprogram router" "CHAPdriverlast" |
4f578862 PH |
17464 | .scindex IIDquerou1 "&(queryprogram)& router" |
17465 | .scindex IIDquerou2 "routers" "&(queryprogram)&" | |
9b371988 PH |
17466 | .cindex "routing" "by external program" |
17467 | The &(queryprogram)& router routes an address by running an external command | |
17468 | and acting on its output. This is an expensive way to route, and is intended | |
17469 | mainly for use in lightly-loaded systems, or for performing experiments. | |
17470 | However, if it is possible to use the precondition options (&%domains%&, | |
17471 | &%local_parts%&, etc) to skip this router for most addresses, it could sensibly | |
17472 | be used in special cases, even on a busy host. There are the following private | |
17473 | options: | |
17474 | .cindex "options" "&(queryprogram)& router" | |
168e428f | 17475 | |
9b371988 | 17476 | .option command queryprogram string&!! unset |
168e428f PH |
17477 | This option must be set. It specifies the command that is to be run. The |
17478 | command is split up into a command name and arguments, and then each is | |
9b371988 PH |
17479 | expanded separately (exactly as for a &(pipe)& transport, described in chapter |
17480 | &<<CHAPpipetransport>>&). | |
168e428f | 17481 | |
168e428f | 17482 | |
9b371988 PH |
17483 | .option command_group queryprogram string unset |
17484 | .cindex "gid (group id)" "in &(queryprogram)& router" | |
4f578862 PH |
17485 | This option specifies a gid to be set when running the command while routing an |
17486 | address for deliver. It must be set if &%command_user%& specifies a numerical | |
17487 | uid. If it begins with a digit, it is interpreted as the numerical value of the | |
17488 | gid. Otherwise it is looked up using &[getgrnam()]&. | |
168e428f PH |
17489 | |
17490 | ||
9b371988 PH |
17491 | .option command_user queryprogram string unset |
17492 | .cindex "uid (user id)" "for &(queryprogram)&" | |
168e428f | 17493 | This option must be set. It specifies the uid which is set when running the |
4f578862 PH |
17494 | command while routing an address for delivery. If the value begins with a digit, |
17495 | it is interpreted as the numerical value of the uid. Otherwise, it is looked up | |
17496 | using &[getpwnam()]& to obtain a value for the uid and, if &%command_group%& is | |
17497 | not set, a value for the gid also. | |
17498 | ||
17499 | &*Warning:*& Changing uid and gid is possible only when Exim is running as | |
17500 | root, which it does during a normal delivery in a conventional configuration. | |
17501 | However, when an address is being verified during message reception, Exim is | |
17502 | usually running as the Exim user, not as root. If the &(queryprogram)& router | |
17503 | is called from a non-root process, Exim cannot change uid or gid before running | |
17504 | the command. In this circumstance the command runs under the current uid and | |
17505 | gid. | |
168e428f | 17506 | |
168e428f | 17507 | |
9b371988 | 17508 | .option current_directory queryprogram string / |
168e428f PH |
17509 | This option specifies an absolute path which is made the current directory |
17510 | before running the command. | |
17511 | ||
17512 | ||
9b371988 | 17513 | .option timeout queryprogram time 1h |
168e428f PH |
17514 | If the command does not complete within the timeout period, its process group |
17515 | is killed and the message is frozen. A value of zero time specifies no | |
17516 | timeout. | |
17517 | ||
17518 | ||
17519 | The standard output of the command is connected to a pipe, which is read when | |
17520 | the command terminates. It should consist of a single line of output, | |
17521 | containing up to five fields, separated by white space. The maximum length of | |
17522 | the line is 1023 characters. Longer lines are silently truncated. The first | |
17523 | field is one of the following words (case-insensitive): | |
17524 | ||
9b371988 PH |
17525 | .ilist |
17526 | &'Accept'&: routing succeeded; the remaining fields specify what to do (see | |
168e428f | 17527 | below). |
9b371988 PH |
17528 | .next |
17529 | &'Decline'&: the router declines; pass the address to the next router, unless | |
17530 | &%no_more%& is set. | |
17531 | .next | |
17532 | &'Fail'&: routing failed; do not pass the address to any more routers. Any | |
168e428f PH |
17533 | subsequent text on the line is an error message. If the router is run as part |
17534 | of address verification during an incoming SMTP message, the message is | |
17535 | included in the SMTP response. | |
9b371988 PH |
17536 | .next |
17537 | &'Defer'&: routing could not be completed at this time; try again later. Any | |
168e428f PH |
17538 | subsequent text on the line is an error message which is logged. It is not |
17539 | included in any SMTP response. | |
9b371988 PH |
17540 | .next |
17541 | &'Freeze'&: the same as &'defer'&, except that the message is frozen. | |
17542 | .next | |
17543 | &'Pass'&: pass the address to the next router (or the router specified by | |
17544 | &%pass_router%&), overriding &%no_more%&. | |
17545 | .next | |
17546 | &'Redirect'&: the message is redirected. The remainder of the line is a list of | |
168e428f | 17547 | new addresses, which are routed independently, starting with the first router, |
9b371988 PH |
17548 | or the router specified by &%redirect_router%&, if set. |
17549 | .endlist | |
168e428f | 17550 | |
9b371988 | 17551 | When the first word is &'accept'&, the remainder of the line consists of a |
168e428f PH |
17552 | number of keyed data values, as follows (split into two lines here, to fit on |
17553 | the page): | |
9b371988 PH |
17554 | .code |
17555 | ACCEPT TRANSPORT=<transport> HOSTS=<list of hosts> | |
17556 | LOOKUP=byname|bydns DATA=<text> | |
17557 | .endd | |
168e428f | 17558 | The data items can be given in any order, and all are optional. If no transport |
9b371988 PH |
17559 | is included, the transport specified by the generic &%transport%& option is |
17560 | used. The list of hosts and the lookup type are needed only if the transport is | |
17561 | an &(smtp)& transport that does not itself supply a list of hosts. | |
168e428f | 17562 | |
9b371988 | 17563 | The format of the list of hosts is the same as for the &(manualroute)& router. |
068aaea8 | 17564 | As well as host names and IP addresses with optional port numbers, as described |
9b371988 PH |
17565 | in section &<<SECTformatonehostitem>>&, it may contain names followed by |
17566 | &`/MX`& to specify sublists of hosts that are obtained by looking up MX records | |
17567 | (see section &<<SECThostshowused>>&). | |
168e428f PH |
17568 | |
17569 | If the lookup type is not specified, Exim behaves as follows when trying to | |
17570 | find an IP address for each host: First, a DNS lookup is done. If this yields | |
17571 | anything other than HOST_NOT_FOUND, that result is used. Otherwise, Exim | |
9b371988 | 17572 | goes on to try a call to &[getipnodebyname()]& or &[gethostbyname()]&, and the |
168e428f PH |
17573 | result of the lookup is the result of that call. |
17574 | ||
f89d2485 | 17575 | .vindex "&$address_data$&" |
9b371988 | 17576 | If the DATA field is set, its value is placed in the &$address_data$& |
168e428f | 17577 | variable. For example, this return line |
9b371988 PH |
17578 | .code |
17579 | accept hosts=x1.y.example:x2.y.example data="rule1" | |
17580 | .endd | |
168e428f | 17581 | routes the address to the default transport, passing a list of two hosts. When |
9b371988 | 17582 | the transport runs, the string &"rule1"& is in &$address_data$&. |
4f578862 PH |
17583 | .ecindex IIDquerou1 |
17584 | .ecindex IIDquerou2 | |
168e428f PH |
17585 | |
17586 | ||
17587 | ||
17588 | ||
9b371988 PH |
17589 | . //////////////////////////////////////////////////////////////////////////// |
17590 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 17591 | |
9b371988 | 17592 | .chapter "The redirect router" "CHAPredirect" |
4f578862 PH |
17593 | .scindex IIDredrou1 "&(redirect)& router" |
17594 | .scindex IIDredrou2 "routers" "&(redirect)&" | |
9b371988 PH |
17595 | .cindex "alias file" "in a &(redirect)& router" |
17596 | .cindex "address redirection" "&(redirect)& router" | |
17597 | The &(redirect)& router handles several kinds of address redirection. Its most | |
168e428f | 17598 | common uses are for resolving local part aliases from a central alias file |
9b371988 | 17599 | (usually called &_/etc/aliases_&) and for handling users' personal &_.forward_& |
168e428f PH |
17600 | files, but it has many other potential uses. The incoming address can be |
17601 | redirected in several different ways: | |
17602 | ||
9b371988 PH |
17603 | .ilist |
17604 | It can be replaced by one or more new addresses which are themselves routed | |
168e428f | 17605 | independently. |
9b371988 PH |
17606 | .next |
17607 | It can be routed to be delivered to a given file or directory. | |
17608 | .next | |
17609 | It can be routed to be delivered to a specified pipe command. | |
17610 | .next | |
17611 | It can cause an automatic reply to be generated. | |
17612 | .next | |
f89d2485 | 17613 | It can be forced to fail, optionally with a custom error message. |
9b371988 | 17614 | .next |
f89d2485 | 17615 | It can be temporarily deferred, optionally with a custom message. |
9b371988 PH |
17616 | .next |
17617 | It can be discarded. | |
17618 | .endlist | |
17619 | ||
17620 | The generic &%transport%& option must not be set for &(redirect)& routers. | |
168e428f | 17621 | However, there are some private options which define transports for delivery to |
9b371988 PH |
17622 | files and pipes, and for generating autoreplies. See the &%file_transport%&, |
17623 | &%pipe_transport%& and &%reply_transport%& descriptions below. | |
168e428f PH |
17624 | |
17625 | ||
17626 | ||
f89d2485 | 17627 | .section "Redirection data" "SECID124" |
168e428f | 17628 | The router operates by interpreting a text string which it obtains either by |
9b371988 PH |
17629 | expanding the contents of the &%data%& option, or by reading the entire |
17630 | contents of a file whose name is given in the &%file%& option. These two | |
17631 | options are mutually exclusive. The first is commonly used for handling system | |
17632 | aliases, in a configuration like this: | |
17633 | .code | |
17634 | system_aliases: | |
17635 | driver = redirect | |
17636 | data = ${lookup{$local_part}lsearch{/etc/aliases}} | |
17637 | .endd | |
168e428f | 17638 | If the lookup fails, the expanded string in this example is empty. When the |
9b371988 | 17639 | expansion of &%data%& results in an empty string, the router declines. A forced |
168e428f PH |
17640 | expansion failure also causes the router to decline; other expansion failures |
17641 | cause delivery to be deferred. | |
17642 | ||
9b371988 PH |
17643 | A configuration using &%file%& is commonly used for handling users' |
17644 | &_.forward_& files, like this: | |
17645 | .code | |
17646 | userforward: | |
17647 | driver = redirect | |
17648 | check_local_user | |
17649 | file = $home/.forward | |
17650 | no_verify | |
17651 | .endd | |
168e428f | 17652 | If the file does not exist, or causes no action to be taken (for example, it is |
9b371988 | 17653 | empty or consists only of comments), the router declines. &*Warning*&: This |
168e428f PH |
17654 | is not the case when the file contains syntactically valid items that happen to |
17655 | yield empty addresses, for example, items containing only RFC 2822 address | |
17656 | comments. | |
17657 | ||
17658 | ||
17659 | ||
f89d2485 | 17660 | .section "Forward files and address verification" "SECID125" |
9b371988 PH |
17661 | .cindex "address redirection" "while verifying" |
17662 | It is usual to set &%no_verify%& on &(redirect)& routers which handle users' | |
17663 | &_.forward_& files, as in the example above. There are two reasons for this: | |
168e428f | 17664 | |
9b371988 PH |
17665 | .ilist |
17666 | When Exim is receiving an incoming SMTP message from a remote host, it is | |
db9452a9 PH |
17667 | running under the Exim uid, not as root. Exim is unable to change uid to read |
17668 | the file as the user, and it may not be able to read it as the Exim user. So in | |
17669 | practice the router may not be able to operate. | |
9b371988 PH |
17670 | .next |
17671 | However, even when the router can operate, the existence of a &_.forward_& file | |
168e428f PH |
17672 | is unimportant when verifying an address. What should be checked is whether the |
17673 | local part is a valid user name or not. Cutting out the redirection processing | |
17674 | saves some resources. | |
9b371988 | 17675 | .endlist |
168e428f PH |
17676 | |
17677 | ||
17678 | ||
17679 | ||
17680 | ||
17681 | ||
f89d2485 | 17682 | .section "Interpreting redirection data" "SECID126" |
9b371988 PH |
17683 | .cindex "Sieve filter" "specifying in redirection data" |
17684 | .cindex "filter" "specifying in redirection data" | |
17685 | The contents of the data string, whether obtained from &%data%& or &%file%&, | |
17686 | can be interpreted in two different ways: | |
168e428f | 17687 | |
9b371988 PH |
17688 | .ilist |
17689 | If the &%allow_filter%& option is set true, and the data begins with the text | |
17690 | &"#Exim filter"& or &"#Sieve filter"&, it is interpreted as a list of | |
17691 | &'filtering'& instructions in the form of an Exim or Sieve filter file, | |
168e428f | 17692 | respectively. Details of the syntax and semantics of filter files are described |
9b371988 | 17693 | in a separate document entitled &'Exim's interfaces to mail filtering'&; this |
168e428f | 17694 | document is intended for use by end users. |
9b371988 PH |
17695 | .next |
17696 | Otherwise, the data must be a comma-separated list of redirection items, as | |
168e428f | 17697 | described in the next section. |
9b371988 | 17698 | .endlist |
168e428f | 17699 | |
9b371988 | 17700 | When a message is redirected to a file (a &"mail folder"&), the file name given |
168e428f | 17701 | in a non-filter redirection list must always be an absolute path. A filter may |
9b371988 PH |
17702 | generate a relative path &-- how this is handled depends on the transport's |
17703 | configuration. See section &<<SECTfildiropt>>& for a discussion of this issue | |
17704 | for the &(appendfile)& transport. | |
168e428f PH |
17705 | |
17706 | ||
17707 | ||
9b371988 PH |
17708 | .section "Items in a non-filter redirection list" "SECTitenonfilred" |
17709 | .cindex "address redirection" "non-filter list items" | |
168e428f PH |
17710 | When the redirection data is not an Exim or Sieve filter, for example, if it |
17711 | comes from a conventional alias or forward file, it consists of a list of | |
17712 | addresses, file names, pipe commands, or certain special items (see section | |
9b371988 PH |
17713 | &<<SECTspecitredli>>& below). The special items can be individually enabled or |
17714 | disabled by means of options whose names begin with &%allow_%& or &%forbid_%&, | |
168e428f PH |
17715 | depending on their default values. The items in the list are separated by |
17716 | commas or newlines. | |
17717 | If a comma is required in an item, the entire item must be enclosed in double | |
17718 | quotes. | |
17719 | ||
17720 | Lines starting with a # character are comments, and are ignored, and # may | |
17721 | also appear following a comma, in which case everything between the # and the | |
17722 | next newline character is ignored. | |
17723 | ||
17724 | If an item is entirely enclosed in double quotes, these are removed. Otherwise | |
17725 | double quotes are retained because some forms of mail address require their use | |
068aaea8 | 17726 | (but never to enclose the entire address). In the following description, |
9b371988 | 17727 | &"item"& refers to what remains after any surrounding double quotes have been |
068aaea8 | 17728 | removed. |
168e428f | 17729 | |
f89d2485 | 17730 | .vindex "&$local_part$&" |
9b371988 PH |
17731 | &*Warning*&: If you use an Exim expansion to construct a redirection address, |
17732 | and the expansion contains a reference to &$local_part$&, you should make use | |
17733 | of the &%quote_local_part%& expansion operator, in case the local part contains | |
068aaea8 | 17734 | special characters. For example, to redirect all mail for the domain |
9b371988 | 17735 | &'obsolete.example'&, retaining the existing local part, you could use this |
168e428f | 17736 | setting: |
9b371988 PH |
17737 | .code |
17738 | data = ${quote_local_part:$local_part}@newdomain.example | |
17739 | .endd | |
168e428f PH |
17740 | |
17741 | ||
9b371988 PH |
17742 | .section "Redirecting to a local mailbox" "SECTredlocmai" |
17743 | .cindex "routing" "loops in" | |
f89d2485 | 17744 | .cindex "loop" "while routing, avoidance of" |
9b371988 | 17745 | .cindex "address redirection" "to local mailbox" |
168e428f PH |
17746 | A redirection item may safely be the same as the address currently under |
17747 | consideration. This does not cause a routing loop, because a router is | |
17748 | automatically skipped if any ancestor of the address that is being processed | |
17749 | is the same as the current address and was processed by the current router. | |
17750 | Such an address is therefore passed to the following routers, so it is handled | |
17751 | as if there were no redirection. When making this loop-avoidance test, the | |
17752 | complete local part, including any prefix or suffix, is used. | |
17753 | ||
9b371988 | 17754 | .cindex "address redirection" "local part without domain" |
168e428f PH |
17755 | Specifying the same local part without a domain is a common usage in personal |
17756 | filter files when the user wants to have messages delivered to the local | |
17757 | mailbox and also forwarded elsewhere. For example, the user whose login is | |
9b371988 PH |
17758 | &'cleo'& might have a &_.forward_& file containing this: |
17759 | .code | |
17760 | cleo, cleopatra@egypt.example | |
17761 | .endd | |
17762 | .cindex "backslash in alias file" | |
17763 | .cindex "alias file" "backslash in" | |
168e428f | 17764 | For compatibility with other MTAs, such unqualified local parts may be |
f89d2485 | 17765 | preceded by &"\"&, but this is not a requirement for loop prevention. However, |
168e428f PH |
17766 | it does make a difference if more than one domain is being handled |
17767 | synonymously. | |
17768 | ||
9b371988 PH |
17769 | If an item begins with &"\"& and the rest of the item parses as a valid RFC |
17770 | 2822 address that does not include a domain, the item is qualified using the | |
17771 | domain of the incoming address. In the absence of a leading &"\"&, unqualified | |
17772 | addresses are qualified using the value in &%qualify_recipient%&, but you can | |
17773 | force the incoming domain to be used by setting &%qualify_preserve_domain%&. | |
168e428f PH |
17774 | |
17775 | Care must be taken if there are alias names for local users. | |
17776 | Consider an MTA handling a single local domain where the system alias file | |
17777 | contains: | |
9b371988 PH |
17778 | .code |
17779 | Sam.Reman: spqr | |
17780 | .endd | |
17781 | Now suppose that Sam (whose login id is &'spqr'&) wants to save copies of | |
168e428f PH |
17782 | messages in the local mailbox, and also forward copies elsewhere. He creates |
17783 | this forward file: | |
9b371988 PH |
17784 | .code |
17785 | Sam.Reman, spqr@reme.elsewhere.example | |
17786 | .endd | |
17787 | With these settings, an incoming message addressed to &'Sam.Reman'& fails. The | |
17788 | &(redirect)& router for system aliases does not process &'Sam.Reman'& the | |
168e428f PH |
17789 | second time round, because it has previously routed it, |
17790 | and the following routers presumably cannot handle the alias. The forward file | |
17791 | should really contain | |
9b371988 PH |
17792 | .code |
17793 | spqr, spqr@reme.elsewhere.example | |
17794 | .endd | |
17795 | but because this is such a common error, the &%check_ancestor%& option (see | |
168e428f | 17796 | below) exists to provide a way to get round it. This is normally set on a |
9b371988 | 17797 | &(redirect)& router that is handling users' &_.forward_& files. |
168e428f PH |
17798 | |
17799 | ||
17800 | ||
9b371988 | 17801 | .section "Special items in redirection lists" "SECTspecitredli" |
168e428f PH |
17802 | In addition to addresses, the following types of item may appear in redirection |
17803 | lists (that is, in non-filter redirection data): | |
17804 | ||
9b371988 PH |
17805 | .ilist |
17806 | .cindex "pipe" "in redirection list" | |
17807 | .cindex "address redirection" "to pipe" | |
17808 | An item is treated as a pipe command if it begins with &"|"& and does not parse | |
168e428f | 17809 | as a valid RFC 2822 address that includes a domain. A transport for running the |
9b371988 | 17810 | command must be specified by the &%pipe_transport%& option. |
168e428f PH |
17811 | Normally, either the router or the transport specifies a user and a group under |
17812 | which to run the delivery. The default is to use the Exim user and group. | |
9b371988 | 17813 | |
168e428f PH |
17814 | Single or double quotes can be used for enclosing the individual arguments of |
17815 | the pipe command; no interpretation of escapes is done for single quotes. If | |
17816 | the command contains a comma character, it is necessary to put the whole item | |
17817 | in double quotes, for example: | |
9b371988 PH |
17818 | .code |
17819 | "|/some/command ready,steady,go" | |
17820 | .endd | |
168e428f PH |
17821 | since items in redirection lists are terminated by commas. Do not, however, |
17822 | quote just the command. An item such as | |
9b371988 PH |
17823 | .code |
17824 | |"/some/command ready,steady,go" | |
17825 | .endd | |
168e428f PH |
17826 | is interpreted as a pipe with a rather strange command name, and no arguments. |
17827 | ||
9b371988 PH |
17828 | .next |
17829 | .cindex "file" "in redirection list" | |
17830 | .cindex "address redirection" "to file" | |
17831 | An item is interpreted as a path name if it begins with &"/"& and does not | |
17832 | parse as a valid RFC 2822 address that includes a domain. For example, | |
17833 | .code | |
17834 | /home/world/minbari | |
17835 | .endd | |
168e428f | 17836 | is treated as a file name, but |
9b371988 PH |
17837 | .code |
17838 | /s=molari/o=babylon/@x400gate.way | |
17839 | .endd | |
168e428f | 17840 | is treated as an address. For a file name, a transport must be specified using |
9b371988 | 17841 | the &%file_transport%& option. However, if the generated path name ends with a |
168e428f | 17842 | forward slash character, it is interpreted as a directory name rather than a |
9b371988 PH |
17843 | file name, and &%directory_transport%& is used instead. |
17844 | ||
168e428f PH |
17845 | Normally, either the router or the transport specifies a user and a group under |
17846 | which to run the delivery. The default is to use the Exim user and group. | |
9b371988 PH |
17847 | |
17848 | .cindex "&_/dev/null_&" | |
17849 | However, if a redirection item is the path &_/dev/null_&, delivery to it is | |
17850 | bypassed at a high level, and the log entry shows &"**bypassed**"& | |
168e428f PH |
17851 | instead of a transport name. In this case the user and group are not used. |
17852 | ||
9b371988 PH |
17853 | .next |
17854 | .cindex "included address list" | |
17855 | .cindex "address redirection" "included external list" | |
168e428f | 17856 | If an item is of the form |
9b371988 PH |
17857 | .code |
17858 | :include:<path name> | |
17859 | .endd | |
168e428f | 17860 | a list of further items is taken from the given file and included at that |
9b371988 PH |
17861 | point. &*Note*&: Such a file can not be a filter file; it is just an |
17862 | out-of-line addition to the list. The items in the included list are separated | |
17863 | by commas or newlines and are not subject to expansion. If this is the first | |
17864 | item in an alias list in an &(lsearch)& file, a colon must be used to terminate | |
17865 | the alias name. This example is incorrect: | |
17866 | .code | |
17867 | list1 :include:/opt/lists/list1 | |
17868 | .endd | |
168e428f | 17869 | It must be given as |
9b371988 PH |
17870 | .code |
17871 | list1: :include:/opt/lists/list1 | |
17872 | .endd | |
17873 | .next | |
17874 | .cindex "address redirection" "to black hole" | |
168e428f | 17875 | Sometimes you want to throw away mail to a particular local part. Making the |
9b371988 PH |
17876 | &%data%& option expand to an empty string does not work, because that causes |
17877 | the router to decline. Instead, the alias item | |
17878 | .cindex "black hole" | |
17879 | .cindex "abandoning mail" | |
f89d2485 PH |
17880 | &':blackhole:'& can be used. It does what its name implies. No delivery is |
17881 | done, and no error message is generated. This has the same effect as specifing | |
17882 | &_/dev/null_& as a destination, but it can be independently disabled. | |
9b371988 | 17883 | |
f89d2485 | 17884 | &*Warning*&: If &':blackhole:'& appears anywhere in a redirection list, no |
168e428f PH |
17885 | delivery is done for the original local part, even if other redirection items |
17886 | are present. If you are generating a multi-item list (for example, by reading a | |
17887 | database) and need the ability to provide a no-op item, you must use | |
9b371988 PH |
17888 | &_/dev/null_&. |
17889 | ||
17890 | .next | |
17891 | .cindex "delivery" "forcing failure" | |
17892 | .cindex "delivery" "forcing deferral" | |
17893 | .cindex "failing delivery" "forcing" | |
f89d2485 | 17894 | .cindex "deferred delivery, forcing" |
9b371988 | 17895 | .cindex "customizing" "failure message" |
168e428f PH |
17896 | An attempt to deliver a particular address can be deferred or forced to fail by |
17897 | redirection items of the form | |
9b371988 PH |
17898 | .code |
17899 | :defer: | |
17900 | :fail: | |
17901 | .endd | |
400eda43 NM |
17902 | respectively. When a redirection list contains such an item, it applies |
17903 | to the entire redirection; any other items in the list are ignored. Any | |
17904 | text following &':fail:'& or &':defer:'& is placed in the error text | |
17905 | associated with the failure. For example, an alias file might contain: | |
9b371988 PH |
17906 | .code |
17907 | X.Employee: :fail: Gone away, no forwarding address | |
17908 | .endd | |
168e428f PH |
17909 | In the case of an address that is being verified from an ACL or as the subject |
17910 | of a | |
f89d2485 | 17911 | .cindex "VRFY" "error text, display of" |
168e428f PH |
17912 | VRFY command, the text is included in the SMTP error response by |
17913 | default. | |
f89d2485 | 17914 | .cindex "EXPN" "error text, display of" |
5abeaa6e PH |
17915 | The text is not included in the response to an EXPN command. In non-SMTP cases |
17916 | the text is included in the error message that Exim generates. | |
17917 | ||
17918 | .cindex "SMTP" "error codes" | |
17919 | By default, Exim sends a 451 SMTP code for a &':defer:'&, and 550 for | |
17920 | &':fail:'&. However, if the message starts with three digits followed by a | |
17921 | space, optionally followed by an extended code of the form &'n.n.n'&, also | |
17922 | followed by a space, and the very first digit is the same as the default error | |
17923 | code, the code from the message is used instead. If the very first digit is | |
17924 | incorrect, a panic error is logged, and the default code is used. You can | |
17925 | suppress the use of the supplied code in a redirect router by setting the | |
17926 | &%forbid_smtp_code%& option true. In this case, any SMTP code is quietly | |
17927 | ignored. | |
9b371988 | 17928 | |
f89d2485 | 17929 | .vindex "&$acl_verify_message$&" |
168e428f | 17930 | In an ACL, an explicitly provided message overrides the default, but the |
9b371988 | 17931 | default message is available in the variable &$acl_verify_message$& and can |
5abeaa6e | 17932 | therefore be included in a custom message if this is desired. |
9b371988 PH |
17933 | |
17934 | Normally the error text is the rest of the redirection list &-- a comma does | |
17935 | not terminate it &-- but a newline does act as a terminator. Newlines are not | |
17936 | normally present in alias expansions. In &(lsearch)& lookups they are removed | |
17937 | as part of the continuation process, but they may exist in other kinds of | |
17938 | lookup and in &':include:'& files. | |
17939 | ||
168e428f | 17940 | During routing for message delivery (as opposed to verification), a redirection |
9b371988 PH |
17941 | containing &':fail:'& causes an immediate failure of the incoming address, |
17942 | whereas &':defer:'& causes the message to remain on the queue so that a | |
168e428f PH |
17943 | subsequent delivery attempt can happen at a later time. If an address is |
17944 | deferred for too long, it will ultimately fail, because the normal retry | |
17945 | rules still apply. | |
17946 | ||
9b371988 PH |
17947 | .next |
17948 | .cindex "alias file" "exception to default" | |
168e428f | 17949 | Sometimes it is useful to use a single-key search type with a default (see |
9b371988 PH |
17950 | chapter &<<CHAPfdlookup>>&) to look up aliases. However, there may be a need |
17951 | for exceptions to the default. These can be handled by aliasing them to | |
f89d2485 PH |
17952 | &':unknown:'&. This differs from &':fail:'& in that it causes the &(redirect)& |
17953 | router to decline, whereas &':fail:'& forces routing to fail. A lookup which | |
17954 | results in an empty redirection list has the same effect. | |
9b371988 PH |
17955 | .endlist |
17956 | ||
17957 | ||
0a4e3112 | 17958 | .section "Duplicate addresses" "SECTdupaddr" |
9b371988 | 17959 | .cindex "duplicate addresses" |
f89d2485 | 17960 | .cindex "address duplicate, discarding" |
9b371988 | 17961 | .cindex "pipe" "duplicated" |
168e428f PH |
17962 | Exim removes duplicate addresses from the list to which it is delivering, so as |
17963 | to deliver just one copy to each address. This does not apply to deliveries | |
17964 | routed to pipes by different immediate parent addresses, but an indirect | |
17965 | aliasing scheme of the type | |
9b371988 PH |
17966 | .code |
17967 | pipe: |/some/command $local_part | |
17968 | localpart1: pipe | |
17969 | localpart2: pipe | |
17970 | .endd | |
168e428f | 17971 | does not work with a message that is addressed to both local parts, because |
9b371988 | 17972 | when the second is aliased to the intermediate local part &"pipe"& it gets |
168e428f PH |
17973 | discarded as being the same as a previously handled address. However, a scheme |
17974 | such as | |
9b371988 PH |
17975 | .code |
17976 | localpart1: |/some/command $local_part | |
17977 | localpart2: |/some/command $local_part | |
17978 | .endd | |
168e428f PH |
17979 | does result in two different pipe deliveries, because the immediate parents of |
17980 | the pipes are distinct. | |
17981 | ||
17982 | ||
17983 | ||
f89d2485 | 17984 | .section "Repeated redirection expansion" "SECID128" |
9b371988 PH |
17985 | .cindex "repeated redirection expansion" |
17986 | .cindex "address redirection" "repeated for each delivery attempt" | |
168e428f PH |
17987 | When a message cannot be delivered to all of its recipients immediately, |
17988 | leading to two or more delivery attempts, redirection expansion is carried out | |
17989 | afresh each time for those addresses whose children were not all previously | |
17990 | delivered. If redirection is being used as a mailing list, this can lead to new | |
9b371988 | 17991 | members of the list receiving copies of old messages. The &%one_time%& option |
168e428f PH |
17992 | can be used to avoid this. |
17993 | ||
17994 | ||
f89d2485 | 17995 | .section "Errors in redirection lists" "SECID129" |
9b371988 PH |
17996 | .cindex "address redirection" "errors" |
17997 | If &%skip_syntax_errors%& is set, a malformed address that causes a parsing | |
168e428f PH |
17998 | error is skipped, and an entry is written to the main log. This may be useful |
17999 | for mailing lists that are automatically managed. Otherwise, if an error is | |
18000 | detected while generating the list of new addresses, the original address is | |
9b371988 | 18001 | deferred. See also &%syntax_errors_to%&. |
168e428f | 18002 | |
168e428f | 18003 | |
168e428f | 18004 | |
f89d2485 | 18005 | .section "Private options for the redirect router" "SECID130" |
168e428f | 18006 | |
9b371988 PH |
18007 | .cindex "options" "&(redirect)& router" |
18008 | The private options for the &(redirect)& router are as follows: | |
168e428f | 18009 | |
168e428f | 18010 | |
9b371988 PH |
18011 | .option allow_defer redirect boolean false |
18012 | Setting this option allows the use of &':defer:'& in non-filter redirection | |
18013 | data, or the &%defer%& command in an Exim filter file. | |
168e428f | 18014 | |
168e428f | 18015 | |
9b371988 PH |
18016 | .option allow_fail redirect boolean false |
18017 | .cindex "failing delivery" "from filter" | |
18018 | If this option is true, the &':fail:'& item can be used in a redirection list, | |
18019 | and the &%fail%& command may be used in an Exim filter file. | |
168e428f PH |
18020 | |
18021 | ||
9b371988 PH |
18022 | .option allow_filter redirect boolean false |
18023 | .cindex "filter" "enabling use of" | |
18024 | .cindex "Sieve filter" "enabling use of" | |
168e428f | 18025 | Setting this option allows Exim to interpret redirection data that starts with |
9b371988 | 18026 | &"#Exim filter"& or &"#Sieve filter"& as a set of filtering instructions. There |
168e428f | 18027 | are some features of Exim filter files that some administrators may wish to |
9b371988 | 18028 | lock out; see the &%forbid_filter_%&&'xxx'& options below. |
168e428f PH |
18029 | |
18030 | It is also possible to lock out Exim filters or Sieve filters while allowing | |
9b371988 | 18031 | the other type; see &%forbid_exim_filter%& and &%forbid_sieve_filter%&. |
168e428f | 18032 | |
168e428f | 18033 | |
9b371988 PH |
18034 | The filter is run using the uid and gid set by the generic &%user%& and |
18035 | &%group%& options. These take their defaults from the password data if | |
18036 | &%check_local_user%& is set, so in the normal case of users' personal filter | |
18037 | files, the filter is run as the relevant user. When &%allow_filter%& is set | |
18038 | true, Exim insists that either &%check_local_user%& or &%user%& is set. | |
168e428f PH |
18039 | |
18040 | ||
168e428f | 18041 | |
9b371988 PH |
18042 | .option allow_freeze redirect boolean false |
18043 | .cindex "freezing messages" "allowing in filter" | |
18044 | Setting this option allows the use of the &%freeze%& command in an Exim filter. | |
168e428f PH |
18045 | This command is more normally encountered in system filters, and is disabled by |
18046 | default for redirection filters because it isn't something you usually want to | |
18047 | let ordinary users do. | |
18048 | ||
18049 | ||
18050 | ||
9b371988 | 18051 | .option check_ancestor redirect boolean false |
168e428f PH |
18052 | This option is concerned with handling generated addresses that are the same |
18053 | as some address in the list of redirection ancestors of the current address. | |
18054 | Although it is turned off by default in the code, it is set in the default | |
9b371988 PH |
18055 | configuration file for handling users' &_.forward_& files. It is recommended |
18056 | for this use of the &(redirect)& router. | |
168e428f | 18057 | |
9b371988 PH |
18058 | When &%check_ancestor%& is set, if a generated address (including the domain) |
18059 | is the same as any ancestor of the current address, it is replaced by a copy of | |
168e428f | 18060 | the current address. This helps in the case where local part A is aliased to B, |
9b371988 PH |
18061 | and B has a &_.forward_& file pointing back to A. For example, within a single |
18062 | domain, the local part &"Joe.Bloggs"& is aliased to &"jb"& and | |
18063 | &_&~jb/.forward_& contains: | |
18064 | .code | |
18065 | \Joe.Bloggs, <other item(s)> | |
18066 | .endd | |
18067 | Without the &%check_ancestor%& setting, either local part (&"jb"& or | |
18068 | &"joe.bloggs"&) gets processed once by each router and so ends up as it was | |
18069 | originally. If &"jb"& is the real mailbox name, mail to &"jb"& gets delivered | |
18070 | (having been turned into &"joe.bloggs"& by the &_.forward_& file and back to | |
18071 | &"jb"& by the alias), but mail to &"joe.bloggs"& fails. Setting | |
18072 | &%check_ancestor%& on the &(redirect)& router that handles the &_.forward_& | |
18073 | file prevents it from turning &"jb"& back into &"joe.bloggs"& when that was the | |
18074 | original address. See also the &%repeat_use%& option below. | |
18075 | ||
18076 | ||
18077 | .option check_group redirect boolean "see below" | |
18078 | When the &%file%& option is used, the group owner of the file is checked only | |
168e428f | 18079 | when this option is set. The permitted groups are those listed in the |
9b371988 PH |
18080 | &%owngroups%& option, together with the user's default group if |
18081 | &%check_local_user%& is set. If the file has the wrong group, routing is | |
18082 | deferred. The default setting for this option is true if &%check_local_user%& | |
18083 | is set and the &%modemask%& option permits the group write bit, or if the | |
18084 | &%owngroups%& option is set. Otherwise it is false, and no group check occurs. | |
168e428f PH |
18085 | |
18086 | ||
168e428f | 18087 | |
9b371988 PH |
18088 | .option check_owner redirect boolean "see below" |
18089 | When the &%file%& option is used, the owner of the file is checked only when | |
18090 | this option is set. If &%check_local_user%& is set, the local user is | |
18091 | permitted; otherwise the owner must be one of those listed in the &%owners%& | |
18092 | option. The default value for this option is true if &%check_local_user%& or | |
18093 | &%owners%& is set. Otherwise the default is false, and no owner check occurs. | |
168e428f PH |
18094 | |
18095 | ||
9b371988 PH |
18096 | .option data redirect string&!! unset |
18097 | This option is mutually exclusive with &%file%&. One or other of them must be | |
18098 | set, but not both. The contents of &%data%& are expanded, and then used as the | |
168e428f PH |
18099 | list of forwarding items, or as a set of filtering instructions. If the |
18100 | expansion is forced to fail, or the result is an empty string or a string that | |
18101 | has no effect (consists entirely of comments), the router declines. | |
18102 | ||
9b371988 PH |
18103 | When filtering instructions are used, the string must begin with &"#Exim |
18104 | filter"&, and all comments in the string, including this initial one, must be | |
168e428f | 18105 | terminated with newline characters. For example: |
9b371988 | 18106 | .code |
168e428f PH |
18107 | data = #Exim filter\n\ |
18108 | if $h_to: contains Exim then save $home/mail/exim endif | |
9b371988 | 18109 | .endd |
168e428f | 18110 | If you are reading the data from a database where newlines cannot be included, |
9b371988 | 18111 | you can use the &${sg}$& expansion item to turn the escape string of your |
168e428f PH |
18112 | choice into a newline. |
18113 | ||
18114 | ||
9b371988 PH |
18115 | .option directory_transport redirect string&!! unset |
18116 | A &(redirect)& router sets up a direct delivery to a directory when a path name | |
18117 | ending with a slash is specified as a new &"address"&. The transport used is | |
168e428f | 18118 | specified by this option, which, after expansion, must be the name of a |
9b371988 | 18119 | configured transport. This should normally be an &(appendfile)& transport. |
168e428f PH |
18120 | |
18121 | ||
9b371988 | 18122 | .option file redirect string&!! unset |
168e428f | 18123 | This option specifies the name of a file that contains the redirection data. It |
9b371988 | 18124 | is mutually exclusive with the &%data%& option. The string is expanded before |
168e428f PH |
18125 | use; if the expansion is forced to fail, the router declines. Other expansion |
18126 | failures cause delivery to be deferred. The result of a successful expansion | |
18127 | must be an absolute path. The entire file is read and used as the redirection | |
18128 | data. If the data is an empty string or a string that has no effect (consists | |
18129 | entirely of comments), the router declines. | |
18130 | ||
9b371988 PH |
18131 | .cindex "NFS" "checking for file existence" |
18132 | If the attempt to open the file fails with a &"does not exist"& error, Exim | |
168e428f | 18133 | runs a check on the containing directory, |
9b371988 | 18134 | unless &%ignore_enotdir%& is true (see below). |
168e428f | 18135 | If the directory does not appear to exist, delivery is deferred. This can |
9b371988 | 18136 | happen when users' &_.forward_& files are in NFS-mounted directories, and there |
168e428f PH |
18137 | is a mount problem. If the containing directory does exist, but the file does |
18138 | not, the router declines. | |
18139 | ||
18140 | ||
9b371988 | 18141 | .option file_transport redirect string&!! unset |
f89d2485 | 18142 | .vindex "&$address_file$&" |
9b371988 PH |
18143 | A &(redirect)& router sets up a direct delivery to a file when a path name not |
18144 | ending in a slash is specified as a new &"address"&. The transport used is | |
168e428f | 18145 | specified by this option, which, after expansion, must be the name of a |
9b371988 PH |
18146 | configured transport. This should normally be an &(appendfile)& transport. When |
18147 | it is running, the file name is in &$address_file$&. | |
168e428f PH |
18148 | |
18149 | ||
db9452a9 PH |
18150 | .option filter_prepend_home redirect boolean true |
18151 | When this option is true, if a &(save)& command in an Exim filter specifies a | |
18152 | relative path, and &$home$& is defined, it is automatically prepended to the | |
18153 | relative path. If this option is set false, this action does not happen. The | |
18154 | relative path is then passed to the transport unmodified. | |
db9452a9 PH |
18155 | |
18156 | ||
9b371988 PH |
18157 | .option forbid_blackhole redirect boolean false |
18158 | If this option is true, the &':blackhole:'& item may not appear in a | |
18159 | redirection list. | |
168e428f PH |
18160 | |
18161 | ||
9b371988 | 18162 | .option forbid_exim_filter redirect boolean false |
168e428f | 18163 | If this option is set true, only Sieve filters are permitted when |
9b371988 | 18164 | &%allow_filter%& is true. |
168e428f PH |
18165 | |
18166 | ||
18167 | ||
168e428f | 18168 | |
9b371988 PH |
18169 | .option forbid_file redirect boolean false |
18170 | .cindex "delivery" "to file; forbidding" | |
18171 | .cindex "Sieve filter" "forbidding delivery to a file" | |
18172 | .cindex "Sieve filter" "&""keep""& facility; disabling" | |
168e428f PH |
18173 | If this option is true, this router may not generate a new address that |
18174 | specifies delivery to a local file or directory, either from a filter or from a | |
9b371988 | 18175 | conventional forward file. This option is forced to be true if &%one_time%& is |
168e428f | 18176 | set. It applies to Sieve filters as well as to Exim filters, but if true, it |
9b371988 | 18177 | locks out the Sieve's &"keep"& facility. |
168e428f PH |
18178 | |
18179 | ||
9b371988 PH |
18180 | .option forbid_filter_dlfunc redirect boolean false |
18181 | .cindex "filter" "locking out certain features" | |
068aaea8 | 18182 | If this option is true, string expansions in Exim filters are not allowed to |
9b371988 | 18183 | make use of the &%dlfunc%& expansion facility to run dynamically loaded |
068aaea8 PH |
18184 | functions. |
18185 | ||
9b371988 | 18186 | .option forbid_filter_existstest redirect boolean false |
9b371988 | 18187 | .cindex "expansion" "statting a file" |
168e428f | 18188 | If this option is true, string expansions in Exim filters are not allowed to |
9b371988 | 18189 | make use of the &%exists%& condition or the &%stat%& expansion item. |
168e428f | 18190 | |
9b371988 | 18191 | .option forbid_filter_logwrite redirect boolean false |
168e428f PH |
18192 | If this option is true, use of the logging facility in Exim filters is not |
18193 | permitted. Logging is in any case available only if the filter is being run | |
18194 | under some unprivileged uid (which is normally the case for ordinary users' | |
9b371988 | 18195 | &_.forward_& files). |
168e428f | 18196 | |
168e428f | 18197 | |
9b371988 | 18198 | .option forbid_filter_lookup redirect boolean false |
168e428f | 18199 | If this option is true, string expansions in Exim filter files are not allowed |
9b371988 | 18200 | to make use of &%lookup%& items. |
168e428f PH |
18201 | |
18202 | ||
9b371988 | 18203 | .option forbid_filter_perl redirect boolean false |
068aaea8 | 18204 | This option has an effect only if Exim is built with embedded Perl support. If |
168e428f PH |
18205 | it is true, string expansions in Exim filter files are not allowed to make use |
18206 | of the embedded Perl support. | |
18207 | ||
18208 | ||
9b371988 | 18209 | .option forbid_filter_readfile redirect boolean false |
168e428f | 18210 | If this option is true, string expansions in Exim filter files are not allowed |
9b371988 | 18211 | to make use of &%readfile%& items. |
168e428f PH |
18212 | |
18213 | ||
9b371988 | 18214 | .option forbid_filter_readsocket redirect boolean false |
168e428f | 18215 | If this option is true, string expansions in Exim filter files are not allowed |
9b371988 | 18216 | to make use of &%readsocket%& items. |
168e428f | 18217 | |
168e428f | 18218 | |
9b371988 | 18219 | .option forbid_filter_reply redirect boolean false |
168e428f | 18220 | If this option is true, this router may not generate an automatic reply |
9b371988 PH |
18221 | message. Automatic replies can be generated only from Exim or Sieve filter |
18222 | files, not from traditional forward files. This option is forced to be true if | |
18223 | &%one_time%& is set. | |
168e428f PH |
18224 | |
18225 | ||
9b371988 | 18226 | .option forbid_filter_run redirect boolean false |
168e428f | 18227 | If this option is true, string expansions in Exim filter files are not allowed |
9b371988 | 18228 | to make use of &%run%& items. |
168e428f | 18229 | |
168e428f | 18230 | |
9b371988 | 18231 | .option forbid_include redirect boolean false |
168e428f | 18232 | If this option is true, items of the form |
9b371988 PH |
18233 | .code |
18234 | :include:<path name> | |
18235 | .endd | |
168e428f PH |
18236 | are not permitted in non-filter redirection lists. |
18237 | ||
18238 | ||
9b371988 PH |
18239 | .option forbid_pipe redirect boolean false |
18240 | .cindex "delivery" "to pipe; forbidding" | |
168e428f PH |
18241 | If this option is true, this router may not generate a new address which |
18242 | specifies delivery to a pipe, either from an Exim filter or from a conventional | |
9b371988 | 18243 | forward file. This option is forced to be true if &%one_time%& is set. |
168e428f | 18244 | |
168e428f | 18245 | |
9b371988 | 18246 | .option forbid_sieve_filter redirect boolean false |
168e428f | 18247 | If this option is set true, only Exim filters are permitted when |
9b371988 | 18248 | &%allow_filter%& is true. |
168e428f PH |
18249 | |
18250 | ||
5abeaa6e PH |
18251 | .cindex "SMTP" "error codes" |
18252 | .option forbid_smtp_code redirect boolean false | |
18253 | If this option is set true, any SMTP error codes that are present at the start | |
18254 | of messages specified for &`:defer:`& or &`:fail:`& are quietly ignored, and | |
18255 | the default codes (451 and 550, respectively) are always used. | |
5abeaa6e PH |
18256 | |
18257 | ||
168e428f PH |
18258 | |
18259 | ||
9b371988 PH |
18260 | .option hide_child_in_errmsg redirect boolean false |
18261 | .cindex "bounce message" "redirection details; suppressing" | |
168e428f | 18262 | If this option is true, it prevents Exim from quoting a child address if it |
9b371988 PH |
18263 | generates a bounce or delay message for it. Instead it says &"an address |
18264 | generated from <&'the top level address'&>"&. Of course, this applies only to | |
18265 | bounces generated locally. If a message is forwarded to another host, &'its'& | |
168e428f PH |
18266 | bounce may well quote the generated address. |
18267 | ||
18268 | ||
9b371988 PH |
18269 | .option ignore_eacces redirect boolean false |
18270 | .cindex "EACCES" | |
168e428f | 18271 | If this option is set and an attempt to open a redirection file yields the |
9b371988 | 18272 | EACCES error (permission denied), the &(redirect)& router behaves as if the |
168e428f PH |
18273 | file did not exist. |
18274 | ||
18275 | ||
9b371988 PH |
18276 | .option ignore_enotdir redirect boolean false |
18277 | .cindex "ENOTDIR" | |
168e428f | 18278 | If this option is set and an attempt to open a redirection file yields the |
9b371988 | 18279 | ENOTDIR error (something on the path is not a directory), the &(redirect)& |
168e428f PH |
18280 | router behaves as if the file did not exist. |
18281 | ||
9b371988 PH |
18282 | Setting &%ignore_enotdir%& has another effect as well: When a &(redirect)& |
18283 | router that has the &%file%& option set discovers that the file does not exist | |
18284 | (the ENOENT error), it tries to &[stat()]& the parent directory, as a check | |
168e428f | 18285 | against unmounted NFS directories. If the parent can not be statted, delivery |
9b371988 PH |
18286 | is deferred. However, it seems wrong to do this check when &%ignore_enotdir%& |
18287 | is set, because that option tells Exim to ignore &"something on the path is not | |
18288 | a directory"& (the ENOTDIR error). This is a confusing area, because it seems | |
168e428f PH |
18289 | that some operating systems give ENOENT where others give ENOTDIR. |
18290 | ||
18291 | ||
18292 | ||
9b371988 PH |
18293 | .option include_directory redirect string unset |
18294 | If this option is set, the path names of any &':include:'& items in a | |
18295 | redirection list must start with this directory. | |
168e428f PH |
18296 | |
18297 | ||
9b371988 | 18298 | .option modemask redirect "octal integer" 022 |
168e428f | 18299 | This specifies mode bits which must not be set for a file specified by the |
9b371988 | 18300 | &%file%& option. If any of the forbidden bits are set, delivery is deferred. |
168e428f | 18301 | |
168e428f | 18302 | |
9b371988 PH |
18303 | .option one_time redirect boolean false |
18304 | .cindex "one-time aliasing/forwarding expansion" | |
18305 | .cindex "alias file" "one-time expansion" | |
18306 | .cindex "forward file" "one-time expansion" | |
18307 | .cindex "mailing lists" "one-time expansion" | |
18308 | .cindex "address redirection" "one-time expansion" | |
168e428f | 18309 | Sometimes the fact that Exim re-evaluates aliases and reprocesses redirection |
068aaea8 PH |
18310 | files each time it tries to deliver a message causes a problem when one or more |
18311 | of the generated addresses fails be delivered at the first attempt. The problem | |
9b371988 PH |
18312 | is not one of duplicate delivery &-- Exim is clever enough to handle that &-- |
18313 | but of what happens when the redirection list changes during the time that the | |
068aaea8 PH |
18314 | message is on Exim's queue. This is particularly true in the case of mailing |
18315 | lists, where new subscribers might receive copies of messages that were posted | |
18316 | before they subscribed. | |
18317 | ||
9b371988 PH |
18318 | If &%one_time%& is set and any addresses generated by the router fail to |
18319 | deliver at the first attempt, the failing addresses are added to the message as | |
18320 | &"top level"& addresses, and the parent address that generated them is marked | |
18321 | &"delivered"&. Thus, redirection does not happen again at the next delivery | |
068aaea8 | 18322 | attempt. |
168e428f | 18323 | |
9b371988 | 18324 | &*Warning 1*&: Any header line addition or removal that is specified by this |
068aaea8 | 18325 | router would be lost if delivery did not succeed at the first attempt. For this |
9b371988 PH |
18326 | reason, the &%headers_add%& and &%headers_remove%& generic options are not |
18327 | permitted when &%one_time%& is set. | |
168e428f | 18328 | |
9b371988 PH |
18329 | &*Warning 2*&: To ensure that the router generates only addresses (as opposed |
18330 | to pipe or file deliveries or auto-replies) &%forbid_file%&, &%forbid_pipe%&, | |
18331 | and &%forbid_filter_reply%& are forced to be true when &%one_time%& is set. | |
168e428f | 18332 | |
9b371988 PH |
18333 | &*Warning 3*&: The &%unseen%& generic router option may not be set with |
18334 | &%one_time%&. | |
068aaea8 | 18335 | |
168e428f PH |
18336 | The original top-level address is remembered with each of the generated |
18337 | addresses, and is output in any log messages. However, any intermediate parent | |
18338 | addresses are not recorded. This makes a difference to the log only if | |
9b371988 | 18339 | &%all_parents%& log selector is set. It is expected that &%one_time%& will |
168e428f PH |
18340 | typically be used for mailing lists, where there is normally just one level of |
18341 | expansion. | |
18342 | ||
18343 | ||
9b371988 PH |
18344 | .option owners redirect "string list" unset |
18345 | .cindex "ownership" "alias file" | |
18346 | .cindex "ownership" "forward file" | |
18347 | .cindex "alias file" "ownership" | |
18348 | .cindex "forward file" "ownership" | |
18349 | This specifies a list of permitted owners for the file specified by &%file%&. | |
18350 | This list is in addition to the local user when &%check_local_user%& is set. | |
18351 | See &%check_owner%& above. | |
168e428f PH |
18352 | |
18353 | ||
9b371988 PH |
18354 | .option owngroups redirect "string list" unset |
18355 | This specifies a list of permitted groups for the file specified by &%file%&. | |
18356 | The list is in addition to the local user's primary group when | |
18357 | &%check_local_user%& is set. See &%check_group%& above. | |
168e428f | 18358 | |
168e428f | 18359 | |
9b371988 | 18360 | .option pipe_transport redirect string&!! unset |
f89d2485 | 18361 | .vindex "&$address_pipe$&" |
9b371988 PH |
18362 | A &(redirect)& router sets up a direct delivery to a pipe when a string |
18363 | starting with a vertical bar character is specified as a new &"address"&. The | |
18364 | transport used is specified by this option, which, after expansion, must be the | |
18365 | name of a configured transport. This should normally be a &(pipe)& transport. | |
18366 | When the transport is run, the pipe command is in &$address_pipe$&. | |
168e428f | 18367 | |
168e428f | 18368 | |
9b371988 | 18369 | .option qualify_domain redirect string&!! unset |
f89d2485 | 18370 | .vindex "&$qualify_recipient$&" |
4f578862 PH |
18371 | If this option is set, and an unqualified address (one without a domain) is |
18372 | generated, and that address would normally be qualified by the global setting | |
18373 | in &%qualify_recipient%&, it is instead qualified with the domain specified by | |
18374 | expanding this string. If the expansion fails, the router declines. If you want | |
18375 | to revert to the default, you can have the expansion generate | |
18376 | &$qualify_recipient$&. | |
18377 | ||
18378 | This option applies to all unqualified addresses generated by Exim filters, | |
18379 | but for traditional &_.forward_& files, it applies only to addresses that are | |
18380 | not preceded by a backslash. Sieve filters cannot generate unqualified | |
18381 | addresses. | |
168e428f | 18382 | |
9b371988 PH |
18383 | .option qualify_preserve_domain redirect boolean false |
18384 | .cindex "domain" "in redirection; preserving" | |
18385 | .cindex "preserving domain in redirection" | |
18386 | .cindex "address redirection" "domain; preserving" | |
4f578862 PH |
18387 | If this option is set, the router's local &%qualify_domain%& option must not be |
18388 | set (a configuration error occurs if it is). If an unqualified address (one | |
18389 | without a domain) is generated, it is qualified with the domain of the parent | |
18390 | address (the immediately preceding ancestor) instead of the global | |
18391 | &%qualify_recipient%& value. In the case of a traditional &_.forward_& file, | |
18392 | this applies whether or not the address is preceded by a backslash. | |
168e428f | 18393 | |
168e428f | 18394 | |
9b371988 | 18395 | .option repeat_use redirect boolean true |
168e428f PH |
18396 | If this option is set false, the router is skipped for a child address that has |
18397 | any ancestor that was routed by this router. This test happens before any of | |
18398 | the other preconditions are tested. Exim's default anti-looping rules skip | |
18399 | only when the ancestor is the same as the current address. See also | |
9b371988 | 18400 | &%check_ancestor%& above and the generic &%redirect_router%& option. |
168e428f | 18401 | |
168e428f | 18402 | |
9b371988 PH |
18403 | .option reply_transport redirect string&!! unset |
18404 | A &(redirect)& router sets up an automatic reply when a &%mail%& or | |
18405 | &%vacation%& command is used in a filter file. The transport used is specified | |
18406 | by this option, which, after expansion, must be the name of a configured | |
18407 | transport. This should normally be an &(autoreply)& transport. Other transports | |
18408 | are unlikely to do anything sensible or useful. | |
168e428f | 18409 | |
168e428f | 18410 | |
9b371988 PH |
18411 | .option rewrite redirect boolean true |
18412 | .cindex "address redirection" "disabling rewriting" | |
168e428f PH |
18413 | If this option is set false, addresses generated by the router are not |
18414 | subject to address rewriting. Otherwise, they are treated like new addresses | |
18415 | and are rewritten according to the global rewriting rules. | |
18416 | ||
18417 | ||
9b371988 | 18418 | .option sieve_subaddress redirect string&!! unset |
068aaea8 PH |
18419 | The value of this option is passed to a Sieve filter to specify the |
18420 | :subaddress part of an address. | |
18421 | ||
9b371988 | 18422 | .option sieve_useraddress redirect string&!! unset |
068aaea8 PH |
18423 | The value of this option is passed to a Sieve filter to specify the :user part |
18424 | of an address. However, if it is unset, the entire original local part | |
18425 | (including any prefix or suffix) is used for :user. | |
18426 | ||
18427 | ||
9b371988 | 18428 | .option sieve_vacation_directory redirect string&!! unset |
9b371988 PH |
18429 | .cindex "Sieve filter" "vacation directory" |
18430 | To enable the &"vacation"& extension for Sieve filters, you must set | |
18431 | &%sieve_vacation_directory%& to the directory where vacation databases are held | |
168e428f | 18432 | (do not put anything else in that directory), and ensure that the |
9b371988 PH |
18433 | &%reply_transport%& option refers to an &(autoreply)& transport. Each user |
18434 | needs their own directory; Exim will create it if necessary. | |
168e428f PH |
18435 | |
18436 | ||
18437 | ||
9b371988 PH |
18438 | .option skip_syntax_errors redirect boolean false |
18439 | .cindex "forward file" "broken" | |
18440 | .cindex "address redirection" "broken files" | |
18441 | .cindex "alias file" "broken" | |
18442 | .cindex "broken alias or forward files" | |
18443 | .cindex "ignoring faulty addresses" | |
18444 | .cindex "skipping faulty addresses" | |
18445 | .cindex "error" "skipping bad syntax" | |
18446 | If &%skip_syntax_errors%& is set, syntactically malformed addresses in | |
168e428f | 18447 | non-filter redirection data are skipped, and each failing address is logged. If |
9b371988 PH |
18448 | &%syntax_errors_to%& is set, a message is sent to the address it defines, |
18449 | giving details of the failures. If &%syntax_errors_text%& is set, its contents | |
168e428f | 18450 | are expanded and placed at the head of the error message generated by |
9b371988 PH |
18451 | &%syntax_errors_to%&. Usually it is appropriate to set &%syntax_errors_to%& to |
18452 | be the same address as the generic &%errors_to%& option. The | |
18453 | &%skip_syntax_errors%& option is often used when handling mailing lists. | |
168e428f PH |
18454 | |
18455 | If all the addresses in a redirection list are skipped because of syntax | |
18456 | errors, the router declines to handle the original address, and it is passed to | |
18457 | the following routers. | |
18458 | ||
9b371988 | 18459 | If &%skip_syntax_errors%& is set when an Exim filter is interpreted, any syntax |
168e428f PH |
18460 | error in the filter causes filtering to be abandoned without any action being |
18461 | taken. The incident is logged, and the router declines to handle the address, | |
18462 | so it is passed to the following routers. | |
18463 | ||
9b371988 PH |
18464 | .cindex "Sieve filter" "syntax errors in" |
18465 | Syntax errors in a Sieve filter file cause the &"keep"& action to occur. This | |
18466 | action is specified by RFC 3028. The values of &%skip_syntax_errors%&, | |
18467 | &%syntax_errors_to%&, and &%syntax_errors_text%& are not used. | |
168e428f | 18468 | |
9b371988 PH |
18469 | &%skip_syntax_errors%& can be used to specify that errors in users' forward |
18470 | lists or filter files should not prevent delivery. The &%syntax_errors_to%& | |
168e428f PH |
18471 | option, used with an address that does not get redirected, can be used to |
18472 | notify users of these errors, by means of a router like this: | |
9b371988 | 18473 | .code |
168e428f PH |
18474 | userforward: |
18475 | driver = redirect | |
18476 | allow_filter | |
18477 | check_local_user | |
18478 | file = $home/.forward | |
18479 | file_transport = address_file | |
18480 | pipe_transport = address_pipe | |
18481 | reply_transport = address_reply | |
18482 | no_verify | |
18483 | skip_syntax_errors | |
9b371988 | 18484 | syntax_errors_to = real-$local_part@$domain |
168e428f | 18485 | syntax_errors_text = \ |
9b371988 PH |
18486 | This is an automatically generated message. An error has\n\ |
18487 | been found in your .forward file. Details of the error are\n\ | |
18488 | reported below. While this error persists, you will receive\n\ | |
18489 | a copy of this message for every message that is addressed\n\ | |
18490 | to you. If your .forward file is a filter file, or if it is\n\ | |
18491 | a non-filter file containing no valid forwarding addresses,\n\ | |
18492 | a copy of each incoming message will be put in your normal\n\ | |
18493 | mailbox. If a non-filter file contains at least one valid\n\ | |
18494 | forwarding address, forwarding to the valid addresses will\n\ | |
18495 | happen, and those will be the only deliveries that occur. | |
18496 | .endd | |
168e428f | 18497 | You also need a router to ensure that local addresses that are prefixed by |
9b371988 PH |
18498 | &`real-`& are recognized, but not forwarded or filtered. For example, you could |
18499 | put this immediately before the &(userforward)& router: | |
18500 | .code | |
18501 | real_localuser: | |
18502 | driver = accept | |
18503 | check_local_user | |
18504 | local_part_prefix = real- | |
18505 | transport = local_delivery | |
18506 | .endd | |
595028e4 PH |
18507 | For security, it would probably be a good idea to restrict the use of this |
18508 | router to locally-generated messages, using a condition such as this: | |
18509 | .code | |
18510 | condition = ${if match {$sender_host_address}\ | |
18511 | {\N^(|127\.0\.0\.1)$\N}} | |
18512 | .endd | |
595028e4 | 18513 | |
168e428f | 18514 | |
9b371988 PH |
18515 | .option syntax_errors_text redirect string&!! unset |
18516 | See &%skip_syntax_errors%& above. | |
168e428f | 18517 | |
168e428f | 18518 | |
9b371988 PH |
18519 | .option syntax_errors_to redirect string unset |
18520 | See &%skip_syntax_errors%& above. | |
4f578862 PH |
18521 | .ecindex IIDredrou1 |
18522 | .ecindex IIDredrou2 | |
168e428f PH |
18523 | |
18524 | ||
18525 | ||
18526 | ||
18527 | ||
18528 | ||
9b371988 PH |
18529 | . //////////////////////////////////////////////////////////////////////////// |
18530 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 18531 | |
9b371988 PH |
18532 | .chapter "Environment for running local transports" "CHAPenvironment" &&& |
18533 | "Environment for local transports" | |
4f578862 PH |
18534 | .scindex IIDenvlotra1 "local transports" "environment for" |
18535 | .scindex IIDenvlotra2 "environment for local transports" | |
18536 | .scindex IIDenvlotra3 "transport" "local; environment for" | |
9b371988 | 18537 | Local transports handle deliveries to files and pipes. (The &(autoreply)& |
168e428f PH |
18538 | transport can be thought of as similar to a pipe.) Exim always runs transports |
18539 | in subprocesses, under specified uids and gids. Typical deliveries to local | |
18540 | mailboxes run under the uid and gid of the local user. | |
18541 | ||
18542 | Exim also sets a specific current directory while running the transport; for | |
9b371988 | 18543 | some transports a home directory setting is also relevant. The &(pipe)& |
168e428f | 18544 | transport is the only one that sets up environment variables; see section |
9b371988 | 18545 | &<<SECTpipeenv>>& for details. |
168e428f PH |
18546 | |
18547 | The values used for the uid, gid, and the directories may come from several | |
18548 | different places. In many cases, the router that handles the address associates | |
9b371988 PH |
18549 | settings with that address as a result of its &%check_local_user%&, &%group%&, |
18550 | or &%user%& options. However, values may also be given in the transport's own | |
168e428f PH |
18551 | configuration, and these override anything that comes from the router. |
18552 | ||
18553 | ||
18554 | ||
f89d2485 | 18555 | .section "Concurrent deliveries" "SECID131" |
9b371988 PH |
18556 | .cindex "concurrent deliveries" |
18557 | .cindex "simultaneous deliveries" | |
f89d2485 | 18558 | If two different messages for the same local recipient arrive more or less |
168e428f | 18559 | simultaneously, the two delivery processes are likely to run concurrently. When |
9b371988 | 18560 | the &(appendfile)& transport is used to write to a file, Exim applies locking |
168e428f PH |
18561 | rules to stop concurrent processes from writing to the same file at the same |
18562 | time. | |
18563 | ||
9b371988 | 18564 | However, when you use a &(pipe)& transport, it is up to you to arrange any |
168e428f | 18565 | locking that is needed. Here is a silly example: |
9b371988 PH |
18566 | .code |
18567 | my_transport: | |
18568 | driver = pipe | |
18569 | command = /bin/sh -c 'cat >>/some/file' | |
18570 | .endd | |
168e428f PH |
18571 | This is supposed to write the message at the end of the file. However, if two |
18572 | messages arrive at the same time, the file will be scrambled. You can use the | |
9b371988 PH |
18573 | &%exim_lock%& utility program (see section &<<SECTmailboxmaint>>&) to lock a |
18574 | file using the same algorithm that Exim itself uses. | |
168e428f PH |
18575 | |
18576 | ||
18577 | ||
18578 | ||
9b371988 PH |
18579 | .section "Uids and gids" "SECTenvuidgid" |
18580 | .cindex "local transports" "uid and gid" | |
18581 | .cindex "transport" "local; uid and gid" | |
18582 | All transports have the options &%group%& and &%user%&. If &%group%& is set, it | |
18583 | overrides any group that the router set in the address, even if &%user%& is not | |
168e428f PH |
18584 | set for the transport. This makes it possible, for example, to run local mail |
18585 | delivery under the uid of the recipient (set by the router), but in a special | |
18586 | group (set by the transport). For example: | |
9b371988 PH |
18587 | .code |
18588 | # Routers ... | |
18589 | # User/group are set by check_local_user in this router | |
18590 | local_users: | |
18591 | driver = accept | |
18592 | check_local_user | |
18593 | transport = group_delivery | |
168e428f | 18594 | |
9b371988 PH |
18595 | # Transports ... |
18596 | # This transport overrides the group | |
18597 | group_delivery: | |
18598 | driver = appendfile | |
18599 | file = /var/spool/mail/$local_part | |
18600 | group = mail | |
18601 | .endd | |
18602 | If &%user%& is set for a transport, its value overrides what is set in the | |
18603 | address by the router. If &%user%& is non-numeric and &%group%& is not set, the | |
18604 | gid associated with the user is used. If &%user%& is numeric, &%group%& must be | |
18605 | set. | |
168e428f | 18606 | |
0a4e3112 | 18607 | .oindex "&%initgroups%&" |
9b371988 PH |
18608 | When the uid is taken from the transport's configuration, the &[initgroups()]& |
18609 | function is called for the groups associated with that uid if the | |
18610 | &%initgroups%& option is set for the transport. When the uid is not specified | |
18611 | by the transport, but is associated with the address by a router, the option | |
18612 | for calling &[initgroups()]& is taken from the router configuration. | |
18613 | ||
18614 | .cindex "&(pipe)& transport" "uid for" | |
18615 | The &(pipe)& transport contains the special option &%pipe_as_creator%&. If this | |
18616 | is set and &%user%& is not set, the uid of the process that called Exim to | |
18617 | receive the message is used, and if &%group%& is not set, the corresponding | |
18618 | original gid is also used. | |
168e428f | 18619 | |
9b371988 PH |
18620 | This is the detailed preference order for obtaining a gid; the first of the |
18621 | following that is set is used: | |
18622 | ||
18623 | .ilist | |
18624 | A &%group%& setting of the transport; | |
18625 | .next | |
18626 | A &%group%& setting of the router; | |
18627 | .next | |
18628 | A gid associated with a user setting of the router, either as a result of | |
18629 | &%check_local_user%& or an explicit non-numeric &%user%& setting; | |
18630 | .next | |
18631 | The group associated with a non-numeric &%user%& setting of the transport; | |
18632 | .next | |
18633 | In a &(pipe)& transport, the creator's gid if &%deliver_as_creator%& is set and | |
18634 | the uid is the creator's uid; | |
18635 | .next | |
18636 | The Exim gid if the Exim uid is being used as a default. | |
18637 | .endlist | |
18638 | ||
18639 | If, for example, the user is specified numerically on the router and there are | |
18640 | no group settings, no gid is available. In this situation, an error occurs. | |
18641 | This is different for the uid, for which there always is an ultimate default. | |
18642 | The first of the following that is set is used: | |
18643 | ||
18644 | .ilist | |
18645 | A &%user%& setting of the transport; | |
18646 | .next | |
18647 | In a &(pipe)& transport, the creator's uid if &%deliver_as_creator%& is set; | |
18648 | .next | |
18649 | A &%user%& setting of the router; | |
18650 | .next | |
18651 | A &%check_local_user%& setting of the router; | |
18652 | .next | |
18653 | The Exim uid. | |
18654 | .endlist | |
18655 | ||
18656 | Of course, an error will still occur if the uid that is chosen is on the | |
18657 | &%never_users%& list. | |
9b371988 PH |
18658 | |
18659 | ||
18660 | ||
18661 | ||
18662 | ||
f89d2485 | 18663 | .section "Current and home directories" "SECID132" |
9b371988 PH |
18664 | .cindex "current directory for local transport" |
18665 | .cindex "home directory" "for local transport" | |
18666 | .cindex "transport" "local; home directory for" | |
18667 | .cindex "transport" "local; current directory for" | |
168e428f | 18668 | Routers may set current and home directories for local transports by means of |
9b371988 PH |
18669 | the &%transport_current_directory%& and &%transport_home_directory%& options. |
18670 | However, if the transport's &%current_directory%& or &%home_directory%& options | |
168e428f PH |
18671 | are set, they override the router's values. In detail, the home directory |
18672 | for a local transport is taken from the first of these values that is set: | |
18673 | ||
9b371988 PH |
18674 | .ilist |
18675 | The &%home_directory%& option on the transport; | |
18676 | .next | |
18677 | The &%transport_home_directory%& option on the router; | |
18678 | .next | |
18679 | The password data if &%check_local_user%& is set on the router; | |
18680 | .next | |
18681 | The &%router_home_directory%& option on the router. | |
18682 | .endlist | |
168e428f PH |
18683 | |
18684 | The current directory is taken from the first of these values that is set: | |
18685 | ||
9b371988 PH |
18686 | .ilist |
18687 | The &%current_directory%& option on the transport; | |
18688 | .next | |
18689 | The &%transport_current_directory%& option on the router. | |
18690 | .endlist | |
168e428f PH |
18691 | |
18692 | ||
18693 | If neither the router nor the transport sets a current directory, Exim uses the | |
18694 | value of the home directory, if it is set. Otherwise it sets the current | |
9b371988 | 18695 | directory to &_/_& before running a local transport. |
168e428f PH |
18696 | |
18697 | ||
18698 | ||
f89d2485 PH |
18699 | .section "Expansion variables derived from the address" "SECID133" |
18700 | .vindex "&$domain$&" | |
18701 | .vindex "&$local_part$&" | |
18702 | .vindex "&$original_domain$&" | |
168e428f | 18703 | Normally a local delivery is handling a single address, and in that case the |
9b371988 PH |
18704 | variables such as &$domain$& and &$local_part$& are set during local |
18705 | deliveries. However, in some circumstances more than one address may be handled | |
18706 | at once (for example, while writing batch SMTP for onward transmission by some | |
18707 | other means). In this case, the variables associated with the local part are | |
18708 | never set, &$domain$& is set only if all the addresses have the same domain, | |
18709 | and &$original_domain$& is never set. | |
4f578862 PH |
18710 | .ecindex IIDenvlotra1 |
18711 | .ecindex IIDenvlotra2 | |
18712 | .ecindex IIDenvlotra3 | |
168e428f PH |
18713 | |
18714 | ||
18715 | ||
18716 | ||
18717 | ||
18718 | ||
18719 | ||
9b371988 PH |
18720 | . //////////////////////////////////////////////////////////////////////////// |
18721 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 18722 | |
9b371988 | 18723 | .chapter "Generic options for transports" "CHAPtransportgeneric" |
4f578862 PH |
18724 | .scindex IIDgenoptra1 "generic options" "transport" |
18725 | .scindex IIDgenoptra2 "options" "generic; for transports" | |
18726 | .scindex IIDgenoptra3 "transport" "generic options for" | |
168e428f PH |
18727 | The following generic options apply to all transports: |
18728 | ||
18729 | ||
9b371988 PH |
18730 | .option body_only transports boolean false |
18731 | .cindex "transport" "body only" | |
18732 | .cindex "message" "transporting body only" | |
18733 | .cindex "body of message" "transporting" | |
168e428f | 18734 | If this option is set, the message's headers are not transported. It is |
9b371988 PH |
18735 | mutually exclusive with &%headers_only%&. If it is used with the &(appendfile)& |
18736 | or &(pipe)& transports, the settings of &%message_prefix%& and | |
18737 | &%message_suffix%& should be checked, because this option does not | |
18738 | automatically suppress them. | |
168e428f PH |
18739 | |
18740 | ||
9b371988 PH |
18741 | .option current_directory transports string&!! unset |
18742 | .cindex "transport" "current directory for" | |
168e428f PH |
18743 | This specifies the current directory that is to be set while running the |
18744 | transport, overriding any value that may have been set by the router. | |
18745 | If the expansion fails for any reason, including forced failure, an error is | |
18746 | logged, and delivery is deferred. | |
18747 | ||
18748 | ||
9b371988 | 18749 | .option disable_logging transports boolean false |
168e428f PH |
18750 | If this option is set true, nothing is logged for any |
18751 | deliveries by the transport or for any | |
18752 | transport errors. You should not set this option unless you really, really know | |
18753 | what you are doing. | |
18754 | ||
18755 | ||
9b371988 PH |
18756 | .option debug_print transports string&!! unset |
18757 | .cindex "testing" "variables in drivers" | |
18758 | If this option is set and debugging is enabled (see the &%-d%& command line | |
168e428f PH |
18759 | option), the string is expanded and included in the debugging output when the |
18760 | transport is run. | |
18761 | If expansion of the string fails, the error message is written to the debugging | |
18762 | output, and Exim carries on processing. | |
18763 | This facility is provided to help with checking out the values of variables and | |
9b371988 PH |
18764 | so on when debugging driver configurations. For example, if a &%headers_add%& |
18765 | option is not working properly, &%debug_print%& could be used to output the | |
168e428f PH |
18766 | variables it references. A newline is added to the text if it does not end with |
18767 | one. | |
18768 | ||
18769 | ||
9b371988 PH |
18770 | .option delivery_date_add transports boolean false |
18771 | .cindex "&'Delivery-date:'& header line" | |
18772 | If this option is true, a &'Delivery-date:'& header is added to the message. | |
18773 | This gives the actual time the delivery was made. As this is not a standard | |
18774 | header, Exim has a configuration option (&%delivery_date_remove%&) which | |
18775 | requests its removal from incoming messages, so that delivered messages can | |
18776 | safely be resent to other recipients. | |
168e428f PH |
18777 | |
18778 | ||
9b371988 | 18779 | .option driver transports string unset |
168e428f PH |
18780 | This specifies which of the available transport drivers is to be used. |
18781 | There is no default, and this option must be set for every transport. | |
18782 | ||
18783 | ||
9b371988 PH |
18784 | .option envelope_to_add transports boolean false |
18785 | .cindex "&'Envelope-to:'& header line" | |
18786 | If this option is true, an &'Envelope-to:'& header is added to the message. | |
18787 | This gives the original address(es) in the incoming envelope that caused this | |
168e428f PH |
18788 | delivery to happen. More than one address may be present if the transport is |
18789 | configured to handle several addresses at once, or if more than one original | |
18790 | address was redirected to the same final address. As this is not a standard | |
9b371988 | 18791 | header, Exim has a configuration option (&%envelope_to_remove%&) which requests |
168e428f PH |
18792 | its removal from incoming messages, so that delivered messages can safely be |
18793 | resent to other recipients. | |
18794 | ||
18795 | ||
9b371988 PH |
18796 | .option group transports string&!! "Exim group" |
18797 | .cindex "transport" "group; specifying" | |
168e428f PH |
18798 | This option specifies a gid for running the transport process, overriding any |
18799 | value that the router supplies, and also overriding any value associated with | |
9b371988 | 18800 | &%user%& (see below). |
168e428f | 18801 | |
168e428f | 18802 | |
9b371988 PH |
18803 | .option headers_add transports string&!! unset |
18804 | .cindex "header lines" "adding in transport" | |
18805 | .cindex "transport" "header lines; adding" | |
168e428f PH |
18806 | This option specifies a string of text that is expanded and added to the header |
18807 | portion of a message as it is transported, as described in section | |
9b371988 PH |
18808 | &<<SECTheadersaddrem>>&. Additional header lines can also be specified by |
18809 | routers. If the result of the expansion is an empty string, or if the expansion | |
18810 | is forced to fail, no action is taken. Other expansion failures are treated as | |
168e428f PH |
18811 | errors and cause the delivery to be deferred. |
18812 | ||
18813 | ||
18814 | ||
9b371988 PH |
18815 | .option headers_only transports boolean false |
18816 | .cindex "transport" "header lines only" | |
18817 | .cindex "message" "transporting headers only" | |
18818 | .cindex "header lines" "transporting" | |
168e428f | 18819 | If this option is set, the message's body is not transported. It is mutually |
9b371988 PH |
18820 | exclusive with &%body_only%&. If it is used with the &(appendfile)& or &(pipe)& |
18821 | transports, the settings of &%message_prefix%& and &%message_suffix%& should be | |
168e428f PH |
18822 | checked, since this option does not automatically suppress them. |
18823 | ||
18824 | ||
9b371988 PH |
18825 | .option headers_remove transports string&!! unset |
18826 | .cindex "header lines" "removing" | |
18827 | .cindex "transport" "header lines; removing" | |
168e428f PH |
18828 | This option specifies a string that is expanded into a list of header names; |
18829 | these headers are omitted from the message as it is transported, as described | |
9b371988 | 18830 | in section &<<SECTheadersaddrem>>&. Header removal can also be specified by |
168e428f PH |
18831 | routers. If the result of the expansion is an empty string, or if the expansion |
18832 | is forced to fail, no action is taken. Other expansion failures are treated as | |
18833 | errors and cause the delivery to be deferred. | |
18834 | ||
18835 | ||
18836 | ||
9b371988 PH |
18837 | .option headers_rewrite transports string unset |
18838 | .cindex "transport" "header lines; rewriting" | |
18839 | .cindex "rewriting" "at transport time" | |
168e428f PH |
18840 | This option allows addresses in header lines to be rewritten at transport time, |
18841 | that is, as the message is being copied to its destination. The contents of the | |
18842 | option are a colon-separated list of rewriting rules. Each rule is in exactly | |
18843 | the same form as one of the general rewriting rules that are applied when a | |
9b371988 PH |
18844 | message is received. These are described in chapter &<<CHAPrewrite>>&. For |
18845 | example, | |
18846 | .code | |
168e428f PH |
18847 | headers_rewrite = a@b c@d f : \ |
18848 | x@y w@z | |
9b371988 PH |
18849 | .endd |
18850 | changes &'a@b'& into &'c@d'& in &'From:'& header lines, and &'x@y'& into | |
18851 | &'w@z'& in all address-bearing header lines. The rules are applied to the | |
18852 | header lines just before they are written out at transport time, so they affect | |
18853 | only those copies of the message that pass through the transport. However, only | |
18854 | the message's original header lines, and any that were added by a system | |
18855 | filter, are rewritten. If a router or transport adds header lines, they are not | |
18856 | affected by this option. These rewriting rules are &'not'& applied to the | |
18857 | envelope. You can change the return path using &%return_path%&, but you cannot | |
168e428f PH |
18858 | change envelope recipients at this time. |
18859 | ||
18860 | ||
9b371988 PH |
18861 | .option home_directory transports string&!! unset |
18862 | .cindex "transport" "home directory for" | |
f89d2485 | 18863 | .vindex "&$home$&" |
c0712871 | 18864 | This option specifies a home directory setting for a local transport, |
4f578862 PH |
18865 | overriding any value that may be set by the router. The home directory is |
18866 | placed in &$home$& while expanding the transport's private options. It is also | |
18867 | used as the current directory if no current directory is set by the | |
9b371988 | 18868 | &%current_directory%& option on the transport or the |
4f578862 PH |
18869 | &%transport_current_directory%& option on the router. If the expansion fails |
18870 | for any reason, including forced failure, an error is logged, and delivery is | |
18871 | deferred. | |
168e428f PH |
18872 | |
18873 | ||
9b371988 PH |
18874 | .option initgroups transports boolean false |
18875 | .cindex "additional groups" | |
18876 | .cindex "groups" "additional" | |
18877 | .cindex "transport" "group; additional" | |
168e428f | 18878 | If this option is true and the uid for the delivery process is provided by the |
9b371988 | 18879 | transport, the &[initgroups()]& function is called when running the transport |
168e428f PH |
18880 | to ensure that any additional groups associated with the uid are set up. |
18881 | ||
18882 | ||
9b371988 PH |
18883 | .option message_size_limit transports string&!! 0 |
18884 | .cindex "limit" "message size per transport" | |
f89d2485 | 18885 | .cindex "size" "of message, limit" |
9b371988 | 18886 | .cindex "transport" "message size; limiting" |
168e428f | 18887 | This option controls the size of messages passed through the transport. It is |
ad268134 PH |
18888 | expanded before use; the result of the expansion must be a sequence of decimal |
18889 | digits, optionally followed by K or M. If the expansion fails for any reason, | |
18890 | including forced failure, or if the result is not of the required form, | |
18891 | delivery is deferred. If the value is greater than zero and the size of a | |
18892 | message exceeds this limit, the address is failed. If there is any chance that | |
18893 | the resulting bounce message could be routed to the same transport, you should | |
18894 | ensure that &%return_size_limit%& is less than the transport's | |
18895 | &%message_size_limit%&, as otherwise the bounce message will fail to get | |
18896 | delivered. | |
168e428f PH |
18897 | |
18898 | ||
18899 | ||
9b371988 | 18900 | .option rcpt_include_affixes transports boolean false |
f89d2485 PH |
18901 | .cindex "prefix" "for local part, including in envelope" |
18902 | .cindex "suffix for local part" "including in envelope" | |
9b371988 PH |
18903 | .cindex "local part" "prefix" |
18904 | .cindex "local part" "suffix" | |
168e428f PH |
18905 | When this option is false (the default), and an address that has had any |
18906 | affixes (prefixes or suffixes) removed from the local part is delivered by any | |
18907 | form of SMTP or LMTP, the affixes are not included. For example, if a router | |
18908 | that contains | |
9b371988 PH |
18909 | .code |
18910 | local_part_prefix = *- | |
18911 | .endd | |
18912 | routes the address &'abc-xyz@some.domain'& to an SMTP transport, the envelope | |
168e428f | 18913 | is delivered with |
9b371988 PH |
18914 | .code |
18915 | RCPT TO:<xyz@some.domain> | |
18916 | .endd | |
4f578862 PH |
18917 | This is also the case when an ACL-time callout is being used to verify a |
18918 | recipient address. However, if &%rcpt_include_affixes%& is set true, the | |
9b371988 PH |
18919 | whole local part is included in the RCPT command. This option applies to BSMTP |
18920 | deliveries by the &(appendfile)& and &(pipe)& transports as well as to the | |
18921 | &(lmtp)& and &(smtp)& transports. | |
18922 | ||
18923 | ||
18924 | .option retry_use_local_part transports boolean "see below" | |
18925 | .cindex "hints database" "retry keys" | |
168e428f PH |
18926 | When a delivery suffers a temporary failure, a retry record is created |
18927 | in Exim's hints database. For remote deliveries, the key for the retry record | |
18928 | is based on the name and/or IP address of the failing remote host. For local | |
18929 | deliveries, the key is normally the entire address, including both the local | |
18930 | part and the domain. This is suitable for most common cases of local delivery | |
9b371988 | 18931 | temporary failure &-- for example, exceeding a mailbox quota should delay only |
168e428f PH |
18932 | deliveries to that mailbox, not to the whole domain. |
18933 | ||
18934 | However, in some special cases you may want to treat a temporary local delivery | |
18935 | as a failure associated with the domain, and not with a particular local part. | |
18936 | (For example, if you are storing all mail for some domain in files.) You can do | |
9b371988 | 18937 | this by setting &%retry_use_local_part%& false. |
168e428f PH |
18938 | |
18939 | For all the local transports, its default value is true. For remote transports, | |
18940 | the default value is false for tidiness, but changing the value has no effect | |
18941 | on a remote transport in the current implementation. | |
18942 | ||
18943 | ||
9b371988 PH |
18944 | .option return_path transports string&!! unset |
18945 | .cindex "envelope sender" | |
18946 | .cindex "transport" "return path; changing" | |
18947 | .cindex "return path" "changing in transport" | |
168e428f PH |
18948 | If this option is set, the string is expanded at transport time and replaces |
18949 | the existing return path (envelope sender) value in the copy of the message | |
18950 | that is being delivered. An empty return path is permitted. This feature is | |
18951 | designed for remote deliveries, where the value of this option is used in the | |
9b371988 PH |
18952 | SMTP MAIL command. If you set &%return_path%& for a local transport, the |
18953 | only effect is to change the address that is placed in the &'Return-path:'& | |
168e428f PH |
18954 | header line, if one is added to the message (see the next option). |
18955 | ||
db9452a9 PH |
18956 | &*Note:*& A changed return path is not logged unless you add |
18957 | &%return_path_on_delivery%& to the log selector. | |
db9452a9 | 18958 | |
f89d2485 | 18959 | .vindex "&$return_path$&" |
9b371988 | 18960 | The expansion can refer to the existing value via &$return_path$&. This is |
168e428f | 18961 | either the message's envelope sender, or an address set by the |
9b371988 | 18962 | &%errors_to%& option on a router. If the expansion is forced to fail, no |
168e428f | 18963 | replacement occurs; if it fails for another reason, delivery is deferred. This |
9b371988 | 18964 | option can be used to support VERP (Variable Envelope Return Paths) &-- see |
4f578862 | 18965 | section &<<SECTverp>>&. |
168e428f | 18966 | |
4f578862 PH |
18967 | &*Note*&: If a delivery error is detected locally, including the case when a |
18968 | remote server rejects a message at SMTP time, the bounce message is not sent to | |
18969 | the value of this option. It is sent to the previously set errors address. | |
18970 | This defaults to the incoming sender address, but can be changed by setting | |
18971 | &%errors_to%& in a router. | |
168e428f PH |
18972 | |
18973 | ||
18974 | ||
9b371988 PH |
18975 | .option return_path_add transports boolean false |
18976 | .cindex "&'Return-path:'& header line" | |
18977 | If this option is true, a &'Return-path:'& header is added to the message. | |
168e428f PH |
18978 | Although the return path is normally available in the prefix line of BSD |
18979 | mailboxes, this is commonly not displayed by MUAs, and so the user does not | |
18980 | have easy access to it. | |
18981 | ||
9b371988 PH |
18982 | RFC 2821 states that the &'Return-path:'& header is added to a message &"when |
18983 | the delivery SMTP server makes the final delivery"&. This implies that this | |
18984 | header should not be present in incoming messages. Exim has a configuration | |
18985 | option, &%return_path_remove%&, which requests removal of this header from | |
18986 | incoming messages, so that delivered messages can safely be resent to other | |
18987 | recipients. | |
168e428f | 18988 | |
168e428f | 18989 | |
9b371988 PH |
18990 | .option shadow_condition transports string&!! unset |
18991 | See &%shadow_transport%& below. | |
168e428f PH |
18992 | |
18993 | ||
9b371988 PH |
18994 | .option shadow_transport transports string unset |
18995 | .cindex "shadow transport" | |
18996 | .cindex "transport" "shadow" | |
18997 | A local transport may set the &%shadow_transport%& option to the name of | |
18998 | another local transport. Shadow remote transports are not supported. | |
168e428f PH |
18999 | |
19000 | Whenever a delivery to the main transport succeeds, and either | |
9b371988 PH |
19001 | &%shadow_condition%& is unset, or its expansion does not result in the empty |
19002 | string or one of the strings &"0"& or &"no"& or &"false"&, the message is also | |
19003 | passed to the shadow transport, with the same delivery address or addresses. If | |
19004 | expansion fails, no action is taken except that non-forced expansion failures | |
19005 | cause a log line to be written. | |
168e428f PH |
19006 | |
19007 | The result of the shadow transport is discarded and does not affect the | |
19008 | subsequent processing of the message. Only a single level of shadowing is | |
9b371988 PH |
19009 | provided; the &%shadow_transport%& option is ignored on any transport when it |
19010 | is running as a shadow. Options concerned with output from pipes are also | |
19011 | ignored. The log line for the successful delivery has an item added on the end, | |
19012 | of the form | |
19013 | .code | |
19014 | ST=<shadow transport name> | |
19015 | .endd | |
168e428f | 19016 | If the shadow transport did not succeed, the error message is put in |
9b371988 PH |
19017 | parentheses afterwards. Shadow transports can be used for a number of different |
19018 | purposes, including keeping more detailed log information than Exim normally | |
f89d2485 | 19019 | provides, and implementing automatic acknowledgment policies based on message |
9b371988 | 19020 | headers that some sites insist on. |
168e428f PH |
19021 | |
19022 | ||
9b371988 PH |
19023 | .option transport_filter transports string&!! unset |
19024 | .cindex "transport" "filter" | |
19025 | .cindex "filter" "transport filter" | |
168e428f PH |
19026 | This option sets up a filtering (in the Unix shell sense) process for messages |
19027 | at transport time. It should not be confused with mail filtering as set up by | |
19028 | individual users or via a system filter. | |
19029 | ||
19030 | When the message is about to be written out, the command specified by | |
4f578862 | 19031 | &%transport_filter%& is started up in a separate, parallel process, and |
9b371988 PH |
19032 | the entire message, including the header lines, is passed to it on its standard |
19033 | input (this in fact is done from a third process, to avoid deadlock). The | |
19034 | command must be specified as an absolute path. | |
168e428f PH |
19035 | |
19036 | The lines of the message that are written to the transport filter are | |
9b371988 PH |
19037 | terminated by newline (&"\n"&). The message is passed to the filter before any |
19038 | SMTP-specific processing, such as turning &"\n"& into &"\r\n"& and escaping | |
068aaea8 | 19039 | lines beginning with a dot, and also before any processing implied by the |
9b371988 PH |
19040 | settings of &%check_string%& and &%escape_string%& in the &(appendfile)& or |
19041 | &(pipe)& transports. | |
168e428f PH |
19042 | |
19043 | The standard error for the filter process is set to the same destination as its | |
19044 | standard output; this is read and written to the message's ultimate | |
4f578862 | 19045 | destination. The process that writes the message to the filter, the |
9b371988 | 19046 | filter itself, and the original process that reads the result and delivers it |
4f578862 | 19047 | are all run in parallel, like a shell pipeline. |
9b371988 PH |
19048 | |
19049 | The filter can perform any transformations it likes, but of course should take | |
94fb0f79 TF |
19050 | care not to break RFC 2822 syntax. Exim does not check the result, except to |
19051 | test for a final newline when SMTP is in use. All messages transmitted over | |
19052 | SMTP must end with a newline, so Exim supplies one if it is missing. | |
9b371988 | 19053 | |
9b371988 | 19054 | .cindex "content scanning" "per user" |
068aaea8 PH |
19055 | A transport filter can be used to provide content-scanning on a per-user basis |
19056 | at delivery time if the only required effect of the scan is to modify the | |
19057 | message. For example, a content scan could insert a new header line containing | |
19058 | a spam score. This could be interpreted by a filter in the user's MUA. It is | |
19059 | not possible to discard a message at this stage. | |
168e428f | 19060 | |
9b371988 | 19061 | .cindex "SMTP" "SIZE" |
168e428f PH |
19062 | A problem might arise if the filter increases the size of a message that is |
19063 | being sent down an SMTP connection. If the receiving SMTP server has indicated | |
19064 | support for the SIZE parameter, Exim will have sent the size of the message | |
19065 | at the start of the SMTP session. If what is actually sent is substantially | |
19066 | more, the server might reject the message. This can be worked round by setting | |
9b371988 | 19067 | the &%size_addition%& option on the &(smtp)& transport, either to allow for |
168e428f PH |
19068 | additions to the message, or to disable the use of SIZE altogether. |
19069 | ||
f89d2485 | 19070 | .vindex "&$pipe_addresses$&" |
9b371988 | 19071 | The value of the &%transport_filter%& option is the command string for starting |
168e428f | 19072 | the filter, which is run directly from Exim, not under a shell. The string is |
9b371988 | 19073 | parsed by Exim in the same way as a command string for the &(pipe)& transport: |
4f578862 PH |
19074 | Exim breaks it up into arguments and then expands each argument separately (see |
19075 | section &<<SECThowcommandrun>>&). Any kind of expansion failure causes delivery | |
19076 | to be deferred. The special argument &$pipe_addresses$& is replaced by a number | |
19077 | of arguments, one for each address that applies to this delivery. (This isn't | |
19078 | an ideal name for this feature here, but as it was already implemented for the | |
19079 | &(pipe)& transport, it seemed sensible not to change it.) | |
168e428f | 19080 | |
f89d2485 PH |
19081 | .vindex "&$host$&" |
19082 | .vindex "&$host_address$&" | |
9b371988 | 19083 | The expansion variables &$host$& and &$host_address$& are available when the |
168e428f PH |
19084 | transport is a remote one. They contain the name and IP address of the host to |
19085 | which the message is being sent. For example: | |
9b371988 | 19086 | .code |
168e428f PH |
19087 | transport_filter = /some/directory/transport-filter.pl \ |
19088 | $host $host_address $sender_address $pipe_addresses | |
9b371988 | 19089 | .endd |
168e428f | 19090 | |
4f578862 PH |
19091 | Two problems arise if you want to use more complicated expansion items to |
19092 | generate transport filter commands, both of which due to the fact that the | |
19093 | command is split up &'before'& expansion. | |
19094 | .ilist | |
19095 | If an expansion item contains white space, you must quote it, so that it is all | |
19096 | part of the same command item. If the entire option setting is one such | |
19097 | expansion item, you have to take care what kind of quoting you use. For | |
19098 | example: | |
19099 | .code | |
19100 | transport_filter = '/bin/cmd${if eq{$host}{a.b.c}{1}{2}}' | |
19101 | .endd | |
19102 | This runs the command &(/bin/cmd1)& if the host name is &'a.b.c'&, and | |
19103 | &(/bin/cmd2)& otherwise. If double quotes had been used, they would have been | |
19104 | stripped by Exim when it read the option's value. When the value is used, if | |
19105 | the single quotes were missing, the line would be split into two items, | |
19106 | &`/bin/cmd${if`& and &`eq{$host}{a.b.c}{1}{2}`&, and an error would occur when | |
19107 | Exim tried to expand the first one. | |
19108 | .next | |
19109 | Except for the special case of &$pipe_addresses$& that is mentioned above, an | |
19110 | expansion cannot generate multiple arguments, or a command name followed by | |
19111 | arguments. Consider this example: | |
19112 | .code | |
f89d2485 | 19113 | transport_filter = ${lookup{$host}lsearch{/a/file}\ |
4f578862 PH |
19114 | {$value}{/bin/cat}} |
19115 | .endd | |
19116 | The result of the lookup is interpreted as the name of the command, even | |
19117 | if it contains white space. The simplest way round this is to use a shell: | |
19118 | .code | |
f89d2485 | 19119 | transport_filter = /bin/sh -c ${lookup{$host}lsearch{/a/file}\ |
4f578862 PH |
19120 | {$value}{/bin/cat}} |
19121 | .endd | |
19122 | .endlist | |
168e428f | 19123 | |
4f578862 PH |
19124 | The filter process is run under the same uid and gid as the normal delivery. |
19125 | For remote deliveries this is the Exim uid/gid by default. The command should | |
19126 | normally yield a zero return code. Transport filters are not supposed to fail. | |
19127 | A non-zero code is taken to mean that the transport filter encountered some | |
19128 | serious problem. Delivery of the message is deferred; the message remains on | |
19129 | the queue and is tried again later. It is not possible to cause a message to be | |
19130 | bounced from a transport filter. | |
19131 | ||
168e428f PH |
19132 | If a transport filter is set on an autoreply transport, the original message is |
19133 | passed through the filter as it is being copied into the newly generated | |
9b371988 | 19134 | message, which happens if the &%return_message%& option is set. |
168e428f PH |
19135 | |
19136 | ||
9b371988 | 19137 | .option transport_filter_timeout transports time 5m |
f89d2485 | 19138 | .cindex "transport" "filter, timeout" |
168e428f | 19139 | When Exim is reading the output of a transport filter, it a applies a timeout |
068aaea8 PH |
19140 | that can be set by this option. Exceeding the timeout is normally treated as a |
19141 | temporary delivery failure. However, if a transport filter is used with a | |
9b371988 PH |
19142 | &(pipe)& transport, a timeout in the transport filter is treated in the same |
19143 | way as a timeout in the pipe command itself. By default, a timeout is a hard | |
19144 | error, but if the &(pipe)& transport's &%timeout_defer%& option is set true, it | |
19145 | becomes a temporary error. | |
168e428f PH |
19146 | |
19147 | ||
9b371988 PH |
19148 | .option user transports string&!! "Exim user" |
19149 | .cindex "uid (user id)" "local delivery" | |
f89d2485 | 19150 | .cindex "transport" "user, specifying" |
168e428f PH |
19151 | This option specifies the user under whose uid the delivery process is to be |
19152 | run, overriding any uid that may have been set by the router. If the user is | |
19153 | given as a name, the uid is looked up from the password data, and the | |
9b371988 | 19154 | associated group is taken as the value of the gid to be used if the &%group%& |
168e428f PH |
19155 | option is not set. |
19156 | ||
19157 | For deliveries that use local transports, a user and group are normally | |
19158 | specified explicitly or implicitly (for example, as a result of | |
9b371988 | 19159 | &%check_local_user%&) by the router or transport. |
168e428f | 19160 | |
9b371988 | 19161 | .cindex "hints database" "access by remote transport" |
168e428f PH |
19162 | For remote transports, you should leave this option unset unless you really are |
19163 | sure you know what you are doing. When a remote transport is running, it needs | |
19164 | to be able to access Exim's hints databases, because each host may have its own | |
19165 | retry data. | |
4f578862 PH |
19166 | .ecindex IIDgenoptra1 |
19167 | .ecindex IIDgenoptra2 | |
19168 | .ecindex IIDgenoptra3 | |
168e428f PH |
19169 | |
19170 | ||
19171 | ||
19172 | ||
19173 | ||
19174 | ||
9b371988 PH |
19175 | . //////////////////////////////////////////////////////////////////////////// |
19176 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 19177 | |
9b371988 PH |
19178 | .chapter "Address batching in local transports" "CHAPbatching" &&& |
19179 | "Address batching" | |
19180 | .cindex "transport" "local; address batching in" | |
19181 | The only remote transport (&(smtp)&) is normally configured to handle more than | |
168e428f PH |
19182 | one address at a time, so that when several addresses are routed to the same |
19183 | remote host, just one copy of the message is sent. Local transports, however, | |
19184 | normally handle one address at a time. That is, a separate instance of the | |
19185 | transport is run for each address that is routed to the transport. A separate | |
19186 | copy of the message is delivered each time. | |
19187 | ||
9b371988 | 19188 | .cindex "batched local delivery" |
0a4e3112 PH |
19189 | .oindex "&%batch_max%&" |
19190 | .oindex "&%batch_id%&" | |
168e428f PH |
19191 | In special cases, it may be desirable to handle several addresses at once in a |
19192 | local transport, for example: | |
19193 | ||
9b371988 PH |
19194 | .ilist |
19195 | In an &(appendfile)& transport, when storing messages in files for later | |
168e428f PH |
19196 | delivery by some other means, a single copy of the message with multiple |
19197 | recipients saves space. | |
9b371988 PH |
19198 | .next |
19199 | In an &(lmtp)& transport, when delivering over &"local SMTP"& to some process, | |
168e428f | 19200 | a single copy saves time, and is the normal way LMTP is expected to work. |
9b371988 PH |
19201 | .next |
19202 | In a &(pipe)& transport, when passing the message | |
168e428f PH |
19203 | to a scanner program or |
19204 | to some other delivery mechanism such as UUCP, multiple recipients may be | |
19205 | acceptable. | |
9b371988 | 19206 | .endlist |
168e428f | 19207 | |
c0712871 PH |
19208 | These three local transports all have the same options for controlling multiple |
19209 | (&"batched"&) deliveries, namely &%batch_max%& and &%batch_id%&. To save | |
19210 | repeating the information for each transport, these options are described here. | |
168e428f | 19211 | |
9b371988 | 19212 | The &%batch_max%& option specifies the maximum number of addresses that can be |
c0712871 PH |
19213 | delivered together in a single run of the transport. Its default value is one |
19214 | (no batching). When more than one address is routed to a transport that has a | |
19215 | &%batch_max%& value greater than one, the addresses are delivered in a batch | |
19216 | (that is, in a single run of the transport with multiple recipients), subject | |
19217 | to certain conditions: | |
168e428f | 19218 | |
9b371988 | 19219 | .ilist |
f89d2485 | 19220 | .vindex "&$local_part$&" |
9b371988 | 19221 | If any of the transport's options contain a reference to &$local_part$&, no |
168e428f | 19222 | batching is possible. |
9b371988 | 19223 | .next |
f89d2485 | 19224 | .vindex "&$domain$&" |
9b371988 | 19225 | If any of the transport's options contain a reference to &$domain$&, only |
168e428f | 19226 | addresses with the same domain are batched. |
9b371988 PH |
19227 | .next |
19228 | .cindex "customizing" "batching condition" | |
19229 | If &%batch_id%& is set, it is expanded for each address, and only those | |
168e428f | 19230 | addresses with the same expanded value are batched. This allows you to specify |
c0712871 PH |
19231 | customized batching conditions. Failure of the expansion for any reason, |
19232 | including forced failure, disables batching, but it does not stop the delivery | |
19233 | from taking place. | |
9b371988 PH |
19234 | .next |
19235 | Batched addresses must also have the same errors address (where to send | |
168e428f PH |
19236 | delivery errors), the same header additions and removals, the same user and |
19237 | group for the transport, and if a host list is present, the first host must | |
19238 | be the same. | |
9b371988 | 19239 | .endlist |
168e428f | 19240 | |
c0712871 PH |
19241 | In the case of the &(appendfile)& and &(pipe)& transports, batching applies |
19242 | both when the file or pipe command is specified in the transport, and when it | |
19243 | is specified by a &(redirect)& router, but all the batched addresses must of | |
19244 | course be routed to the same file or pipe command. These two transports have an | |
19245 | option called &%use_bsmtp%&, which causes them to deliver the message in | |
19246 | &"batched SMTP"& format, with the envelope represented as SMTP commands. The | |
19247 | &%check_string%& and &%escape_string%& options are forced to the values | |
9b371988 PH |
19248 | .code |
19249 | check_string = "." | |
19250 | escape_string = ".." | |
19251 | .endd | |
168e428f | 19252 | when batched SMTP is in use. A full description of the batch SMTP mechanism is |
9b371988 PH |
19253 | given in section &<<SECTbatchSMTP>>&. The &(lmtp)& transport does not have a |
19254 | &%use_bsmtp%& option, because it always delivers using the SMTP protocol. | |
168e428f | 19255 | |
c0712871 PH |
19256 | .cindex "&'Envelope-to:'& header line" |
19257 | If the generic &%envelope_to_add%& option is set for a batching transport, the | |
19258 | &'Envelope-to:'& header that is added to the message contains all the addresses | |
19259 | that are being processed together. If you are using a batching &(appendfile)& | |
19260 | transport without &%use_bsmtp%&, the only way to preserve the recipient | |
19261 | addresses is to set the &%envelope_to_add%& option. | |
19262 | ||
9b371988 | 19263 | .cindex "&(pipe)& transport" "with multiple addresses" |
f89d2485 | 19264 | .vindex "&$pipe_addresses$&" |
c0712871 PH |
19265 | If you are using a &(pipe)& transport without BSMTP, and setting the |
19266 | transport's &%command%& option, you can include &$pipe_addresses$& as part of | |
19267 | the command. This is not a true variable; it is a bit of magic that causes each | |
19268 | of the recipient addresses to be inserted into the command as a separate | |
19269 | argument. This provides a way of accessing all the addresses that are being | |
19270 | delivered in the batch. &*Note:*& This is not possible for pipe commands that | |
f89d2485 | 19271 | are specified by a &(redirect)& router. |
168e428f | 19272 | |
168e428f PH |
19273 | |
19274 | ||
19275 | ||
9b371988 PH |
19276 | . //////////////////////////////////////////////////////////////////////////// |
19277 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 19278 | |
9b371988 | 19279 | .chapter "The appendfile transport" "CHAPappendfile" |
4f578862 PH |
19280 | .scindex IIDapptra1 "&(appendfile)& transport" |
19281 | .scindex IIDapptra2 "transports" "&(appendfile)&" | |
9b371988 PH |
19282 | .cindex "directory creation" |
19283 | .cindex "creating directories" | |
19284 | The &(appendfile)& transport delivers a message by appending it to an existing | |
168e428f PH |
19285 | file, or by creating an entirely new file in a specified directory. Single |
19286 | files to which messages are appended can be in the traditional Unix mailbox | |
19287 | format, or optionally in the MBX format supported by the Pine MUA and | |
9b371988 PH |
19288 | University of Washington IMAP daemon, &'inter alia'&. When each message is |
19289 | being delivered as a separate file, &"maildir"& format can optionally be used | |
19290 | to give added protection against failures that happen part-way through the | |
19291 | delivery. A third form of separate-file delivery known as &"mailstore"& is also | |
168e428f | 19292 | supported. For all file formats, Exim attempts to create as many levels of |
9b371988 | 19293 | directory as necessary, provided that &%create_directory%& is set. |
168e428f PH |
19294 | |
19295 | The code for the optional formats is not included in the Exim binary by | |
19296 | default. It is necessary to set SUPPORT_MBX, SUPPORT_MAILDIR and/or | |
9b371988 | 19297 | SUPPORT_MAILSTORE in &_Local/Makefile_& to have the appropriate code |
168e428f PH |
19298 | included. |
19299 | ||
9b371988 | 19300 | .cindex "quota" "system" |
f89d2485 | 19301 | Exim recognizes system quota errors, and generates an appropriate message. Exim |
168e428f PH |
19302 | also supports its own quota control within the transport, for use when the |
19303 | system facility is unavailable or cannot be used for some reason. | |
19304 | ||
19305 | If there is an error while appending to a file (for example, quota exceeded or | |
19306 | partition filled), Exim attempts to reset the file's length and last | |
19307 | modification time back to what they were before. If there is an error while | |
19308 | creating an entirely new file, the new file is removed. | |
19309 | ||
19310 | Before appending to a file, a number of security checks are made, and the | |
19311 | file is locked. A detailed description is given below, after the list of | |
19312 | private options. | |
19313 | ||
9b371988 PH |
19314 | The &(appendfile)& transport is most commonly used for local deliveries to |
19315 | users' mailboxes. However, it can also be used as a pseudo-remote transport for | |
19316 | putting messages into files for remote delivery by some means other than Exim. | |
19317 | &"Batch SMTP"& format is often used in this case (see the &%use_bsmtp%& | |
19318 | option). | |
168e428f PH |
19319 | |
19320 | ||
19321 | ||
9b371988 PH |
19322 | .section "The file and directory options" "SECTfildiropt" |
19323 | The &%file%& option specifies a single file, to which the message is appended; | |
19324 | the &%directory%& option specifies a directory, in which a new file containing | |
168e428f | 19325 | the message is created. Only one of these two options can be set, and for |
9b371988 | 19326 | normal deliveries to mailboxes, one of them &'must'& be set. |
168e428f | 19327 | |
f89d2485 PH |
19328 | .vindex "&$address_file$&" |
19329 | .vindex "&$local_part$&" | |
9b371988 | 19330 | However, &(appendfile)& is also used for delivering messages to files or |
168e428f | 19331 | directories whose names (or parts of names) are obtained from alias, |
9b371988 PH |
19332 | forwarding, or filtering operations (for example, a &%save%& command in a |
19333 | user's Exim filter). When such a transport is running, &$local_part$& contains | |
19334 | the local part that was aliased or forwarded, and &$address_file$& contains the | |
168e428f PH |
19335 | name (or partial name) of the file or directory generated by the redirection |
19336 | operation. There are two cases: | |
19337 | ||
9b371988 PH |
19338 | .ilist |
19339 | If neither &%file%& nor &%directory%& is set, the redirection operation | |
19340 | must specify an absolute path (one that begins with &`/`&). This is the most | |
168e428f | 19341 | common case when users with local accounts use filtering to sort mail into |
9b371988 | 19342 | different folders. See for example, the &(address_file)& transport in the |
168e428f PH |
19343 | default configuration. If the path ends with a slash, it is assumed to be the |
19344 | name of a directory. A delivery to a directory can also be forced by setting | |
9b371988 PH |
19345 | &%maildir_format%& or &%mailstore_format%&. |
19346 | .next | |
19347 | If &%file%& or &%directory%& is set for a delivery from a redirection, it is | |
19348 | used to determine the file or directory name for the delivery. Normally, the | |
19349 | contents of &$address_file$& are used in some way in the string expansion. | |
19350 | .endlist | |
168e428f PH |
19351 | |
19352 | ||
9b371988 PH |
19353 | .cindex "Sieve filter" "configuring &(appendfile)&" |
19354 | .cindex "Sieve filter" "relative mailbox path handling" | |
168e428f PH |
19355 | As an example of the second case, consider an environment where users do not |
19356 | have home directories. They may be permitted to use Exim filter commands of the | |
19357 | form: | |
9b371988 PH |
19358 | .code |
19359 | save folder23 | |
19360 | .endd | |
168e428f | 19361 | or Sieve filter commands of the form: |
9b371988 PH |
19362 | .code |
19363 | require "fileinto"; | |
19364 | fileinto "folder23"; | |
19365 | .endd | |
19366 | In this situation, the expansion of &%file%& or &%directory%& in the transport | |
19367 | must transform the relative path into an appropriate absolute file name. In the | |
19368 | case of Sieve filters, the name &'inbox'& must be handled. It is the name that | |
19369 | is used as a result of a &"keep"& action in the filter. This example shows one | |
19370 | way of handling this requirement: | |
19371 | .code | |
168e428f PH |
19372 | file = ${if eq{$address_file}{inbox} \ |
19373 | {/var/mail/$local_part} \ | |
19374 | {${if eq{${substr_0_1:$address_file}}{/} \ | |
19375 | {$address_file} \ | |
19376 | {$home/mail/$address_file} \ | |
19377 | }} \ | |
19378 | } | |
9b371988 PH |
19379 | .endd |
19380 | With this setting of &%file%&, &'inbox'& refers to the standard mailbox | |
19381 | location, absolute paths are used without change, and other folders are in the | |
19382 | &_mail_& directory within the home directory. | |
19383 | ||
19384 | &*Note 1*&: While processing an Exim filter, a relative path such as | |
19385 | &_folder23_& is turned into an absolute path if a home directory is known to | |
19386 | the router. In particular, this is the case if &%check_local_user%& is set. If | |
168e428f | 19387 | you want to prevent this happening at routing time, you can set |
9b371988 | 19388 | &%router_home_directory%& empty. This forces the router to pass the relative |
168e428f PH |
19389 | path to the transport. |
19390 | ||
9b371988 PH |
19391 | &*Note 2*&: An absolute path in &$address_file$& is not treated specially; |
19392 | the &%file%& or &%directory%& option is still used if it is set. | |
168e428f PH |
19393 | |
19394 | ||
19395 | ||
168e428f | 19396 | |
f89d2485 | 19397 | .section "Private options for appendfile" "SECID134" |
9b371988 | 19398 | .cindex "options" "&(appendfile)& transport" |
168e428f PH |
19399 | |
19400 | ||
168e428f | 19401 | |
9b371988 PH |
19402 | .option allow_fifo appendfile boolean false |
19403 | .cindex "fifo (named pipe)" | |
19404 | .cindex "named pipe (fifo)" | |
19405 | .cindex "pipe" "named (fifo)" | |
168e428f PH |
19406 | Setting this option permits delivery to named pipes (FIFOs) as well as to |
19407 | regular files. If no process is reading the named pipe at delivery time, the | |
19408 | delivery is deferred. | |
19409 | ||
19410 | ||
9b371988 PH |
19411 | .option allow_symlink appendfile boolean false |
19412 | .cindex "symbolic link" "to mailbox" | |
19413 | .cindex "mailbox" "symbolic link" | |
19414 | By default, &(appendfile)& will not deliver if the path name for the file is | |
168e428f PH |
19415 | that of a symbolic link. Setting this option relaxes that constraint, but there |
19416 | are security issues involved in the use of symbolic links. Be sure you know | |
19417 | what you are doing if you set this. Details of exactly what this option affects | |
19418 | are included in the discussion which follows this list of options. | |
19419 | ||
19420 | ||
9b371988 PH |
19421 | .option batch_id appendfile string&!! unset |
19422 | See the description of local delivery batching in chapter &<<CHAPbatching>>&. | |
19423 | However, batching is automatically disabled for &(appendfile)& deliveries that | |
168e428f PH |
19424 | happen as a result of forwarding or aliasing or other redirection directly to a |
19425 | file. | |
19426 | ||
19427 | ||
9b371988 PH |
19428 | .option batch_max appendfile integer 1 |
19429 | See the description of local delivery batching in chapter &<<CHAPbatching>>&. | |
168e428f | 19430 | |
168e428f | 19431 | |
9b371988 PH |
19432 | .option check_group appendfile boolean false |
19433 | When this option is set, the group owner of the file defined by the &%file%& | |
168e428f PH |
19434 | option is checked to see that it is the same as the group under which the |
19435 | delivery process is running. The default setting is false because the default | |
19436 | file mode is 0600, which means that the group is irrelevant. | |
19437 | ||
19438 | ||
9b371988 PH |
19439 | .option check_owner appendfile boolean true |
19440 | When this option is set, the owner of the file defined by the &%file%& option | |
19441 | is checked to ensure that it is the same as the user under which the delivery | |
168e428f PH |
19442 | process is running. |
19443 | ||
19444 | ||
9b371988 PH |
19445 | .option check_string appendfile string "see below" |
19446 | .cindex "&""From""& line" | |
19447 | As &(appendfile)& writes the message, the start of each line is tested for | |
19448 | matching &%check_string%&, and if it does, the initial matching characters are | |
19449 | replaced by the contents of &%escape_string%&. The value of &%check_string%& is | |
19450 | a literal string, not a regular expression, and the case of any letters it | |
168e428f PH |
19451 | contains is significant. |
19452 | ||
9b371988 PH |
19453 | If &%use_bsmtp%& is set the values of &%check_string%& and &%escape_string%& |
19454 | are forced to &"."& and &".."& respectively, and any settings in the | |
19455 | configuration are ignored. Otherwise, they default to &"From&~"& and | |
19456 | &">From&~"& when the &%file%& option is set, and unset when any of the | |
19457 | &%directory%&, &%maildir%&, or &%mailstore%& options are set. | |
19458 | ||
19459 | The default settings, along with &%message_prefix%& and &%message_suffix%&, are | |
19460 | suitable for traditional &"BSD"& mailboxes, where a line beginning with | |
19461 | &"From&~"& indicates the start of a new message. All four options need changing | |
19462 | if another format is used. For example, to deliver to mailboxes in MMDF format: | |
19463 | .cindex "MMDF format mailbox" | |
19464 | .cindex "mailbox" "MMDF format" | |
19465 | .code | |
19466 | check_string = "\1\1\1\1\n" | |
19467 | escape_string = "\1\1\1\1 \n" | |
19468 | message_prefix = "\1\1\1\1\n" | |
19469 | message_suffix = "\1\1\1\1\n" | |
19470 | .endd | |
19471 | .option create_directory appendfile boolean true | |
19472 | .cindex "directory creation" | |
168e428f PH |
19473 | When this option is true, Exim attempts to create any missing superior |
19474 | directories for the file that it is about to write. A created directory's mode | |
9b371988 | 19475 | is given by the &%directory_mode%& option. |
168e428f PH |
19476 | |
19477 | The group ownership of a newly created directory is highly dependent on the | |
19478 | operating system (and possibly the file system) that is being used. For | |
19479 | example, in Solaris, if the parent directory has the setgid bit set, its group | |
19480 | is propagated to the child; if not, the currently set group is used. However, | |
19481 | in FreeBSD, the parent's group is always used. | |
19482 | ||
19483 | ||
19484 | ||
9b371988 | 19485 | .option create_file appendfile string anywhere |
168e428f | 19486 | This option constrains the location of files and directories that are created |
9b371988 PH |
19487 | by this transport. It applies to files defined by the &%file%& option and |
19488 | directories defined by the &%directory%& option. In the case of maildir | |
19489 | delivery, it applies to the top level directory, not the maildir directories | |
19490 | beneath. | |
19491 | ||
19492 | The option must be set to one of the words &"anywhere"&, &"inhome"&, or | |
19493 | &"belowhome"&. In the second and third cases, a home directory must have been | |
19494 | set for the transport. This option is not useful when an explicit file name is | |
168e428f | 19495 | given for normal mailbox deliveries. It is intended for the case when file |
9b371988 PH |
19496 | names are generated from users' &_.forward_& files. These are usually handled |
19497 | by an &(appendfile)& transport called &%address_file%&. See also | |
19498 | &%file_must_exist%&. | |
168e428f PH |
19499 | |
19500 | ||
9b371988 PH |
19501 | .option directory appendfile string&!! unset |
19502 | This option is mutually exclusive with the &%file%& option, but one of &%file%& | |
19503 | or &%directory%& must be set, unless the delivery is the direct result of a | |
19504 | redirection (see section &<<SECTfildiropt>>&). | |
168e428f | 19505 | |
9b371988 | 19506 | When &%directory%& is set, the string is expanded, and the message is delivered |
168e428f PH |
19507 | into a new file or files in or below the given directory, instead of being |
19508 | appended to a single mailbox file. A number of different formats are provided | |
9b371988 PH |
19509 | (see &%maildir_format%& and &%mailstore_format%&), and see section |
19510 | &<<SECTopdir>>& for further details of this form of delivery. | |
168e428f PH |
19511 | |
19512 | ||
f89d2485 | 19513 | .option directory_file appendfile string&!! "see below" |
9b371988 | 19514 | .cindex "base62" |
f89d2485 | 19515 | .vindex "&$inode$&" |
9b371988 PH |
19516 | When &%directory%& is set, but neither &%maildir_format%& nor |
19517 | &%mailstore_format%& is set, &(appendfile)& delivers each message into a file | |
f89d2485 PH |
19518 | whose name is obtained by expanding this string. The default value is: |
19519 | .code | |
19520 | q${base62:$tod_epoch}-$inode | |
19521 | .endd | |
19522 | This generates a unique name from the current time, in base 62 form, and the | |
19523 | inode of the file. The variable &$inode$& is available only when expanding this | |
19524 | option. | |
168e428f | 19525 | |
168e428f | 19526 | |
9b371988 PH |
19527 | .option directory_mode appendfile "octal integer" 0700 |
19528 | If &(appendfile)& creates any directories as a result of the | |
19529 | &%create_directory%& option, their mode is specified by this option. | |
168e428f | 19530 | |
168e428f | 19531 | |
9b371988 PH |
19532 | .option escape_string appendfile string "see description" |
19533 | See &%check_string%& above. | |
168e428f PH |
19534 | |
19535 | ||
9b371988 PH |
19536 | .option file appendfile string&!! unset |
19537 | This option is mutually exclusive with the &%directory%& option, but one of | |
19538 | &%file%& or &%directory%& must be set, unless the delivery is the direct result | |
19539 | of a redirection (see section &<<SECTfildiropt>>&). The &%file%& option | |
19540 | specifies a single file, to which the message is appended. One or more of | |
19541 | &%use_fcntl_lock%&, &%use_flock_lock%&, or &%use_lockfile%& must be set with | |
19542 | &%file%&. | |
168e428f | 19543 | |
9b371988 PH |
19544 | .cindex "NFS" "lock file" |
19545 | .cindex "locking files" | |
19546 | .cindex "lock files" | |
168e428f PH |
19547 | If you are using more than one host to deliver over NFS into the same |
19548 | mailboxes, you should always use lock files. | |
19549 | ||
19550 | The string value is expanded for each delivery, and must yield an absolute | |
19551 | path. The most common settings of this option are variations on one of these | |
19552 | examples: | |
9b371988 PH |
19553 | .code |
19554 | file = /var/spool/mail/$local_part | |
19555 | file = /home/$local_part/inbox | |
19556 | file = $home/inbox | |
19557 | .endd | |
19558 | .cindex "&""sticky""& bit" | |
168e428f | 19559 | In the first example, all deliveries are done into the same directory. If Exim |
9b371988 PH |
19560 | is configured to use lock files (see &%use_lockfile%& below) it must be able to |
19561 | create a file in the directory, so the &"sticky"& bit must be turned on for | |
19562 | deliveries to be possible, or alternatively the &%group%& option can be used to | |
168e428f PH |
19563 | run the delivery under a group id which has write access to the directory. |
19564 | ||
19565 | ||
19566 | ||
9b371988 PH |
19567 | .option file_format appendfile string unset |
19568 | .cindex "file" "mailbox; checking existing format" | |
168e428f PH |
19569 | This option requests the transport to check the format of an existing file |
19570 | before adding to it. The check consists of matching a specific string at the | |
19571 | start of the file. The value of the option consists of an even number of | |
19572 | colon-separated strings. The first of each pair is the test string, and the | |
19573 | second is the name of a transport. If the transport associated with a matched | |
19574 | string is not the current transport, control is passed over to the other | |
9b371988 | 19575 | transport. For example, suppose the standard &(local_delivery)& transport has |
168e428f | 19576 | this added to it: |
9b371988 | 19577 | .code |
168e428f PH |
19578 | file_format = "From : local_delivery :\ |
19579 | \1\1\1\1\n : local_mmdf_delivery" | |
9b371988 PH |
19580 | .endd |
19581 | Mailboxes that begin with &"From"& are still handled by this transport, but if | |
19582 | a mailbox begins with four binary ones followed by a newline, control is passed | |
19583 | to a transport called &%local_mmdf_delivery%&, which presumably is configured | |
168e428f PH |
19584 | to do the delivery in MMDF format. If a mailbox does not exist or is empty, it |
19585 | is assumed to match the current transport. If the start of a mailbox doesn't | |
19586 | match any string, or if the transport named for a given string is not defined, | |
19587 | delivery is deferred. | |
19588 | ||
19589 | ||
9b371988 | 19590 | .option file_must_exist appendfile boolean false |
db9452a9 PH |
19591 | If this option is true, the file specified by the &%file%& option must exist. |
19592 | A temporary error occurs if it does not, causing delivery to be deferred. | |
19593 | If this option is false, the file is created if it does not exist. | |
168e428f PH |
19594 | |
19595 | ||
9b371988 PH |
19596 | .option lock_fcntl_timeout appendfile time 0s |
19597 | .cindex "timeout" "mailbox locking" | |
f89d2485 | 19598 | .cindex "mailbox" "locking, blocking and non-blocking" |
9b371988 PH |
19599 | .cindex "locking files" |
19600 | By default, the &(appendfile)& transport uses non-blocking calls to &[fcntl()]& | |
168e428f | 19601 | when locking an open mailbox file. If the call fails, the delivery process |
9b371988 | 19602 | sleeps for &%lock_interval%& and tries again, up to &%lock_retries%& times. |
168e428f PH |
19603 | Non-blocking calls are used so that the file is not kept open during the wait |
19604 | for the lock; the reason for this is to make it as safe as possible for | |
19605 | deliveries over NFS in the case when processes might be accessing an NFS | |
19606 | mailbox without using a lock file. This should not be done, but | |
19607 | misunderstandings and hence misconfigurations are not unknown. | |
19608 | ||
19609 | On a busy system, however, the performance of a non-blocking lock approach is | |
19610 | not as good as using a blocking lock with a timeout. In this case, the waiting | |
19611 | is done inside the system call, and Exim's delivery process acquires the lock | |
19612 | and can proceed as soon as the previous lock holder releases it. | |
19613 | ||
9b371988 | 19614 | If &%lock_fcntl_timeout%& is set to a non-zero time, blocking locks, with that |
168e428f PH |
19615 | timeout, are used. There may still be some retrying: the maximum number of |
19616 | retries is | |
9b371988 PH |
19617 | .code |
19618 | (lock_retries * lock_interval) / lock_fcntl_timeout | |
19619 | .endd | |
168e428f | 19620 | rounded up to the next whole number. In other words, the total time during |
9b371988 PH |
19621 | which &(appendfile)& is trying to get a lock is roughly the same, unless |
19622 | &%lock_fcntl_timeout%& is set very large. | |
168e428f PH |
19623 | |
19624 | You should consider setting this option if you are getting a lot of delayed | |
19625 | local deliveries because of errors of the form | |
9b371988 PH |
19626 | .code |
19627 | failed to lock mailbox /some/file (fcntl) | |
19628 | .endd | |
168e428f | 19629 | |
9b371988 PH |
19630 | .option lock_flock_timeout appendfile time 0s |
19631 | This timeout applies to file locking when using &[flock()]& (see | |
19632 | &%use_flock%&); the timeout operates in a similar manner to | |
19633 | &%lock_fcntl_timeout%&. | |
168e428f PH |
19634 | |
19635 | ||
9b371988 | 19636 | .option lock_interval appendfile time 3s |
168e428f PH |
19637 | This specifies the time to wait between attempts to lock the file. See below |
19638 | for details of locking. | |
19639 | ||
19640 | ||
9b371988 | 19641 | .option lock_retries appendfile integer 10 |
168e428f PH |
19642 | This specifies the maximum number of attempts to lock the file. A value of zero |
19643 | is treated as 1. See below for details of locking. | |
19644 | ||
19645 | ||
9b371988 | 19646 | .option lockfile_mode appendfile "octal integer" 0600 |
168e428f | 19647 | This specifies the mode of the created lock file, when a lock file is being |
c0712871 | 19648 | used (see &%use_lockfile%& and &%use_mbx_lock%&). |
168e428f PH |
19649 | |
19650 | ||
9b371988 PH |
19651 | .option lockfile_timeout appendfile time 30m |
19652 | .cindex "timeout" "mailbox locking" | |
19653 | When a lock file is being used (see &%use_lockfile%&), if a lock file already | |
168e428f PH |
19654 | exists and is older than this value, it is assumed to have been left behind by |
19655 | accident, and Exim attempts to remove it. | |
19656 | ||
19657 | ||
9b371988 PH |
19658 | .option mailbox_filecount appendfile string&!! unset |
19659 | .cindex "mailbox" "specifying size of" | |
19660 | .cindex "size" "of mailbox" | |
168e428f PH |
19661 | If this option is set, it is expanded, and the result is taken as the current |
19662 | number of files in the mailbox. It must be a decimal number, optionally | |
19663 | followed by K or M. This provides a way of obtaining this information from an | |
19664 | external source that maintains the data. | |
19665 | ||
19666 | ||
9b371988 PH |
19667 | .option mailbox_size appendfile string&!! unset |
19668 | .cindex "mailbox" "specifying size of" | |
19669 | .cindex "size" "of mailbox" | |
168e428f PH |
19670 | If this option is set, it is expanded, and the result is taken as the current |
19671 | size the mailbox. It must be a decimal number, optionally followed by K or M. | |
19672 | This provides a way of obtaining this information from an external source that | |
19673 | maintains the data. This is likely to be helpful for maildir deliveries where | |
19674 | it is computationally expensive to compute the size of a mailbox. | |
19675 | ||
19676 | ||
19677 | ||
9b371988 PH |
19678 | .option maildir_format appendfile boolean false |
19679 | .cindex "maildir format" "specifying" | |
19680 | If this option is set with the &%directory%& option, the delivery is into a new | |
19681 | file, in the &"maildir"& format that is used by other mail software. When the | |
19682 | transport is activated directly from a &(redirect)& router (for example, the | |
19683 | &(address_file)& transport in the default configuration), setting | |
19684 | &%maildir_format%& causes the path received from the router to be treated as a | |
19685 | directory, whether or not it ends with &`/`&. This option is available only if | |
19686 | SUPPORT_MAILDIR is present in &_Local/Makefile_&. See section | |
19687 | &<<SECTmaildirdelivery>>& below for further details. | |
168e428f PH |
19688 | |
19689 | ||
9b371988 PH |
19690 | .option maildir_quota_directory_regex appendfile string "See below" |
19691 | .cindex "maildir format" "quota; directories included in" | |
19692 | .cindex "quota" "maildir; directories included in" | |
19693 | This option is relevant only when &%maildir_use_size_file%& is set. It defines | |
c0712871 PH |
19694 | a regular expression for specifying directories, relative to the quota |
19695 | directory (see &%quota_directory%&), that should be included in the quota | |
19696 | calculation. The default value is: | |
9b371988 PH |
19697 | .code |
19698 | maildir_quota_directory_regex = ^(?:cur|new|\..*)$ | |
19699 | .endd | |
c0712871 | 19700 | This includes the &_cur_& and &_new_& directories, and any maildir++ folders |
168e428f | 19701 | (directories whose names begin with a dot). If you want to exclude the |
9b371988 | 19702 | &_Trash_& |
168e428f | 19703 | folder from the count (as some sites do), you need to change this setting to |
9b371988 PH |
19704 | .code |
19705 | maildir_quota_directory_regex = ^(?:cur|new|\.(?!Trash).*)$ | |
19706 | .endd | |
168e428f | 19707 | This uses a negative lookahead in the regular expression to exclude the |
c0712871 PH |
19708 | directory whose name is &_.Trash_&. When a directory is excluded from quota |
19709 | calculations, quota processing is bypassed for any messages that are delivered | |
19710 | directly into that directory. | |
168e428f | 19711 | |
168e428f | 19712 | |
9b371988 | 19713 | .option maildir_retries appendfile integer 10 |
168e428f | 19714 | This option specifies the number of times to retry when writing a file in |
9b371988 | 19715 | &"maildir"& format. See section &<<SECTmaildirdelivery>>& below. |
168e428f PH |
19716 | |
19717 | ||
9b371988 | 19718 | .option maildir_tag appendfile string&!! unset |
168e428f | 19719 | This option applies only to deliveries in maildir format, and is described in |
9b371988 | 19720 | section &<<SECTmaildirdelivery>>& below. |
168e428f PH |
19721 | |
19722 | ||
9b371988 PH |
19723 | .option maildir_use_size_file appendfile boolean false |
19724 | .cindex "maildir format" "&_maildirsize_& file" | |
19725 | Setting this option true enables support for &_maildirsize_& files. Exim | |
19726 | creates a &_maildirsize_& file in a maildir if one does not exist, taking the | |
19727 | quota from the &%quota%& option of the transport. If &%quota%& is unset, the | |
c0712871 PH |
19728 | value is zero. See &%maildir_quota_directory_regex%& above and section |
19729 | &<<SECTmaildirdelivery>>& below for further details. | |
c0712871 | 19730 | |
c0712871 PH |
19731 | .option maildirfolder_create_regex appendfile string unset |
19732 | .cindex "maildir format" "&_maildirfolder_& file" | |
19733 | .cindex "&_maildirfolder_&, creating" | |
19734 | The value of this option is a regular expression. If it is unset, it has no | |
3cb1b51e | 19735 | effect. Otherwise, before a maildir delivery takes place, the pattern is |
c0712871 PH |
19736 | matched against the name of the maildir directory, that is, the directory |
19737 | containing the &_new_& and &_tmp_& subdirectories that will be used for the | |
19738 | delivery. If there is a match, Exim checks for the existence of a file called | |
19739 | &_maildirfolder_& in the directory, and creates it if it does not exist. | |
19740 | See section &<<SECTmaildirdelivery>>& for more details. | |
168e428f | 19741 | |
168e428f | 19742 | |
9b371988 PH |
19743 | .option mailstore_format appendfile boolean false |
19744 | .cindex "mailstore format" "specifying" | |
19745 | If this option is set with the &%directory%& option, the delivery is into two | |
19746 | new files in &"mailstore"& format. The option is available only if | |
19747 | SUPPORT_MAILSTORE is present in &_Local/Makefile_&. See section &<<SECTopdir>>& | |
19748 | below for further details. | |
168e428f | 19749 | |
168e428f | 19750 | |
9b371988 | 19751 | .option mailstore_prefix appendfile string&!! unset |
168e428f | 19752 | This option applies only to deliveries in mailstore format, and is described in |
9b371988 | 19753 | section &<<SECTopdir>>& below. |
168e428f PH |
19754 | |
19755 | ||
9b371988 | 19756 | .option mailstore_suffix appendfile string&!! unset |
168e428f | 19757 | This option applies only to deliveries in mailstore format, and is described in |
9b371988 | 19758 | section &<<SECTopdir>>& below. |
168e428f | 19759 | |
168e428f | 19760 | |
9b371988 PH |
19761 | .option mbx_format appendfile boolean false |
19762 | .cindex "locking files" | |
19763 | .cindex "file" "locking" | |
19764 | .cindex "file" "MBX format" | |
f89d2485 | 19765 | .cindex "MBX format, specifying" |
168e428f | 19766 | This option is available only if Exim has been compiled with SUPPORT_MBX |
9b371988 | 19767 | set in &_Local/Makefile_&. If &%mbx_format%& is set with the &%file%& option, |
168e428f PH |
19768 | the message is appended to the mailbox file in MBX format instead of |
19769 | traditional Unix format. This format is supported by Pine4 and its associated | |
9b371988 | 19770 | IMAP and POP daemons, by means of the &'c-client'& library that they all use. |
168e428f | 19771 | |
9b371988 PH |
19772 | &*Note*&: The &%message_prefix%& and &%message_suffix%& options are not |
19773 | automatically changed by the use of &%mbx_format%&. They should normally be set | |
168e428f PH |
19774 | empty when using MBX format, so this option almost always appears in this |
19775 | combination: | |
9b371988 PH |
19776 | .code |
19777 | mbx_format = true | |
19778 | message_prefix = | |
19779 | message_suffix = | |
19780 | .endd | |
168e428f | 19781 | If none of the locking options are mentioned in the configuration, |
9b371988 PH |
19782 | &%use_mbx_lock%& is assumed and the other locking options default to false. It |
19783 | is possible to specify the other kinds of locking with &%mbx_format%&, but | |
19784 | &%use_fcntl_lock%& and &%use_mbx_lock%& are mutually exclusive. MBX locking | |
19785 | interworks with &'c-client'&, providing for shared access to the mailbox. It | |
168e428f PH |
19786 | should not be used if any program that does not use this form of locking is |
19787 | going to access the mailbox, nor should it be used if the mailbox file is NFS | |
19788 | mounted, because it works only when the mailbox is accessed from a single host. | |
19789 | ||
9b371988 PH |
19790 | If you set &%use_fcntl_lock%& with an MBX-format mailbox, you cannot use |
19791 | the standard version of &'c-client'&, because as long as it has a mailbox open | |
168e428f PH |
19792 | (this means for the whole of a Pine or IMAP session), Exim will not be able to |
19793 | append messages to it. | |
19794 | ||
19795 | ||
9b371988 PH |
19796 | .option message_prefix appendfile string&!! "see below" |
19797 | .cindex "&""From""& line" | |
168e428f | 19798 | The string specified here is expanded and output at the start of every message. |
9b371988 PH |
19799 | The default is unset unless &%file%& is specified and &%use_bsmtp%& is not set, |
19800 | in which case it is: | |
19801 | .code | |
168e428f PH |
19802 | message_prefix = "From ${if def:return_path{$return_path}\ |
19803 | {MAILER-DAEMON}} $tod_bsdinbox\n" | |
9b371988 | 19804 | .endd |
595028e4 PH |
19805 | &*Note:*& If you set &%use_crlf%& true, you must change any occurrences of |
19806 | &`\n`& to &`\r\n`& in &%message_prefix%&. | |
168e428f | 19807 | |
9b371988 | 19808 | .option message_suffix appendfile string&!! "see below" |
168e428f | 19809 | The string specified here is expanded and output at the end of every message. |
9b371988 PH |
19810 | The default is unset unless &%file%& is specified and &%use_bsmtp%& is not set, |
19811 | in which case it is a single newline character. The suffix can be suppressed by | |
168e428f | 19812 | setting |
9b371988 PH |
19813 | .code |
19814 | message_suffix = | |
19815 | .endd | |
595028e4 PH |
19816 | &*Note:*& If you set &%use_crlf%& true, you must change any occurrences of |
19817 | &`\n`& to &`\r\n`& in &%message_suffix%&. | |
168e428f | 19818 | |
9b371988 | 19819 | .option mode appendfile "octal integer" 0600 |
168e428f PH |
19820 | If the output file is created, it is given this mode. If it already exists and |
19821 | has wider permissions, they are reduced to this mode. If it has narrower | |
9b371988 | 19822 | permissions, an error occurs unless &%mode_fail_narrower%& is false. However, |
f89d2485 | 19823 | if the delivery is the result of a &%save%& command in a filter file specifying |
9b371988 | 19824 | a particular mode, the mode of the output file is always forced to take that |
168e428f PH |
19825 | value, and this option is ignored. |
19826 | ||
19827 | ||
9b371988 | 19828 | .option mode_fail_narrower appendfile boolean true |
168e428f | 19829 | This option applies in the case when an existing mailbox file has a narrower |
9b371988 PH |
19830 | mode than that specified by the &%mode%& option. If &%mode_fail_narrower%& is |
19831 | true, the delivery is deferred (&"mailbox has the wrong mode"&); otherwise Exim | |
19832 | continues with the delivery attempt, using the existing mode of the file. | |
168e428f | 19833 | |
168e428f | 19834 | |
9b371988 PH |
19835 | .option notify_comsat appendfile boolean false |
19836 | If this option is true, the &'comsat'& daemon is notified after every | |
19837 | successful delivery to a user mailbox. This is the daemon that notifies logged | |
19838 | on users about incoming mail. | |
168e428f | 19839 | |
168e428f | 19840 | |
9b371988 PH |
19841 | .option quota appendfile string&!! unset |
19842 | .cindex "quota" "imposed by Exim" | |
168e428f | 19843 | This option imposes a limit on the size of the file to which Exim is appending, |
9b371988 PH |
19844 | or to the total space used in the directory tree when the &%directory%& option |
19845 | is set. In the latter case, computation of the space used is expensive, because | |
168e428f | 19846 | all the files in the directory (and any sub-directories) have to be |
9b371988 PH |
19847 | individually inspected and their sizes summed. (See &%quota_size_regex%& and |
19848 | &%maildir_use_size_file%& for ways to avoid this in environments where users | |
19849 | have no shell access to their mailboxes). | |
168e428f PH |
19850 | |
19851 | As there is no interlock against two simultaneous deliveries into a | |
19852 | multi-file mailbox, it is possible for the quota to be overrun in this case. | |
19853 | For single-file mailboxes, of course, an interlock is a necessity. | |
19854 | ||
9b371988 | 19855 | A file's size is taken as its &'used'& value. Because of blocking effects, this |
168e428f PH |
19856 | may be a lot less than the actual amount of disk space allocated to the file. |
19857 | If the sizes of a number of files are being added up, the rounding effect can | |
19858 | become quite noticeable, especially on systems that have large block sizes. | |
9b371988 | 19859 | Nevertheless, it seems best to stick to the &'used'& figure, because this is |
168e428f PH |
19860 | the obvious value which users understand most easily. |
19861 | ||
19862 | The value of the option is expanded, and must then be a numerical value | |
068aaea8 PH |
19863 | (decimal point allowed), optionally followed by one of the letters K, M, or G, |
19864 | for kilobytes, megabytes, or gigabytes. If Exim is running on a system with | |
19865 | large file support (Linux and FreeBSD have this), mailboxes larger than 2G can | |
19866 | be handled. | |
168e428f | 19867 | |
9b371988 | 19868 | &*Note*&: A value of zero is interpreted as &"no quota"&. |
168e428f | 19869 | |
068aaea8 PH |
19870 | The expansion happens while Exim is running as root, before it changes uid for |
19871 | the delivery. This means that files that are inaccessible to the end user can | |
19872 | be used to hold quota values that are looked up in the expansion. When delivery | |
19873 | fails because this quota is exceeded, the handling of the error is as for | |
19874 | system quota failures. | |
19875 | ||
168e428f PH |
19876 | By default, Exim's quota checking mimics system quotas, and restricts the |
19877 | mailbox to the specified maximum size, though the value is not accurate to the | |
19878 | last byte, owing to separator lines and additional headers that may get added | |
19879 | during message delivery. When a mailbox is nearly full, large messages may get | |
19880 | refused even though small ones are accepted, because the size of the current | |
19881 | message is added to the quota when the check is made. This behaviour can be | |
9b371988 | 19882 | changed by setting &%quota_is_inclusive%& false. When this is done, the check |
168e428f PH |
19883 | for exceeding the quota does not include the current message. Thus, deliveries |
19884 | continue until the quota has been exceeded; thereafter, no further messages are | |
9b371988 | 19885 | delivered. See also &%quota_warn_threshold%&. |
168e428f | 19886 | |
168e428f | 19887 | |
9b371988 | 19888 | .option quota_directory appendfile string&!! unset |
168e428f PH |
19889 | This option defines the directory to check for quota purposes when delivering |
19890 | into individual files. The default is the delivery directory, or, if a file | |
9b371988 | 19891 | called &_maildirfolder_& exists in a maildir directory, the parent of the |
168e428f PH |
19892 | delivery directory. |
19893 | ||
19894 | ||
9b371988 PH |
19895 | .option quota_filecount appendfile string&!! 0 |
19896 | This option applies when the &%directory%& option is set. It limits the total | |
168e428f | 19897 | number of files in the directory (compare the inode limit in system quotas). It |
9b371988 | 19898 | can only be used if &%quota%& is also set. The value is expanded; an expansion |
4f578862 PH |
19899 | failure causes delivery to be deferred. A value of zero is interpreted as |
19900 | &"no quota"&. | |
168e428f PH |
19901 | |
19902 | ||
9b371988 PH |
19903 | .option quota_is_inclusive appendfile boolean true |
19904 | See &%quota%& above. | |
168e428f PH |
19905 | |
19906 | ||
9b371988 | 19907 | .option quota_size_regex appendfile string unset |
168e428f PH |
19908 | This option applies when one of the delivery modes that writes a separate file |
19909 | for each message is being used. When Exim wants to find the size of one of | |
9b371988 | 19910 | these files in order to test the quota, it first checks &%quota_size_regex%&. |
168e428f PH |
19911 | If this is set to a regular expression that matches the file name, and it |
19912 | captures one string, that string is interpreted as a representation of the | |
9b371988 | 19913 | file's size. The value of &%quota_size_regex%& is not expanded. |
168e428f PH |
19914 | |
19915 | This feature is useful only when users have no shell access to their mailboxes | |
9b371988 PH |
19916 | &-- otherwise they could defeat the quota simply by renaming the files. This |
19917 | facility can be used with maildir deliveries, by setting &%maildir_tag%& to add | |
168e428f | 19918 | the file length to the file name. For example: |
9b371988 PH |
19919 | .code |
19920 | maildir_tag = ,S=$message_size | |
19921 | quota_size_regex = ,S=(\d+) | |
19922 | .endd | |
9b371988 | 19923 | An alternative to &$message_size$& is &$message_linecount$&, which contains the |
068aaea8 PH |
19924 | number of lines in the message. |
19925 | ||
168e428f | 19926 | The regular expression should not assume that the length is at the end of the |
9b371988 | 19927 | file name (even though &%maildir_tag%& puts it there) because maildir MUAs |
168e428f PH |
19928 | sometimes add other information onto the ends of message file names. |
19929 | ||
19930 | ||
068aaea8 | 19931 | |
9b371988 | 19932 | .option quota_warn_message appendfile string&!! "see below" |
168e428f | 19933 | See below for the use of this option. If it is not set when |
9b371988 PH |
19934 | &%quota_warn_threshold%& is set, it defaults to |
19935 | .code | |
168e428f PH |
19936 | quota_warn_message = "\ |
19937 | To: $local_part@$domain\n\ | |
19938 | Subject: Your mailbox\n\n\ | |
19939 | This message is automatically created \ | |
19940 | by mail delivery software.\n\n\ | |
19941 | The size of your mailbox has exceeded \ | |
19942 | a warning threshold that is\n\ | |
19943 | set by the system administrator.\n" | |
9b371988 | 19944 | .endd |
168e428f PH |
19945 | |
19946 | ||
9b371988 PH |
19947 | .option quota_warn_threshold appendfile string&!! 0 |
19948 | .cindex "quota" "warning threshold" | |
19949 | .cindex "mailbox" "size warning" | |
19950 | .cindex "size" "of mailbox" | |
19951 | This option is expanded in the same way as &%quota%& (see above). If the | |
168e428f PH |
19952 | resulting value is greater than zero, and delivery of the message causes the |
19953 | size of the file or total space in the directory tree to cross the given | |
9b371988 PH |
19954 | threshold, a warning message is sent. If &%quota%& is also set, the threshold |
19955 | may be specified as a percentage of it by following the value with a percent | |
19956 | sign. For example: | |
19957 | .code | |
19958 | quota = 10M | |
19959 | quota_warn_threshold = 75% | |
19960 | .endd | |
19961 | If &%quota%& is not set, a setting of &%quota_warn_threshold%& that ends with a | |
168e428f PH |
19962 | percent sign is ignored. |
19963 | ||
9b371988 PH |
19964 | The warning message itself is specified by the &%quota_warn_message%& option, |
19965 | and it must start with a &'To:'& header line containing the recipient(s) of the | |
068aaea8 | 19966 | warning message. These do not necessarily have to include the recipient(s) of |
9b371988 | 19967 | the original message. A &'Subject:'& line should also normally be supplied. You |
4f578862 PH |
19968 | can include any other header lines that you want. If you do not include a |
19969 | &'From:'& line, the default is: | |
19970 | .code | |
19971 | From: Mail Delivery System <mailer-daemon@$qualify_domain_sender> | |
19972 | .endd | |
19973 | .oindex &%errors_reply_to%& | |
19974 | If you supply a &'Reply-To:'& line, it overrides the global &%errors_reply_to%& | |
19975 | option. | |
068aaea8 | 19976 | |
9b371988 | 19977 | The &%quota%& option does not have to be set in order to use this option; they |
068aaea8 PH |
19978 | are independent of one another except when the threshold is specified as a |
19979 | percentage. | |
168e428f PH |
19980 | |
19981 | ||
9b371988 PH |
19982 | .option use_bsmtp appendfile boolean false |
19983 | .cindex "envelope sender" | |
19984 | If this option is set true, &(appendfile)& writes messages in &"batch SMTP"& | |
168e428f PH |
19985 | format, with the envelope sender and recipient(s) included as SMTP commands. If |
19986 | you want to include a leading HELO command with such messages, you can do | |
9b371988 PH |
19987 | so by setting the &%message_prefix%& option. See section &<<SECTbatchSMTP>>& |
19988 | for details of batch SMTP. | |
168e428f | 19989 | |
168e428f | 19990 | |
9b371988 PH |
19991 | .option use_crlf appendfile boolean false |
19992 | .cindex "carriage return" | |
19993 | .cindex "linefeed" | |
168e428f PH |
19994 | This option causes lines to be terminated with the two-character CRLF sequence |
19995 | (carriage return, linefeed) instead of just a linefeed character. In the case | |
19996 | of batched SMTP, the byte sequence written to the file is then an exact image | |
19997 | of what would be sent down a real SMTP connection. | |
19998 | ||
595028e4 PH |
19999 | &*Note:*& The contents of the &%message_prefix%& and &%message_suffix%& options |
20000 | (which are used to supply the traditional &"From&~"& and blank line separators | |
20001 | in Berkeley-style mailboxes) are written verbatim, so must contain their own | |
20002 | carriage return characters if these are needed. In cases where these options | |
20003 | have non-empty defaults, the values end with a single linefeed, so they must be | |
20004 | changed to end with &`\r\n`& if &%use_crlf%& is set. | |
168e428f PH |
20005 | |
20006 | ||
9b371988 PH |
20007 | .option use_fcntl_lock appendfile boolean "see below" |
20008 | This option controls the use of the &[fcntl()]& function to lock a file for | |
168e428f | 20009 | exclusive use when a message is being appended. It is set by default unless |
9b371988 PH |
20010 | &%use_flock_lock%& is set. Otherwise, it should be turned off only if you know |
20011 | that all your MUAs use lock file locking. When both &%use_fcntl_lock%& and | |
20012 | &%use_flock_lock%& are unset, &%use_lockfile%& must be set. | |
168e428f | 20013 | |
168e428f | 20014 | |
9b371988 PH |
20015 | .option use_flock_lock appendfile boolean false |
20016 | This option is provided to support the use of &[flock()]& for file locking, for | |
168e428f | 20017 | the few situations where it is needed. Most modern operating systems support |
9b371988 PH |
20018 | &[fcntl()]& and &[lockf()]& locking, and these two functions interwork with |
20019 | each other. Exim uses &[fcntl()]& locking by default. | |
168e428f PH |
20020 | |
20021 | This option is required only if you are using an operating system where | |
9b371988 PH |
20022 | &[flock()]& is used by programs that access mailboxes (typically MUAs), and |
20023 | where &[flock()]& does not correctly interwork with &[fcntl()]&. You can use | |
20024 | both &[fcntl()]& and &[flock()]& locking simultaneously if you want. | |
168e428f | 20025 | |
9b371988 PH |
20026 | .cindex "Solaris" "&[flock()]& support" |
20027 | Not all operating systems provide &[flock()]&. Some versions of Solaris do not | |
168e428f | 20028 | have it (and some, I think, provide a not quite right version built on top of |
9b371988 | 20029 | &[lockf()]&). If the OS does not have &[flock()]&, Exim will be built without |
168e428f PH |
20030 | the ability to use it, and any attempt to do so will cause a configuration |
20031 | error. | |
20032 | ||
9b371988 PH |
20033 | &*Warning*&: &[flock()]& locks do not work on NFS files (unless &[flock()]& |
20034 | is just being mapped onto &[fcntl()]& by the OS). | |
168e428f PH |
20035 | |
20036 | ||
9b371988 | 20037 | .option use_lockfile appendfile boolean "see below" |
168e428f PH |
20038 | If this option is turned off, Exim does not attempt to create a lock file when |
20039 | appending to a mailbox file. In this situation, the only locking is by | |
9b371988 | 20040 | &[fcntl()]&. You should only turn &%use_lockfile%& off if you are absolutely |
168e428f | 20041 | sure that every MUA that is ever going to look at your users' mailboxes uses |
9b371988 | 20042 | &[fcntl()]& rather than a lock file, and even then only when you are not |
168e428f PH |
20043 | delivering over NFS from more than one host. |
20044 | ||
9b371988 | 20045 | .cindex "NFS" "lock file" |
168e428f | 20046 | In order to append to an NFS file safely from more than one host, it is |
9b371988 PH |
20047 | necessary to take out a lock &'before'& opening the file, and the lock file |
20048 | achieves this. Otherwise, even with &[fcntl()]& locking, there is a risk of | |
168e428f PH |
20049 | file corruption. |
20050 | ||
9b371988 PH |
20051 | The &%use_lockfile%& option is set by default unless &%use_mbx_lock%& is set. |
20052 | It is not possible to turn both &%use_lockfile%& and &%use_fcntl_lock%& off, | |
20053 | except when &%mbx_format%& is set. | |
168e428f | 20054 | |
168e428f | 20055 | |
9b371988 | 20056 | .option use_mbx_lock appendfile boolean "see below" |
168e428f | 20057 | This option is available only if Exim has been compiled with SUPPORT_MBX |
9b371988 PH |
20058 | set in &_Local/Makefile_&. Setting the option specifies that special MBX |
20059 | locking rules be used. It is set by default if &%mbx_format%& is set and none | |
20060 | of the locking options are mentioned in the configuration. The locking rules | |
20061 | are the same as are used by the &'c-client'& library that underlies Pine and | |
20062 | the IMAP4 and POP daemons that come with it (see the discussion below). The | |
20063 | rules allow for shared access to the mailbox. However, this kind of locking | |
20064 | does not work when the mailbox is NFS mounted. | |
168e428f | 20065 | |
9b371988 PH |
20066 | You can set &%use_mbx_lock%& with either (or both) of &%use_fcntl_lock%& and |
20067 | &%use_flock_lock%& to control what kind of locking is used in implementing the | |
20068 | MBX locking rules. The default is to use &[fcntl()]& if &%use_mbx_lock%& is set | |
20069 | without &%use_fcntl_lock%& or &%use_flock_lock%&. | |
168e428f PH |
20070 | |
20071 | ||
20072 | ||
20073 | ||
9b371988 PH |
20074 | .section "Operational details for appending" "SECTopappend" |
20075 | .cindex "appending to a file" | |
20076 | .cindex "file" "appending" | |
168e428f PH |
20077 | Before appending to a file, the following preparations are made: |
20078 | ||
9b371988 PH |
20079 | .ilist |
20080 | If the name of the file is &_/dev/null_&, no action is taken, and a success | |
168e428f PH |
20081 | return is given. |
20082 | ||
9b371988 PH |
20083 | .next |
20084 | .cindex "directory creation" | |
168e428f | 20085 | If any directories on the file's path are missing, Exim creates them if the |
9b371988 PH |
20086 | &%create_directory%& option is set. A created directory's mode is given by the |
20087 | &%directory_mode%& option. | |
168e428f | 20088 | |
9b371988 PH |
20089 | .next |
20090 | If &%file_format%& is set, the format of an existing file is checked. If this | |
168e428f PH |
20091 | indicates that a different transport should be used, control is passed to that |
20092 | transport. | |
20093 | ||
9b371988 PH |
20094 | .next |
20095 | .cindex "file" "locking" | |
20096 | .cindex "locking files" | |
20097 | .cindex "NFS" "lock file" | |
20098 | If &%use_lockfile%& is set, a lock file is built in a way that will work | |
168e428f | 20099 | reliably over NFS, as follows: |
9b371988 PH |
20100 | |
20101 | .olist | |
20102 | Create a &"hitching post"& file whose name is that of the lock file with the | |
168e428f PH |
20103 | current time, primary host name, and process id added, by opening for writing |
20104 | as a new file. If this fails with an access error, delivery is deferred. | |
9b371988 PH |
20105 | .next |
20106 | Close the hitching post file, and hard link it to the lock file name. | |
20107 | .next | |
20108 | If the call to &[link()]& succeeds, creation of the lock file has succeeded. | |
168e428f | 20109 | Unlink the hitching post name. |
9b371988 PH |
20110 | .next |
20111 | Otherwise, use &[stat()]& to get information about the hitching post file, and | |
168e428f PH |
20112 | then unlink hitching post name. If the number of links is exactly two, creation |
20113 | of the lock file succeeded but something (for example, an NFS server crash and | |
9b371988 PH |
20114 | restart) caused this fact not to be communicated to the &[link()]& call. |
20115 | .next | |
20116 | If creation of the lock file failed, wait for &%lock_interval%& and try again, | |
20117 | up to &%lock_retries%& times. However, since any program that writes to a | |
168e428f PH |
20118 | mailbox should complete its task very quickly, it is reasonable to time out old |
20119 | lock files that are normally the result of user agent and system crashes. If an | |
9b371988 PH |
20120 | existing lock file is older than &%lockfile_timeout%& Exim attempts to unlink |
20121 | it before trying again. | |
20122 | .endlist olist | |
20123 | ||
20124 | .next | |
20125 | A call is made to &[lstat()]& to discover whether the main file exists, and if | |
20126 | so, what its characteristics are. If &[lstat()]& fails for any reason other | |
168e428f PH |
20127 | than non-existence, delivery is deferred. |
20128 | ||
9b371988 PH |
20129 | .next |
20130 | .cindex "symbolic link" "to mailbox" | |
20131 | .cindex "mailbox" "symbolic link" | |
168e428f | 20132 | If the file does exist and is a symbolic link, delivery is deferred, unless the |
9b371988 PH |
20133 | &%allow_symlink%& option is set, in which case the ownership of the link is |
20134 | checked, and then &[stat()]& is called to find out about the real file, which | |
168e428f PH |
20135 | is then subjected to the checks below. The check on the top-level link |
20136 | ownership prevents one user creating a link for another's mailbox in a sticky | |
20137 | directory, though allowing symbolic links in this case is definitely not a good | |
20138 | idea. If there is a chain of symbolic links, the intermediate ones are not | |
20139 | checked. | |
20140 | ||
9b371988 PH |
20141 | .next |
20142 | If the file already exists but is not a regular file, or if the file's owner | |
20143 | and group (if the group is being checked &-- see &%check_group%& above) are | |
168e428f PH |
20144 | different from the user and group under which the delivery is running, |
20145 | delivery is deferred. | |
20146 | ||
9b371988 PH |
20147 | .next |
20148 | If the file's permissions are more generous than specified, they are reduced. | |
20149 | If they are insufficient, delivery is deferred, unless &%mode_fail_narrower%& | |
168e428f PH |
20150 | is set false, in which case the delivery is tried using the existing |
20151 | permissions. | |
20152 | ||
9b371988 PH |
20153 | .next |
20154 | The file's inode number is saved, and the file is then opened for appending. | |
20155 | If this fails because the file has vanished, &(appendfile)& behaves as if it | |
168e428f PH |
20156 | hadn't existed (see below). For any other failures, delivery is deferred. |
20157 | ||
9b371988 PH |
20158 | .next |
20159 | If the file is opened successfully, check that the inode number hasn't | |
168e428f PH |
20160 | changed, that it is still a regular file, and that the owner and permissions |
20161 | have not changed. If anything is wrong, defer delivery and freeze the message. | |
20162 | ||
9b371988 PH |
20163 | .next |
20164 | If the file did not exist originally, defer delivery if the &%file_must_exist%& | |
168e428f | 20165 | option is set. Otherwise, check that the file is being created in a permitted |
9b371988 | 20166 | directory if the &%create_file%& option is set (deferring on failure), and then |
168e428f | 20167 | open for writing as a new file, with the O_EXCL and O_CREAT options, |
9b371988 | 20168 | except when dealing with a symbolic link (the &%allow_symlink%& option must be |
168e428f PH |
20169 | set). In this case, which can happen if the link points to a non-existent file, |
20170 | the file is opened for writing using O_CREAT but not O_EXCL, because | |
20171 | that prevents link following. | |
20172 | ||
9b371988 PH |
20173 | .next |
20174 | .cindex "loop" "while file testing" | |
168e428f PH |
20175 | If opening fails because the file exists, obey the tests given above for |
20176 | existing files. However, to avoid looping in a situation where the file is | |
20177 | being continuously created and destroyed, the exists/not-exists loop is broken | |
20178 | after 10 repetitions, and the message is then frozen. | |
20179 | ||
9b371988 PH |
20180 | .next |
20181 | If opening fails with any other error, defer delivery. | |
20182 | ||
20183 | .next | |
20184 | .cindex "file" "locking" | |
20185 | .cindex "locking files" | |
20186 | Once the file is open, unless both &%use_fcntl_lock%& and &%use_flock_lock%& | |
20187 | are false, it is locked using &[fcntl()]& or &[flock()]& or both. If | |
20188 | &%use_mbx_lock%& is false, an exclusive lock is requested in each case. | |
20189 | However, if &%use_mbx_lock%& is true, Exim takes out a shared lock on the open | |
20190 | file, and an exclusive lock on the file whose name is | |
20191 | .code | |
20192 | /tmp/.<device-number>.<inode-number> | |
20193 | .endd | |
168e428f | 20194 | using the device and inode numbers of the open mailbox file, in accordance with |
c0712871 PH |
20195 | the MBX locking rules. This file is created with a mode that is specified by |
20196 | the &%lockfile_mode%& option. | |
9b371988 | 20197 | |
168e428f PH |
20198 | If Exim fails to lock the file, there are two possible courses of action, |
20199 | depending on the value of the locking timeout. This is obtained from | |
9b371988 PH |
20200 | &%lock_fcntl_timeout%& or &%lock_flock_timeout%&, as appropriate. |
20201 | ||
168e428f | 20202 | If the timeout value is zero, the file is closed, Exim waits for |
9b371988 PH |
20203 | &%lock_interval%&, and then goes back and re-opens the file as above and tries |
20204 | to lock it again. This happens up to &%lock_retries%& times, after which the | |
168e428f | 20205 | delivery is deferred. |
9b371988 PH |
20206 | |
20207 | If the timeout has a value greater than zero, blocking calls to &[fcntl()]& or | |
20208 | &[flock()]& are used (with the given timeout), so there has already been some | |
168e428f PH |
20209 | waiting involved by the time locking fails. Nevertheless, Exim does not give up |
20210 | immediately. It retries up to | |
9b371988 PH |
20211 | .code |
20212 | (lock_retries * lock_interval) / <timeout> | |
20213 | .endd | |
168e428f | 20214 | times (rounded up). |
9b371988 | 20215 | .endlist |
168e428f | 20216 | |
9b371988 PH |
20217 | At the end of delivery, Exim closes the file (which releases the &[fcntl()]& |
20218 | and/or &[flock()]& locks) and then deletes the lock file if one was created. | |
168e428f | 20219 | |
168e428f | 20220 | |
9b371988 PH |
20221 | .section "Operational details for delivery to a new file" "SECTopdir" |
20222 | .cindex "delivery" "to single file" | |
20223 | .cindex "&""From""& line" | |
20224 | When the &%directory%& option is set instead of &%file%&, each message is | |
20225 | delivered into a newly-created file or set of files. When &(appendfile)& is | |
20226 | activated directly from a &(redirect)& router, neither &%file%& nor | |
20227 | &%directory%& is normally set, because the path for delivery is supplied by the | |
20228 | router. (See for example, the &(address_file)& transport in the default | |
20229 | configuration.) In this case, delivery is to a new file if either the path name | |
20230 | ends in &`/`&, or the &%maildir_format%& or &%mailstore_format%& option is set. | |
168e428f PH |
20231 | |
20232 | No locking is required while writing the message to a new file, so the various | |
9b371988 | 20233 | locking options of the transport are ignored. The &"From"& line that by default |
168e428f | 20234 | separates messages in a single file is not normally needed, nor is the escaping |
9b371988 | 20235 | of message lines that start with &"From"&, and there is no need to ensure a |
168e428f | 20236 | newline at the end of each message. Consequently, the default values for |
9b371988 PH |
20237 | &%check_string%&, &%message_prefix%&, and &%message_suffix%& are all unset when |
20238 | any of &%directory%&, &%maildir_format%&, or &%mailstore_format%& is set. | |
168e428f | 20239 | |
9b371988 PH |
20240 | If Exim is required to check a &%quota%& setting, it adds up the sizes of all |
20241 | the files in the delivery directory by default. However, you can specify a | |
20242 | different directory by setting &%quota_directory%&. Also, for maildir | |
20243 | deliveries (see below) the &_maildirfolder_& convention is honoured. | |
168e428f PH |
20244 | |
20245 | ||
9b371988 PH |
20246 | .cindex "maildir format" |
20247 | .cindex "mailstore format" | |
168e428f | 20248 | There are three different ways in which delivery to individual files can be |
9b371988 PH |
20249 | done, controlled by the settings of the &%maildir_format%& and |
20250 | &%mailstore_format%& options. Note that code to support maildir or mailstore | |
168e428f | 20251 | formats is not included in the binary unless SUPPORT_MAILDIR or |
9b371988 | 20252 | SUPPORT_MAILSTORE, respectively, is set in &_Local/Makefile_&. |
168e428f | 20253 | |
9b371988 | 20254 | .cindex "directory creation" |
168e428f | 20255 | In all three cases an attempt is made to create the directory and any necessary |
9b371988 | 20256 | sub-directories if they do not exist, provided that the &%create_directory%& |
168e428f | 20257 | option is set (the default). The location of a created directory can be |
9b371988 PH |
20258 | constrained by setting &%create_file%&. A created directory's mode is given by |
20259 | the &%directory_mode%& option. If creation fails, or if the | |
20260 | &%create_directory%& option is not set when creation is required, delivery is | |
20261 | deferred. | |
168e428f PH |
20262 | |
20263 | ||
20264 | ||
9b371988 PH |
20265 | .section "Maildir delivery" "SECTmaildirdelivery" |
20266 | .cindex "maildir format" "description of" | |
20267 | If the &%maildir_format%& option is true, Exim delivers each message by writing | |
20268 | it to a file whose name is &_tmp/<stime>.H<mtime>P<pid>.<host>_& in the | |
c0712871 PH |
20269 | directory that is defined by the &%directory%& option (the &"delivery |
20270 | directory"&). If the delivery is successful, the file is renamed into the | |
9b371988 | 20271 | &_new_& subdirectory. |
168e428f | 20272 | |
9b371988 PH |
20273 | In the file name, <&'stime'&> is the current time of day in seconds, and |
20274 | <&'mtime'&> is the microsecond fraction of the time. After a maildir delivery, | |
168e428f PH |
20275 | Exim checks that the time-of-day clock has moved on by at least one microsecond |
20276 | before terminating the delivery process. This guarantees uniqueness for the | |
9b371988 | 20277 | file name. However, as a precaution, Exim calls &[stat()]& for the file before |
168e428f | 20278 | opening it. If any response other than ENOENT (does not exist) is given, |
9b371988 | 20279 | Exim waits 2 seconds and tries again, up to &%maildir_retries%& times. |
168e428f | 20280 | |
c0712871 PH |
20281 | Before Exim carries out a maildir delivery, it ensures that subdirectories |
20282 | called &_new_&, &_cur_&, and &_tmp_& exist in the delivery directory. If they | |
20283 | do not exist, Exim tries to create them and any superior directories in their | |
20284 | path, subject to the &%create_directory%& and &%create_file%& options. If the | |
20285 | &%maildirfolder_create_regex%& option is set, and the regular expression it | |
20286 | contains matches the delivery directory, Exim also ensures that a file called | |
20287 | &_maildirfolder_& exists in the delivery directory. If a missing directory or | |
20288 | &_maildirfolder_& file cannot be created, delivery is deferred. | |
20289 | ||
20290 | These features make it possible to use Exim to create all the necessary files | |
20291 | and directories in a maildir mailbox, including subdirectories for maildir++ | |
20292 | folders. Consider this example: | |
20293 | .code | |
20294 | maildir_format = true | |
20295 | directory = /var/mail/$local_part\ | |
20296 | ${if eq{$local_part_suffix}{}{}\ | |
20297 | {/.${substr_1:$local_part_suffix}}} | |
20298 | maildirfolder_create_regex = /\.[^/]+$ | |
20299 | .endd | |
20300 | If &$local_part_suffix$& is empty (there was no suffix for the local part), | |
20301 | delivery is into a toplevel maildir with a name like &_/var/mail/pimbo_& (for | |
20302 | the user called &'pimbo'&). The pattern in &%maildirfolder_create_regex%& does | |
db9452a9 | 20303 | not match this name, so Exim will not look for or create the file |
c0712871 PH |
20304 | &_/var/mail/pimbo/maildirfolder_&, though it will create |
20305 | &_/var/mail/pimbo/{cur,new,tmp}_& if necessary. | |
20306 | ||
20307 | However, if &$local_part_suffix$& contains &`-eximusers`& (for example), | |
20308 | delivery is into the maildir++ folder &_/var/mail/pimbo/.eximusers_&, which | |
20309 | does match &%maildirfolder_create_regex%&. In this case, Exim will create | |
20310 | &_/var/mail/pimbo/.eximusers/maildirfolder_& as well as the three maildir | |
20311 | directories &_/var/mail/pimbo/.eximusers/{cur,new,tmp}_&. | |
20312 | ||
20313 | &*Warning:*& Take care when setting &%maildirfolder_create_regex%& that it does | |
20314 | not inadvertently match the toplevel maildir directory, because a | |
20315 | &_maildirfolder_& file at top level would completely break quota calculations. | |
c0712871 | 20316 | |
9b371988 PH |
20317 | .cindex "quota" "in maildir delivery" |
20318 | .cindex "maildir++" | |
20319 | If Exim is required to check a &%quota%& setting before a maildir delivery, and | |
20320 | &%quota_directory%& is not set, it looks for a file called &_maildirfolder_& in | |
20321 | the maildir directory (alongside &_new_&, &_cur_&, &_tmp_&). If this exists, | |
168e428f PH |
20322 | Exim assumes the directory is a maildir++ folder directory, which is one level |
20323 | down from the user's top level mailbox directory. This causes it to start at | |
20324 | the parent directory instead of the current directory when calculating the | |
20325 | amount of space used. | |
20326 | ||
20327 | One problem with delivering into a multi-file mailbox is that it is | |
20328 | computationally expensive to compute the size of the mailbox for quota | |
20329 | checking. Various approaches have been taken to reduce the amount of work | |
20330 | needed. The next two sections describe two of them. A third alternative is to | |
20331 | use some external process for maintaining the size data, and use the expansion | |
9b371988 | 20332 | of the &%mailbox_size%& option as a way of importing it into Exim. |
168e428f PH |
20333 | |
20334 | ||
20335 | ||
20336 | ||
f89d2485 | 20337 | .section "Using tags to record message sizes" "SECID135" |
9b371988 PH |
20338 | If &%maildir_tag%& is set, the string is expanded for each delivery. |
20339 | When the maildir file is renamed into the &_new_& sub-directory, the | |
168e428f | 20340 | tag is added to its name. However, if adding the tag takes the length of the |
9b371988 | 20341 | name to the point where the test &[stat()]& call fails with ENAMETOOLONG, |
168e428f PH |
20342 | the tag is dropped and the maildir file is created with no tag. |
20343 | ||
f89d2485 | 20344 | .vindex "&$message_size$&" |
168e428f | 20345 | Tags can be used to encode the size of files in their names; see |
9b371988 PH |
20346 | &%quota_size_regex%& above for an example. The expansion of &%maildir_tag%& |
20347 | happens after the message has been written. The value of the &$message_size$& | |
20348 | variable is set to the number of bytes actually written. If the expansion is | |
20349 | forced to fail, the tag is ignored, but a non-forced failure causes delivery to | |
20350 | be deferred. The expanded tag may contain any printing characters except &"/"&. | |
168e428f PH |
20351 | Non-printing characters in the string are ignored; if the resulting string is |
20352 | empty, it is ignored. If it starts with an alphanumeric character, a leading | |
20353 | colon is inserted. | |
20354 | ||
20355 | ||
20356 | ||
f89d2485 | 20357 | .section "Using a maildirsize file" "SECID136" |
9b371988 PH |
20358 | .cindex "quota" "in maildir delivery" |
20359 | .cindex "maildir format" "&_maildirsize_& file" | |
20360 | If &%maildir_use_size_file%& is true, Exim implements the maildir++ rules for | |
20361 | storing quota and message size information in a file called &_maildirsize_& | |
c0712871 PH |
20362 | within the toplevel maildir directory. If this file does not exist, Exim |
20363 | creates it, setting the quota from the &%quota%& option of the transport. If | |
20364 | the maildir directory itself does not exist, it is created before any attempt | |
20365 | to write a &_maildirsize_& file. | |
168e428f | 20366 | |
9b371988 | 20367 | The &_maildirsize_& file is used to hold information about the sizes of |
168e428f PH |
20368 | messages in the maildir, thus speeding up quota calculations. The quota value |
20369 | in the file is just a cache; if the quota is changed in the transport, the new | |
20370 | value overrides the cached value when the next message is delivered. The cache | |
20371 | is maintained for the benefit of other programs that access the maildir and | |
20372 | need to know the quota. | |
20373 | ||
9b371988 | 20374 | If the &%quota%& option in the transport is unset or zero, the &_maildirsize_& |
168e428f PH |
20375 | file is maintained (with a zero quota setting), but no quota is imposed. |
20376 | ||
20377 | A regular expression is available for controlling which directories in the | |
c0712871 PH |
20378 | maildir participate in quota calculations when a &_maildirsizefile_& is in use. |
20379 | See the description of the &%maildir_quota_directory_regex%& option above for | |
20380 | details. | |
168e428f PH |
20381 | |
20382 | ||
f89d2485 | 20383 | .section "Mailstore delivery" "SECID137" |
9b371988 PH |
20384 | .cindex "mailstore format" "description of" |
20385 | If the &%mailstore_format%& option is true, each message is written as two | |
20386 | files in the given directory. A unique base name is constructed from the | |
20387 | message id and the current delivery process, and the files that are written use | |
20388 | this base name plus the suffixes &_.env_& and &_.msg_&. The &_.env_& file | |
20389 | contains the message's envelope, and the &_.msg_& file contains the message | |
20390 | itself. The base name is placed in the variable &$mailstore_basename$&. | |
168e428f PH |
20391 | |
20392 | During delivery, the envelope is first written to a file with the suffix | |
9b371988 PH |
20393 | &_.tmp_&. The &_.msg_& file is then written, and when it is complete, the |
20394 | &_.tmp_& file is renamed as the &_.env_& file. Programs that access messages in | |
20395 | mailstore format should wait for the presence of both a &_.msg_& and a &_.env_& | |
168e428f | 20396 | file before accessing either of them. An alternative approach is to wait for |
9b371988 | 20397 | the absence of a &_.tmp_& file. |
168e428f | 20398 | |
9b371988 | 20399 | The envelope file starts with any text defined by the &%mailstore_prefix%& |
168e428f PH |
20400 | option, expanded and terminated by a newline if there isn't one. Then follows |
20401 | the sender address on one line, then all the recipient addresses, one per line. | |
9b371988 PH |
20402 | There can be more than one recipient only if the &%batch_max%& option is set |
20403 | greater than one. Finally, &%mailstore_suffix%& is expanded and the result | |
168e428f PH |
20404 | appended to the file, followed by a newline if it does not end with one. |
20405 | ||
9b371988 | 20406 | If expansion of &%mailstore_prefix%& or &%mailstore_suffix%& ends with a forced |
168e428f | 20407 | failure, it is ignored. Other expansion errors are treated as serious |
068aaea8 | 20408 | configuration errors, and delivery is deferred. The variable |
9b371988 | 20409 | &$mailstore_basename$& is available for use during these expansions. |
168e428f PH |
20410 | |
20411 | ||
f89d2485 | 20412 | .section "Non-special new file delivery" "SECID138" |
9b371988 PH |
20413 | If neither &%maildir_format%& nor &%mailstore_format%& is set, a single new |
20414 | file is created directly in the named directory. For example, when delivering | |
168e428f | 20415 | messages into files in batched SMTP format for later delivery to some host (see |
9b371988 PH |
20416 | section &<<SECTbatchSMTP>>&), a setting such as |
20417 | .code | |
20418 | directory = /var/bsmtp/$host | |
20419 | .endd | |
168e428f PH |
20420 | might be used. A message is written to a file with a temporary name, which is |
20421 | then renamed when the delivery is complete. The final name is obtained by | |
9b371988 | 20422 | expanding the contents of the &%directory_file%& option. |
4f578862 PH |
20423 | .ecindex IIDapptra1 |
20424 | .ecindex IIDapptra2 | |
168e428f PH |
20425 | |
20426 | ||
20427 | ||
20428 | ||
20429 | ||
20430 | ||
9b371988 PH |
20431 | . //////////////////////////////////////////////////////////////////////////// |
20432 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 20433 | |
f89d2485 | 20434 | .chapter "The autoreply transport" "CHID8" |
4f578862 PH |
20435 | .scindex IIDauttra1 "transports" "&(autoreply)&" |
20436 | .scindex IIDauttra2 "&(autoreply)& transport" | |
9b371988 | 20437 | The &(autoreply)& transport is not a true transport in that it does not cause |
4f578862 PH |
20438 | the message to be transmitted. Instead, it generates a new mail message as an |
20439 | automatic reply to the incoming message. &'References:'& and | |
20440 | &'Auto-Submitted:'& header lines are included. These are constructed according | |
20441 | to the rules in RFCs 2822 and 3834, respectively. | |
168e428f PH |
20442 | |
20443 | If the router that passes the message to this transport does not have the | |
9b371988 PH |
20444 | &%unseen%& option set, the original message (for the current recipient) is not |
20445 | delivered anywhere. However, when the &%unseen%& option is set on the router | |
20446 | that passes the message to this transport, routing of the address continues, so | |
168e428f PH |
20447 | another router can set up a normal message delivery. |
20448 | ||
20449 | ||
9b371988 PH |
20450 | The &(autoreply)& transport is usually run as the result of mail filtering, a |
20451 | &"vacation"& message being the standard example. However, it can also be run | |
168e428f | 20452 | directly from a router like any other transport. To reduce the possibility of |
9b371988 | 20453 | message cascades, messages created by the &(autoreply)& transport always have |
168e428f PH |
20454 | empty envelope sender addresses, like bounce messages. |
20455 | ||
20456 | The parameters of the message to be sent can be specified in the configuration | |
20457 | by options described below. However, these are used only when the address | |
20458 | passed to the transport does not contain its own reply information. When the | |
20459 | transport is run as a consequence of a | |
9b371988 PH |
20460 | &%mail%& |
20461 | or &%vacation%& command in a filter file, the parameters of the message are | |
168e428f PH |
20462 | supplied by the filter, and passed with the address. The transport's options |
20463 | that define the message are then ignored (so they are not usually set in this | |
20464 | case). The message is specified entirely by the filter or by the transport; it | |
9b371988 PH |
20465 | is never built from a mixture of options. However, the &%file_optional%&, |
20466 | &%mode%&, and &%return_message%& options apply in all cases. | |
168e428f | 20467 | |
9b371988 PH |
20468 | &(Autoreply)& is implemented as a local transport. When used as a result of a |
20469 | command in a user's filter file, &(autoreply)& normally runs under the uid and | |
168e428f | 20470 | gid of the user, and with appropriate current and home directories (see chapter |
9b371988 | 20471 | &<<CHAPenvironment>>&). |
168e428f | 20472 | |
9b371988 | 20473 | There is a subtle difference between routing a message to a &(pipe)& transport |
168e428f | 20474 | that generates some text to be returned to the sender, and routing it to an |
9b371988 | 20475 | &(autoreply)& transport. This difference is noticeable only if more than one |
168e428f PH |
20476 | address from the same message is so handled. In the case of a pipe, the |
20477 | separate outputs from the different addresses are gathered up and returned to | |
9b371988 | 20478 | the sender in a single message, whereas if &(autoreply)& is used, a separate |
168e428f PH |
20479 | message is generated for each address that is passed to it. |
20480 | ||
20481 | Non-printing characters are not permitted in the header lines generated for the | |
9b371988 | 20482 | message that &(autoreply)& creates, with the exception of newlines that are |
068aaea8 | 20483 | immediately followed by white space. If any non-printing characters are found, |
168e428f PH |
20484 | the transport defers. |
20485 | Whether characters with the top bit set count as printing characters or not is | |
9b371988 | 20486 | controlled by the &%print_topbitchars%& global option. |
168e428f PH |
20487 | |
20488 | If any of the generic options for manipulating headers (for example, | |
9b371988 PH |
20489 | &%headers_add%&) are set on an &(autoreply)& transport, they apply to the copy |
20490 | of the original message that is included in the generated message when | |
20491 | &%return_message%& is set. They do not apply to the generated message itself. | |
168e428f | 20492 | |
f89d2485 | 20493 | .vindex "&$sender_address$&" |
9b371988 | 20494 | If the &(autoreply)& transport receives return code 2 from Exim when it submits |
168e428f | 20495 | the message, indicating that there were no recipients, it does not treat this |
9b371988 | 20496 | as an error. This means that autoreplies sent to &$sender_address$& when this |
168e428f PH |
20497 | is empty (because the incoming message is a bounce message) do not cause |
20498 | problems. They are just discarded. | |
20499 | ||
20500 | ||
20501 | ||
f89d2485 | 20502 | .section "Private options for autoreply" "SECID139" |
9b371988 | 20503 | .cindex "options" "&(autoreply)& transport" |
168e428f | 20504 | |
9b371988 PH |
20505 | .option bcc autoreply string&!! unset |
20506 | This specifies the addresses that are to receive &"blind carbon copies"& of the | |
168e428f PH |
20507 | message when the message is specified by the transport. |
20508 | ||
20509 | ||
9b371988 PH |
20510 | .option cc autoreply string&!! unset |
20511 | This specifies recipients of the message and the contents of the &'Cc:'& header | |
168e428f PH |
20512 | when the message is specified by the transport. |
20513 | ||
20514 | ||
9b371988 | 20515 | .option file autoreply string&!! unset |
168e428f | 20516 | The contents of the file are sent as the body of the message when the message |
9b371988 | 20517 | is specified by the transport. If both &%file%& and &%text%& are set, the text |
168e428f PH |
20518 | string comes first. |
20519 | ||
20520 | ||
9b371988 PH |
20521 | .option file_expand autoreply boolean false |
20522 | If this is set, the contents of the file named by the &%file%& option are | |
168e428f PH |
20523 | subjected to string expansion as they are added to the message. |
20524 | ||
20525 | ||
9b371988 PH |
20526 | .option file_optional autoreply boolean false |
20527 | If this option is true, no error is generated if the file named by the &%file%& | |
168e428f PH |
20528 | option or passed with the address does not exist or cannot be read. |
20529 | ||
20530 | ||
9b371988 PH |
20531 | .option from autoreply string&!! unset |
20532 | This specifies the contents of the &'From:'& header when the message is | |
20533 | specified by the transport. | |
168e428f | 20534 | |
168e428f | 20535 | |
9b371988 PH |
20536 | .option headers autoreply string&!! unset |
20537 | This specifies additional RFC 2822 headers that are to be added to the message | |
20538 | when the message is specified by the transport. Several can be given by using | |
20539 | &"\n"& to separate them. There is no check on the format. | |
168e428f | 20540 | |
168e428f | 20541 | |
9b371988 | 20542 | .option log autoreply string&!! unset |
168e428f PH |
20543 | This option names a file in which a record of every message sent is logged when |
20544 | the message is specified by the transport. | |
20545 | ||
20546 | ||
9b371988 PH |
20547 | .option mode autoreply "octal integer" 0600 |
20548 | If either the log file or the &"once"& file has to be created, this mode is | |
d1e83bff | 20549 | used. |
168e428f PH |
20550 | |
20551 | ||
9b371988 | 20552 | .option never_mail autoreply "address list&!!" unset |
168e428f PH |
20553 | If any run of the transport creates a message with a recipient that matches any |
20554 | item in the list, that recipient is quietly discarded. If all recipients are | |
c0712871 PH |
20555 | discarded, no message is created. This applies both when the recipients are |
20556 | generated by a filter and when they are specified in the transport. | |
168e428f PH |
20557 | |
20558 | ||
20559 | ||
9b371988 PH |
20560 | .option once autoreply string&!! unset |
20561 | This option names a file or DBM database in which a record of each &'To:'& | |
20562 | recipient is kept when the message is specified by the transport. &*Note*&: | |
20563 | This does not apply to &'Cc:'& or &'Bcc:'& recipients. | |
d1e83bff | 20564 | |
9b371988 PH |
20565 | If &%once%& is unset, or is set to an empty string, the message is always sent. |
20566 | By default, if &%once%& is set to a non-empty file name, the message | |
d1e83bff | 20567 | is not sent if a potential recipient is already listed in the database. |
9b371988 | 20568 | However, if the &%once_repeat%& option specifies a time greater than zero, the |
d1e83bff | 20569 | message is sent if that much time has elapsed since a message was last sent to |
9b371988 PH |
20570 | this recipient. A setting of zero time for &%once_repeat%& (the default) |
20571 | prevents a message from being sent a second time &-- in this case, zero means | |
20572 | infinity. | |
d1e83bff | 20573 | |
9b371988 PH |
20574 | If &%once_file_size%& is zero, a DBM database is used to remember recipients, |
20575 | and it is allowed to grow as large as necessary. If &%once_file_size%& is set | |
20576 | greater than zero, it changes the way Exim implements the &%once%& option. | |
20577 | Instead of using a DBM file to record every recipient it sends to, it uses a | |
20578 | regular file, whose size will never get larger than the given value. | |
d1e83bff PH |
20579 | |
20580 | In the file, Exim keeps a linear list of recipient addresses and the times at | |
20581 | which they were sent messages. If the file is full when a new address needs to | |
9b371988 | 20582 | be added, the oldest address is dropped. If &%once_repeat%& is not set, this |
d1e83bff PH |
20583 | means that a given recipient may receive multiple messages, but at |
20584 | unpredictable intervals that depend on the rate of turnover of addresses in the | |
9b371988 | 20585 | file. If &%once_repeat%& is set, it specifies a maximum time between repeats. |
168e428f | 20586 | |
168e428f | 20587 | |
9b371988 PH |
20588 | .option once_file_size autoreply integer 0 |
20589 | See &%once%& above. | |
168e428f | 20590 | |
168e428f | 20591 | |
9b371988 PH |
20592 | .option once_repeat autoreply time&!! 0s |
20593 | See &%once%& above. | |
168e428f PH |
20594 | After expansion, the value of this option must be a valid time value. |
20595 | ||
20596 | ||
9b371988 PH |
20597 | .option reply_to autoreply string&!! unset |
20598 | This specifies the contents of the &'Reply-To:'& header when the message is | |
168e428f PH |
20599 | specified by the transport. |
20600 | ||
20601 | ||
9b371988 | 20602 | .option return_message autoreply boolean false |
168e428f | 20603 | If this is set, a copy of the original message is returned with the new |
9b371988 | 20604 | message, subject to the maximum size set in the &%return_size_limit%& global |
168e428f PH |
20605 | configuration option. |
20606 | ||
20607 | ||
9b371988 PH |
20608 | .option subject autoreply string&!! unset |
20609 | This specifies the contents of the &'Subject:'& header when the message is | |
20610 | specified by the transport. It is tempting to quote the original subject in | |
20611 | automatic responses. For example: | |
20612 | .code | |
20613 | subject = Re: $h_subject: | |
20614 | .endd | |
168e428f PH |
20615 | There is a danger in doing this, however. It may allow a third party to |
20616 | subscribe your users to an opt-in mailing list, provided that the list accepts | |
20617 | bounce messages as subscription confirmations. Well-managed lists require a | |
20618 | non-bounce message to confirm a subscription, so the danger is relatively | |
20619 | small. | |
20620 | ||
20621 | ||
20622 | ||
9b371988 | 20623 | .option text autoreply string&!! unset |
168e428f | 20624 | This specifies a single string to be used as the body of the message when the |
9b371988 PH |
20625 | message is specified by the transport. If both &%text%& and &%file%& are set, |
20626 | the text comes first. | |
168e428f | 20627 | |
168e428f | 20628 | |
9b371988 PH |
20629 | .option to autoreply string&!! unset |
20630 | This specifies recipients of the message and the contents of the &'To:'& header | |
168e428f | 20631 | when the message is specified by the transport. |
4f578862 PH |
20632 | .ecindex IIDauttra1 |
20633 | .ecindex IIDauttra2 | |
168e428f PH |
20634 | |
20635 | ||
20636 | ||
20637 | ||
9b371988 PH |
20638 | . //////////////////////////////////////////////////////////////////////////// |
20639 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 20640 | |
9b371988 PH |
20641 | .chapter "The lmtp transport" "CHAPLMTP" |
20642 | .cindex "transports" "&(lmtp)&" | |
20643 | .cindex "&(lmtp)& transport" | |
20644 | .cindex "LMTP" "over a pipe" | |
20645 | .cindex "LMTP" "over a socket" | |
20646 | The &(lmtp)& transport runs the LMTP protocol (RFC 2033) over a pipe to a | |
168e428f PH |
20647 | specified command |
20648 | or by interacting with a Unix domain socket. | |
9b371988 | 20649 | This transport is something of a cross between the &(pipe)& and &(smtp)& |
168e428f | 20650 | transports. Exim also has support for using LMTP over TCP/IP; this is |
9b371988 PH |
20651 | implemented as an option for the &(smtp)& transport. Because LMTP is expected |
20652 | to be of minority interest, the default build-time configure in &_src/EDITME_& | |
168e428f | 20653 | has it commented out. You need to ensure that |
9b371988 PH |
20654 | .code |
20655 | TRANSPORT_LMTP=yes | |
20656 | .endd | |
20657 | .cindex "options" "&(lmtp)& transport" | |
20658 | is present in your &_Local/Makefile_& in order to have the &(lmtp)& transport | |
20659 | included in the Exim binary. The private options of the &(lmtp)& transport are | |
20660 | as follows: | |
168e428f | 20661 | |
9b371988 PH |
20662 | .option batch_id lmtp string&!! unset |
20663 | See the description of local delivery batching in chapter &<<CHAPbatching>>&. | |
168e428f | 20664 | |
168e428f | 20665 | |
9b371988 | 20666 | .option batch_max lmtp integer 1 |
168e428f PH |
20667 | This limits the number of addresses that can be handled in a single delivery. |
20668 | Most LMTP servers can handle several addresses at once, so it is normally a | |
20669 | good idea to increase this value. See the description of local delivery | |
9b371988 | 20670 | batching in chapter &<<CHAPbatching>>&. |
168e428f PH |
20671 | |
20672 | ||
9b371988 PH |
20673 | .option command lmtp string&!! unset |
20674 | This option must be set if &%socket%& is not set. The string is a command which | |
068aaea8 PH |
20675 | is run in a separate process. It is split up into a command name and list of |
20676 | arguments, each of which is separately expanded (so expansion cannot change the | |
20677 | number of arguments). The command is run directly, not via a shell. The message | |
20678 | is passed to the new process using the standard input and output to operate the | |
20679 | LMTP protocol. | |
20680 | ||
9b371988 PH |
20681 | .option ignore_quota lmtp boolean false |
20682 | .cindex "LMTP" "ignoring quota errors" | |
20683 | If this option is set true, the string &`IGNOREQUOTA`& is added to RCPT | |
20684 | commands, provided that the LMTP server has advertised support for IGNOREQUOTA | |
20685 | in its response to the LHLO command. | |
168e428f | 20686 | |
9b371988 PH |
20687 | .option socket lmtp string&!! unset |
20688 | This option must be set if &%command%& is not set. The result of expansion must | |
168e428f PH |
20689 | be the name of a Unix domain socket. The transport connects to the socket and |
20690 | delivers the message to it using the LMTP protocol. | |
20691 | ||
20692 | ||
9b371988 | 20693 | .option timeout lmtp time 5m |
f89d2485 | 20694 | The transport is aborted if the created process or Unix domain socket does not |
7d0ab55c TF |
20695 | respond to LMTP commands or message input within this timeout. Delivery |
20696 | is deferred, and will be tried again later. Here is an example of a typical | |
595028e4 | 20697 | LMTP transport: |
9b371988 PH |
20698 | .code |
20699 | lmtp: | |
20700 | driver = lmtp | |
20701 | command = /some/local/lmtp/delivery/program | |
20702 | batch_max = 20 | |
20703 | user = exim | |
20704 | .endd | |
168e428f | 20705 | This delivers up to 20 addresses at a time, in a mixture of domains if |
9b371988 | 20706 | necessary, running as the user &'exim'&. |
168e428f PH |
20707 | |
20708 | ||
168e428f | 20709 | |
9b371988 PH |
20710 | . //////////////////////////////////////////////////////////////////////////// |
20711 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 20712 | |
9b371988 | 20713 | .chapter "The pipe transport" "CHAPpipetransport" |
4f578862 PH |
20714 | .scindex IIDpiptra1 "transports" "&(pipe)&" |
20715 | .scindex IIDpiptra2 "&(pipe)& transport" | |
9b371988 PH |
20716 | The &(pipe)& transport is used to deliver messages via a pipe to a command |
20717 | running in another process. One example is the use of &(pipe)& as a | |
20718 | pseudo-remote transport for passing messages to some other delivery mechanism | |
20719 | (such as UUCP). Another is the use by individual users to automatically process | |
20720 | their incoming messages. The &(pipe)& transport can be used in one of the | |
20721 | following ways: | |
168e428f | 20722 | |
9b371988 | 20723 | .ilist |
f89d2485 | 20724 | .vindex "&$local_part$&" |
068aaea8 | 20725 | A router routes one address to a transport in the normal way, and the |
9b371988 | 20726 | transport is configured as a &(pipe)& transport. In this case, &$local_part$& |
068aaea8 | 20727 | contains the local part of the address (as usual), and the command that is run |
9b371988 PH |
20728 | is specified by the &%command%& option on the transport. |
20729 | .next | |
f89d2485 | 20730 | .vindex "&$pipe_addresses$&" |
c0712871 PH |
20731 | If the &%batch_max%& option is set greater than 1 (the default is 1), the |
20732 | transport can handle more than one address in a single run. In this case, when | |
20733 | more than one address is routed to the transport, &$local_part$& is not set | |
20734 | (because it is not unique). However, the pseudo-variable &$pipe_addresses$& | |
20735 | (described in section &<<SECThowcommandrun>>& below) contains all the addresses | |
20736 | that are routed to the transport. | |
9b371988 | 20737 | .next |
f89d2485 | 20738 | .vindex "&$address_pipe$&" |
068aaea8 | 20739 | A router redirects an address directly to a pipe command (for example, from an |
c0712871 PH |
20740 | alias or forward file). In this case, &$address_pipe$& contains the text of the |
20741 | pipe command, and the &%command%& option on the transport is ignored. If only | |
20742 | one address is being transported (&%batch_max%& is not greater than one, or | |
20743 | only one address was redirected to this pipe command), &$local_part$& contains | |
20744 | the local part that was redirected. | |
9b371988 | 20745 | .endlist |
168e428f PH |
20746 | |
20747 | ||
9b371988 | 20748 | The &(pipe)& transport is a non-interactive delivery method. Exim can also |
168e428f | 20749 | deliver messages over pipes using the LMTP interactive protocol. This is |
9b371988 | 20750 | implemented by the &(lmtp)& transport. |
168e428f | 20751 | |
9b371988 PH |
20752 | In the case when &(pipe)& is run as a consequence of an entry in a local user's |
20753 | &_.forward_& file, the command runs under the uid and gid of that user. In | |
20754 | other cases, the uid and gid have to be specified explicitly, either on the | |
20755 | transport or on the router that handles the address. Current and &"home"& | |
20756 | directories are also controllable. See chapter &<<CHAPenvironment>>& for | |
db9452a9 PH |
20757 | details of the local delivery environment and chapter &<<CHAPbatching>>& |
20758 | for a discussion of local delivery batching. | |
168e428f PH |
20759 | |
20760 | ||
f89d2485 | 20761 | .section "Concurrent delivery" "SECID140" |
168e428f PH |
20762 | If two messages arrive at almost the same time, and both are routed to a pipe |
20763 | delivery, the two pipe transports may be run concurrently. You must ensure that | |
20764 | any pipe commands you set up are robust against this happening. If the commands | |
9b371988 | 20765 | write to a file, the &%exim_lock%& utility might be of use. |
168e428f PH |
20766 | |
20767 | ||
20768 | ||
20769 | ||
f89d2485 | 20770 | .section "Returned status and data" "SECID141" |
9b371988 | 20771 | .cindex "&(pipe)& transport" "returned data" |
168e428f | 20772 | If the command exits with a non-zero return code, the delivery is deemed to |
9b371988 | 20773 | have failed, unless either the &%ignore_status%& option is set (in which case |
168e428f | 20774 | the return code is treated as zero), or the return code is one of those listed |
9b371988 PH |
20775 | in the &%temp_errors%& option, which are interpreted as meaning &"try again |
20776 | later"&. In this case, delivery is deferred. Details of a permanent failure are | |
168e428f | 20777 | logged, but are not included in the bounce message, which merely contains |
9b371988 | 20778 | &"local delivery failed"&. |
168e428f PH |
20779 | |
20780 | If the return code is greater than 128 and the command being run is a shell | |
20781 | script, it normally means that the script was terminated by a signal whose | |
20782 | value is the return code minus 128. | |
20783 | ||
9b371988 | 20784 | If Exim is unable to run the command (that is, if &[execve()]& fails), the |
168e428f PH |
20785 | return code is set to 127. This is the value that a shell returns if it is |
20786 | asked to run a non-existent command. The wording for the log line suggests that | |
20787 | a non-existent command may be the problem. | |
20788 | ||
9b371988 | 20789 | The &%return_output%& option can affect the result of a pipe delivery. If it is |
168e428f PH |
20790 | set and the command produces any output on its standard output or standard |
20791 | error streams, the command is considered to have failed, even if it gave a zero | |
9b371988 PH |
20792 | return code or if &%ignore_status%& is set. The output from the command is |
20793 | included as part of the bounce message. The &%return_fail_output%& option is | |
168e428f PH |
20794 | similar, except that output is returned only when the command exits with a |
20795 | failure return code, that is, a value other than zero or a code that matches | |
9b371988 | 20796 | &%temp_errors%&. |
168e428f PH |
20797 | |
20798 | ||
20799 | ||
9b371988 PH |
20800 | .section "How the command is run" "SECThowcommandrun" |
20801 | .cindex "&(pipe)& transport" "path for command" | |
168e428f | 20802 | The command line is (by default) broken down into a command name and arguments |
9b371988 PH |
20803 | by the &(pipe)& transport itself. The &%allow_commands%& and |
20804 | &%restrict_to_path%& options can be used to restrict the commands that may be | |
20805 | run. | |
168e428f | 20806 | |
9b371988 | 20807 | .cindex "quoting" "in pipe command" |
168e428f PH |
20808 | Unquoted arguments are delimited by white space. If an argument appears in |
20809 | double quotes, backslash is interpreted as an escape character in the usual | |
20810 | way. If an argument appears in single quotes, no escaping is done. | |
20811 | ||
20812 | String expansion is applied to the command line except when it comes from a | |
9b371988 | 20813 | traditional &_.forward_& file (commands from a filter file are expanded). The |
168e428f PH |
20814 | expansion is applied to each argument in turn rather than to the whole line. |
20815 | For this reason, any string expansion item that contains white space must be | |
20816 | quoted so as to be contained within a single argument. A setting such as | |
9b371988 PH |
20817 | .code |
20818 | command = /some/path ${if eq{$local_part}{postmaster}{xx}{yy}} | |
20819 | .endd | |
168e428f PH |
20820 | will not work, because the expansion item gets split between several |
20821 | arguments. You have to write | |
9b371988 PH |
20822 | .code |
20823 | command = /some/path "${if eq{$local_part}{postmaster}{xx}{yy}}" | |
20824 | .endd | |
168e428f PH |
20825 | to ensure that it is all in one argument. The expansion is done in this way, |
20826 | argument by argument, so that the number of arguments cannot be changed as a | |
20827 | result of expansion, and quotes or backslashes in inserted variables do not | |
4f578862 PH |
20828 | interact with external quoting. However, this leads to problems if you want to |
20829 | generate multiple arguments (or the command name plus arguments) from a single | |
20830 | expansion. In this situation, the simplest solution is to use a shell. For | |
20831 | example: | |
20832 | .code | |
20833 | command = /bin/sh -c ${lookup{$local_part}lsearch{/some/file}} | |
20834 | .endd | |
168e428f | 20835 | |
9b371988 PH |
20836 | .cindex "transport" "filter" |
20837 | .cindex "filter" "transport filter" | |
f89d2485 | 20838 | .vindex "&$pipe_addresses$&" |
168e428f | 20839 | Special handling takes place when an argument consists of precisely the text |
9b371988 | 20840 | &`$pipe_addresses`&. This is not a general expansion variable; the only |
168e428f PH |
20841 | place this string is recognized is when it appears as an argument for a pipe or |
20842 | transport filter command. It causes each address that is being handled to be | |
9b371988 | 20843 | inserted in the argument list at that point &'as a separate argument'&. This |
168e428f | 20844 | avoids any problems with spaces or shell metacharacters, and is of use when a |
9b371988 | 20845 | &(pipe)& transport is handling groups of addresses in a batch. |
168e428f PH |
20846 | |
20847 | After splitting up into arguments and expansion, the resulting command is run | |
9b371988 | 20848 | in a subprocess directly from the transport, &'not'& under a shell. The |
168e428f PH |
20849 | message that is being delivered is supplied on the standard input, and the |
20850 | standard output and standard error are both connected to a single pipe that is | |
9b371988 PH |
20851 | read by Exim. The &%max_output%& option controls how much output the command |
20852 | may produce, and the &%return_output%& and &%return_fail_output%& options | |
20853 | control what is done with it. | |
168e428f PH |
20854 | |
20855 | Not running the command under a shell (by default) lessens the security risks | |
20856 | in cases when a command from a user's filter file is built out of data that was | |
20857 | taken from an incoming message. If a shell is required, it can of course be | |
20858 | explicitly specified as the command to be run. However, there are circumstances | |
9b371988 | 20859 | where existing commands (for example, in &_.forward_& files) expect to be run |
168e428f | 20860 | under a shell and cannot easily be modified. To allow for these cases, there is |
9b371988 | 20861 | an option called &%use_shell%&, which changes the way the &(pipe)& transport |
168e428f | 20862 | works. Instead of breaking up the command line as just described, it expands it |
9b371988 PH |
20863 | as a single string and passes the result to &_/bin/sh_&. The |
20864 | &%restrict_to_path%& option and the &$pipe_addresses$& facility cannot be used | |
20865 | with &%use_shell%&, and the whole mechanism is inherently less secure. | |
168e428f PH |
20866 | |
20867 | ||
20868 | ||
9b371988 PH |
20869 | .section "Environment variables" "SECTpipeenv" |
20870 | .cindex "&(pipe)& transport" "environment for command" | |
20871 | .cindex "environment for pipe transport" | |
168e428f PH |
20872 | The environment variables listed below are set up when the command is invoked. |
20873 | This list is a compromise for maximum compatibility with other MTAs. Note that | |
9b371988 | 20874 | the &%environment%& option can be used to add additional variables to this |
168e428f | 20875 | environment. |
9b371988 PH |
20876 | .display |
20877 | &`DOMAIN `& the domain of the address | |
20878 | &`HOME `& the home directory, if set | |
20879 | &`HOST `& the host name when called from a router (see below) | |
20880 | &`LOCAL_PART `& see below | |
20881 | &`LOCAL_PART_PREFIX `& see below | |
20882 | &`LOCAL_PART_SUFFIX `& see below | |
20883 | &`LOGNAME `& see below | |
20884 | &`MESSAGE_ID `& Exim's local ID for the message | |
20885 | &`PATH `& as specified by the &%path%& option below | |
20886 | &`QUALIFY_DOMAIN `& the sender qualification domain | |
20887 | &`RECIPIENT `& the complete recipient address | |
20888 | &`SENDER `& the sender of the message (empty if a bounce) | |
20889 | &`SHELL `& &`/bin/sh`& | |
20890 | &`TZ `& the value of the &%timezone%& option, if set | |
20891 | &`USER `& see below | |
20892 | .endd | |
20893 | When a &(pipe)& transport is called directly from (for example) an &(accept)& | |
168e428f PH |
20894 | router, LOCAL_PART is set to the local part of the address. When it is |
20895 | called as a result of a forward or alias expansion, LOCAL_PART is set to | |
20896 | the local part of the address that was expanded. In both cases, any affixes are | |
20897 | removed from the local part, and made available in LOCAL_PART_PREFIX and | |
20898 | LOCAL_PART_SUFFIX, respectively. LOGNAME and USER are set to the | |
20899 | same value as LOCAL_PART for compatibility with other MTAs. | |
20900 | ||
9b371988 PH |
20901 | .cindex "HOST" |
20902 | HOST is set only when a &(pipe)& transport is called from a router that | |
20903 | associates hosts with an address, typically when using &(pipe)& as a | |
168e428f PH |
20904 | pseudo-remote transport. HOST is set to the first host name specified by |
20905 | the router. | |
20906 | ||
9b371988 PH |
20907 | .cindex "HOME" |
20908 | If the transport's generic &%home_directory%& option is set, its value is used | |
168e428f | 20909 | for the HOME environment variable. Otherwise, a home directory may be set |
9b371988 PH |
20910 | by the router's &%transport_home_directory%& option, which defaults to the |
20911 | user's home directory if &%check_local_user%& is set. | |
168e428f PH |
20912 | |
20913 | ||
f89d2485 | 20914 | .section "Private options for pipe" "SECID142" |
9b371988 | 20915 | .cindex "options" "&(pipe)& transport" |
168e428f PH |
20916 | |
20917 | ||
20918 | ||
9b371988 PH |
20919 | .option allow_commands pipe "string list&!!" unset |
20920 | .cindex "&(pipe)& transport" "permitted commands" | |
168e428f | 20921 | The string is expanded, and is then interpreted as a colon-separated list of |
9b371988 PH |
20922 | permitted commands. If &%restrict_to_path%& is not set, the only commands |
20923 | permitted are those in the &%allow_commands%& list. They need not be absolute | |
20924 | paths; the &%path%& option is still used for relative paths. If | |
20925 | &%restrict_to_path%& is set with &%allow_commands%&, the command must either be | |
20926 | in the &%allow_commands%& list, or a name without any slashes that is found on | |
20927 | the path. In other words, if neither &%allow_commands%& nor | |
20928 | &%restrict_to_path%& is set, there is no restriction on the command, but | |
20929 | otherwise only commands that are permitted by one or the other are allowed. For | |
20930 | example, if | |
20931 | .code | |
20932 | allow_commands = /usr/bin/vacation | |
20933 | .endd | |
20934 | and &%restrict_to_path%& is not set, the only permitted command is | |
20935 | &_/usr/bin/vacation_&. The &%allow_commands%& option may not be set if | |
20936 | &%use_shell%& is set. | |
168e428f | 20937 | |
168e428f | 20938 | |
9b371988 PH |
20939 | .option batch_id pipe string&!! unset |
20940 | See the description of local delivery batching in chapter &<<CHAPbatching>>&. | |
168e428f | 20941 | |
168e428f | 20942 | |
9b371988 | 20943 | .option batch_max pipe integer 1 |
168e428f | 20944 | This limits the number of addresses that can be handled in a single delivery. |
9b371988 | 20945 | See the description of local delivery batching in chapter &<<CHAPbatching>>&. |
168e428f PH |
20946 | |
20947 | ||
9b371988 PH |
20948 | .option check_string pipe string unset |
20949 | As &(pipe)& writes the message, the start of each line is tested for matching | |
20950 | &%check_string%&, and if it does, the initial matching characters are replaced | |
20951 | by the contents of &%escape_string%&, provided both are set. The value of | |
20952 | &%check_string%& is a literal string, not a regular expression, and the case of | |
20953 | any letters it contains is significant. When &%use_bsmtp%& is set, the contents | |
20954 | of &%check_string%& and &%escape_string%& are forced to values that implement | |
20955 | the SMTP escaping protocol. Any settings made in the configuration file are | |
168e428f PH |
20956 | ignored. |
20957 | ||
20958 | ||
9b371988 PH |
20959 | .option command pipe string&!! unset |
20960 | This option need not be set when &(pipe)& is being used to deliver to pipes | |
168e428f PH |
20961 | obtained directly from address redirections. In other cases, the option must be |
20962 | set, to provide a command to be run. It need not yield an absolute path (see | |
9b371988 | 20963 | the &%path%& option below). The command is split up into separate arguments by |
168e428f | 20964 | Exim, and each argument is separately expanded, as described in section |
9b371988 | 20965 | &<<SECThowcommandrun>>& above. |
168e428f PH |
20966 | |
20967 | ||
9b371988 PH |
20968 | .option environment pipe string&!! unset |
20969 | .cindex "&(pipe)& transport" "environment for command" | |
20970 | .cindex "environment for &(pipe)& transport" | |
168e428f | 20971 | This option is used to add additional variables to the environment in which the |
9b371988 PH |
20972 | command runs (see section &<<SECTpipeenv>>& for the default list). Its value is |
20973 | a string which is expanded, and then interpreted as a colon-separated list of | |
20974 | environment settings of the form <&'name'&>=<&'value'&>. | |
168e428f | 20975 | |
168e428f | 20976 | |
9b371988 PH |
20977 | .option escape_string pipe string unset |
20978 | See &%check_string%& above. | |
168e428f PH |
20979 | |
20980 | ||
9b371988 PH |
20981 | .option freeze_exec_fail pipe boolean false |
20982 | .cindex "exec failure" | |
20983 | .cindex "failure of exec" | |
20984 | .cindex "&(pipe)& transport" "failure of exec" | |
168e428f | 20985 | Failure to exec the command in a pipe transport is by default treated like |
9b371988 | 20986 | any other failure while running the command. However, if &%freeze_exec_fail%& |
168e428f | 20987 | is set, failure to exec is treated specially, and causes the message to be |
9b371988 | 20988 | frozen, whatever the setting of &%ignore_status%&. |
168e428f | 20989 | |
168e428f | 20990 | |
9b371988 | 20991 | .option ignore_status pipe boolean false |
168e428f PH |
20992 | If this option is true, the status returned by the subprocess that is set up to |
20993 | run the command is ignored, and Exim behaves as if zero had been returned. | |
068aaea8 PH |
20994 | Otherwise, a non-zero status or termination by signal causes an error return |
20995 | from the transport unless the status value is one of those listed in | |
9b371988 | 20996 | &%temp_errors%&; these cause the delivery to be deferred and tried again later. |
068aaea8 | 20997 | |
9b371988 PH |
20998 | &*Note*&: This option does not apply to timeouts, which do not return a status. |
20999 | See the &%timeout_defer%& option for how timeouts are handled. | |
168e428f | 21000 | |
9b371988 PH |
21001 | .option log_defer_output pipe boolean false |
21002 | .cindex "&(pipe)& transport" "logging output" | |
168e428f | 21003 | If this option is set, and the status returned by the command is |
9b371988 | 21004 | one of the codes listed in &%temp_errors%& (that is, delivery was deferred), |
168e428f PH |
21005 | and any output was produced, the first line of it is written to the main log. |
21006 | ||
21007 | ||
9b371988 | 21008 | .option log_fail_output pipe boolean false |
168e428f PH |
21009 | If this option is set, and the command returns any output, and also ends with a |
21010 | return code that is neither zero nor one of the return codes listed in | |
9b371988 PH |
21011 | &%temp_errors%& (that is, the delivery failed), the first line of output is |
21012 | written to the main log. This option and &%log_output%& are mutually exclusive. | |
21013 | Only one of them may be set. | |
168e428f PH |
21014 | |
21015 | ||
168e428f | 21016 | |
9b371988 | 21017 | .option log_output pipe boolean false |
168e428f | 21018 | If this option is set and the command returns any output, the first line of |
9b371988 PH |
21019 | output is written to the main log, whatever the return code. This option and |
21020 | &%log_fail_output%& are mutually exclusive. Only one of them may be set. | |
168e428f PH |
21021 | |
21022 | ||
168e428f | 21023 | |
9b371988 | 21024 | .option max_output pipe integer 20K |
168e428f PH |
21025 | This specifies the maximum amount of output that the command may produce on its |
21026 | standard output and standard error file combined. If the limit is exceeded, the | |
21027 | process running the command is killed. This is intended as a safety measure to | |
21028 | catch runaway processes. The limit is applied independently of the settings of | |
21029 | the options that control what is done with such output (for example, | |
9b371988 | 21030 | &%return_output%&). Because of buffering effects, the amount of output may |
168e428f PH |
21031 | exceed the limit by a small amount before Exim notices. |
21032 | ||
21033 | ||
9b371988 | 21034 | .option message_prefix pipe string&!! "see below" |
168e428f | 21035 | The string specified here is expanded and output at the start of every message. |
9b371988 PH |
21036 | The default is unset if &%use_bsmtp%& is set. Otherwise it is |
21037 | .code | |
168e428f PH |
21038 | message_prefix = \ |
21039 | From ${if def:return_path{$return_path}{MAILER-DAEMON}}\ | |
21040 | ${tod_bsdinbox}\n | |
9b371988 PH |
21041 | .endd |
21042 | .cindex "Cyrus" | |
21043 | .cindex "&%tmail%&" | |
21044 | .cindex "&""From""& line" | |
21045 | This is required by the commonly used &_/usr/bin/vacation_& program. | |
21046 | However, it must &'not'& be present if delivery is to the Cyrus IMAP server, | |
21047 | or to the &%tmail%& local delivery agent. The prefix can be suppressed by | |
21048 | setting | |
21049 | .code | |
21050 | message_prefix = | |
21051 | .endd | |
595028e4 PH |
21052 | &*Note:*& If you set &%use_crlf%& true, you must change any occurrences of |
21053 | &`\n`& to &`\r\n`& in &%message_prefix%&. | |
595028e4 | 21054 | |
168e428f | 21055 | |
9b371988 | 21056 | .option message_suffix pipe string&!! "see below" |
168e428f | 21057 | The string specified here is expanded and output at the end of every message. |
9b371988 | 21058 | The default is unset if &%use_bsmtp%& is set. Otherwise it is a single newline. |
168e428f | 21059 | The suffix can be suppressed by setting |
9b371988 PH |
21060 | .code |
21061 | message_suffix = | |
21062 | .endd | |
595028e4 PH |
21063 | &*Note:*& If you set &%use_crlf%& true, you must change any occurrences of |
21064 | &`\n`& to &`\r\n`& in &%message_suffix%&. | |
595028e4 | 21065 | |
168e428f | 21066 | |
f89d2485 | 21067 | .option path pipe string "see below" |
168e428f | 21068 | This option specifies the string that is set up in the PATH environment |
f89d2485 PH |
21069 | variable of the subprocess. The default is: |
21070 | .code | |
21071 | /bin:/usr/bin | |
21072 | .endd | |
21073 | If the &%command%& option does not yield an absolute path name, the command is | |
21074 | sought in the PATH directories, in the usual way. &*Warning*&: This does not | |
21075 | apply to a command specified as a transport filter. | |
168e428f PH |
21076 | |
21077 | ||
a29e5231 PP |
21078 | .option permit_coredump pipe boolean false |
21079 | Normally Exim inhibits core-dumps during delivery. If you have a need to get | |
21080 | a core-dump of a pipe command, enable this command. This enables core-dumps | |
21081 | during delivery and affects both the Exim binary and the pipe command run. | |
21082 | It is recommended that this option remain off unless and until you have a need | |
21083 | for it and that this only be enabled when needed, as the risk of excessive | |
21084 | resource consumption can be quite high. Note also that Exim is typically | |
21085 | installed as a setuid binary and most operating systems will inhibit coredumps | |
21086 | of these by default, so further OS-specific action may be required. | |
21087 | ||
21088 | ||
9b371988 PH |
21089 | .option pipe_as_creator pipe boolean false |
21090 | .cindex "uid (user id)" "local delivery" | |
21091 | If the generic &%user%& option is not set and this option is true, the delivery | |
168e428f PH |
21092 | process is run under the uid that was in force when Exim was originally called |
21093 | to accept the message. If the group id is not otherwise set (via the generic | |
9b371988 | 21094 | &%group%& option), the gid that was in force when Exim was originally called to |
168e428f PH |
21095 | accept the message is used. |
21096 | ||
21097 | ||
9b371988 PH |
21098 | .option restrict_to_path pipe boolean false |
21099 | When this option is set, any command name not listed in &%allow_commands%& must | |
168e428f | 21100 | contain no slashes. The command is searched for only in the directories listed |
9b371988 PH |
21101 | in the &%path%& option. This option is intended for use in the case when a pipe |
21102 | command has been generated from a user's &_.forward_& file. This is usually | |
21103 | handled by a &(pipe)& transport called &%address_pipe%&. | |
168e428f PH |
21104 | |
21105 | ||
9b371988 | 21106 | .option return_fail_output pipe boolean false |
168e428f | 21107 | If this option is true, and the command produced any output and ended with a |
9b371988 | 21108 | return code other than zero or one of the codes listed in &%temp_errors%& (that |
168e428f PH |
21109 | is, the delivery failed), the output is returned in the bounce message. |
21110 | However, if the message has a null sender (that is, it is itself a bounce | |
9b371988 PH |
21111 | message), output from the command is discarded. This option and |
21112 | &%return_output%& are mutually exclusive. Only one of them may be set. | |
168e428f PH |
21113 | |
21114 | ||
21115 | ||
9b371988 | 21116 | .option return_output pipe boolean false |
168e428f PH |
21117 | If this option is true, and the command produced any output, the delivery is |
21118 | deemed to have failed whatever the return code from the command, and the output | |
21119 | is returned in the bounce message. Otherwise, the output is just discarded. | |
21120 | However, if the message has a null sender (that is, it is a bounce message), | |
21121 | output from the command is always discarded, whatever the setting of this | |
9b371988 PH |
21122 | option. This option and &%return_fail_output%& are mutually exclusive. Only one |
21123 | of them may be set. | |
168e428f | 21124 | |
168e428f PH |
21125 | |
21126 | ||
9b371988 PH |
21127 | .option temp_errors pipe "string list" "see below" |
21128 | .cindex "&(pipe)& transport" "temporary failure" | |
168e428f | 21129 | This option contains either a colon-separated list of numbers, or a single |
9b371988 PH |
21130 | asterisk. If &%ignore_status%& is false |
21131 | and &%return_output%& is not set, | |
168e428f PH |
21132 | and the command exits with a non-zero return code, the failure is treated as |
21133 | temporary and the delivery is deferred if the return code matches one of the | |
21134 | numbers, or if the setting is a single asterisk. Otherwise, non-zero return | |
21135 | codes are treated as permanent errors. The default setting contains the codes | |
9b371988 | 21136 | defined by EX_TEMPFAIL and EX_CANTCREAT in &_sysexits.h_&. If Exim is |
168e428f PH |
21137 | compiled on a system that does not define these macros, it assumes values of 75 |
21138 | and 73, respectively. | |
21139 | ||
21140 | ||
9b371988 | 21141 | .option timeout pipe time 1h |
168e428f | 21142 | If the command fails to complete within this time, it is killed. This normally |
9b371988 | 21143 | causes the delivery to fail (but see &%timeout_defer%&). A zero time interval |
068aaea8 PH |
21144 | specifies no timeout. In order to ensure that any subprocesses created by the |
21145 | command are also killed, Exim makes the initial process a process group leader, | |
21146 | and kills the whole process group on a timeout. However, this can be defeated | |
21147 | if one of the processes starts a new process group. | |
21148 | ||
9b371988 PH |
21149 | .option timeout_defer pipe boolean false |
21150 | A timeout in a &(pipe)& transport, either in the command that the transport | |
21151 | runs, or in a transport filter that is associated with it, is by default | |
21152 | treated as a hard error, and the delivery fails. However, if &%timeout_defer%& | |
21153 | is set true, both kinds of timeout become temporary errors, causing the | |
21154 | delivery to be deferred. | |
168e428f | 21155 | |
9b371988 | 21156 | .option umask pipe "octal integer" 022 |
168e428f PH |
21157 | This specifies the umask setting for the subprocess that runs the command. |
21158 | ||
21159 | ||
9b371988 PH |
21160 | .option use_bsmtp pipe boolean false |
21161 | .cindex "envelope sender" | |
21162 | If this option is set true, the &(pipe)& transport writes messages in &"batch | |
21163 | SMTP"& format, with the envelope sender and recipient(s) included as SMTP | |
168e428f | 21164 | commands. If you want to include a leading HELO command with such messages, |
9b371988 PH |
21165 | you can do so by setting the &%message_prefix%& option. See section |
21166 | &<<SECTbatchSMTP>>& for details of batch SMTP. | |
168e428f | 21167 | |
4f578862 PH |
21168 | .option use_classresources pipe boolean false |
21169 | .cindex "class resources (BSD)" | |
21170 | This option is available only when Exim is running on FreeBSD, NetBSD, or | |
21171 | BSD/OS. If it is set true, the &[setclassresources()]& function is used to set | |
21172 | resource limits when a &(pipe)& transport is run to perform a delivery. The | |
21173 | limits for the uid under which the pipe is to run are obtained from the login | |
21174 | class database. | |
4f578862 | 21175 | |
168e428f | 21176 | |
9b371988 PH |
21177 | .option use_crlf pipe boolean false |
21178 | .cindex "carriage return" | |
21179 | .cindex "linefeed" | |
168e428f PH |
21180 | This option causes lines to be terminated with the two-character CRLF sequence |
21181 | (carriage return, linefeed) instead of just a linefeed character. In the case | |
21182 | of batched SMTP, the byte sequence written to the pipe is then an exact image | |
21183 | of what would be sent down a real SMTP connection. | |
21184 | ||
9b371988 PH |
21185 | The contents of the &%message_prefix%& and &%message_suffix%& options are |
21186 | written verbatim, so must contain their own carriage return characters if these | |
595028e4 PH |
21187 | are needed. When &%use_bsmtp%& is not set, the default values for both |
21188 | &%message_prefix%& and &%message_suffix%& end with a single linefeed, so their | |
21189 | values must be changed to end with &`\r\n`& if &%use_crlf%& is set. | |
168e428f PH |
21190 | |
21191 | ||
9b371988 | 21192 | .option use_shell pipe boolean false |
f89d2485 | 21193 | .vindex "&$pipe_addresses$&" |
9b371988 | 21194 | If this option is set, it causes the command to be passed to &_/bin/sh_& |
168e428f | 21195 | instead of being run directly from the transport, as described in section |
9b371988 | 21196 | &<<SECThowcommandrun>>&. This is less secure, but is needed in some situations |
168e428f | 21197 | where the command is expected to be run under a shell and cannot easily be |
9b371988 PH |
21198 | modified. The &%allow_commands%& and &%restrict_to_path%& options, and the |
21199 | &`$pipe_addresses`& facility are incompatible with &%use_shell%&. The | |
21200 | command is expanded as a single string, and handed to &_/bin/sh_& as data for | |
21201 | its &%-c%& option. | |
21202 | ||
21203 | ||
21204 | ||
f89d2485 | 21205 | .section "Using an external local delivery agent" "SECID143" |
9b371988 PH |
21206 | .cindex "local delivery" "using an external agent" |
21207 | .cindex "&'procmail'&" | |
21208 | .cindex "external local delivery" | |
21209 | .cindex "delivery" "&'procmail'&" | |
21210 | .cindex "delivery" "by external agent" | |
21211 | The &(pipe)& transport can be used to pass all messages that require local | |
21212 | delivery to a separate local delivery agent such as &%procmail%&. When doing | |
168e428f PH |
21213 | this, care must be taken to ensure that the pipe is run under an appropriate |
21214 | uid and gid. In some configurations one wants this to be a uid that is trusted | |
21215 | by the delivery agent to supply the correct sender of the message. It may be | |
21216 | necessary to recompile or reconfigure the delivery agent so that it trusts an | |
21217 | appropriate user. The following is an example transport and router | |
9b371988 PH |
21218 | configuration for &%procmail%&: |
21219 | .code | |
21220 | # transport | |
21221 | procmail_pipe: | |
21222 | driver = pipe | |
21223 | command = /usr/local/bin/procmail -d $local_part | |
21224 | return_path_add | |
21225 | delivery_date_add | |
21226 | envelope_to_add | |
21227 | check_string = "From " | |
21228 | escape_string = ">From " | |
a2e4e31d | 21229 | umask = 077 |
9b371988 PH |
21230 | user = $local_part |
21231 | group = mail | |
168e428f | 21232 | |
9b371988 PH |
21233 | # router |
21234 | procmail: | |
21235 | driver = accept | |
21236 | check_local_user | |
21237 | transport = procmail_pipe | |
21238 | .endd | |
168e428f | 21239 | In this example, the pipe is run as the local user, but with the group set to |
9b371988 PH |
21240 | &'mail'&. An alternative is to run the pipe as a specific user such as &'mail'& |
21241 | or &'exim'&, but in this case you must arrange for &%procmail%& to trust that | |
21242 | user to supply a correct sender address. If you do not specify either a | |
21243 | &%group%& or a &%user%& option, the pipe command is run as the local user. The | |
21244 | home directory is the user's home directory by default. | |
21245 | ||
21246 | &*Note*&: The command that the pipe transport runs does &'not'& begin with | |
21247 | .code | |
21248 | IFS=" " | |
21249 | .endd | |
21250 | as shown in some &%procmail%& documentation, because Exim does not by default | |
21251 | use a shell to run pipe commands. | |
21252 | ||
21253 | .cindex "Cyrus" | |
168e428f PH |
21254 | The next example shows a transport and a router for a system where local |
21255 | deliveries are handled by the Cyrus IMAP server. | |
9b371988 | 21256 | .code |
168e428f PH |
21257 | # transport |
21258 | local_delivery_cyrus: | |
21259 | driver = pipe | |
21260 | command = /usr/cyrus/bin/deliver \ | |
21261 | -m ${substr_1:$local_part_suffix} -- $local_part | |
21262 | user = cyrus | |
21263 | group = mail | |
21264 | return_output | |
21265 | log_output | |
21266 | message_prefix = | |
21267 | message_suffix = | |
21268 | ||
21269 | # router | |
21270 | local_user_cyrus: | |
21271 | driver = accept | |
21272 | check_local_user | |
21273 | local_part_suffix = .* | |
21274 | transport = local_delivery_cyrus | |
9b371988 PH |
21275 | .endd |
21276 | Note the unsetting of &%message_prefix%& and &%message_suffix%&, and the use of | |
21277 | &%return_output%& to cause any text written by Cyrus to be returned to the | |
168e428f | 21278 | sender. |
4f578862 PH |
21279 | .ecindex IIDpiptra1 |
21280 | .ecindex IIDpiptra2 | |
168e428f PH |
21281 | |
21282 | ||
9b371988 PH |
21283 | . //////////////////////////////////////////////////////////////////////////// |
21284 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 21285 | |
9b371988 | 21286 | .chapter "The smtp transport" "CHAPsmtptrans" |
4f578862 PH |
21287 | .scindex IIDsmttra1 "transports" "&(smtp)&" |
21288 | .scindex IIDsmttra2 "&(smtp)& transport" | |
9b371988 | 21289 | The &(smtp)& transport delivers messages over TCP/IP connections using the SMTP |
168e428f PH |
21290 | or LMTP protocol. The list of hosts to try can either be taken from the address |
21291 | that is being processed (having been set up by the router), or specified | |
21292 | explicitly for the transport. Timeout and retry processing (see chapter | |
9b371988 | 21293 | &<<CHAPretry>>&) is applied to each IP address independently. |
168e428f PH |
21294 | |
21295 | ||
f89d2485 | 21296 | .section "Multiple messages on a single connection" "SECID144" |
168e428f PH |
21297 | The sending of multiple messages over a single TCP/IP connection can arise in |
21298 | two ways: | |
21299 | ||
9b371988 PH |
21300 | .ilist |
21301 | If a message contains more than &%max_rcpt%& (see below) addresses that are | |
168e428f PH |
21302 | routed to the same host, more than one copy of the message has to be sent to |
21303 | that host. In this situation, multiple copies may be sent in a single run of | |
9b371988 PH |
21304 | the &(smtp)& transport over a single TCP/IP connection. (What Exim actually |
21305 | does when it has too many addresses to send in one message also depends on the | |
21306 | value of the global &%remote_max_parallel%& option. Details are given in | |
21307 | section &<<SECToutSMTPTCP>>&.) | |
21308 | .next | |
21309 | .cindex "hints database" "remembering routing" | |
168e428f PH |
21310 | When a message has been successfully delivered over a TCP/IP connection, Exim |
21311 | looks in its hints database to see if there are any other messages awaiting a | |
21312 | connection to the same host. If there are, a new delivery process is started | |
21313 | for one of them, and the current TCP/IP connection is passed on to it. The new | |
21314 | process may in turn send multiple copies and possibly create yet another | |
21315 | process. | |
9b371988 | 21316 | .endlist |
168e428f PH |
21317 | |
21318 | ||
21319 | For each copy sent over the same TCP/IP connection, a sequence counter is | |
9b371988 | 21320 | incremented, and if it ever gets to the value of &%connection_max_messages%&, |
168e428f PH |
21321 | no further messages are sent over that connection. |
21322 | ||
21323 | ||
21324 | ||
595028e4 | 21325 | .section "Use of the $host and $host_address variables" "SECID145" |
f89d2485 PH |
21326 | .vindex "&$host$&" |
21327 | .vindex "&$host_address$&" | |
9b371988 PH |
21328 | At the start of a run of the &(smtp)& transport, the values of &$host$& and |
21329 | &$host_address$& are the name and IP address of the first host on the host list | |
168e428f | 21330 | passed by the router. However, when the transport is about to connect to a |
9b371988 PH |
21331 | specific host, and while it is connected to that host, &$host$& and |
21332 | &$host_address$& are set to the values for that host. These are the values | |
21333 | that are in force when the &%helo_data%&, &%hosts_try_auth%&, &%interface%&, | |
21334 | &%serialize_hosts%&, and the various TLS options are expanded. | |
168e428f PH |
21335 | |
21336 | ||
595028e4 PH |
21337 | .section "Use of $tls_cipher and $tls_peerdn" "usecippeer" |
21338 | .vindex &$tls_cipher$& | |
21339 | .vindex &$tls_peerdn$& | |
21340 | At the start of a run of the &(smtp)& transport, the values of &$tls_cipher$& | |
21341 | and &$tls_peerdn$& are the values that were set when the message was received. | |
21342 | These are the values that are used for options that are expanded before any | |
21343 | SMTP connections are made. Just before each connection is made, these two | |
21344 | variables are emptied. If TLS is subsequently started, they are set to the | |
21345 | appropriate values for the outgoing connection, and these are the values that | |
21346 | are in force when any authenticators are run and when the | |
21347 | &%authenticated_sender%& option is expanded. | |
595028e4 | 21348 | |
168e428f | 21349 | |
f89d2485 | 21350 | .section "Private options for smtp" "SECID146" |
9b371988 PH |
21351 | .cindex "options" "&(smtp)& transport" |
21352 | The private options of the &(smtp)& transport are as follows: | |
168e428f PH |
21353 | |
21354 | ||
3cb1b51e PH |
21355 | .option address_retry_include_sender smtp boolean true |
21356 | .cindex "4&'xx'& responses" "retrying after" | |
21357 | When an address is delayed because of a 4&'xx'& response to a RCPT command, it | |
21358 | is the combination of sender and recipient that is delayed in subsequent queue | |
21359 | runs until the retry time is reached. You can delay the recipient without | |
21360 | reference to the sender (which is what earlier versions of Exim did), by | |
21361 | setting &%address_retry_include_sender%& false. However, this can lead to | |
21362 | problems with servers that regularly issue 4&'xx'& responses to RCPT commands. | |
3cb1b51e | 21363 | |
9b371988 PH |
21364 | .option allow_localhost smtp boolean false |
21365 | .cindex "local host" "sending to" | |
21366 | .cindex "fallback" "hosts specified on transport" | |
21367 | When a host specified in &%hosts%& or &%fallback_hosts%& (see below) turns out | |
21368 | to be the local host, or is listed in &%hosts_treat_as_local%&, delivery is | |
21369 | deferred by default. However, if &%allow_localhost%& is set, Exim goes on to do | |
168e428f PH |
21370 | the delivery anyway. This should be used only in special cases when the |
21371 | configuration ensures that no looping will result (for example, a differently | |
21372 | configured Exim is listening on the port to which the message is sent). | |
21373 | ||
21374 | ||
9b371988 PH |
21375 | .option authenticated_sender smtp string&!! unset |
21376 | .cindex "Cyrus" | |
4f578862 PH |
21377 | When Exim has authenticated as a client, or if &%authenticated_sender_force%& |
21378 | is true, this option sets a value for the AUTH= item on outgoing MAIL commands, | |
21379 | overriding any existing authenticated sender value. If the string expansion is | |
21380 | forced to fail, the option is ignored. Other expansion failures cause delivery | |
21381 | to be deferred. If the result of expansion is an empty string, that is also | |
21382 | ignored. | |
168e428f | 21383 | |
595028e4 PH |
21384 | The expansion happens after the outgoing connection has been made and TLS |
21385 | started, if required. This means that the &$host$&, &$host_address$&, | |
21386 | &$tls_cipher$&, and &$tls_peerdn$& variables are set according to the | |
21387 | particular connection. | |
595028e4 | 21388 | |
168e428f | 21389 | If the SMTP session is not authenticated, the expansion of |
9b371988 | 21390 | &%authenticated_sender%& still happens (and can cause the delivery to be |
4f578862 PH |
21391 | deferred if it fails), but no AUTH= item is added to MAIL commands |
21392 | unless &%authenticated_sender_force%& is true. | |
168e428f | 21393 | |
9b371988 | 21394 | This option allows you to use the &(smtp)& transport in LMTP mode to |
168e428f | 21395 | deliver mail to Cyrus IMAP and provide the proper local part as the |
9b371988 PH |
21396 | &"authenticated sender"&, via a setting such as: |
21397 | .code | |
21398 | authenticated_sender = $local_part | |
21399 | .endd | |
168e428f PH |
21400 | This removes the need for IMAP subfolders to be assigned special ACLs to |
21401 | allow direct delivery to those subfolders. | |
21402 | ||
21403 | Because of expected uses such as that just described for Cyrus (when no | |
21404 | domain is involved), there is no checking on the syntax of the provided | |
21405 | value. | |
21406 | ||
21407 | ||
4f578862 PH |
21408 | .option authenticated_sender_force smtp boolean false |
21409 | If this option is set true, the &%authenticated_sender%& option's value | |
21410 | is used for the AUTH= item on outgoing MAIL commands, even if Exim has not | |
21411 | authenticated as a client. | |
4f578862 PH |
21412 | |
21413 | ||
9b371988 | 21414 | .option command_timeout smtp time 5m |
168e428f PH |
21415 | This sets a timeout for receiving a response to an SMTP command that has been |
21416 | sent out. It is also used when waiting for the initial banner line from the | |
21417 | remote host. Its value must not be zero. | |
21418 | ||
21419 | ||
9b371988 PH |
21420 | .option connect_timeout smtp time 5m |
21421 | This sets a timeout for the &[connect()]& function, which sets up a TCP/IP call | |
168e428f PH |
21422 | to a remote host. A setting of zero allows the system timeout (typically |
21423 | several minutes) to act. To have any effect, the value of this option must be | |
21424 | less than the system timeout. However, it has been observed that on some | |
21425 | systems there is no system timeout, which is why the default value for this | |
21426 | option is 5 minutes, a value recommended by RFC 1123. | |
21427 | ||
21428 | ||
9b371988 PH |
21429 | .option connection_max_messages smtp integer 500 |
21430 | .cindex "SMTP" "passed connection" | |
21431 | .cindex "SMTP" "multiple deliveries" | |
21432 | .cindex "multiple SMTP deliveries" | |
168e428f PH |
21433 | This controls the maximum number of separate message deliveries that are sent |
21434 | over a single TCP/IP connection. If the value is zero, there is no limit. | |
9b371988 | 21435 | For testing purposes, this value can be overridden by the &%-oB%& command line |
168e428f PH |
21436 | option. |
21437 | ||
21438 | ||
9b371988 | 21439 | .option data_timeout smtp time 5m |
168e428f PH |
21440 | This sets a timeout for the transmission of each block in the data portion of |
21441 | the message. As a result, the overall timeout for a message depends on the size | |
9b371988 | 21442 | of the message. Its value must not be zero. See also &%final_timeout%&. |
168e428f PH |
21443 | |
21444 | ||
9b371988 | 21445 | .option delay_after_cutoff smtp boolean true |
168e428f PH |
21446 | This option controls what happens when all remote IP addresses for a given |
21447 | domain have been inaccessible for so long that they have passed their retry | |
21448 | cutoff times. | |
21449 | ||
21450 | In the default state, if the next retry time has not been reached for any of | |
21451 | them, the address is bounced without trying any deliveries. In other words, | |
21452 | Exim delays retrying an IP address after the final cutoff time until a new | |
21453 | retry time is reached, and can therefore bounce an address without ever trying | |
21454 | a delivery, when machines have been down for a long time. Some people are | |
21455 | unhappy at this prospect, so... | |
21456 | ||
9b371988 | 21457 | If &%delay_after_cutoff%& is set false, Exim behaves differently. If all IP |
168e428f PH |
21458 | addresses are past their final cutoff time, Exim tries to deliver to those |
21459 | IP addresses that have not been tried since the message arrived. If there are | |
21460 | none, of if they all fail, the address is bounced. In other words, it does not | |
21461 | delay when a new message arrives, but immediately tries those expired IP | |
21462 | addresses that haven't been tried since the message arrived. If there is a | |
21463 | continuous stream of messages for the dead hosts, unsetting | |
9b371988 | 21464 | &%delay_after_cutoff%& means that there will be many more attempts to deliver |
168e428f PH |
21465 | to them. |
21466 | ||
21467 | ||
9b371988 PH |
21468 | .option dns_qualify_single smtp boolean true |
21469 | If the &%hosts%& or &%fallback_hosts%& option is being used, | |
21470 | and the &%gethostbyname%& option is false, | |
21471 | the RES_DEFNAMES resolver option is set. See the &%qualify_single%& option | |
21472 | in chapter &<<CHAPdnslookup>>& for more details. | |
168e428f | 21473 | |
168e428f | 21474 | |
9b371988 | 21475 | .option dns_search_parents smtp boolean false |
9b371988 PH |
21476 | If the &%hosts%& or &%fallback_hosts%& option is being used, and the |
21477 | &%gethostbyname%& option is false, the RES_DNSRCH resolver option is set. | |
21478 | See the &%search_parents%& option in chapter &<<CHAPdnslookup>>& for more | |
21479 | details. | |
168e428f PH |
21480 | |
21481 | ||
168e428f | 21482 | |
9b371988 | 21483 | .option fallback_hosts smtp "string list" unset |
9b371988 | 21484 | .cindex "fallback" "hosts specified on transport" |
168e428f | 21485 | String expansion is not applied to this option. The argument must be a |
068aaea8 PH |
21486 | colon-separated list of host names or IP addresses, optionally also including |
21487 | port numbers, though the separator can be changed, as described in section | |
9b371988 PH |
21488 | &<<SECTlistconstruct>>&. Each individual item in the list is the same as an |
21489 | item in a &%route_list%& setting for the &(manualroute)& router, as described | |
21490 | in section &<<SECTformatonehostitem>>&. | |
068aaea8 PH |
21491 | |
21492 | Fallback hosts can also be specified on routers, which associate them with the | |
9b371988 PH |
21493 | addresses they process. As for the &%hosts%& option without &%hosts_override%&, |
21494 | &%fallback_hosts%& specified on the transport is used only if the address does | |
21495 | not have its own associated fallback host list. Unlike &%hosts%&, a setting of | |
21496 | &%fallback_hosts%& on an address is not overridden by &%hosts_override%&. | |
21497 | However, &%hosts_randomize%& does apply to fallback host lists. | |
168e428f PH |
21498 | |
21499 | If Exim is unable to deliver to any of the hosts for a particular address, and | |
21500 | the errors are not permanent rejections, the address is put on a separate | |
21501 | transport queue with its host list replaced by the fallback hosts, unless the | |
21502 | address was routed via MX records and the current host was in the original MX | |
21503 | list. In that situation, the fallback host list is not used. | |
21504 | ||
21505 | Once normal deliveries are complete, the fallback queue is delivered by | |
21506 | re-running the same transports with the new host lists. If several failing | |
9b371988 | 21507 | addresses have the same fallback hosts (and &%max_rcpt%& permits it), a single |
168e428f PH |
21508 | copy of the message is sent. |
21509 | ||
21510 | The resolution of the host names on the fallback list is controlled by the | |
9b371988 | 21511 | &%gethostbyname%& option, as for the &%hosts%& option. Fallback hosts apply |
168e428f | 21512 | both to cases when the host list comes with the address and when it is taken |
9b371988 PH |
21513 | from &%hosts%&. This option provides a &"use a smart host only if delivery |
21514 | fails"& facility. | |
168e428f PH |
21515 | |
21516 | ||
9b371988 | 21517 | .option final_timeout smtp time 10m |
168e428f | 21518 | This is the timeout that applies while waiting for the response to the final |
9b371988 PH |
21519 | line containing just &"."& that terminates a message. Its value must not be |
21520 | zero. | |
168e428f | 21521 | |
9b371988 PH |
21522 | .option gethostbyname smtp boolean false |
21523 | If this option is true when the &%hosts%& and/or &%fallback_hosts%& options are | |
21524 | being used, names are looked up using &[gethostbyname()]& | |
21525 | (or &[getipnodebyname()]& when available) | |
168e428f | 21526 | instead of using the DNS. Of course, that function may in fact use the DNS, but |
9b371988 PH |
21527 | it may also consult other sources of information such as &_/etc/hosts_&. |
21528 | ||
f013fb92 | 21529 | .option gnutls_require_kx smtp string unset |
f89d2485 PH |
21530 | This option controls the key exchange mechanisms when GnuTLS is used in an Exim |
21531 | client. For details, see section &<<SECTreqciphgnu>>&. | |
21532 | ||
f013fb92 | 21533 | .option gnutls_require_mac smtp string unset |
f89d2485 PH |
21534 | This option controls the MAC algorithms when GnuTLS is used in an Exim |
21535 | client. For details, see section &<<SECTreqciphgnu>>&. | |
21536 | ||
f013fb92 | 21537 | .option gnutls_require_protocols smtp string unset |
f89d2485 PH |
21538 | This option controls the protocols when GnuTLS is used in an Exim |
21539 | client. For details, see section &<<SECTreqciphgnu>>&. | |
f89d2485 | 21540 | |
f013fb92 | 21541 | .option gnutls_compat_mode smtp boolean unset |
e6060e2c NM |
21542 | This option controls whether GnuTLS is used in compatibility mode in an Exim |
21543 | server. This reduces security slightly, but improves interworking with older | |
21544 | implementations of TLS. | |
21545 | ||
f89d2485 PH |
21546 | .option helo_data smtp string&!! "see below" |
21547 | .cindex "HELO" "argument, setting" | |
21548 | .cindex "EHLO" "argument, setting" | |
21549 | .cindex "LHLO argument setting" | |
21550 | The value of this option is expanded after a connection to a another host has | |
21551 | been set up. The result is used as the argument for the EHLO, HELO, or LHLO | |
21552 | command that starts the outgoing SMTP or LMTP session. The default value of the | |
21553 | option is: | |
21554 | .code | |
21555 | $primary_hostname | |
21556 | .endd | |
21557 | During the expansion, the variables &$host$& and &$host_address$& are set to | |
21558 | the identity of the remote host, and the variables &$sending_ip_address$& and | |
21559 | &$sending_port$& are set to the local IP address and port number that are being | |
595028e4 PH |
21560 | used. These variables can be used to generate different values for different |
21561 | servers or different local IP addresses. For example, if you want the string | |
21562 | that is used for &%helo_data%& to be obtained by a DNS lookup of the outgoing | |
21563 | interface address, you could use this: | |
f89d2485 PH |
21564 | .code |
21565 | helo_data = ${lookup dnsdb{ptr=$sending_ip_address}{$value}\ | |
21566 | {$primary_hostname}} | |
21567 | .endd | |
21568 | The use of &%helo_data%& applies both to sending messages and when doing | |
21569 | callouts. | |
9b371988 PH |
21570 | |
21571 | .option hosts smtp "string list&!!" unset | |
21572 | Hosts are associated with an address by a router such as &(dnslookup)&, which | |
068aaea8 | 21573 | finds the hosts by looking up the address domain in the DNS, or by |
9b371988 PH |
21574 | &(manualroute)&, which has lists of hosts in its configuration. However, |
21575 | email addresses can be passed to the &(smtp)& transport by any router, and not | |
068aaea8 PH |
21576 | all of them can provide an associated list of hosts. |
21577 | ||
9b371988 | 21578 | The &%hosts%& option specifies a list of hosts to be used if the address being |
068aaea8 | 21579 | processed does not have any hosts associated with it. The hosts specified by |
9b371988 PH |
21580 | &%hosts%& are also used, whether or not the address has its own hosts, if |
21581 | &%hosts_override%& is set. | |
168e428f PH |
21582 | |
21583 | The string is first expanded, before being interpreted as a colon-separated | |
068aaea8 PH |
21584 | list of host names or IP addresses, possibly including port numbers. The |
21585 | separator may be changed to something other than colon, as described in section | |
9b371988 PH |
21586 | &<<SECTlistconstruct>>&. Each individual item in the list is the same as an |
21587 | item in a &%route_list%& setting for the &(manualroute)& router, as described | |
21588 | in section &<<SECTformatonehostitem>>&. However, note that the &`/MX`& facility | |
21589 | of the &(manualroute)& router is not available here. | |
068aaea8 PH |
21590 | |
21591 | If the expansion fails, delivery is deferred. Unless the failure was caused by | |
21592 | the inability to complete a lookup, the error is logged to the panic log as | |
21593 | well as the main log. Host names are looked up either by searching directly for | |
9b371988 PH |
21594 | address records in the DNS or by calling &[gethostbyname()]& (or |
21595 | &[getipnodebyname()]& when available), depending on the setting of the | |
21596 | &%gethostbyname%& option. When Exim is compiled with IPv6 support, if a host | |
21597 | that is looked up in the DNS has both IPv4 and IPv6 addresses, both types of | |
21598 | address are used. | |
168e428f PH |
21599 | |
21600 | During delivery, the hosts are tried in order, subject to their retry status, | |
9b371988 | 21601 | unless &%hosts_randomize%& is set. |
168e428f | 21602 | |
168e428f | 21603 | |
9b371988 | 21604 | .option hosts_avoid_esmtp smtp "host list&!!" unset |
f89d2485 | 21605 | .cindex "ESMTP, avoiding use of" |
9b371988 PH |
21606 | .cindex "HELO" "forcing use of" |
21607 | .cindex "EHLO" "avoiding use of" | |
21608 | .cindex "PIPELINING" "avoiding the use of" | |
168e428f PH |
21609 | This option is for use with broken hosts that announce ESMTP facilities (for |
21610 | example, PIPELINING) and then fail to implement them properly. When a host | |
9b371988 | 21611 | matches &%hosts_avoid_esmtp%&, Exim sends HELO rather than EHLO at the |
168e428f PH |
21612 | start of the SMTP session. This means that it cannot use any of the ESMTP |
21613 | facilities such as AUTH, PIPELINING, SIZE, and STARTTLS. | |
21614 | ||
21615 | ||
f89d2485 PH |
21616 | .option hosts_avoid_pipelining smtp "host list&!!" unset |
21617 | .cindex "PIPELINING" "avoiding the use of" | |
21618 | Exim will not use the SMTP PIPELINING extension when delivering to any host | |
21619 | that matches this list, even if the server host advertises PIPELINING support. | |
f89d2485 PH |
21620 | |
21621 | ||
9b371988 PH |
21622 | .option hosts_avoid_tls smtp "host list&!!" unset |
21623 | .cindex "TLS" "avoiding for certain hosts" | |
168e428f | 21624 | Exim will not try to start a TLS session when delivering to any host that |
9b371988 | 21625 | matches this list. See chapter &<<CHAPTLS>>& for details of TLS. |
168e428f | 21626 | |
168e428f | 21627 | |
9b371988 PH |
21628 | .option hosts_max_try smtp integer 5 |
21629 | .cindex "host" "maximum number to try" | |
21630 | .cindex "limit" "number of hosts tried" | |
21631 | .cindex "limit" "number of MX tried" | |
21632 | .cindex "MX record" "maximum tried" | |
168e428f PH |
21633 | This option limits the number of IP addresses that are tried for any one |
21634 | delivery in cases where there are temporary delivery errors. Section | |
9b371988 | 21635 | &<<SECTvalhosmax>>& describes in detail how the value of this option is used. |
168e428f PH |
21636 | |
21637 | ||
9b371988 | 21638 | .option hosts_max_try_hardlimit smtp integer 50 |
168e428f | 21639 | This is an additional check on the maximum number of IP addresses that Exim |
9b371988 PH |
21640 | tries for any one delivery. Section &<<SECTvalhosmax>>& describes its use and |
21641 | why it exists. | |
168e428f PH |
21642 | |
21643 | ||
168e428f | 21644 | |
9b371988 PH |
21645 | .option hosts_nopass_tls smtp "host list&!!" unset |
21646 | .cindex "TLS" "passing connection" | |
21647 | .cindex "multiple SMTP deliveries" | |
21648 | .cindex "TLS" "multiple message deliveries" | |
168e428f PH |
21649 | For any host that matches this list, a connection on which a TLS session has |
21650 | been started will not be passed to a new delivery process for sending another | |
9b371988 PH |
21651 | message on the same connection. See section &<<SECTmulmessam>>& for an |
21652 | explanation of when this might be needed. | |
168e428f PH |
21653 | |
21654 | ||
9b371988 PH |
21655 | .option hosts_override smtp boolean false |
21656 | If this option is set and the &%hosts%& option is also set, any hosts that are | |
168e428f | 21657 | attached to the address are ignored, and instead the hosts specified by the |
9b371988 PH |
21658 | &%hosts%& option are always used. This option does not apply to |
21659 | &%fallback_hosts%&. | |
168e428f | 21660 | |
168e428f | 21661 | |
9b371988 PH |
21662 | .option hosts_randomize smtp boolean false |
21663 | .cindex "randomized host list" | |
21664 | .cindex "host" "list of; randomized" | |
21665 | .cindex "fallback" "randomized hosts" | |
168e428f | 21666 | If this option is set, and either the list of hosts is taken from the |
9b371988 | 21667 | &%hosts%& or the &%fallback_hosts%& option, or the hosts supplied by the router |
168e428f | 21668 | were not obtained from MX records (this includes fallback hosts from the |
f89d2485 | 21669 | router), and were not randomized by the router, the order of trying the hosts |
168e428f PH |
21670 | is randomized each time the transport runs. Randomizing the order of a host |
21671 | list can be used to do crude load sharing. | |
21672 | ||
9b371988 | 21673 | When &%hosts_randomize%& is true, a host list may be split into groups whose |
168e428f PH |
21674 | order is separately randomized. This makes it possible to set up MX-like |
21675 | behaviour. The boundaries between groups are indicated by an item that is just | |
9b371988 PH |
21676 | &`+`& in the host list. For example: |
21677 | .code | |
21678 | hosts = host1:host2:host3:+:host4:host5 | |
21679 | .endd | |
168e428f PH |
21680 | The order of the first three hosts and the order of the last two hosts is |
21681 | randomized for each use, but the first three always end up before the last two. | |
9b371988 | 21682 | If &%hosts_randomize%& is not set, a &`+`& item in the list is ignored. |
168e428f | 21683 | |
9b371988 PH |
21684 | .option hosts_require_auth smtp "host list&!!" unset |
21685 | .cindex "authentication" "required by client" | |
168e428f PH |
21686 | This option provides a list of servers for which authentication must succeed |
21687 | before Exim will try to transfer a message. If authentication fails for | |
21688 | servers which are not in this list, Exim tries to send unauthenticated. If | |
21689 | authentication fails for one of these servers, delivery is deferred. This | |
21690 | temporary error is detectable in the retry rules, so it can be turned into a | |
9b371988 PH |
21691 | hard failure if required. See also &%hosts_try_auth%&, and chapter |
21692 | &<<CHAPSMTPAUTH>>& for details of authentication. | |
168e428f | 21693 | |
168e428f | 21694 | |
9b371988 PH |
21695 | .option hosts_require_tls smtp "host list&!!" unset |
21696 | .cindex "TLS" "requiring for certain servers" | |
168e428f | 21697 | Exim will insist on using a TLS session when delivering to any host that |
9b371988 PH |
21698 | matches this list. See chapter &<<CHAPTLS>>& for details of TLS. |
21699 | &*Note*&: This option affects outgoing mail only. To insist on TLS for | |
168e428f PH |
21700 | incoming messages, use an appropriate ACL. |
21701 | ||
9b371988 PH |
21702 | .option hosts_try_auth smtp "host list&!!" unset |
21703 | .cindex "authentication" "optional in client" | |
168e428f PH |
21704 | This option provides a list of servers to which, provided they announce |
21705 | authentication support, Exim will attempt to authenticate as a client when it | |
21706 | connects. If authentication fails, Exim will try to transfer the message | |
9b371988 PH |
21707 | unauthenticated. See also &%hosts_require_auth%&, and chapter |
21708 | &<<CHAPSMTPAUTH>>& for details of authentication. | |
21709 | ||
21710 | .option interface smtp "string list&!!" unset | |
21711 | .cindex "bind IP address" | |
21712 | .cindex "IP address" "binding" | |
f89d2485 PH |
21713 | .vindex "&$host$&" |
21714 | .vindex "&$host_address$&" | |
168e428f | 21715 | This option specifies which interface to bind to when making an outgoing SMTP |
7d0ab55c TF |
21716 | call. The value is an IP address, not an interface name such as |
21717 | &`eth0`&. Do not confuse this with the interface address that was used when a | |
595028e4 PH |
21718 | message was received, which is in &$received_ip_address$&, formerly known as |
21719 | &$interface_address$&. The name was changed to minimize confusion with the | |
21720 | outgoing interface address. There is no variable that contains an outgoing | |
3cb1b51e PH |
21721 | interface address because, unless it is set by this option, its value is |
21722 | unknown. | |
3cb1b51e PH |
21723 | |
21724 | During the expansion of the &%interface%& option the variables &$host$& and | |
21725 | &$host_address$& refer to the host to which a connection is about to be made | |
21726 | during the expansion of the string. Forced expansion failure, or an empty | |
21727 | string result causes the option to be ignored. Otherwise, after expansion, the | |
21728 | string must be a list of IP addresses, colon-separated by default, but the | |
21729 | separator can be changed in the usual way. For example: | |
9b371988 PH |
21730 | .code |
21731 | interface = <; 192.168.123.123 ; 3ffe:ffff:836f::fe86:a061 | |
21732 | .endd | |
168e428f PH |
21733 | The first interface of the correct type (IPv4 or IPv6) is used for the outgoing |
21734 | connection. If none of them are the correct type, the option is ignored. If | |
9b371988 | 21735 | &%interface%& is not set, or is ignored, the system's IP functions choose which |
168e428f PH |
21736 | interface to use if the host has more than one. |
21737 | ||
21738 | ||
9b371988 PH |
21739 | .option keepalive smtp boolean true |
21740 | .cindex "keepalive" "on outgoing connection" | |
168e428f PH |
21741 | This option controls the setting of SO_KEEPALIVE on outgoing TCP/IP socket |
21742 | connections. When set, it causes the kernel to probe idle connections | |
9b371988 | 21743 | periodically, by sending packets with &"old"& sequence numbers. The other end |
f89d2485 | 21744 | of the connection should send a acknowledgment if the connection is still okay |
9b371988 PH |
21745 | or a reset if the connection has been aborted. The reason for doing this is |
21746 | that it has the beneficial effect of freeing up certain types of connection | |
21747 | that can get stuck when the remote host is disconnected without tidying up the | |
21748 | TCP/IP call properly. The keepalive mechanism takes several hours to detect | |
168e428f PH |
21749 | unreachable hosts. |
21750 | ||
21751 | ||
9b371988 PH |
21752 | .option lmtp_ignore_quota smtp boolean false |
21753 | .cindex "LMTP" "ignoring quota errors" | |
21754 | If this option is set true when the &%protocol%& option is set to &"lmtp"&, the | |
21755 | string &`IGNOREQUOTA`& is added to RCPT commands, provided that the LMTP server | |
068aaea8 PH |
21756 | has advertised support for IGNOREQUOTA in its response to the LHLO command. |
21757 | ||
9b371988 PH |
21758 | .option max_rcpt smtp integer 100 |
21759 | .cindex "RCPT" "maximum number of outgoing" | |
168e428f PH |
21760 | This option limits the number of RCPT commands that are sent in a single |
21761 | SMTP message transaction. Each set of addresses is treated independently, and | |
9b371988 | 21762 | so can cause parallel connections to the same host if &%remote_max_parallel%& |
168e428f PH |
21763 | permits this. |
21764 | ||
21765 | ||
9b371988 | 21766 | .option multi_domain smtp boolean true |
f89d2485 | 21767 | .vindex "&$domain$&" |
9b371988 PH |
21768 | When this option is set, the &(smtp)& transport can handle a number of |
21769 | addresses containing a mixture of different domains provided they all resolve | |
21770 | to the same list of hosts. Turning the option off restricts the transport to | |
21771 | handling only one domain at a time. This is useful if you want to use | |
21772 | &$domain$& in an expansion for the transport, because it is set only when there | |
21773 | is a single domain involved in a remote delivery. | |
168e428f PH |
21774 | |
21775 | ||
9b371988 PH |
21776 | .option port smtp string&!! "see below" |
21777 | .cindex "port" "sending TCP/IP" | |
21778 | .cindex "TCP/IP" "setting outgoing port" | |
3cb1b51e PH |
21779 | This option specifies the TCP/IP port on the server to which Exim connects. |
21780 | &*Note:*& Do not confuse this with the port that was used when a message was | |
21781 | received, which is in &$received_port$&, formerly known as &$interface_port$&. | |
21782 | The name was changed to minimize confusion with the outgoing port. There is no | |
21783 | variable that contains an outgoing port. | |
3cb1b51e PH |
21784 | |
21785 | If the value of this option begins with a digit it is taken as a port number; | |
21786 | otherwise it is looked up using &[getservbyname()]&. The default value is | |
21787 | normally &"smtp"&, but if &%protocol%& is set to &"lmtp"&, the default is | |
21788 | &"lmtp"&. If the expansion fails, or if a port number cannot be found, delivery | |
21789 | is deferred. | |
168e428f PH |
21790 | |
21791 | ||
21792 | ||
9b371988 PH |
21793 | .option protocol smtp string smtp |
21794 | .cindex "LMTP" "over TCP/IP" | |
21795 | If this option is set to &"lmtp"& instead of &"smtp"&, the default value for | |
21796 | the &%port%& option changes to &"lmtp"&, and the transport operates the LMTP | |
21797 | protocol (RFC 2033) instead of SMTP. This protocol is sometimes used for local | |
168e428f | 21798 | deliveries into closed message stores. Exim also has support for running LMTP |
9b371988 | 21799 | over a pipe to a local process &-- see chapter &<<CHAPLMTP>>&. |
168e428f PH |
21800 | |
21801 | ||
9b371988 | 21802 | .option retry_include_ip_address smtp boolean true |
168e428f PH |
21803 | Exim normally includes both the host name and the IP address in the key it |
21804 | constructs for indexing retry data after a temporary delivery failure. This | |
21805 | means that when one of several IP addresses for a host is failing, it gets | |
21806 | tried periodically (controlled by the retry rules), but use of the other IP | |
21807 | addresses is not affected. | |
21808 | ||
21809 | However, in some dialup environments hosts are assigned a different IP address | |
21810 | each time they connect. In this situation the use of the IP address as part of | |
21811 | the retry key leads to undesirable behaviour. Setting this option false causes | |
21812 | Exim to use only the host name. This should normally be done on a separate | |
9b371988 PH |
21813 | instance of the &(smtp)& transport, set up specially to handle the dialup |
21814 | hosts. | |
168e428f | 21815 | |
168e428f | 21816 | |
9b371988 PH |
21817 | .option serialize_hosts smtp "host list&!!" unset |
21818 | .cindex "serializing connections" | |
21819 | .cindex "host" "serializing connections" | |
168e428f PH |
21820 | Because Exim operates in a distributed manner, if several messages for the same |
21821 | host arrive at around the same time, more than one simultaneous connection to | |
21822 | the remote host can occur. This is not usually a problem except when there is a | |
21823 | slow link between the hosts. In that situation it may be helpful to restrict | |
21824 | Exim to one connection at a time. This can be done by setting | |
9b371988 | 21825 | &%serialize_hosts%& to match the relevant hosts. |
168e428f | 21826 | |
9b371988 | 21827 | .cindex "hints database" "serializing deliveries to a host" |
168e428f PH |
21828 | Exim implements serialization by means of a hints database in which a record is |
21829 | written whenever a process connects to one of the restricted hosts. The record | |
21830 | is deleted when the connection is completed. Obviously there is scope for | |
21831 | records to get left lying around if there is a system or program crash. To | |
21832 | guard against this, Exim ignores any records that are more than six hours old. | |
21833 | ||
21834 | If you set up this kind of serialization, you should also arrange to delete the | |
21835 | relevant hints database whenever your system reboots. The names of the files | |
9b371988 | 21836 | start with &_misc_& and they are kept in the &_spool/db_& directory. There |
168e428f PH |
21837 | may be one or two files, depending on the type of DBM in use. The same files |
21838 | are used for ETRN serialization. | |
21839 | ||
21840 | ||
9b371988 PH |
21841 | .option size_addition smtp integer 1024 |
21842 | .cindex "SMTP" "SIZE" | |
21843 | .cindex "message" "size issue for transport filter" | |
21844 | .cindex "size" "of message" | |
21845 | .cindex "transport" "filter" | |
21846 | .cindex "filter" "transport filter" | |
168e428f PH |
21847 | If a remote SMTP server indicates that it supports the SIZE option of the |
21848 | MAIL command, Exim uses this to pass over the message size at the start of | |
9b371988 | 21849 | an SMTP transaction. It adds the value of &%size_addition%& to the value it |
168e428f PH |
21850 | sends, to allow for headers and other text that may be added during delivery by |
21851 | configuration options or in a transport filter. It may be necessary to increase | |
21852 | this if a lot of text is added to messages. | |
21853 | ||
9b371988 | 21854 | Alternatively, if the value of &%size_addition%& is set negative, it disables |
168e428f PH |
21855 | the use of the SIZE option altogether. |
21856 | ||
21857 | ||
9b371988 | 21858 | .option tls_certificate smtp string&!! unset |
f89d2485 PH |
21859 | .cindex "TLS" "client certificate, location of" |
21860 | .cindex "certificate" "client, location of" | |
21861 | .vindex "&$host$&" | |
21862 | .vindex "&$host_address$&" | |
168e428f | 21863 | The value of this option must be the absolute path to a file which contains the |
9b371988 PH |
21864 | client's certificate, for possible use when sending a message over an encrypted |
21865 | connection. The values of &$host$& and &$host_address$& are set to the name and | |
21866 | address of the server during the expansion. See chapter &<<CHAPTLS>>& for | |
168e428f PH |
21867 | details of TLS. |
21868 | ||
9b371988 PH |
21869 | &*Note*&: This option must be set if you want Exim to be able to use a TLS |
21870 | certificate when sending messages as a client. The global option of the same | |
21871 | name specifies the certificate for Exim as a server; it is not automatically | |
21872 | assumed that the same certificate should be used when Exim is operating as a | |
21873 | client. | |
168e428f PH |
21874 | |
21875 | ||
9b371988 PH |
21876 | .option tls_crl smtp string&!! unset |
21877 | .cindex "TLS" "client certificate revocation list" | |
21878 | .cindex "certificate" "revocation list for client" | |
168e428f PH |
21879 | This option specifies a certificate revocation list. The expanded value must |
21880 | be the name of a file that contains a CRL in PEM format. | |
21881 | ||
21882 | ||
9b371988 | 21883 | .option tls_privatekey smtp string&!! unset |
f89d2485 PH |
21884 | .cindex "TLS" "client private key, location of" |
21885 | .vindex "&$host$&" | |
21886 | .vindex "&$host_address$&" | |
168e428f | 21887 | The value of this option must be the absolute path to a file which contains the |
9b371988 PH |
21888 | client's private key. This is used when sending a message over an encrypted |
21889 | connection using a client certificate. The values of &$host$& and | |
21890 | &$host_address$& are set to the name and address of the server during the | |
4f578862 PH |
21891 | expansion. If this option is unset, or the expansion is forced to fail, or the |
21892 | result is an empty string, the private key is assumed to be in the same file as | |
21893 | the certificate. See chapter &<<CHAPTLS>>& for details of TLS. | |
9b371988 PH |
21894 | |
21895 | ||
21896 | .option tls_require_ciphers smtp string&!! unset | |
21897 | .cindex "TLS" "requiring specific ciphers" | |
21898 | .cindex "cipher" "requiring specific" | |
f89d2485 PH |
21899 | .vindex "&$host$&" |
21900 | .vindex "&$host_address$&" | |
168e428f PH |
21901 | The value of this option must be a list of permitted cipher suites, for use |
21902 | when setting up an outgoing encrypted connection. (There is a global option of | |
9b371988 PH |
21903 | the same name for controlling incoming connections.) The values of &$host$& and |
21904 | &$host_address$& are set to the name and address of the server during the | |
21905 | expansion. See chapter &<<CHAPTLS>>& for details of TLS; note that this option | |
21906 | is used in different ways by OpenSSL and GnuTLS (see sections | |
21907 | &<<SECTreqciphssl>>& and &<<SECTreqciphgnu>>&). For GnuTLS, the order of the | |
21908 | ciphers is a preference order. | |
168e428f PH |
21909 | |
21910 | ||
21911 | ||
9b371988 | 21912 | .option tls_tempfail_tryclear smtp boolean true |
3cb1b51e | 21913 | .cindex "4&'xx'& responses" "to STARTTLS" |
9b371988 | 21914 | When the server host is not in &%hosts_require_tls%&, and there is a problem in |
168e428f PH |
21915 | setting up a TLS session, this option determines whether or not Exim should try |
21916 | to deliver the message unencrypted. If it is set false, delivery to the | |
21917 | current host is deferred; if there are other hosts, they are tried. If this | |
9b371988 | 21918 | option is set true, Exim attempts to deliver unencrypted after a 4&'xx'& |
168e428f PH |
21919 | response to STARTTLS. Also, if STARTTLS is accepted, but the subsequent |
21920 | TLS negotiation fails, Exim closes the current connection (because it is in an | |
21921 | unknown state), opens a new one to the same host, and then tries the delivery | |
21922 | in clear. | |
21923 | ||
21924 | ||
9b371988 PH |
21925 | .option tls_verify_certificates smtp string&!! unset |
21926 | .cindex "TLS" "server certificate verification" | |
21927 | .cindex "certificate" "verification of server" | |
f89d2485 PH |
21928 | .vindex "&$host$&" |
21929 | .vindex "&$host_address$&" | |
168e428f PH |
21930 | The value of this option must be the absolute path to a file containing |
21931 | permitted server certificates, for use when setting up an encrypted connection. | |
21932 | Alternatively, if you are using OpenSSL, you can set | |
9b371988 | 21933 | &%tls_verify_certificates%& to the name of a directory containing certificate |
168e428f | 21934 | files. This does not work with GnuTLS; the option must be set to the name of a |
9b371988 PH |
21935 | single file if you are using GnuTLS. The values of &$host$& and |
21936 | &$host_address$& are set to the name and address of the server during the | |
21937 | expansion of this option. See chapter &<<CHAPTLS>>& for details of TLS. | |
168e428f PH |
21938 | |
21939 | ||
21940 | ||
21941 | ||
9b371988 PH |
21942 | .section "How the limits for the number of hosts to try are used" &&& |
21943 | "SECTvalhosmax" | |
21944 | .cindex "host" "maximum number to try" | |
21945 | .cindex "limit" "hosts; maximum number tried" | |
168e428f | 21946 | There are two options that are concerned with the number of hosts that are |
9b371988 PH |
21947 | tried when an SMTP delivery takes place. They are &%hosts_max_try%& and |
21948 | &%hosts_max_try_hardlimit%&. | |
168e428f PH |
21949 | |
21950 | ||
9b371988 PH |
21951 | The &%hosts_max_try%& option limits the number of hosts that are tried |
21952 | for a single delivery. However, despite the term &"host"& in its name, the | |
21953 | option actually applies to each IP address independently. In other words, a | |
21954 | multihomed host is treated as several independent hosts, just as it is for | |
21955 | retrying. | |
168e428f PH |
21956 | |
21957 | Many of the larger ISPs have multiple MX records which often point to | |
21958 | multihomed hosts. As a result, a list of a dozen or more IP addresses may be | |
21959 | created as a result of routing one of these domains. | |
21960 | ||
21961 | Trying every single IP address on such a long list does not seem sensible; if | |
21962 | several at the top of the list fail, it is reasonable to assume there is some | |
21963 | problem that is likely to affect all of them. Roughly speaking, the value of | |
9b371988 | 21964 | &%hosts_max_try%& is the maximum number that are tried before deferring the |
168e428f PH |
21965 | delivery. However, the logic cannot be quite that simple. |
21966 | ||
21967 | Firstly, IP addresses that are skipped because their retry times have not | |
21968 | arrived do not count, and in addition, addresses that are past their retry | |
21969 | limits are also not counted, even when they are tried. This means that when | |
21970 | some IP addresses are past their retry limits, more than the value of | |
9b371988 | 21971 | &%hosts_max_retry%& may be tried. The reason for this behaviour is to ensure |
168e428f PH |
21972 | that all IP addresses are considered before timing out an email address (but |
21973 | see below for an exception). | |
21974 | ||
9b371988 | 21975 | Secondly, when the &%hosts_max_try%& limit is reached, Exim looks down the host |
168e428f PH |
21976 | list to see if there is a subsequent host with a different (higher valued) MX. |
21977 | If there is, that host is considered next, and the current IP address is used | |
21978 | but not counted. This behaviour helps in the case of a domain with a retry rule | |
21979 | that hardly ever delays any hosts, as is now explained: | |
21980 | ||
21981 | Consider the case of a long list of hosts with one MX value, and a few with a | |
9b371988 | 21982 | higher MX value. If &%hosts_max_try%& is small (the default is 5) only a few |
168e428f PH |
21983 | hosts at the top of the list are tried at first. With the default retry rule, |
21984 | which specifies increasing retry times, the higher MX hosts are eventually | |
21985 | tried when those at the top of the list are skipped because they have not | |
21986 | reached their retry times. | |
21987 | ||
21988 | However, it is common practice to put a fixed short retry time on domains for | |
21989 | large ISPs, on the grounds that their servers are rarely down for very long. | |
21990 | Unfortunately, these are exactly the domains that tend to resolve to long lists | |
21991 | of hosts. The short retry time means that the lowest MX hosts are tried every | |
21992 | time. The attempts may be in a different order because of random sorting, but | |
9b371988 PH |
21993 | without the special MX check, the higher MX hosts would never be tried until |
21994 | all the lower MX hosts had timed out (which might be several days), because | |
21995 | there are always some lower MX hosts that have reached their retry times. With | |
21996 | the special check, Exim considers at least one IP address from each MX value at | |
21997 | every delivery attempt, even if the &%hosts_max_try%& limit has already been | |
21998 | reached. | |
21999 | ||
22000 | The above logic means that &%hosts_max_try%& is not a hard limit, and in | |
168e428f | 22001 | particular, Exim normally eventually tries all the IP addresses before timing |
9b371988 | 22002 | out an email address. When &%hosts_max_try%& was implemented, this seemed a |
168e428f PH |
22003 | reasonable thing to do. Recently, however, some lunatic DNS configurations have |
22004 | been set up with hundreds of IP addresses for some domains. It can | |
22005 | take a very long time indeed for an address to time out in these cases. | |
22006 | ||
9b371988 | 22007 | The &%hosts_max_try_hardlimit%& option was added to help with this problem. |
168e428f PH |
22008 | Exim never tries more than this number of IP addresses; if it hits this limit |
22009 | and they are all timed out, the email address is bounced, even though not all | |
22010 | possible IP addresses have been tried. | |
4f578862 PH |
22011 | .ecindex IIDsmttra1 |
22012 | .ecindex IIDsmttra2 | |
168e428f PH |
22013 | |
22014 | ||
22015 | ||
22016 | ||
22017 | ||
9b371988 PH |
22018 | . //////////////////////////////////////////////////////////////////////////// |
22019 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 22020 | |
9b371988 | 22021 | .chapter "Address rewriting" "CHAPrewrite" |
4f578862 | 22022 | .scindex IIDaddrew "rewriting" "addresses" |
168e428f PH |
22023 | There are some circumstances in which Exim automatically rewrites domains in |
22024 | addresses. The two most common are when an address is given without a domain | |
9b371988 | 22025 | (referred to as an &"unqualified address"&) or when an address contains an |
168e428f PH |
22026 | abbreviated domain that is expanded by DNS lookup. |
22027 | ||
22028 | Unqualified envelope addresses are accepted only for locally submitted | |
9b371988 PH |
22029 | messages, or for messages that are received from hosts matching |
22030 | &%sender_unqualified_hosts%& or &%recipient_unqualified_hosts%&, as | |
22031 | appropriate. Unqualified addresses in header lines are qualified if they are in | |
22032 | locally submitted messages, or messages from hosts that are permitted to send | |
22033 | unqualified envelope addresses. Otherwise, unqualified addresses in header | |
22034 | lines are neither qualified nor rewritten. | |
22035 | ||
22036 | One situation in which Exim does &'not'& automatically rewrite a domain is | |
168e428f | 22037 | when it is the name of a CNAME record in the DNS. The older RFCs suggest that |
9b371988 PH |
22038 | such a domain should be rewritten using the &"canonical"& name, and some MTAs |
22039 | do this. The new RFCs do not contain this suggestion. | |
168e428f PH |
22040 | |
22041 | ||
f89d2485 | 22042 | .section "Explicitly configured address rewriting" "SECID147" |
168e428f PH |
22043 | This chapter describes the rewriting rules that can be used in the |
22044 | main rewrite section of the configuration file, and also in the generic | |
9b371988 | 22045 | &%headers_rewrite%& option that can be set on any transport. |
168e428f PH |
22046 | |
22047 | Some people believe that configured address rewriting is a Mortal Sin. | |
22048 | Others believe that life is not possible without it. Exim provides the | |
22049 | facility; you do not have to use it. | |
22050 | ||
9b371988 | 22051 | The main rewriting rules that appear in the &"rewrite"& section of the |
168e428f PH |
22052 | configuration file are applied to addresses in incoming messages, both envelope |
22053 | addresses and addresses in header lines. Each rule specifies the types of | |
22054 | address to which it applies. | |
22055 | ||
db9452a9 PH |
22056 | Whether or not addresses in header lines are rewritten depends on the origin of |
22057 | the headers and the type of rewriting. Global rewriting, that is, rewriting | |
22058 | rules from the rewrite section of the configuration file, is applied only to | |
22059 | those headers that were received with the message. Header lines that are added | |
22060 | by ACLs or by a system filter or by individual routers or transports (which | |
22061 | are specific to individual recipient addresses) are not rewritten by the global | |
22062 | rules. | |
22063 | ||
22064 | Rewriting at transport time, by means of the &%headers_rewrite%& option, | |
22065 | applies all headers except those added by routers and transports. That is, as | |
22066 | well as the headers that were received with the message, it also applies to | |
22067 | headers that were added by an ACL or a system filter. | |
db9452a9 | 22068 | |
168e428f PH |
22069 | |
22070 | In general, rewriting addresses from your own system or domain has some | |
22071 | legitimacy. Rewriting other addresses should be done only with great care and | |
22072 | in special circumstances. The author of Exim believes that rewriting should be | |
9b371988 | 22073 | used sparingly, and mainly for &"regularizing"& addresses in your own domains. |
168e428f PH |
22074 | Although it can sometimes be used as a routing tool, this is very strongly |
22075 | discouraged. | |
22076 | ||
22077 | There are two commonly encountered circumstances where rewriting is used, as | |
22078 | illustrated by these examples: | |
22079 | ||
9b371988 PH |
22080 | .ilist |
22081 | The company whose domain is &'hitch.fict.example'& has a number of hosts that | |
168e428f | 22082 | exchange mail with each other behind a firewall, but there is only a single |
9b371988 PH |
22083 | gateway to the outer world. The gateway rewrites &'*.hitch.fict.example'& as |
22084 | &'hitch.fict.example'& when sending mail off-site. | |
22085 | .next | |
22086 | A host rewrites the local parts of its own users so that, for example, | |
22087 | &'fp42@hitch.fict.example'& becomes &'Ford.Prefect@hitch.fict.example'&. | |
22088 | .endlist | |
168e428f PH |
22089 | |
22090 | ||
22091 | ||
f89d2485 | 22092 | .section "When does rewriting happen?" "SECID148" |
9b371988 PH |
22093 | .cindex "rewriting" "timing of" |
22094 | .cindex "&ACL;" "rewriting addresses in" | |
168e428f PH |
22095 | Configured address rewriting can take place at several different stages of a |
22096 | message's processing. | |
22097 | ||
f89d2485 | 22098 | .vindex "&$sender_address$&" |
168e428f | 22099 | At the start of an ACL for MAIL, the sender address may have been rewritten |
9b371988 | 22100 | by a special SMTP-time rewrite rule (see section &<<SECTrewriteS>>&), but no |
168e428f PH |
22101 | ordinary rewrite rules have yet been applied. If, however, the sender address |
22102 | is verified in the ACL, it is rewritten before verification, and remains | |
9b371988 | 22103 | rewritten thereafter. The subsequent value of &$sender_address$& is the |
168e428f PH |
22104 | rewritten address. This also applies if sender verification happens in a |
22105 | RCPT ACL. Otherwise, when the sender address is not verified, it is | |
22106 | rewritten as soon as a message's header lines have been received. | |
22107 | ||
f89d2485 PH |
22108 | .vindex "&$domain$&" |
22109 | .vindex "&$local_part$&" | |
168e428f PH |
22110 | Similarly, at the start of an ACL for RCPT, the current recipient's address |
22111 | may have been rewritten by a special SMTP-time rewrite rule, but no ordinary | |
22112 | rewrite rules have yet been applied to it. However, the behaviour is different | |
22113 | from the sender address when a recipient is verified. The address is rewritten | |
22114 | for the verification, but the rewriting is not remembered at this stage. The | |
9b371988 PH |
22115 | value of &$local_part$& and &$domain$& after verification are always the same |
22116 | as they were before (that is, they contain the unrewritten &-- except for | |
22117 | SMTP-time rewriting &-- address). | |
168e428f | 22118 | |
4f578862 PH |
22119 | As soon as a message's header lines have been received, all the envelope |
22120 | recipient addresses are permanently rewritten, and rewriting is also applied to | |
22121 | the addresses in the header lines (if configured). This happens before adding | |
22122 | any header lines that were specified in MAIL or RCPT ACLs, and | |
9b371988 | 22123 | .cindex "&[local_scan()]& function" "address rewriting; timing of" |
4f578862 | 22124 | before the DATA ACL and &[local_scan()]& functions are run. |
168e428f PH |
22125 | |
22126 | When an address is being routed, either for delivery or for verification, | |
22127 | rewriting is applied immediately to child addresses that are generated by | |
9b371988 | 22128 | redirection, unless &%no_rewrite%& is set on the router. |
168e428f | 22129 | |
4f578862 | 22130 | .cindex "envelope sender" "rewriting at transport time" |
9b371988 | 22131 | .cindex "rewriting" "at transport time" |
4f578862 | 22132 | .cindex "header lines" "rewriting at transport time" |
168e428f | 22133 | At transport time, additional rewriting of addresses in header lines can be |
9b371988 PH |
22134 | specified by setting the generic &%headers_rewrite%& option on a transport. |
22135 | This option contains rules that are identical in form to those in the rewrite | |
4f578862 PH |
22136 | section of the configuration file. They are applied to the original message |
22137 | header lines and any that were added by ACLs or a system filter. They are not | |
22138 | applied to header lines that are added by routers or the transport. | |
22139 | ||
22140 | The outgoing envelope sender can be rewritten by means of the &%return_path%& | |
22141 | transport option. However, it is not possible to rewrite envelope recipients at | |
22142 | transport time. | |
168e428f PH |
22143 | |
22144 | ||
22145 | ||
22146 | ||
f89d2485 | 22147 | .section "Testing the rewriting rules that apply on input" "SECID149" |
9b371988 PH |
22148 | .cindex "rewriting" "testing" |
22149 | .cindex "testing" "rewriting" | |
168e428f | 22150 | Exim's input rewriting configuration appears in a part of the run time |
9b371988 PH |
22151 | configuration file headed by &"begin rewrite"&. It can be tested by the |
22152 | &%-brw%& command line option. This takes an address (which can be a full RFC | |
22153 | 2822 address) as its argument. The output is a list of how the address would be | |
168e428f PH |
22154 | transformed by the rewriting rules for each of the different places it might |
22155 | appear in an incoming message, that is, for each different header and for the | |
22156 | envelope sender and recipient fields. For example, | |
9b371988 PH |
22157 | .code |
22158 | exim -brw ph10@exim.workshop.example | |
22159 | .endd | |
168e428f | 22160 | might produce the output |
9b371988 PH |
22161 | .code |
22162 | sender: Philip.Hazel@exim.workshop.example | |
22163 | from: Philip.Hazel@exim.workshop.example | |
22164 | to: ph10@exim.workshop.example | |
22165 | cc: ph10@exim.workshop.example | |
22166 | bcc: ph10@exim.workshop.example | |
22167 | reply-to: Philip.Hazel@exim.workshop.example | |
22168 | env-from: Philip.Hazel@exim.workshop.example | |
22169 | env-to: ph10@exim.workshop.example | |
22170 | .endd | |
168e428f PH |
22171 | which shows that rewriting has been set up for that address when used in any of |
22172 | the source fields, but not when it appears as a recipient address. At the | |
22173 | present time, there is no equivalent way of testing rewriting rules that are | |
22174 | set for a particular transport. | |
22175 | ||
22176 | ||
f89d2485 | 22177 | .section "Rewriting rules" "SECID150" |
9b371988 | 22178 | .cindex "rewriting" "rules" |
168e428f PH |
22179 | The rewrite section of the configuration file consists of lines of rewriting |
22180 | rules in the form | |
9b371988 PH |
22181 | .display |
22182 | <&'source pattern'&> <&'replacement'&> <&'flags'&> | |
22183 | .endd | |
22184 | Rewriting rules that are specified for the &%headers_rewrite%& generic | |
22185 | transport option are given as a colon-separated list. Each item in the list | |
22186 | takes the same form as a line in the main rewriting configuration (except that | |
22187 | any colons must be doubled, of course). | |
168e428f PH |
22188 | |
22189 | The formats of source patterns and replacement strings are described below. | |
22190 | Each is terminated by white space, unless enclosed in double quotes, in which | |
22191 | case normal quoting conventions apply inside the quotes. The flags are single | |
22192 | characters which may appear in any order. Spaces and tabs between them are | |
22193 | ignored. | |
22194 | ||
22195 | For each address that could potentially be rewritten, the rules are scanned in | |
22196 | order, and replacements for the address from earlier rules can themselves be | |
9b371988 | 22197 | replaced by later rules (but see the &"q"& and &"R"& flags). |
168e428f PH |
22198 | |
22199 | The order in which addresses are rewritten is undefined, may change between | |
22200 | releases, and must not be relied on, with one exception: when a message is | |
22201 | received, the envelope sender is always rewritten first, before any header | |
22202 | lines are rewritten. For example, the replacement string for a rewrite of an | |
9b371988 PH |
22203 | address in &'To:'& must not assume that the message's address in &'From:'& has |
22204 | (or has not) already been rewritten. However, a rewrite of &'From:'& may assume | |
22205 | that the envelope sender has already been rewritten. | |
168e428f | 22206 | |
f89d2485 PH |
22207 | .vindex "&$domain$&" |
22208 | .vindex "&$local_part$&" | |
9b371988 | 22209 | The variables &$local_part$& and &$domain$& can be used in the replacement |
168e428f PH |
22210 | string to refer to the address that is being rewritten. Note that lookup-driven |
22211 | rewriting can be done by a rule of the form | |
9b371988 PH |
22212 | .code |
22213 | *@* ${lookup ... | |
22214 | .endd | |
22215 | where the lookup key uses &$1$& and &$2$& or &$local_part$& and &$domain$& to | |
168e428f PH |
22216 | refer to the address that is being rewritten. |
22217 | ||
22218 | ||
f89d2485 | 22219 | .section "Rewriting patterns" "SECID151" |
9b371988 PH |
22220 | .cindex "rewriting" "patterns" |
22221 | .cindex "address list" "in a rewriting pattern" | |
168e428f | 22222 | The source pattern in a rewriting rule is any item which may appear in an |
9b371988 | 22223 | address list (see section &<<SECTaddresslist>>&). It is in fact processed as a |
168e428f | 22224 | single-item address list, which means that it is expanded before being tested |
068aaea8 | 22225 | against the address. As always, if you use a regular expression as a pattern, |
9b371988 | 22226 | you must take care to escape dollar and backslash characters, or use the &`\N`& |
068aaea8 | 22227 | facility to suppress string expansion within the regular expression. |
168e428f PH |
22228 | |
22229 | Domains in patterns should be given in lower case. Local parts in patterns are | |
22230 | case-sensitive. If you want to do case-insensitive matching of local parts, you | |
9b371988 | 22231 | can use a regular expression that starts with &`^(?i)`&. |
168e428f | 22232 | |
9b371988 PH |
22233 | .cindex "numerical variables (&$1$& &$2$& etc)" "in rewriting rules" |
22234 | After matching, the numerical variables &$1$&, &$2$&, etc. may be set, | |
168e428f | 22235 | depending on the type of match which occurred. These can be used in the |
9b371988 | 22236 | replacement string to insert portions of the incoming address. &$0$& always |
168e428f PH |
22237 | refers to the complete incoming address. When a regular expression is used, the |
22238 | numerical variables are set from its capturing subexpressions. For other types | |
22239 | of pattern they are set as follows: | |
22240 | ||
9b371988 PH |
22241 | .ilist |
22242 | If a local part or domain starts with an asterisk, the numerical variables | |
22243 | refer to the character strings matched by asterisks, with &$1$& associated with | |
22244 | the first asterisk, and &$2$& with the second, if present. For example, if the | |
168e428f | 22245 | pattern |
9b371988 PH |
22246 | .code |
22247 | *queen@*.fict.example | |
22248 | .endd | |
22249 | is matched against the address &'hearts-queen@wonderland.fict.example'& then | |
22250 | .code | |
22251 | $0 = hearts-queen@wonderland.fict.example | |
22252 | $1 = hearts- | |
22253 | $2 = wonderland | |
22254 | .endd | |
168e428f | 22255 | Note that if the local part does not start with an asterisk, but the domain |
9b371988 | 22256 | does, it is &$1$& that contains the wild part of the domain. |
168e428f | 22257 | |
9b371988 PH |
22258 | .next |
22259 | If the domain part of the pattern is a partial lookup, the wild and fixed parts | |
168e428f | 22260 | of the domain are placed in the next available numerical variables. Suppose, |
9b371988 | 22261 | for example, that the address &'foo@bar.baz.example'& is processed by a |
168e428f | 22262 | rewriting rule of the form |
9b371988 PH |
22263 | .display |
22264 | &`*@partial-dbm;/some/dbm/file`& <&'replacement string'&> | |
22265 | .endd | |
22266 | and the key in the file that matches the domain is &`*.baz.example`&. Then | |
22267 | .code | |
22268 | $1 = foo | |
22269 | $2 = bar | |
22270 | $3 = baz.example | |
22271 | .endd | |
22272 | If the address &'foo@baz.example'& is looked up, this matches the same | |
22273 | wildcard file entry, and in this case &$2$& is set to the empty string, but | |
22274 | &$3$& is still set to &'baz.example'&. If a non-wild key is matched in a | |
22275 | partial lookup, &$2$& is again set to the empty string and &$3$& is set to the | |
168e428f | 22276 | whole domain. For non-partial domain lookups, no numerical variables are set. |
9b371988 | 22277 | .endlist |
168e428f PH |
22278 | |
22279 | ||
f89d2485 | 22280 | .section "Rewriting replacements" "SECID152" |
9b371988 | 22281 | .cindex "rewriting" "replacements" |
168e428f | 22282 | If the replacement string for a rule is a single asterisk, addresses that |
9b371988 | 22283 | match the pattern and the flags are &'not'& rewritten, and no subsequent |
168e428f | 22284 | rewriting rules are scanned. For example, |
9b371988 PH |
22285 | .code |
22286 | hatta@lookingglass.fict.example * f | |
22287 | .endd | |
22288 | specifies that &'hatta@lookingglass.fict.example'& is never to be rewritten in | |
22289 | &'From:'& headers. | |
22290 | ||
f89d2485 PH |
22291 | .vindex "&$domain$&" |
22292 | .vindex "&$local_part$&" | |
168e428f PH |
22293 | If the replacement string is not a single asterisk, it is expanded, and must |
22294 | yield a fully qualified address. Within the expansion, the variables | |
9b371988 PH |
22295 | &$local_part$& and &$domain$& refer to the address that is being rewritten. |
22296 | Any letters they contain retain their original case &-- they are not lower | |
168e428f PH |
22297 | cased. The numerical variables are set up according to the type of pattern that |
22298 | matched the address, as described above. If the expansion is forced to fail by | |
9b371988 | 22299 | the presence of &"fail"& in a conditional or lookup item, rewriting by the |
168e428f PH |
22300 | current rule is abandoned, but subsequent rules may take effect. Any other |
22301 | expansion failure causes the entire rewriting operation to be abandoned, and an | |
22302 | entry written to the panic log. | |
22303 | ||
22304 | ||
22305 | ||
f89d2485 | 22306 | .section "Rewriting flags" "SECID153" |
168e428f PH |
22307 | There are three different kinds of flag that may appear on rewriting rules: |
22308 | ||
9b371988 PH |
22309 | .ilist |
22310 | Flags that specify which headers and envelope addresses to rewrite: E, F, T, b, | |
168e428f | 22311 | c, f, h, r, s, t. |
9b371988 PH |
22312 | .next |
22313 | A flag that specifies rewriting at SMTP time: S. | |
22314 | .next | |
22315 | Flags that control the rewriting process: Q, q, R, w. | |
22316 | .endlist | |
168e428f | 22317 | |
9b371988 | 22318 | For rules that are part of the &%headers_rewrite%& generic transport option, |
168e428f PH |
22319 | E, F, T, and S are not permitted. |
22320 | ||
22321 | ||
22322 | ||
f89d2485 PH |
22323 | .section "Flags specifying which headers and envelope addresses to rewrite" &&& |
22324 | "SECID154" | |
9b371988 PH |
22325 | .cindex "rewriting" "flags" |
22326 | If none of the following flag letters, nor the &"S"& flag (see section | |
22327 | &<<SECTrewriteS>>&) are present, a main rewriting rule applies to all headers | |
22328 | and to both the sender and recipient fields of the envelope, whereas a | |
168e428f PH |
22329 | transport-time rewriting rule just applies to all headers. Otherwise, the |
22330 | rewriting rule is skipped unless the relevant addresses are being processed. | |
9b371988 PH |
22331 | .display |
22332 | &`E`& rewrite all envelope fields | |
22333 | &`F`& rewrite the envelope From field | |
22334 | &`T`& rewrite the envelope To field | |
22335 | &`b`& rewrite the &'Bcc:'& header | |
22336 | &`c`& rewrite the &'Cc:'& header | |
22337 | &`f`& rewrite the &'From:'& header | |
22338 | &`h`& rewrite all headers | |
22339 | &`r`& rewrite the &'Reply-To:'& header | |
22340 | &`s`& rewrite the &'Sender:'& header | |
22341 | &`t`& rewrite the &'To:'& header | |
22342 | .endd | |
711df2d9 TF |
22343 | "All headers" means all of the headers listed above that can be selected |
22344 | individually, plus their &'Resent-'& versions. It does not include | |
22345 | other headers such as &'Subject:'& etc. | |
22346 | ||
9b371988 | 22347 | You should be particularly careful about rewriting &'Sender:'& headers, and |
168e428f PH |
22348 | restrict this to special known cases in your own domains. |
22349 | ||
22350 | ||
9b371988 PH |
22351 | .section "The SMTP-time rewriting flag" "SECTrewriteS" |
22352 | .cindex "SMTP" "rewriting malformed addresses" | |
22353 | .cindex "RCPT" "rewriting argument of" | |
22354 | .cindex "MAIL" "rewriting argument of" | |
22355 | The rewrite flag &"S"& specifies a rewrite of incoming envelope addresses at | |
22356 | SMTP time, as soon as an address is received in a MAIL or RCPT command, and | |
168e428f PH |
22357 | before any other processing; even before syntax checking. The pattern is |
22358 | required to be a regular expression, and it is matched against the whole of the | |
22359 | data for the command, including any surrounding angle brackets. | |
22360 | ||
f89d2485 PH |
22361 | .vindex "&$domain$&" |
22362 | .vindex "&$local_part$&" | |
168e428f | 22363 | This form of rewrite rule allows for the handling of addresses that are not |
9b371988 | 22364 | compliant with RFCs 2821 and 2822 (for example, &"bang paths"& in batched SMTP |
168e428f | 22365 | input). Because the input is not required to be a syntactically valid address, |
9b371988 | 22366 | the variables &$local_part$& and &$domain$& are not available during the |
168e428f PH |
22367 | expansion of the replacement string. The result of rewriting replaces the |
22368 | original address in the MAIL or RCPT command. | |
22369 | ||
22370 | ||
f89d2485 | 22371 | .section "Flags controlling the rewriting process" "SECID155" |
168e428f PH |
22372 | There are four flags which control the way the rewriting process works. These |
22373 | take effect only when a rule is invoked, that is, when the address is of the | |
22374 | correct type (matches the flags) and matches the pattern: | |
22375 | ||
9b371988 PH |
22376 | .ilist |
22377 | If the &"Q"& flag is set on a rule, the rewritten address is permitted to be an | |
22378 | unqualified local part. It is qualified with &%qualify_recipient%&. In the | |
22379 | absence of &"Q"& the rewritten address must always include a domain. | |
22380 | .next | |
22381 | If the &"q"& flag is set on a rule, no further rewriting rules are considered, | |
22382 | even if no rewriting actually takes place because of a &"fail"& in the | |
22383 | expansion. The &"q"& flag is not effective if the address is of the wrong type | |
22384 | (does not match the flags) or does not match the pattern. | |
22385 | .next | |
22386 | The &"R"& flag causes a successful rewriting rule to be re-applied to the new | |
22387 | address, up to ten times. It can be combined with the &"q"& flag, to stop | |
168e428f | 22388 | rewriting once it fails to match (after at least one successful rewrite). |
9b371988 PH |
22389 | .next |
22390 | .cindex "rewriting" "whole addresses" | |
168e428f | 22391 | When an address in a header is rewritten, the rewriting normally applies only |
9b371988 | 22392 | to the working part of the address, with any comments and RFC 2822 &"phrase"& |
168e428f | 22393 | left unchanged. For example, rewriting might change |
9b371988 PH |
22394 | .code |
22395 | From: Ford Prefect <fp42@restaurant.hitch.fict.example> | |
22396 | .endd | |
168e428f | 22397 | into |
9b371988 PH |
22398 | .code |
22399 | From: Ford Prefect <prefectf@hitch.fict.example> | |
22400 | .endd | |
22401 | .cindex "RFC 2047" | |
168e428f | 22402 | Sometimes there is a need to replace the whole address item, and this can be |
9b371988 | 22403 | done by adding the flag letter &"w"& to a rule. If this is set on a rule that |
168e428f PH |
22404 | causes an address in a header line to be rewritten, the entire address is |
22405 | replaced, not just the working part. The replacement must be a complete RFC | |
22406 | 2822 address, including the angle brackets if necessary. If text outside angle | |
22407 | brackets contains a character whose value is greater than 126 or less than 32 | |
d1e83bff | 22408 | (except for tab), the text is encoded according to RFC 2047. The character set |
9b371988 | 22409 | is taken from &%headers_charset%&, which defaults to ISO-8859-1. |
168e428f | 22410 | |
9b371988 PH |
22411 | When the &"w"& flag is set on a rule that causes an envelope address to be |
22412 | rewritten, all but the working part of the replacement address is discarded. | |
22413 | .endlist | |
168e428f PH |
22414 | |
22415 | ||
f89d2485 | 22416 | .section "Rewriting examples" "SECID156" |
168e428f | 22417 | Here is an example of the two common rewriting paradigms: |
9b371988 | 22418 | .code |
168e428f PH |
22419 | *@*.hitch.fict.example $1@hitch.fict.example |
22420 | *@hitch.fict.example ${lookup{$1}dbm{/etc/realnames}\ | |
22421 | {$value}fail}@hitch.fict.example bctfrF | |
9b371988 PH |
22422 | .endd |
22423 | Note the use of &"fail"& in the lookup expansion in the second rule, forcing | |
168e428f PH |
22424 | the string expansion to fail if the lookup does not succeed. In this context it |
22425 | has the effect of leaving the original address unchanged, but Exim goes on to | |
9b371988 PH |
22426 | consider subsequent rewriting rules, if any, because the &"q"& flag is not |
22427 | present in that rule. An alternative to &"fail"& would be to supply &$1$& | |
168e428f PH |
22428 | explicitly, which would cause the rewritten address to be the same as before, |
22429 | at the cost of a small bit of processing. Not supplying either of these is an | |
22430 | error, since the rewritten address would then contain no local part. | |
22431 | ||
22432 | The first example above replaces the domain with a superior, more general | |
22433 | domain. This may not be desirable for certain local parts. If the rule | |
9b371988 PH |
22434 | .code |
22435 | root@*.hitch.fict.example * | |
22436 | .endd | |
168e428f | 22437 | were inserted before the first rule, rewriting would be suppressed for the |
9b371988 | 22438 | local part &'root'& at any domain ending in &'hitch.fict.example'&. |
168e428f PH |
22439 | |
22440 | Rewriting can be made conditional on a number of tests, by making use of | |
9b371988 | 22441 | &${if$& in the expansion item. For example, to apply a rewriting rule only to |
168e428f | 22442 | messages that originate outside the local host: |
9b371988 | 22443 | .code |
168e428f PH |
22444 | *@*.hitch.fict.example "${if !eq {$sender_host_address}{}\ |
22445 | {$1@hitch.fict.example}fail}" | |
9b371988 | 22446 | .endd |
168e428f PH |
22447 | The replacement string is quoted in this example because it contains white |
22448 | space. | |
22449 | ||
9b371988 PH |
22450 | .cindex "rewriting" "bang paths" |
22451 | .cindex "bang paths" "rewriting" | |
22452 | Exim does not handle addresses in the form of &"bang paths"&. If it sees such | |
22453 | an address it treats it as an unqualified local part which it qualifies with | |
22454 | the local qualification domain (if the source of the message is local or if the | |
168e428f PH |
22455 | remote host is permitted to send unqualified addresses). Rewriting can |
22456 | sometimes be used to handle simple bang paths with a fixed number of | |
22457 | components. For example, the rule | |
9b371988 PH |
22458 | .code |
22459 | \N^([^!]+)!(.*)@your.domain.example$\N $2@$1 | |
22460 | .endd | |
22461 | rewrites a two-component bang path &'host.name!user'& as the domain address | |
22462 | &'user@host.name'&. However, there is a security implication in using this as | |
168e428f PH |
22463 | a global rewriting rule for envelope addresses. It can provide a backdoor |
22464 | method for using your system as a relay, because the incoming addresses appear | |
22465 | to be local. If the bang path addresses are received via SMTP, it is safer to | |
9b371988 | 22466 | use the &"S"& flag to rewrite them as they are received, so that relay checking |
168e428f | 22467 | can be done on the rewritten addresses. |
4f578862 | 22468 | .ecindex IIDaddrew |
168e428f PH |
22469 | |
22470 | ||
22471 | ||
22472 | ||
22473 | ||
9b371988 PH |
22474 | . //////////////////////////////////////////////////////////////////////////// |
22475 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 22476 | |
9b371988 | 22477 | .chapter "Retry configuration" "CHAPretry" |
f89d2485 | 22478 | .scindex IIDretconf1 "retry" "configuration, description of" |
4f578862 | 22479 | .scindex IIDregconf2 "configuration file" "retry section" |
595028e4 | 22480 | The &"retry"& section of the runtime configuration file contains a list of |
4f578862 | 22481 | retry rules that control how often Exim tries to deliver messages that cannot |
595028e4 PH |
22482 | be delivered at the first attempt. If there are no retry rules (the section is |
22483 | empty or not present), there are no retries. In this situation, temporary | |
22484 | errors are treated as permanent. The default configuration contains a single, | |
22485 | general-purpose retry rule (see section &<<SECID57>>&). The &%-brt%& command | |
22486 | line option can be used to test which retry rule will be used for a given | |
22487 | address, domain and error. | |
168e428f PH |
22488 | |
22489 | The most common cause of retries is temporary failure to deliver to a remote | |
22490 | host because the host is down, or inaccessible because of a network problem. | |
22491 | Exim's retry processing in this case is applied on a per-host (strictly, per IP | |
22492 | address) basis, not on a per-message basis. Thus, if one message has recently | |
22493 | been delayed, delivery of a new message to the same host is not immediately | |
9b371988 PH |
22494 | tried, but waits for the host's retry time to arrive. If the &%retry_defer%& |
22495 | log selector is set, the message | |
22496 | .cindex "retry" "time not reached" | |
22497 | &"retry time not reached"& is written to the main log whenever a delivery is | |
22498 | skipped for this reason. Section &<<SECToutSMTPerr>>& contains more details of | |
22499 | the handling of errors during remote deliveries. | |
168e428f PH |
22500 | |
22501 | Retry processing applies to routing as well as to delivering, except as covered | |
22502 | in the next paragraph. The retry rules do not distinguish between these | |
22503 | actions. It is not possible, for example, to specify different behaviour for | |
9b371988 PH |
22504 | failures to route the domain &'snark.fict.example'& and failures to deliver to |
22505 | the host &'snark.fict.example'&. I didn't think anyone would ever need this | |
168e428f PH |
22506 | added complication, so did not implement it. However, although they share the |
22507 | same retry rule, the actual retry times for routing and transporting a given | |
22508 | domain are maintained independently. | |
22509 | ||
22510 | When a delivery is not part of a queue run (typically an immediate delivery on | |
22511 | receipt of a message), the routers are always run, and local deliveries are | |
22512 | always attempted, even if retry times are set for them. This makes for better | |
22513 | behaviour if one particular message is causing problems (for example, causing | |
22514 | quota overflow, or provoking an error in a filter file). If such a delivery | |
22515 | suffers a temporary failure, the retry data is updated as normal, and | |
22516 | subsequent delivery attempts from queue runs occur only when the retry time for | |
22517 | the local address is reached. | |
22518 | ||
f89d2485 | 22519 | .section "Changing retry rules" "SECID157" |
db9452a9 PH |
22520 | If you change the retry rules in your configuration, you should consider |
22521 | whether or not to delete the retry data that is stored in Exim's spool area in | |
22522 | files with names like &_db/retry_&. Deleting any of Exim's hints files is | |
22523 | always safe; that is why they are called &"hints"&. | |
22524 | ||
22525 | The hints retry data contains suggested retry times based on the previous | |
22526 | rules. In the case of a long-running problem with a remote host, it might | |
22527 | record the fact that the host has timed out. If your new rules increase the | |
22528 | timeout time for such a host, you should definitely remove the old retry data | |
22529 | and let Exim recreate it, based on the new rules. Otherwise Exim might bounce | |
22530 | messages that it should now be retaining. | |
db9452a9 | 22531 | |
168e428f PH |
22532 | |
22533 | ||
f89d2485 | 22534 | .section "Format of retry rules" "SECID158" |
9b371988 | 22535 | .cindex "retry" "rules" |
168e428f PH |
22536 | Each retry rule occupies one line and consists of three or four parts, |
22537 | separated by white space: a pattern, an error name, an optional list of sender | |
22538 | addresses, and a list of retry parameters. The pattern and sender lists must be | |
9b371988 PH |
22539 | enclosed in double quotes if they contain white space. The rules are searched |
22540 | in order until one is found where the pattern, error name, and sender list (if | |
168e428f PH |
22541 | present) match the failing host or address, the error that occurred, and the |
22542 | message's sender, respectively. | |
22543 | ||
22544 | ||
22545 | The pattern is any single item that may appear in an address list (see section | |
9b371988 PH |
22546 | &<<SECTaddresslist>>&). It is in fact processed as a one-item address list, |
22547 | which means that it is expanded before being tested against the address that | |
3cb1b51e | 22548 | has been delayed. A negated address list item is permitted. Address |
db9452a9 PH |
22549 | list processing treats a plain domain name as if it were preceded by &"*@"&, |
22550 | which makes it possible for many retry rules to start with just a domain. For | |
22551 | example, | |
9b371988 PH |
22552 | .code |
22553 | lookingglass.fict.example * F,24h,30m; | |
22554 | .endd | |
22555 | provides a rule for any address in the &'lookingglass.fict.example'& domain, | |
168e428f | 22556 | whereas |
9b371988 PH |
22557 | .code |
22558 | alice@lookingglass.fict.example * F,24h,30m; | |
22559 | .endd | |
22560 | applies only to temporary failures involving the local part &%alice%&. | |
168e428f PH |
22561 | In practice, almost all rules start with a domain name pattern without a local |
22562 | part. | |
22563 | ||
9b371988 PH |
22564 | .cindex "regular expressions" "in retry rules" |
22565 | &*Warning*&: If you use a regular expression in a routing rule pattern, it | |
168e428f PH |
22566 | must match a complete address, not just a domain, because that is how regular |
22567 | expressions work in address lists. | |
9b371988 PH |
22568 | .display |
22569 | &`^\Nxyz\d+\.abc\.example$\N * G,1h,10m,2`& &%Wrong%& | |
22570 | &`^\N[^@]+@xyz\d+\.abc\.example$\N * G,1h,10m,2`& &%Right%& | |
22571 | .endd | |
168e428f PH |
22572 | |
22573 | ||
f89d2485 | 22574 | .section "Choosing which retry rule to use for address errors" "SECID159" |
168e428f PH |
22575 | When Exim is looking for a retry rule after a routing attempt has failed (for |
22576 | example, after a DNS timeout), each line in the retry configuration is tested | |
9b371988 | 22577 | against the complete address only if &%retry_use_local_part%& is set for the |
168e428f | 22578 | router. Otherwise, only the domain is used, except when matching against a |
9b371988 | 22579 | regular expression, when the local part of the address is replaced with &"*"&. |
168e428f | 22580 | A domain on its own can match a domain pattern, or a pattern that starts with |
9b371988 PH |
22581 | &"*@"&. By default, &%retry_use_local_part%& is true for routers where |
22582 | &%check_local_user%& is true, and false for other routers. | |
168e428f PH |
22583 | |
22584 | Similarly, when Exim is looking for a retry rule after a local delivery has | |
22585 | failed (for example, after a mailbox full error), each line in the retry | |
22586 | configuration is tested against the complete address only if | |
9b371988 | 22587 | &%retry_use_local_part%& is set for the transport (it defaults true for all |
168e428f PH |
22588 | local transports). |
22589 | ||
3cb1b51e | 22590 | .cindex "4&'xx'& responses" "retry rules for" |
4f578862 PH |
22591 | However, when Exim is looking for a retry rule after a remote delivery attempt |
22592 | suffers an address error (a 4&'xx'& SMTP response for a recipient address), the | |
22593 | whole address is always used as the key when searching the retry rules. The | |
3cb1b51e PH |
22594 | rule that is found is used to create a retry time for the combination of the |
22595 | failing address and the message's sender. It is the combination of sender and | |
22596 | recipient that is delayed in subsequent queue runs until its retry time is | |
22597 | reached. You can delay the recipient without regard to the sender by setting | |
22598 | &%address_retry_include_sender%& false in the &(smtp)& transport but this can | |
22599 | lead to problems with servers that regularly issue 4&'xx'& responses to RCPT | |
22600 | commands. | |
3cb1b51e | 22601 | |
168e428f | 22602 | |
068aaea8 | 22603 | |
f89d2485 PH |
22604 | .section "Choosing which retry rule to use for host and message errors" &&& |
22605 | "SECID160" | |
068aaea8 PH |
22606 | For a temporary error that is not related to an individual address (for |
22607 | example, a connection timeout), each line in the retry configuration is checked | |
22608 | twice. First, the name of the remote host is used as a domain name (preceded by | |
9b371988 | 22609 | &"*@"& when matching a regular expression). If this does not match the line, |
068aaea8 | 22610 | the domain from the email address is tried in a similar fashion. For example, |
9b371988 PH |
22611 | suppose the MX records for &'a.b.c.example'& are |
22612 | .code | |
22613 | a.b.c.example MX 5 x.y.z.example | |
22614 | MX 6 p.q.r.example | |
22615 | MX 7 m.n.o.example | |
22616 | .endd | |
168e428f | 22617 | and the retry rules are |
9b371988 PH |
22618 | .code |
22619 | p.q.r.example * F,24h,30m; | |
22620 | a.b.c.example * F,4d,45m; | |
22621 | .endd | |
22622 | and a delivery to the host &'x.y.z.example'& suffers a connection failure. The | |
068aaea8 PH |
22623 | first rule matches neither the host nor the domain, so Exim looks at the second |
22624 | rule. This does not match the host, but it does match the domain, so it is used | |
9b371988 PH |
22625 | to calculate the retry time for the host &'x.y.z.example'&. Meanwhile, Exim |
22626 | tries to deliver to &'p.q.r.example'&. If this also suffers a host error, the | |
22627 | first retry rule is used, because it matches the host. | |
168e428f | 22628 | |
9b371988 | 22629 | In other words, temporary failures to deliver to host &'p.q.r.example'& use the |
068aaea8 | 22630 | first rule to determine retry times, but for all the other hosts for the domain |
9b371988 PH |
22631 | &'a.b.c.example'&, the second rule is used. The second rule is also used if |
22632 | routing to &'a.b.c.example'& suffers a temporary failure. | |
168e428f | 22633 | |
9b371988 | 22634 | &*Note*&: The host name is used when matching the patterns, not its IP address. |
068aaea8 | 22635 | However, if a message is routed directly to an IP address without the use of a |
9b371988 PH |
22636 | host name, for example, if a &(manualroute)& router contains a setting such as: |
22637 | .code | |
22638 | route_list = *.a.example 192.168.34.23 | |
22639 | .endd | |
22640 | then the &"host name"& that is used when searching for a retry rule is the | |
068aaea8 PH |
22641 | textual form of the IP address. |
22642 | ||
f89d2485 | 22643 | .section "Retry rules for specific errors" "SECID161" |
9b371988 | 22644 | .cindex "retry" "specific errors; specifying" |
168e428f PH |
22645 | The second field in a retry rule is the name of a particular error, or an |
22646 | asterisk, which matches any error. The errors that can be tested for are: | |
22647 | ||
9b371988 PH |
22648 | .vlist |
22649 | .vitem &%auth_failed%& | |
22650 | Authentication failed when trying to send to a host in the | |
22651 | &%hosts_require_auth%& list in an &(smtp)& transport. | |
168e428f | 22652 | |
4f578862 PH |
22653 | .vitem &%data_4xx%& |
22654 | A 4&'xx'& error was received for an outgoing DATA command, either immediately | |
22655 | after the command, or after sending the message's data. | |
22656 | ||
22657 | .vitem &%mail_4xx%& | |
22658 | A 4&'xx'& error was received for an outgoing MAIL command. | |
22659 | ||
9b371988 | 22660 | .vitem &%rcpt_4xx%& |
4f578862 PH |
22661 | A 4&'xx'& error was received for an outgoing RCPT command. |
22662 | .endlist | |
22663 | ||
22664 | For the three 4&'xx'& errors, either the first or both of the x's can be given | |
22665 | as specific digits, for example: &`mail_45x`& or &`rcpt_436`&. For example, to | |
22666 | recognize 452 errors given to RCPT commands for addresses in a certain domain, | |
22667 | and have retries every ten minutes with a one-hour timeout, you could set up a | |
22668 | retry rule of this form: | |
9b371988 | 22669 | .code |
4f578862 | 22670 | the.domain.name rcpt_452 F,1h,10m |
9b371988 PH |
22671 | .endd |
22672 | These errors apply to both outgoing SMTP (the &(smtp)& transport) and outgoing | |
22673 | LMTP (either the &(lmtp)& transport, or the &(smtp)& transport in LMTP mode). | |
4f578862 PH |
22674 | |
22675 | .vlist | |
4f578862 PH |
22676 | .vitem &%lost_connection%& |
22677 | A server unexpectedly closed the SMTP connection. There may, of course, | |
22678 | legitimate reasons for this (host died, network died), but if it repeats a lot | |
22679 | for the same host, it indicates something odd. | |
168e428f | 22680 | |
9b371988 | 22681 | .vitem &%refused_MX%& |
168e428f PH |
22682 | A connection to a host obtained from an MX record was refused. |
22683 | ||
9b371988 | 22684 | .vitem &%refused_A%& |
168e428f PH |
22685 | A connection to a host not obtained from an MX record was refused. |
22686 | ||
9b371988 | 22687 | .vitem &%refused%& |
168e428f PH |
22688 | A connection was refused. |
22689 | ||
9b371988 | 22690 | .vitem &%timeout_connect_MX%& |
168e428f PH |
22691 | A connection attempt to a host obtained from an MX record timed out. |
22692 | ||
9b371988 | 22693 | .vitem &%timeout_connect_A%& |
168e428f PH |
22694 | A connection attempt to a host not obtained from an MX record timed out. |
22695 | ||
9b371988 | 22696 | .vitem &%timeout_connect%& |
168e428f PH |
22697 | A connection attempt timed out. |
22698 | ||
9b371988 | 22699 | .vitem &%timeout_MX%& |
168e428f PH |
22700 | There was a timeout while connecting or during an SMTP session with a host |
22701 | obtained from an MX record. | |
22702 | ||
9b371988 | 22703 | .vitem &%timeout_A%& |
168e428f PH |
22704 | There was a timeout while connecting or during an SMTP session with a host not |
22705 | obtained from an MX record. | |
22706 | ||
9b371988 | 22707 | .vitem &%timeout%& |
168e428f PH |
22708 | There was a timeout while connecting or during an SMTP session. |
22709 | ||
4f578862 PH |
22710 | .vitem &%tls_required%& |
22711 | The server was required to use TLS (it matched &%hosts_require_tls%& in the | |
22712 | &(smtp)& transport), but either did not offer TLS, or it responded with 4&'xx'& | |
22713 | to STARTTLS, or there was a problem setting up the TLS connection. | |
4f578862 | 22714 | |
9b371988 PH |
22715 | .vitem &%quota%& |
22716 | A mailbox quota was exceeded in a local delivery by the &(appendfile)& | |
22717 | transport. | |
168e428f | 22718 | |
9b371988 PH |
22719 | .vitem &%quota_%&<&'time'&> |
22720 | .cindex "quota" "error testing in retry rule" | |
22721 | .cindex "retry" "quota error testing" | |
22722 | A mailbox quota was exceeded in a local delivery by the &(appendfile)& | |
22723 | transport, and the mailbox has not been accessed for <&'time'&>. For example, | |
22724 | &'quota_4d'& applies to a quota error when the mailbox has not been accessed | |
22725 | for four days. | |
22726 | .endlist | |
22727 | ||
22728 | .cindex "mailbox" "time of last read" | |
22729 | The idea of &%quota_%&<&'time'&> is to make it possible to have shorter | |
22730 | timeouts when the mailbox is full and is not being read by its owner. Ideally, | |
22731 | it should be based on the last time that the user accessed the mailbox. | |
22732 | However, it is not always possible to determine this. Exim uses the following | |
22733 | heuristic rules: | |
22734 | ||
22735 | .ilist | |
22736 | If the mailbox is a single file, the time of last access (the &"atime"&) is | |
22737 | used. As no new messages are being delivered (because the mailbox is over | |
22738 | quota), Exim does not access the file, so this is the time of last user access. | |
22739 | .next | |
22740 | .cindex "maildir format" "time of last read" | |
22741 | For a maildir delivery, the time of last modification of the &_new_& | |
168e428f | 22742 | subdirectory is used. As the mailbox is over quota, no new files are created in |
9b371988 PH |
22743 | the &_new_& subdirectory, because no new messages are being delivered. Any |
22744 | change to the &_new_& subdirectory is therefore assumed to be the result of an | |
22745 | MUA moving a new message to the &_cur_& directory when it is first read. The | |
168e428f | 22746 | time that is used is therefore the last time that the user read a new message. |
9b371988 PH |
22747 | .next |
22748 | For other kinds of multi-file mailbox, the time of last access cannot be | |
168e428f | 22749 | obtained, so a retry rule that uses this type of error field is never matched. |
9b371988 | 22750 | .endlist |
168e428f PH |
22751 | |
22752 | The quota errors apply both to system-enforced quotas and to Exim's own quota | |
9b371988 | 22753 | mechanism in the &(appendfile)& transport. The &'quota'& error also applies |
168e428f PH |
22754 | when a local delivery is deferred because a partition is full (the ENOSPC |
22755 | error). | |
22756 | ||
22757 | ||
22758 | ||
f89d2485 | 22759 | .section "Retry rules for specified senders" "SECID162" |
9b371988 | 22760 | .cindex "retry" "rules; sender-specific" |
168e428f PH |
22761 | You can specify retry rules that apply only when the failing message has a |
22762 | specific sender. In particular, this can be used to define retry rules that | |
22763 | apply only to bounce messages. The third item in a retry rule can be of this | |
22764 | form: | |
4f578862 PH |
22765 | .display |
22766 | &`senders=`&<&'address list'&> | |
9b371988 | 22767 | .endd |
168e428f | 22768 | The retry timings themselves are then the fourth item. For example: |
9b371988 | 22769 | .code |
068aaea8 | 22770 | * rcpt_4xx senders=: F,1h,30m |
9b371988 | 22771 | .endd |
4f578862 PH |
22772 | matches recipient 4&'xx'& errors for bounce messages sent to any address at any |
22773 | host. If the address list contains white space, it must be enclosed in quotes. | |
22774 | For example: | |
9b371988 | 22775 | .code |
4f578862 | 22776 | a.domain rcpt_452 senders="xb.dom : yc.dom" G,8h,10m,1.5 |
9b371988 | 22777 | .endd |
4f578862 PH |
22778 | &*Warning*&: This facility can be unhelpful if it is used for host errors |
22779 | (which do not depend on the recipient). The reason is that the sender is used | |
22780 | only to match the retry rule. Once the rule has been found for a host error, | |
22781 | its contents are used to set a retry time for the host, and this will apply to | |
22782 | all messages, not just those with specific senders. | |
168e428f | 22783 | |
9b371988 PH |
22784 | When testing retry rules using &%-brt%&, you can supply a sender using the |
22785 | &%-f%& command line option, like this: | |
22786 | .code | |
22787 | exim -f "" -brt user@dom.ain | |
22788 | .endd | |
22789 | If you do not set &%-f%& with &%-brt%&, a retry rule that contains a senders | |
22790 | list is never matched. | |
168e428f | 22791 | |
168e428f PH |
22792 | |
22793 | ||
22794 | ||
22795 | ||
f89d2485 | 22796 | .section "Retry parameters" "SECID163" |
9b371988 | 22797 | .cindex "retry" "parameters in rules" |
168e428f PH |
22798 | The third (or fourth, if a senders list is present) field in a retry rule is a |
22799 | sequence of retry parameter sets, separated by semicolons. Each set consists of | |
9b371988 PH |
22800 | .display |
22801 | <&'letter'&>,<&'cutoff time'&>,<&'arguments'&> | |
22802 | .endd | |
168e428f PH |
22803 | The letter identifies the algorithm for computing a new retry time; the cutoff |
22804 | time is the time beyond which this algorithm no longer applies, and the | |
22805 | arguments vary the algorithm's action. The cutoff time is measured from the | |
22806 | time that the first failure for the domain (combined with the local part if | |
22807 | relevant) was detected, not from the time the message was received. | |
22808 | ||
9b371988 PH |
22809 | .cindex "retry" "algorithms" |
22810 | .cindex "retry" "fixed intervals" | |
22811 | .cindex "retry" "increasing intervals" | |
22812 | .cindex "retry" "random intervals" | |
168e428f PH |
22813 | The available algorithms are: |
22814 | ||
9b371988 PH |
22815 | .ilist |
22816 | &'F'&: retry at fixed intervals. There is a single time parameter specifying | |
168e428f | 22817 | the interval. |
9b371988 PH |
22818 | .next |
22819 | &'G'&: retry at geometrically increasing intervals. The first argument | |
168e428f PH |
22820 | specifies a starting value for the interval, and the second a multiplier, which |
22821 | is used to increase the size of the interval at each retry. | |
9b371988 | 22822 | .next |
9b371988 | 22823 | &'H'&: retry at randomized intervals. The arguments are as for &'G'&. For each |
068aaea8 | 22824 | retry, the previous interval is multiplied by the factor in order to get a |
f89d2485 | 22825 | maximum for the next interval. The minimum interval is the first argument of |
068aaea8 PH |
22826 | the parameter, and an actual interval is chosen randomly between them. Such a |
22827 | rule has been found to be helpful in cluster configurations when all the | |
22828 | members of the cluster restart at once, and may therefore synchronize their | |
22829 | queue processing times. | |
9b371988 | 22830 | .endlist |
068aaea8 | 22831 | |
168e428f PH |
22832 | When computing the next retry time, the algorithm definitions are scanned in |
22833 | order until one whose cutoff time has not yet passed is reached. This is then | |
22834 | used to compute a new retry time that is later than the current time. In the | |
22835 | case of fixed interval retries, this simply means adding the interval to the | |
22836 | current time. For geometrically increasing intervals, retry intervals are | |
22837 | computed from the rule's parameters until one that is greater than the previous | |
22838 | interval is found. The main configuration variable | |
9b371988 | 22839 | .cindex "limit" "retry interval" |
f89d2485 | 22840 | .cindex "retry" "interval, maximum" |
0a4e3112 | 22841 | .oindex "&%retry_interval_max%&" |
c0712871 PH |
22842 | &%retry_interval_max%& limits the maximum interval between retries. It |
22843 | cannot be set greater than &`24h`&, which is its default value. | |
168e428f PH |
22844 | |
22845 | A single remote domain may have a number of hosts associated with it, and each | |
22846 | host may have more than one IP address. Retry algorithms are selected on the | |
22847 | basis of the domain name, but are applied to each IP address independently. If, | |
22848 | for example, a host has two IP addresses and one is unusable, Exim will | |
22849 | generate retry times for it and will not try to use it until its next retry | |
22850 | time comes. Thus the good IP address is likely to be tried first most of the | |
22851 | time. | |
22852 | ||
9b371988 | 22853 | .cindex "hints database" "use for retrying" |
168e428f PH |
22854 | Retry times are hints rather than promises. Exim does not make any attempt to |
22855 | run deliveries exactly at the computed times. Instead, a queue runner process | |
22856 | starts delivery processes for delayed messages periodically, and these attempt | |
22857 | new deliveries only for those addresses that have passed their next retry time. | |
22858 | If a new message arrives for a deferred address, an immediate delivery attempt | |
22859 | occurs only if the address has passed its retry time. In the absence of new | |
22860 | messages, the minimum time between retries is the interval between queue runner | |
22861 | processes. There is not much point in setting retry times of five minutes if | |
22862 | your queue runners happen only once an hour, unless there are a significant | |
22863 | number of incoming messages (which might be the case on a system that is | |
22864 | sending everything to a smart host, for example). | |
22865 | ||
22866 | The data in the retry hints database can be inspected by using the | |
9b371988 PH |
22867 | &'exim_dumpdb'& or &'exim_fixdb'& utility programs (see chapter |
22868 | &<<CHAPutils>>&). The latter utility can also be used to change the data. The | |
22869 | &'exinext'& utility script can be used to find out what the next retry times | |
22870 | are for the hosts associated with a particular mail domain, and also for local | |
22871 | deliveries that have been deferred. | |
168e428f PH |
22872 | |
22873 | ||
f89d2485 | 22874 | .section "Retry rule examples" "SECID164" |
168e428f | 22875 | Here are some example retry rules: |
9b371988 PH |
22876 | .code |
22877 | alice@wonderland.fict.example quota_5d F,7d,3h | |
22878 | wonderland.fict.example quota_5d | |
22879 | wonderland.fict.example * F,1h,15m; G,2d,1h,2; | |
22880 | lookingglass.fict.example * F,24h,30m; | |
22881 | * refused_A F,2h,20m; | |
22882 | * * F,2h,15m; G,16h,1h,1.5; F,5d,8h | |
22883 | .endd | |
168e428f | 22884 | The first rule sets up special handling for mail to |
9b371988 | 22885 | &'alice@wonderland.fict.example'& when there is an over-quota error and the |
168e428f PH |
22886 | mailbox has not been read for at least 5 days. Retries continue every three |
22887 | hours for 7 days. The second rule handles over-quota errors for all other local | |
9b371988 PH |
22888 | parts at &'wonderland.fict.example'&; the absence of a local part has the same |
22889 | effect as supplying &"*@"&. As no retry algorithms are supplied, messages that | |
168e428f PH |
22890 | fail are bounced immediately if the mailbox has not been read for at least 5 |
22891 | days. | |
22892 | ||
9b371988 | 22893 | The third rule handles all other errors at &'wonderland.fict.example'&; retries |
168e428f PH |
22894 | happen every 15 minutes for an hour, then with geometrically increasing |
22895 | intervals until two days have passed since a delivery first failed. After the | |
22896 | first hour there is a delay of one hour, then two hours, then four hours, and | |
22897 | so on (this is a rather extreme example). | |
22898 | ||
9b371988 | 22899 | The fourth rule controls retries for the domain &'lookingglass.fict.example'&. |
168e428f PH |
22900 | They happen every 30 minutes for 24 hours only. The remaining two rules handle |
22901 | all other domains, with special action for connection refusal from hosts that | |
22902 | were not obtained from an MX record. | |
22903 | ||
22904 | The final rule in a retry configuration should always have asterisks in the | |
22905 | first two fields so as to provide a general catch-all for any addresses that do | |
22906 | not have their own special handling. This example tries every 15 minutes for 2 | |
22907 | hours, then with intervals starting at one hour and increasing by a factor of | |
22908 | 1.5 up to 16 hours, then every 8 hours up to 5 days. | |
22909 | ||
22910 | ||
22911 | ||
f89d2485 | 22912 | .section "Timeout of retry data" "SECID165" |
9b371988 | 22913 | .cindex "timeout" "of retry data" |
0a4e3112 | 22914 | .oindex "&%retry_data_expire%&" |
9b371988 PH |
22915 | .cindex "hints database" "data expiry" |
22916 | .cindex "retry" "timeout of data" | |
168e428f PH |
22917 | Exim timestamps the data that it writes to its retry hints database. When it |
22918 | consults the data during a delivery it ignores any that is older than the value | |
9b371988 | 22919 | set in &%retry_data_expire%& (default 7 days). If, for example, a host hasn't |
168e428f PH |
22920 | been tried for 7 days, Exim will try to deliver to it immediately a message |
22921 | arrives, and if that fails, it will calculate a retry time as if it were | |
22922 | failing for the first time. | |
22923 | ||
22924 | This improves the behaviour for messages routed to rarely-used hosts such as MX | |
22925 | backups. If such a host was down at one time, and happens to be down again when | |
22926 | Exim tries a month later, using the old retry data would imply that it had been | |
22927 | down all the time, which is not a justified assumption. | |
22928 | ||
22929 | If a host really is permanently dead, this behaviour causes a burst of retries | |
3cb1b51e | 22930 | every now and again, but only if messages routed to it are rare. If there is a |
168e428f PH |
22931 | message at least once every 7 days the retry data never expires. |
22932 | ||
22933 | ||
22934 | ||
22935 | ||
f89d2485 PH |
22936 | .section "Long-term failures" "SECID166" |
22937 | .cindex "delivery failure, long-term" | |
9b371988 | 22938 | .cindex "retry" "after long-term failure" |
168e428f PH |
22939 | Special processing happens when an email address has been failing for so long |
22940 | that the cutoff time for the last algorithm is reached. For example, using the | |
22941 | default retry rule: | |
9b371988 | 22942 | .code |
168e428f | 22943 | * * F,2h,15m; G,16h,1h,1.5; F,4d,6h |
9b371988 | 22944 | .endd |
168e428f PH |
22945 | the cutoff time is four days. Reaching the retry cutoff is independent of how |
22946 | long any specific message has been failing; it is the length of continuous | |
22947 | failure for the recipient address that counts. | |
22948 | ||
22949 | When the cutoff time is reached for a local delivery, or for all the IP | |
22950 | addresses associated with a remote delivery, a subsequent delivery failure | |
22951 | causes Exim to give up on the address, and a bounce message is generated. | |
22952 | In order to cater for new messages that use the failing address, a next retry | |
22953 | time is still computed from the final algorithm, and is used as follows: | |
22954 | ||
22955 | For local deliveries, one delivery attempt is always made for any subsequent | |
22956 | messages. If this delivery fails, the address fails immediately. The | |
22957 | post-cutoff retry time is not used. | |
22958 | ||
22959 | If the delivery is remote, there are two possibilities, controlled by the | |
0a4e3112 | 22960 | .oindex "&%delay_after_cutoff%&" |
9b371988 | 22961 | &%delay_after_cutoff%& option of the &(smtp)& transport. The option is true by |
168e428f PH |
22962 | default. Until the post-cutoff retry time for one of the IP addresses is |
22963 | reached, the failing email address is bounced immediately, without a delivery | |
22964 | attempt taking place. After that time, one new delivery attempt is made to | |
22965 | those IP addresses that are past their retry times, and if that still fails, | |
22966 | the address is bounced and new retry times are computed. | |
22967 | ||
22968 | In other words, when all the hosts for a given email address have been failing | |
22969 | for a long time, Exim bounces rather then defers until one of the hosts' retry | |
22970 | times is reached. Then it tries once, and bounces if that attempt fails. This | |
22971 | behaviour ensures that few resources are wasted in repeatedly trying to deliver | |
22972 | to a broken destination, but if the host does recover, Exim will eventually | |
22973 | notice. | |
22974 | ||
9b371988 | 22975 | If &%delay_after_cutoff%& is set false, Exim behaves differently. If all IP |
168e428f PH |
22976 | addresses are past their final cutoff time, Exim tries to deliver to those IP |
22977 | addresses that have not been tried since the message arrived. If there are | |
22978 | no suitable IP addresses, or if they all fail, the address is bounced. In other | |
22979 | words, it does not delay when a new message arrives, but tries the expired | |
22980 | addresses immediately, unless they have been tried since the message arrived. | |
22981 | If there is a continuous stream of messages for the failing domains, setting | |
9b371988 PH |
22982 | &%delay_after_cutoff%& false means that there will be many more attempts to |
22983 | deliver to permanently failing IP addresses than when &%delay_after_cutoff%& is | |
168e428f PH |
22984 | true. |
22985 | ||
f89d2485 | 22986 | .section "Deliveries that work intermittently" "SECID167" |
4f578862 PH |
22987 | .cindex "retry" "intermittently working deliveries" |
22988 | Some additional logic is needed to cope with cases where a host is | |
22989 | intermittently available, or when a message has some attribute that prevents | |
22990 | its delivery when others to the same address get through. In this situation, | |
22991 | because some messages are successfully delivered, the &"retry clock"& for the | |
c0712871 PH |
22992 | host or address keeps getting reset by the successful deliveries, and so |
22993 | failing messages remain on the queue for ever because the cutoff time is never | |
22994 | reached. | |
22995 | ||
22996 | Two exceptional actions are applied to prevent this happening. The first | |
22997 | applies to errors that are related to a message rather than a remote host. | |
22998 | Section &<<SECToutSMTPerr>>& has a discussion of the different kinds of error; | |
22999 | examples of message-related errors are 4&'xx'& responses to MAIL or DATA | |
23000 | commands, and quota failures. For this type of error, if a message's arrival | |
23001 | time is earlier than the &"first failed"& time for the error, the earlier time | |
23002 | is used when scanning the retry rules to decide when to try next and when to | |
23003 | time out the address. | |
23004 | ||
23005 | The exceptional second action applies in all cases. If a message has been on | |
23006 | the queue for longer than the cutoff time of any applicable retry rule for a | |
23007 | given address, a delivery is attempted for that address, even if it is not yet | |
23008 | time, and if this delivery fails, the address is timed out. A new retry time is | |
23009 | not computed in this case, so that other messages for the same address are | |
23010 | considered immediately. | |
4f578862 PH |
23011 | .ecindex IIDretconf1 |
23012 | .ecindex IIDregconf2 | |
168e428f | 23013 | |
168e428f PH |
23014 | |
23015 | ||
23016 | ||
23017 | ||
23018 | ||
9b371988 PH |
23019 | . //////////////////////////////////////////////////////////////////////////// |
23020 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 23021 | |
9b371988 | 23022 | .chapter "SMTP authentication" "CHAPSMTPAUTH" |
4f578862 PH |
23023 | .scindex IIDauthconf1 "SMTP" "authentication configuration" |
23024 | .scindex IIDauthconf2 "authentication" | |
9b371988 PH |
23025 | The &"authenticators"& section of Exim's run time configuration is concerned |
23026 | with SMTP authentication. This facility is an extension to the SMTP protocol, | |
168e428f | 23027 | described in RFC 2554, which allows a client SMTP host to authenticate itself |
9b371988 PH |
23028 | to a server. This is a common way for a server to recognize clients that are |
23029 | permitted to use it as a relay. SMTP authentication is not of relevance to the | |
23030 | transfer of mail between servers that have no managerial connection with each | |
23031 | other. | |
168e428f | 23032 | |
9b371988 | 23033 | .cindex "AUTH" "description of" |
168e428f PH |
23034 | Very briefly, the way SMTP authentication works is as follows: |
23035 | ||
9b371988 PH |
23036 | .ilist |
23037 | The server advertises a number of authentication &'mechanisms'& in response to | |
168e428f | 23038 | the client's EHLO command. |
9b371988 PH |
23039 | .next |
23040 | The client issues an AUTH command, naming a specific mechanism. The command | |
168e428f | 23041 | may, optionally, contain some authentication data. |
9b371988 PH |
23042 | .next |
23043 | The server may issue one or more &'challenges'&, to which the client must send | |
168e428f PH |
23044 | appropriate responses. In simple authentication mechanisms, the challenges are |
23045 | just prompts for user names and passwords. The server does not have to issue | |
9b371988 | 23046 | any challenges &-- in some mechanisms the relevant data may all be transmitted |
168e428f | 23047 | with the AUTH command. |
9b371988 PH |
23048 | .next |
23049 | The server either accepts or denies authentication. | |
23050 | .next | |
23051 | If authentication succeeds, the client may optionally make use of the AUTH | |
168e428f PH |
23052 | option on the MAIL command to pass an authenticated sender in subsequent |
23053 | mail transactions. Authentication lasts for the remainder of the SMTP | |
23054 | connection. | |
9b371988 PH |
23055 | .next |
23056 | If authentication fails, the client may give up, or it may try a different | |
168e428f PH |
23057 | authentication mechanism, or it may try transferring mail over the |
23058 | unauthenticated connection. | |
9b371988 | 23059 | .endlist |
168e428f PH |
23060 | |
23061 | If you are setting up a client, and want to know which authentication | |
23062 | mechanisms the server supports, you can use Telnet to connect to port 25 (the | |
23063 | SMTP port) on the server, and issue an EHLO command. The response to this | |
23064 | includes the list of supported mechanisms. For example: | |
9b371988 PH |
23065 | .display |
23066 | &`$ `&&*&`telnet server.example 25`&*& | |
23067 | &`Trying 192.168.34.25...`& | |
23068 | &`Connected to server.example.`& | |
595028e4 | 23069 | &`Escape character is '^]'.`& |
9b371988 PH |
23070 | &`220 server.example ESMTP Exim 4.20 ...`& |
23071 | &*&`ehlo client.example`&*& | |
23072 | &`250-server.example Hello client.example [10.8.4.5]`& | |
23073 | &`250-SIZE 52428800`& | |
23074 | &`250-PIPELINING`& | |
23075 | &`250-AUTH PLAIN`& | |
23076 | &`250 HELP`& | |
23077 | .endd | |
168e428f PH |
23078 | The second-last line of this example output shows that the server supports |
23079 | authentication using the PLAIN mechanism. In Exim, the different authentication | |
9b371988 | 23080 | mechanisms are configured by specifying &'authenticator'& drivers. Like the |
168e428f PH |
23081 | routers and transports, which authenticators are included in the binary is |
23082 | controlled by build-time definitions. The following are currently available, | |
23083 | included by setting | |
9b371988 PH |
23084 | .code |
23085 | AUTH_CRAM_MD5=yes | |
23086 | AUTH_CYRUS_SASL=yes | |
23087 | AUTH_PLAINTEXT=yes | |
23088 | AUTH_SPA=yes | |
23089 | .endd | |
23090 | in &_Local/Makefile_&, respectively. The first of these supports the CRAM-MD5 | |
068aaea8 PH |
23091 | authentication mechanism (RFC 2195), and the second provides an interface to |
23092 | the Cyrus SASL authentication library. The third can be configured to support | |
23093 | the PLAIN authentication mechanism (RFC 2595) or the LOGIN mechanism, which is | |
23094 | not formally documented, but used by several MUAs. The fourth authenticator | |
9b371988 | 23095 | supports Microsoft's &'Secure Password Authentication'& mechanism. |
168e428f PH |
23096 | |
23097 | The authenticators are configured using the same syntax as other drivers (see | |
9b371988 PH |
23098 | section &<<SECTfordricon>>&). If no authenticators are required, no |
23099 | authentication section need be present in the configuration file. Each | |
23100 | authenticator can in principle have both server and client functions. When Exim | |
23101 | is receiving SMTP mail, it is acting as a server; when it is sending out | |
23102 | messages over SMTP, it is acting as a client. Authenticator configuration | |
23103 | options are provided for use in both these circumstances. | |
168e428f PH |
23104 | |
23105 | To make it clear which options apply to which situation, the prefixes | |
9b371988 PH |
23106 | &%server_%& and &%client_%& are used on option names that are specific to |
23107 | either the server or the client function, respectively. Server and client | |
23108 | functions are disabled if none of their options are set. If an authenticator is | |
23109 | to be used for both server and client functions, a single definition, using | |
23110 | both sets of options, is required. For example: | |
23111 | .code | |
23112 | cram: | |
23113 | driver = cram_md5 | |
23114 | public_name = CRAM-MD5 | |
4f578862 | 23115 | server_secret = ${if eq{$auth1}{ph10}{secret1}fail} |
9b371988 PH |
23116 | client_name = ph10 |
23117 | client_secret = secret2 | |
23118 | .endd | |
23119 | The &%server_%& option is used when Exim is acting as a server, and the | |
23120 | &%client_%& options when it is acting as a client. | |
168e428f PH |
23121 | |
23122 | Descriptions of the individual authenticators are given in subsequent chapters. | |
23123 | The remainder of this chapter covers the generic options for the | |
23124 | authenticators, followed by general discussion of the way authentication works | |
23125 | in Exim. | |
23126 | ||
23127 | ||
23128 | ||
f89d2485 | 23129 | .section "Generic options for authenticators" "SECID168" |
9b371988 PH |
23130 | .cindex "authentication" "generic options" |
23131 | .cindex "options" "generic; for authenticators" | |
168e428f | 23132 | |
595028e4 PH |
23133 | .option client_condition authenticators string&!! unset |
23134 | When Exim is authenticating as a client, it skips any authenticator whose | |
23135 | &%client_condition%& expansion yields &"0"&, &"no"&, or &"false"&. This can be | |
23136 | used, for example, to skip plain text authenticators when the connection is not | |
23137 | encrypted by a setting such as: | |
23138 | .code | |
23139 | client_condition = ${if !eq{$tls_cipher}{}} | |
23140 | .endd | |
23141 | (Older documentation incorrectly states that &$tls_cipher$& contains the cipher | |
23142 | used for incoming messages. In fact, during SMTP delivery, it contains the | |
23143 | cipher used for the delivery.) | |
595028e4 | 23144 | |
168e428f | 23145 | |
9b371988 | 23146 | .option driver authenticators string unset |
168e428f PH |
23147 | This option must always be set. It specifies which of the available |
23148 | authenticators is to be used. | |
23149 | ||
23150 | ||
9b371988 | 23151 | .option public_name authenticators string unset |
168e428f PH |
23152 | This option specifies the name of the authentication mechanism that the driver |
23153 | implements, and by which it is known to the outside world. These names should | |
23154 | contain only upper case letters, digits, underscores, and hyphens (RFC 2222), | |
9b371988 | 23155 | but Exim in fact matches them caselessly. If &%public_name%& is not set, it |
168e428f PH |
23156 | defaults to the driver's instance name. |
23157 | ||
23158 | ||
9b371988 | 23159 | .option server_advertise_condition authenticators string&!! unset |
168e428f | 23160 | When a server is about to advertise an authentication mechanism, the condition |
9b371988 | 23161 | is expanded. If it yields the empty string, &"0"&, &"no"&, or &"false"&, the |
168e428f PH |
23162 | mechanism is not advertised. |
23163 | If the expansion fails, the mechanism is not advertised. If the failure was not | |
23164 | forced, and was not caused by a lookup defer, the incident is logged. | |
9b371988 | 23165 | See section &<<SECTauthexiser>>& below for further discussion. |
168e428f | 23166 | |
168e428f | 23167 | |
3cb1b51e PH |
23168 | .option server_condition authenticators string&!! unset |
23169 | This option must be set for a &%plaintext%& server authenticator, where it | |
23170 | is used directly to control authentication. See section &<<SECTplainserver>>& | |
23171 | for details. | |
23172 | ||
23173 | For the other authenticators, &%server_condition%& can be used as an additional | |
23174 | authentication or authorization mechanism that is applied after the other | |
23175 | authenticator conditions succeed. If it is set, it is expanded when the | |
23176 | authenticator would otherwise return a success code. If the expansion is forced | |
23177 | to fail, authentication fails. Any other expansion failure causes a temporary | |
23178 | error code to be returned. If the result of a successful expansion is an empty | |
23179 | string, &"0"&, &"no"&, or &"false"&, authentication fails. If the result of the | |
23180 | expansion is &"1"&, &"yes"&, or &"true"&, authentication succeeds. For any | |
23181 | other result, a temporary error code is returned, with the expanded string as | |
23182 | the error text. | |
3cb1b51e PH |
23183 | |
23184 | ||
9b371988 PH |
23185 | .option server_debug_print authenticators string&!! unset |
23186 | If this option is set and authentication debugging is enabled (see the &%-d%& | |
168e428f PH |
23187 | command line option), the string is expanded and included in the debugging |
23188 | output when the authenticator is run as a server. This can help with checking | |
23189 | out the values of variables. | |
23190 | If expansion of the string fails, the error message is written to the debugging | |
23191 | output, and Exim carries on processing. | |
23192 | ||
23193 | ||
9b371988 | 23194 | .option server_set_id authenticators string&!! unset |
f89d2485 | 23195 | .vindex "&$authenticated_id$&" |
168e428f PH |
23196 | When an Exim server successfully authenticates a client, this string is |
23197 | expanded using data from the authentication, and preserved for any incoming | |
9b371988 | 23198 | messages in the variable &$authenticated_id$&. It is also included in the log |
168e428f PH |
23199 | lines for incoming messages. For example, a user/password authenticator |
23200 | configuration might preserve the user name that was used to authenticate, and | |
23201 | refer to it subsequently during delivery of the message. | |
23202 | If expansion fails, the option is ignored. | |
23203 | ||
23204 | ||
9b371988 | 23205 | .option server_mail_auth_condition authenticators string&!! unset |
168e428f PH |
23206 | This option allows a server to discard authenticated sender addresses supplied |
23207 | as part of MAIL commands in SMTP connections that are authenticated by the | |
9b371988 | 23208 | driver on which &%server_mail_auth_condition%& is set. The option is not used |
168e428f PH |
23209 | as part of the authentication process; instead its (unexpanded) value is |
23210 | remembered for later use. | |
23211 | How it is used is described in the following section. | |
23212 | ||
23213 | ||
23214 | ||
23215 | ||
23216 | ||
9b371988 PH |
23217 | .section "The AUTH parameter on MAIL commands" "SECTauthparamail" |
23218 | .cindex "authentication" "sender; authenticated" | |
23219 | .cindex "AUTH" "on MAIL command" | |
168e428f PH |
23220 | When a client supplied an AUTH= item on a MAIL command, Exim applies |
23221 | the following checks before accepting it as the authenticated sender of the | |
23222 | message: | |
23223 | ||
9b371988 PH |
23224 | .ilist |
23225 | If the connection is not using extended SMTP (that is, HELO was used rather | |
168e428f | 23226 | than EHLO), the use of AUTH= is a syntax error. |
9b371988 PH |
23227 | .next |
23228 | If the value of the AUTH= parameter is &"<>"&, it is ignored. | |
23229 | .next | |
f89d2485 | 23230 | .vindex "&$authenticated_sender$&" |
9b371988 PH |
23231 | If &%acl_smtp_mailauth%& is defined, the ACL it specifies is run. While it is |
23232 | running, the value of &$authenticated_sender$& is set to the value obtained | |
23233 | from the AUTH= parameter. If the ACL does not yield &"accept"&, the value of | |
23234 | &$authenticated_sender$& is deleted. The &%acl_smtp_mailauth%& ACL may not | |
23235 | return &"drop"& or &"discard"&. If it defers, a temporary error code (451) is | |
23236 | given for the MAIL command. | |
23237 | .next | |
23238 | If &%acl_smtp_mailauth%& is not defined, the value of the AUTH= parameter | |
23239 | is accepted and placed in &$authenticated_sender$& only if the client has | |
168e428f | 23240 | authenticated. |
9b371988 PH |
23241 | .next |
23242 | If the AUTH= value was accepted by either of the two previous rules, and | |
168e428f | 23243 | the client has authenticated, and the authenticator has a setting for the |
9b371988 | 23244 | &%server_mail_auth_condition%&, the condition is checked at this point. The |
168e428f | 23245 | valued that was saved from the authenticator is expanded. If the expansion |
9b371988 PH |
23246 | fails, or yields an empty string, &"0"&, &"no"&, or &"false"&, the value of |
23247 | &$authenticated_sender$& is deleted. If the expansion yields any other value, | |
23248 | the value of &$authenticated_sender$& is retained and passed on with the | |
168e428f | 23249 | message. |
9b371988 | 23250 | .endlist |
168e428f PH |
23251 | |
23252 | ||
9b371988 | 23253 | When &$authenticated_sender$& is set for a message, it is passed on to other |
168e428f | 23254 | hosts to which Exim authenticates as a client. Do not confuse this value with |
9b371988 | 23255 | &$authenticated_id$&, which is a string obtained from the authentication |
168e428f PH |
23256 | process, and which is not usually a complete email address. |
23257 | ||
f89d2485 | 23258 | .vindex "&$sender_address$&" |
168e428f PH |
23259 | Whenever an AUTH= value is ignored, the incident is logged. The ACL for |
23260 | MAIL, if defined, is run after AUTH= is accepted or ignored. It can | |
9b371988 PH |
23261 | therefore make use of &$authenticated_sender$&. The converse is not true: the |
23262 | value of &$sender_address$& is not yet set up when the &%acl_smtp_mailauth%& | |
168e428f PH |
23263 | ACL is run. |
23264 | ||
23265 | ||
23266 | ||
9b371988 PH |
23267 | .section "Authentication on an Exim server" "SECTauthexiser" |
23268 | .cindex "authentication" "on an Exim server" | |
168e428f PH |
23269 | When Exim receives an EHLO command, it advertises the public names of those |
23270 | authenticators that are configured as servers, subject to the following | |
23271 | conditions: | |
23272 | ||
9b371988 PH |
23273 | .ilist |
23274 | The client host must match &%auth_advertise_hosts%& (default *). | |
23275 | .next | |
23276 | It the &%server_advertise_condition%& option is set, its expansion must not | |
23277 | yield the empty string, &"0"&, &"no"&, or &"false"&. | |
23278 | .endlist | |
168e428f PH |
23279 | |
23280 | The order in which the authenticators are defined controls the order in which | |
23281 | the mechanisms are advertised. | |
23282 | ||
23283 | Some mail clients (for example, some versions of Netscape) require the user to | |
23284 | provide a name and password for authentication whenever AUTH is advertised, | |
23285 | even though authentication may not in fact be needed (for example, Exim may be | |
23286 | set up to allow unconditional relaying from the client by an IP address check). | |
23287 | You can make such clients more friendly by not advertising AUTH to them. | |
23288 | For example, if clients on the 10.9.8.0/24 network are permitted (by the ACL | |
23289 | that runs for RCPT) to relay without authentication, you should set | |
9b371988 PH |
23290 | .code |
23291 | auth_advertise_hosts = ! 10.9.8.0/24 | |
23292 | .endd | |
168e428f PH |
23293 | so that no authentication mechanisms are advertised to them. |
23294 | ||
9b371988 | 23295 | The &%server_advertise_condition%& controls the advertisement of individual |
168e428f | 23296 | authentication mechanisms. For example, it can be used to restrict the |
f89d2485 | 23297 | advertisement of a particular mechanism to encrypted connections, by a setting |
168e428f | 23298 | such as: |
9b371988 PH |
23299 | .code |
23300 | server_advertise_condition = ${if eq{$tls_cipher}{}{no}{yes}} | |
23301 | .endd | |
f89d2485 | 23302 | .vindex "&$tls_cipher$&" |
9b371988 PH |
23303 | If the session is encrypted, &$tls_cipher$& is not empty, and so the expansion |
23304 | yields &"yes"&, which allows the advertisement to happen. | |
168e428f PH |
23305 | |
23306 | When an Exim server receives an AUTH command from a client, it rejects it | |
23307 | immediately if AUTH was not advertised in response to an earlier EHLO | |
23308 | command. This is the case if | |
23309 | ||
9b371988 PH |
23310 | .ilist |
23311 | The client host does not match &%auth_advertise_hosts%&; or | |
23312 | .next | |
23313 | No authenticators are configured with server options; or | |
23314 | .next | |
23315 | Expansion of &%server_advertise_condition%& blocked the advertising of all the | |
168e428f | 23316 | server authenticators. |
9b371988 | 23317 | .endlist |
168e428f PH |
23318 | |
23319 | ||
9b371988 PH |
23320 | Otherwise, Exim runs the ACL specified by &%acl_smtp_auth%& in order |
23321 | to decide whether to accept the command. If &%acl_smtp_auth%& is not set, | |
168e428f PH |
23322 | AUTH is accepted from any client host. |
23323 | ||
23324 | If AUTH is not rejected by the ACL, Exim searches its configuration for a | |
23325 | server authentication mechanism that was advertised in response to EHLO and | |
23326 | that matches the one named in the AUTH command. If it finds one, it runs | |
23327 | the appropriate authentication protocol, and authentication either succeeds or | |
23328 | fails. If there is no matching advertised mechanism, the AUTH command is | |
23329 | rejected with a 504 error. | |
23330 | ||
f89d2485 PH |
23331 | .vindex "&$received_protocol$&" |
23332 | .vindex "&$sender_host_authenticated$&" | |
168e428f | 23333 | When a message is received from an authenticated host, the value of |
9b371988 PH |
23334 | &$received_protocol$& is set to &"esmtpa"& or &"esmtpsa"& instead of &"esmtp"& |
23335 | or &"esmtps"&, and &$sender_host_authenticated$& contains the name (not the | |
23336 | public name) of the authenticator driver that successfully authenticated the | |
23337 | client from which the message was received. This variable is empty if there was | |
23338 | no successful authentication. | |
168e428f PH |
23339 | |
23340 | ||
23341 | ||
23342 | ||
f89d2485 | 23343 | .section "Testing server authentication" "SECID169" |
9b371988 PH |
23344 | .cindex "authentication" "testing a server" |
23345 | .cindex "AUTH" "testing a server" | |
23346 | .cindex "base64 encoding" "creating authentication test data" | |
23347 | Exim's &%-bh%& option can be useful for testing server authentication | |
168e428f PH |
23348 | configurations. The data for the AUTH command has to be sent using base64 |
23349 | encoding. A quick way to produce such data for testing is the following Perl | |
23350 | script: | |
9b371988 PH |
23351 | .code |
23352 | use MIME::Base64; | |
23353 | printf ("%s", encode_base64(eval "\"$ARGV[0]\"")); | |
23354 | .endd | |
23355 | .cindex "binary zero" "in authentication data" | |
168e428f PH |
23356 | This interprets its argument as a Perl string, and then encodes it. The |
23357 | interpretation as a Perl string allows binary zeros, which are required for | |
23358 | some kinds of authentication, to be included in the data. For example, a | |
23359 | command line to run this script on such data might be | |
9b371988 PH |
23360 | .code |
23361 | encode '\0user\0password' | |
23362 | .endd | |
168e428f PH |
23363 | Note the use of single quotes to prevent the shell interpreting the |
23364 | backslashes, so that they can be interpreted by Perl to specify characters | |
23365 | whose code value is zero. | |
23366 | ||
9b371988 | 23367 | &*Warning 1*&: If either of the user or password strings starts with an octal |
168e428f PH |
23368 | digit, you must use three zeros instead of one after the leading backslash. If |
23369 | you do not, the octal digit that starts your string will be incorrectly | |
23370 | interpreted as part of the code for the first character. | |
23371 | ||
9b371988 | 23372 | &*Warning 2*&: If there are characters in the strings that Perl interprets |
168e428f PH |
23373 | specially, you must use a Perl escape to prevent them being misinterpreted. For |
23374 | example, a command such as | |
9b371988 PH |
23375 | .code |
23376 | encode '\0user@domain.com\0pas$$word' | |
23377 | .endd | |
23378 | gives an incorrect answer because of the unescaped &"@"& and &"$"& characters. | |
168e428f | 23379 | |
9b371988 | 23380 | If you have the &%mimencode%& command installed, another way to do produce |
168e428f | 23381 | base64-encoded strings is to run the command |
9b371988 PH |
23382 | .code |
23383 | echo -e -n `\0user\0password' | mimencode | |
23384 | .endd | |
23385 | The &%-e%& option of &%echo%& enables the interpretation of backslash escapes | |
23386 | in the argument, and the &%-n%& option specifies no newline at the end of its | |
23387 | output. However, not all versions of &%echo%& recognize these options, so you | |
168e428f PH |
23388 | should check your version before relying on this suggestion. |
23389 | ||
23390 | ||
23391 | ||
f89d2485 | 23392 | .section "Authentication by an Exim client" "SECID170" |
9b371988 PH |
23393 | .cindex "authentication" "on an Exim client" |
23394 | The &(smtp)& transport has two options called &%hosts_require_auth%& and | |
23395 | &%hosts_try_auth%&. When the &(smtp)& transport connects to a server that | |
168e428f PH |
23396 | announces support for authentication, and the host matches an entry in either |
23397 | of these options, Exim (as a client) tries to authenticate as follows: | |
23398 | ||
9b371988 | 23399 | .ilist |
f89d2485 PH |
23400 | For each authenticator that is configured as a client, in the order in which |
23401 | they are defined in the configuration, it searches the authentication | |
23402 | mechanisms announced by the server for one whose name matches the public name | |
23403 | of the authenticator. | |
f89d2485 PH |
23404 | .next |
23405 | .vindex "&$host$&" | |
23406 | .vindex "&$host_address$&" | |
23407 | When it finds one that matches, it runs the authenticator's client code. The | |
23408 | variables &$host$& and &$host_address$& are available for any string expansions | |
23409 | that the client might do. They are set to the server's name and IP address. If | |
23410 | any expansion is forced to fail, the authentication attempt is abandoned, and | |
23411 | Exim moves on to the next authenticator. Otherwise an expansion failure causes | |
23412 | delivery to be deferred. | |
9b371988 PH |
23413 | .next |
23414 | If the result of the authentication attempt is a temporary error or a timeout, | |
168e428f PH |
23415 | Exim abandons trying to send the message to the host for the moment. It will |
23416 | try again later. If there are any backup hosts available, they are tried in the | |
23417 | usual way. | |
9b371988 PH |
23418 | .next |
23419 | If the response to authentication is a permanent error (5&'xx'& code), Exim | |
23420 | carries on searching the list of authenticators and tries another one if | |
23421 | possible. If all authentication attempts give permanent errors, or if there are | |
23422 | no attempts because no mechanisms match (or option expansions force failure), | |
23423 | what happens depends on whether the host matches &%hosts_require_auth%& or | |
23424 | &%hosts_try_auth%&. In the first case, a temporary error is generated, and | |
168e428f PH |
23425 | delivery is deferred. The error can be detected in the retry rules, and thereby |
23426 | turned into a permanent error if you wish. In the second case, Exim tries to | |
23427 | deliver the message unauthenticated. | |
9b371988 | 23428 | .endlist |
168e428f | 23429 | |
9b371988 | 23430 | .cindex "AUTH" "on MAIL command" |
168e428f | 23431 | When Exim has authenticated itself to a remote server, it adds the AUTH |
9b371988 PH |
23432 | parameter to the MAIL commands it sends, if it has an authenticated sender for |
23433 | the message. If the message came from a remote host, the authenticated sender | |
23434 | is the one that was receiving on an incoming MAIL command, provided that the | |
23435 | incoming connection was authenticated and the &%server_mail_auth%& condition | |
23436 | allowed the authenticated sender to be retained. If a local process calls Exim | |
23437 | to send a message, the sender address that is built from the login name and | |
23438 | &%qualify_domain%& is treated as authenticated. However, if the | |
23439 | &%authenticated_sender%& option is set on the &(smtp)& transport, it overrides | |
168e428f | 23440 | the authenticated sender that was received with the message. |
4f578862 PH |
23441 | .ecindex IIDauthconf1 |
23442 | .ecindex IIDauthconf2 | |
168e428f PH |
23443 | |
23444 | ||
23445 | ||
23446 | ||
23447 | ||
23448 | ||
9b371988 PH |
23449 | . //////////////////////////////////////////////////////////////////////////// |
23450 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 23451 | |
9b371988 | 23452 | .chapter "The plaintext authenticator" "CHAPplaintext" |
4f578862 PH |
23453 | .scindex IIDplaiauth1 "&(plaintext)& authenticator" |
23454 | .scindex IIDplaiauth2 "authenticators" "&(plaintext)&" | |
9b371988 | 23455 | The &(plaintext)& authenticator can be configured to support the PLAIN and |
168e428f PH |
23456 | LOGIN authentication mechanisms, both of which transfer authentication data as |
23457 | plain (unencrypted) text (though base64 encoded). The use of plain text is a | |
4f578862 PH |
23458 | security risk; you are strongly advised to insist on the use of SMTP encryption |
23459 | (see chapter &<<CHAPTLS>>&) if you use the PLAIN or LOGIN mechanisms. If you do | |
23460 | use unencrypted plain text, you should not use the same passwords for SMTP | |
23461 | connections as you do for login accounts. | |
168e428f | 23462 | |
f89d2485 | 23463 | .section "Plaintext options" "SECID171" |
9b371988 | 23464 | .cindex "options" "&(plaintext)& authenticator (server)" |
3cb1b51e PH |
23465 | When configured as a server, &(plaintext)& uses the following options: |
23466 | ||
23467 | .option server_condition authenticators string&!! unset | |
23468 | This is actually a global authentication option, but it must be set in order to | |
23469 | configure the &(plaintext)& driver as a server. Its use is described below. | |
168e428f | 23470 | |
9b371988 | 23471 | .option server_prompts plaintext string&!! unset |
168e428f PH |
23472 | The contents of this option, after expansion, must be a colon-separated list of |
23473 | prompt strings. If expansion fails, a temporary authentication rejection is | |
23474 | given. | |
23475 | ||
3cb1b51e | 23476 | .section "Using plaintext in a server" "SECTplainserver" |
9b371988 PH |
23477 | .cindex "AUTH" "in &(plaintext)& authenticator" |
23478 | .cindex "binary zero" "in &(plaintext)& authenticator" | |
23479 | .cindex "numerical variables (&$1$& &$2$& etc)" &&& | |
23480 | "in &(plaintext)& authenticator" | |
f89d2485 | 23481 | .vindex "&$auth1$&, &$auth2$&, etc" |
9b371988 | 23482 | .cindex "base64 encoding" "in &(plaintext)& authenticator" |
3cb1b51e PH |
23483 | |
23484 | When running as a server, &(plaintext)& performs the authentication test by | |
23485 | expanding a string. The data sent by the client with the AUTH command, or in | |
23486 | response to subsequent prompts, is base64 encoded, and so may contain any byte | |
23487 | values when decoded. If any data is supplied with the command, it is treated as | |
23488 | a list of strings, separated by NULs (binary zeros), the first three of which | |
23489 | are placed in the expansion variables &$auth1$&, &$auth2$&, and &$auth3$& | |
23490 | (neither LOGIN nor PLAIN uses more than three strings). | |
4f578862 PH |
23491 | |
23492 | For compatibility with previous releases of Exim, the values are also placed in | |
23493 | the expansion variables &$1$&, &$2$&, and &$3$&. However, the use of these | |
23494 | variables for this purpose is now deprecated, as it can lead to confusion in | |
23495 | string expansions that also use them for other things. | |
4f578862 PH |
23496 | |
23497 | If there are more strings in &%server_prompts%& than the number of strings | |
23498 | supplied with the AUTH command, the remaining prompts are used to obtain more | |
23499 | data. Each response from the client may be a list of NUL-separated strings. | |
168e428f | 23500 | |
f89d2485 | 23501 | .vindex "&$authenticated_id$&" |
9b371988 PH |
23502 | Once a sufficient number of data strings have been received, |
23503 | &%server_condition%& is expanded. If the expansion is forced to fail, | |
23504 | authentication fails. Any other expansion failure causes a temporary error code | |
23505 | to be returned. If the result of a successful expansion is an empty string, | |
23506 | &"0"&, &"no"&, or &"false"&, authentication fails. If the result of the | |
23507 | expansion is &"1"&, &"yes"&, or &"true"&, authentication succeeds and the | |
23508 | generic &%server_set_id%& option is expanded and saved in &$authenticated_id$&. | |
23509 | For any other result, a temporary error code is returned, with the expanded | |
23510 | string as the error text. | |
23511 | ||
23512 | &*Warning*&: If you use a lookup in the expansion to find the user's | |
168e428f PH |
23513 | password, be sure to make the authentication fail if the user is unknown. |
23514 | There are good and bad examples at the end of the next section. | |
23515 | ||
23516 | ||
23517 | ||
f89d2485 | 23518 | .section "The PLAIN authentication mechanism" "SECID172" |
9b371988 PH |
23519 | .cindex "PLAIN authentication mechanism" |
23520 | .cindex "authentication" "PLAIN mechanism" | |
23521 | .cindex "binary zero" "in &(plaintext)& authenticator" | |
168e428f PH |
23522 | The PLAIN authentication mechanism (RFC 2595) specifies that three strings be |
23523 | sent as one item of data (that is, one combined string containing two NUL | |
23524 | separators). The data is sent either as part of the AUTH command, or | |
23525 | subsequently in response to an empty prompt from the server. | |
23526 | ||
23527 | The second and third strings are a user name and a corresponding password. | |
23528 | Using a single fixed user name and password as an example, this could be | |
23529 | configured as follows: | |
9b371988 | 23530 | .code |
168e428f PH |
23531 | fixed_plain: |
23532 | driver = plaintext | |
23533 | public_name = PLAIN | |
23534 | server_prompts = : | |
23535 | server_condition = \ | |
db9452a9 | 23536 | ${if and {{eq{$auth2}{username}}{eq{$auth3}{mysecret}}}} |
4f578862 | 23537 | server_set_id = $auth2 |
9b371988 | 23538 | .endd |
db9452a9 PH |
23539 | Note that the default result strings from &%if%& (&"true"& or an empty string) |
23540 | are exactly what we want here, so they need not be specified. Obviously, if the | |
23541 | password contains expansion-significant characters such as dollar, backslash, | |
23542 | or closing brace, they have to be escaped. | |
db9452a9 | 23543 | |
9b371988 | 23544 | The &%server_prompts%& setting specifies a single, empty prompt (empty items at |
168e428f PH |
23545 | the end of a string list are ignored). If all the data comes as part of the |
23546 | AUTH command, as is commonly the case, the prompt is not used. This | |
23547 | authenticator is advertised in the response to EHLO as | |
9b371988 PH |
23548 | .code |
23549 | 250-AUTH PLAIN | |
23550 | .endd | |
168e428f | 23551 | and a client host can authenticate itself by sending the command |
9b371988 PH |
23552 | .code |
23553 | AUTH PLAIN AHVzZXJuYW1lAG15c2VjcmV0 | |
23554 | .endd | |
168e428f PH |
23555 | As this contains three strings (more than the number of prompts), no further |
23556 | data is required from the client. Alternatively, the client may just send | |
9b371988 PH |
23557 | .code |
23558 | AUTH PLAIN | |
23559 | .endd | |
168e428f PH |
23560 | to initiate authentication, in which case the server replies with an empty |
23561 | prompt. The client must respond with the combined data string. | |
23562 | ||
23563 | The data string is base64 encoded, as required by the RFC. This example, | |
9b371988 PH |
23564 | when decoded, is <&'NUL'&>&`username`&<&'NUL'&>&`mysecret`&, where <&'NUL'&> |
23565 | represents a zero byte. This is split up into three strings, the first of which | |
23566 | is empty. The &%server_condition%& option in the authenticator checks that the | |
23567 | second two are &`username`& and &`mysecret`& respectively. | |
168e428f PH |
23568 | |
23569 | Having just one fixed user name and password, as in this example, is not very | |
23570 | realistic, though for a small organization with only a handful of | |
23571 | authenticating clients it could make sense. | |
23572 | ||
23573 | A more sophisticated instance of this authenticator could use the user name in | |
4f578862 | 23574 | &$auth2$& to look up a password in a file or database, and maybe do an encrypted |
9b371988 PH |
23575 | comparison (see &%crypteq%& in chapter &<<CHAPexpand>>&). Here is a example of |
23576 | this approach, where the passwords are looked up in a DBM file. &*Warning*&: | |
23577 | This is an incorrect example: | |
23578 | .code | |
168e428f | 23579 | server_condition = \ |
db9452a9 | 23580 | ${if eq{$auth3}{${lookup{$auth2}dbm{/etc/authpwd}}}} |
9b371988 | 23581 | .endd |
4f578862 PH |
23582 | The expansion uses the user name (&$auth2$&) as the key to look up a password, |
23583 | which it then compares to the supplied password (&$auth3$&). Why is this example | |
168e428f PH |
23584 | incorrect? It works fine for existing users, but consider what happens if a |
23585 | non-existent user name is given. The lookup fails, but as no success/failure | |
23586 | strings are given for the lookup, it yields an empty string. Thus, to defeat | |
23587 | the authentication, all a client has to do is to supply a non-existent user | |
23588 | name and an empty password. The correct way of writing this test is: | |
9b371988 | 23589 | .code |
4f578862 | 23590 | server_condition = ${lookup{$auth2}dbm{/etc/authpwd}\ |
db9452a9 | 23591 | {${if eq{$value}{$auth3}}} {false}} |
9b371988 | 23592 | .endd |
168e428f | 23593 | In this case, if the lookup succeeds, the result is checked; if the lookup |
db9452a9 PH |
23594 | fails, &"false"& is returned and authentication fails. If &%crypteq%& is being |
23595 | used instead of &%eq%&, the first example is in fact safe, because &%crypteq%& | |
23596 | always fails if its second argument is empty. However, the second way of | |
23597 | writing the test makes the logic clearer. | |
168e428f PH |
23598 | |
23599 | ||
f89d2485 | 23600 | .section "The LOGIN authentication mechanism" "SECID173" |
9b371988 PH |
23601 | .cindex "LOGIN authentication mechanism" |
23602 | .cindex "authentication" "LOGIN mechanism" | |
168e428f PH |
23603 | The LOGIN authentication mechanism is not documented in any RFC, but is in use |
23604 | in a number of programs. No data is sent with the AUTH command. Instead, a | |
23605 | user name and password are supplied separately, in response to prompts. The | |
23606 | plaintext authenticator can be configured to support this as in this example: | |
9b371988 | 23607 | .code |
168e428f PH |
23608 | fixed_login: |
23609 | driver = plaintext | |
23610 | public_name = LOGIN | |
23611 | server_prompts = User Name : Password | |
23612 | server_condition = \ | |
db9452a9 | 23613 | ${if and {{eq{$auth1}{username}}{eq{$auth2}{mysecret}}}} |
4f578862 | 23614 | server_set_id = $auth1 |
9b371988 | 23615 | .endd |
168e428f PH |
23616 | Because of the way plaintext operates, this authenticator accepts data supplied |
23617 | with the AUTH command (in contravention of the specification of LOGIN), but | |
23618 | if the client does not supply it (as is the case for LOGIN clients), the prompt | |
23619 | strings are used to obtain two data items. | |
23620 | ||
23621 | Some clients are very particular about the precise text of the prompts. For | |
9b371988 PH |
23622 | example, Outlook Express is reported to recognize only &"Username:"& and |
23623 | &"Password:"&. Here is an example of a LOGIN authenticator that uses those | |
23624 | strings. It uses the &%ldapauth%& expansion condition to check the user | |
168e428f | 23625 | name and password by binding to an LDAP server: |
9b371988 | 23626 | .code |
168e428f PH |
23627 | login: |
23628 | driver = plaintext | |
23629 | public_name = LOGIN | |
23630 | server_prompts = Username:: : Password:: | |
450b99e9 TF |
23631 | server_condition = ${if and{{ |
23632 | !eq{}{$auth1} }{ \ | |
23633 | ldapauth{user="cn=${quote_ldap_dn:$auth1},ou=people,o=example.org" \ | |
23634 | pass=${quote:$auth2} \ | |
23635 | ldap://ldap.example.org/} }} } | |
4f578862 | 23636 | server_set_id = uid=$auth1,ou=people,o=example.org |
9b371988 | 23637 | .endd |
450b99e9 TF |
23638 | We have to check that the username is not empty before using it, because LDAP |
23639 | does not permit empty DN components. We must also use the &%quote_ldap_dn%& | |
23640 | operator to correctly quote the DN for authentication. However, the basic | |
23641 | &%quote%& operator, rather than any of the LDAP quoting operators, is the | |
23642 | correct one to use for the password, because quoting is needed only to make | |
23643 | the password conform to the Exim syntax. At the LDAP level, the password is an | |
23644 | uninterpreted string. | |
168e428f PH |
23645 | |
23646 | ||
f89d2485 | 23647 | .section "Support for different kinds of authentication" "SECID174" |
168e428f PH |
23648 | A number of string expansion features are provided for the purpose of |
23649 | interfacing to different ways of user authentication. These include checking | |
9b371988 | 23650 | traditionally encrypted passwords from &_/etc/passwd_& (or equivalent), PAM, |
4f578862 | 23651 | Radius, &%ldapauth%&, &'pwcheck'&, and &'saslauthd'&. For details see section |
9b371988 | 23652 | &<<SECTexpcond>>&. |
168e428f PH |
23653 | |
23654 | ||
23655 | ||
23656 | ||
f89d2485 | 23657 | .section "Using plaintext in a client" "SECID175" |
9b371988 | 23658 | .cindex "options" "&(plaintext)& authenticator (client)" |
4f578862 | 23659 | The &(plaintext)& authenticator has two client options: |
168e428f | 23660 | |
4f578862 PH |
23661 | .option client_ignore_invalid_base64 plaintext boolean false |
23662 | If the client receives a server prompt that is not a valid base64 string, | |
23663 | authentication is abandoned by default. However, if this option is set true, | |
23664 | the error in the challenge is ignored and the client sends the response as | |
23665 | usual. | |
168e428f | 23666 | |
9b371988 | 23667 | .option client_send plaintext string&!! unset |
168e428f PH |
23668 | The string is a colon-separated list of authentication data strings. Each |
23669 | string is independently expanded before being sent to the server. The first | |
23670 | string is sent with the AUTH command; any more strings are sent in response | |
4f578862 PH |
23671 | to prompts from the server. Before each string is expanded, the value of the |
23672 | most recent prompt is placed in the next &$auth$&<&'n'&> variable, starting | |
23673 | with &$auth1$& for the first prompt. Up to three prompts are stored in this | |
23674 | way. Thus, the prompt that is received in response to sending the first string | |
23675 | (with the AUTH command) can be used in the expansion of the second string, and | |
23676 | so on. If an invalid base64 string is received when | |
23677 | &%client_ignore_invalid_base64%& is set, an empty string is put in the | |
23678 | &$auth$&<&'n'&> variable. | |
168e428f | 23679 | |
9b371988 | 23680 | &*Note*&: You cannot use expansion to create multiple strings, because |
168e428f PH |
23681 | splitting takes priority and happens first. |
23682 | ||
23683 | Because the PLAIN authentication mechanism requires NUL (binary zero) bytes in | |
23684 | the data, further processing is applied to each string before it is sent. If | |
23685 | there are any single circumflex characters in the string, they are converted to | |
23686 | NULs. Should an actual circumflex be required as data, it must be doubled in | |
23687 | the string. | |
23688 | ||
23689 | This is an example of a client configuration that implements the PLAIN | |
23690 | authentication mechanism with a fixed user name and password: | |
9b371988 PH |
23691 | .code |
23692 | fixed_plain: | |
23693 | driver = plaintext | |
23694 | public_name = PLAIN | |
23695 | client_send = ^username^mysecret | |
23696 | .endd | |
168e428f PH |
23697 | The lack of colons means that the entire text is sent with the AUTH |
23698 | command, with the circumflex characters converted to NULs. A similar example | |
23699 | that uses the LOGIN mechanism is: | |
9b371988 PH |
23700 | .code |
23701 | fixed_login: | |
23702 | driver = plaintext | |
23703 | public_name = LOGIN | |
23704 | client_send = : username : mysecret | |
23705 | .endd | |
168e428f PH |
23706 | The initial colon means that the first string is empty, so no data is sent with |
23707 | the AUTH command itself. The remaining strings are sent in response to | |
23708 | prompts. | |
4f578862 PH |
23709 | .ecindex IIDplaiauth1 |
23710 | .ecindex IIDplaiauth2 | |
168e428f PH |
23711 | |
23712 | ||
23713 | ||
23714 | ||
9b371988 PH |
23715 | . //////////////////////////////////////////////////////////////////////////// |
23716 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 23717 | |
f89d2485 | 23718 | .chapter "The cram_md5 authenticator" "CHID9" |
4f578862 PH |
23719 | .scindex IIDcramauth1 "&(cram_md5)& authenticator" |
23720 | .scindex IIDcramauth2 "authenticators" "&(cram_md5)&" | |
9b371988 PH |
23721 | .cindex "CRAM-MD5 authentication mechanism" |
23722 | .cindex "authentication" "CRAM-MD5 mechanism" | |
168e428f PH |
23723 | The CRAM-MD5 authentication mechanism is described in RFC 2195. The server |
23724 | sends a challenge string to the client, and the response consists of a user | |
23725 | name and the CRAM-MD5 digest of the challenge string combined with a secret | |
23726 | string (password) which is known to both server and client. Thus, the secret | |
23727 | is not sent over the network as plain text, which makes this authenticator more | |
9b371988 | 23728 | secure than &(plaintext)&. However, the downside is that the secret has to be |
168e428f PH |
23729 | available in plain text at either end. |
23730 | ||
23731 | ||
f89d2485 | 23732 | .section "Using cram_md5 as a server" "SECID176" |
9b371988 | 23733 | .cindex "options" "&(cram_md5)& authenticator (server)" |
168e428f PH |
23734 | This authenticator has one server option, which must be set to configure the |
23735 | authenticator as a server: | |
23736 | ||
9b371988 PH |
23737 | .option server_secret cram_md5 string&!! unset |
23738 | .cindex "numerical variables (&$1$& &$2$& etc)" "in &(cram_md5)& authenticator" | |
168e428f | 23739 | When the server receives the client's response, the user name is placed in |
c0712871 | 23740 | the expansion variable &$auth1$&, and &%server_secret%& is expanded to |
4f578862 PH |
23741 | obtain the password for that user. The server then computes the CRAM-MD5 digest |
23742 | that the client should have sent, and checks that it received the correct | |
23743 | string. If the expansion of &%server_secret%& is forced to fail, authentication | |
23744 | fails. If the expansion fails for some other reason, a temporary error code is | |
23745 | returned to the client. | |
23746 | ||
4f578862 PH |
23747 | For compatibility with previous releases of Exim, the user name is also placed |
23748 | in &$1$&. However, the use of this variables for this purpose is now | |
23749 | deprecated, as it can lead to confusion in string expansions that also use | |
23750 | numeric variables for other things. | |
168e428f PH |
23751 | |
23752 | For example, the following authenticator checks that the user name given by the | |
9b371988 PH |
23753 | client is &"ph10"&, and if so, uses &"secret"& as the password. For any other |
23754 | user name, authentication fails. | |
23755 | .code | |
23756 | fixed_cram: | |
23757 | driver = cram_md5 | |
23758 | public_name = CRAM-MD5 | |
4f578862 PH |
23759 | server_secret = ${if eq{$auth1}{ph10}{secret}fail} |
23760 | server_set_id = $auth1 | |
9b371988 | 23761 | .endd |
f89d2485 | 23762 | .vindex "&$authenticated_id$&" |
9b371988 | 23763 | If authentication succeeds, the setting of &%server_set_id%& preserves the user |
f89d2485 | 23764 | name in &$authenticated_id$&. A more typical configuration might look up the |
068aaea8 | 23765 | secret string in a file, using the user name as the key. For example: |
9b371988 PH |
23766 | .code |
23767 | lookup_cram: | |
23768 | driver = cram_md5 | |
23769 | public_name = CRAM-MD5 | |
f89d2485 PH |
23770 | server_secret = ${lookup{$auth1}lsearch{/etc/authpwd}\ |
23771 | {$value}fail} | |
4f578862 | 23772 | server_set_id = $auth1 |
9b371988 | 23773 | .endd |
168e428f | 23774 | Note that this expansion explicitly forces failure if the lookup fails |
f89d2485 | 23775 | because &$auth1$& contains an unknown user name. |
168e428f PH |
23776 | |
23777 | ||
f89d2485 | 23778 | .section "Using cram_md5 as a client" "SECID177" |
9b371988 PH |
23779 | .cindex "options" "&(cram_md5)& authenticator (client)" |
23780 | When used as a client, the &(cram_md5)& authenticator has two options: | |
168e428f PH |
23781 | |
23782 | ||
23783 | ||
9b371988 | 23784 | .option client_name cram_md5 string&!! "the primary host name" |
168e428f PH |
23785 | This string is expanded, and the result used as the user name data when |
23786 | computing the response to the server's challenge. | |
23787 | ||
23788 | ||
9b371988 | 23789 | .option client_secret cram_md5 string&!! unset |
168e428f PH |
23790 | This option must be set for the authenticator to work as a client. Its value is |
23791 | expanded and the result used as the secret string when computing the response. | |
23792 | ||
23793 | ||
f89d2485 PH |
23794 | .vindex "&$host$&" |
23795 | .vindex "&$host_address$&" | |
168e428f | 23796 | Different user names and secrets can be used for different servers by referring |
9b371988 PH |
23797 | to &$host$& or &$host_address$& in the options. Forced failure of either |
23798 | expansion string is treated as an indication that this authenticator is not | |
23799 | prepared to handle this case. Exim moves on to the next configured client | |
23800 | authenticator. Any other expansion failure causes Exim to give up trying to | |
23801 | send the message to the current server. | |
168e428f | 23802 | |
9b371988 | 23803 | A simple example configuration of a &(cram_md5)& authenticator, using fixed |
168e428f | 23804 | strings, is: |
9b371988 PH |
23805 | .code |
23806 | fixed_cram: | |
23807 | driver = cram_md5 | |
23808 | public_name = CRAM-MD5 | |
23809 | client_name = ph10 | |
23810 | client_secret = secret | |
23811 | .endd | |
4f578862 PH |
23812 | .ecindex IIDcramauth1 |
23813 | .ecindex IIDcramauth2 | |
168e428f PH |
23814 | |
23815 | ||
23816 | ||
9b371988 PH |
23817 | . //////////////////////////////////////////////////////////////////////////// |
23818 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 23819 | |
f89d2485 | 23820 | .chapter "The cyrus_sasl authenticator" "CHID10" |
4f578862 PH |
23821 | .scindex IIDcyrauth1 "&(cyrus_sasl)& authenticator" |
23822 | .scindex IIDcyrauth2 "authenticators" "&(cyrus_sasl)&" | |
9b371988 | 23823 | .cindex "Cyrus" "SASL library" |
3cb1b51e | 23824 | .cindex "Kerberos" |
168e428f | 23825 | The code for this authenticator was provided by Matthew Byng-Maddick of A L |
9b371988 | 23826 | Digital Ltd (&url(http://www.aldigital.co.uk)). |
168e428f | 23827 | |
9b371988 PH |
23828 | The &(cyrus_sasl)& authenticator provides server support for the Cyrus SASL |
23829 | library implementation of the RFC 2222 (&"Simple Authentication and Security | |
23830 | Layer"&). This library supports a number of authentication mechanisms, | |
23831 | including PLAIN and LOGIN, but also several others that Exim does not support | |
23832 | directly. In particular, there is support for Kerberos authentication. | |
168e428f | 23833 | |
9b371988 | 23834 | The &(cyrus_sasl)& authenticator provides a gatewaying mechanism directly to |
168e428f | 23835 | the Cyrus interface, so if your Cyrus library can do, for example, CRAM-MD5, |
9b371988 | 23836 | then so can the &(cyrus_sasl)& authenticator. By default it uses the public |
168e428f PH |
23837 | name of the driver to determine which mechanism to support. |
23838 | ||
23839 | Where access to some kind of secret file is required, for example in GSSAPI | |
9b371988 | 23840 | or CRAM-MD5, it is worth noting that the authenticator runs as the Exim |
168e428f PH |
23841 | user, and that the Cyrus SASL library has no way of escalating privileges |
23842 | by default. You may also find you need to set environment variables, | |
23843 | depending on the driver you are using. | |
23844 | ||
3cb1b51e PH |
23845 | The application name provided by Exim is &"exim"&, so various SASL options may |
23846 | be set in &_exim.conf_& in your SASL directory. If you are using GSSAPI for | |
23847 | Kerberos, note that because of limitations in the GSSAPI interface, | |
23848 | changing the server keytab might need to be communicated down to the Kerberos | |
23849 | layer independently. The mechanism for doing so is dependent upon the Kerberos | |
23850 | implementation. For example, for Heimdal, the environment variable KRB5_KTNAME | |
23851 | may be set to point to an alternative keytab file. Exim will pass this | |
23852 | variable through from its own inherited environment when started as root or the | |
23853 | Exim user. The keytab file needs to be readable by the Exim user. | |
3cb1b51e | 23854 | |
168e428f | 23855 | |
f89d2485 | 23856 | .section "Using cyrus_sasl as a server" "SECID178" |
4f578862 PH |
23857 | The &(cyrus_sasl)& authenticator has four private options. It puts the username |
23858 | (on a successful authentication) into &$auth1$&. For compatibility with | |
23859 | previous releases of Exim, the username is also placed in &$1$&. However, the | |
23860 | use of this variable for this purpose is now deprecated, as it can lead to | |
23861 | confusion in string expansions that also use numeric variables for other | |
23862 | things. | |
4f578862 | 23863 | |
168e428f | 23864 | |
f89d2485 PH |
23865 | .option server_hostname cyrus_sasl string&!! "see below" |
23866 | This option selects the hostname that is used when communicating with the | |
23867 | library. The default value is &`$primary_hostname`&. It is up to the underlying | |
23868 | SASL plug-in what it does with this data. | |
168e428f PH |
23869 | |
23870 | ||
f89d2485 PH |
23871 | .option server_mech cyrus_sasl string "see below" |
23872 | This option selects the authentication mechanism this driver should use. The | |
23873 | default is the value of the generic &%public_name%& option. This option allows | |
23874 | you to use a different underlying mechanism from the advertised name. For | |
23875 | example: | |
9b371988 PH |
23876 | .code |
23877 | sasl: | |
23878 | driver = cyrus_sasl | |
23879 | public_name = X-ANYTHING | |
23880 | server_mech = CRAM-MD5 | |
4f578862 | 23881 | server_set_id = $auth1 |
9b371988 | 23882 | .endd |
168e428f | 23883 | |
9b371988 | 23884 | .option server_realm cyrus_sasl string unset |
168e428f PH |
23885 | This specifies the SASL realm that the server claims to be in. |
23886 | ||
23887 | ||
9b371988 | 23888 | .option server_service cyrus_sasl string &`smtp`& |
168e428f PH |
23889 | This is the SASL service that the server claims to implement. |
23890 | ||
23891 | ||
23892 | For straightforward cases, you do not need to set any of the authenticator's | |
23893 | private options. All you need to do is to specify an appropriate mechanism as | |
23894 | the public name. Thus, if you have a SASL library that supports CRAM-MD5 and | |
23895 | PLAIN, you could have two authenticators as follows: | |
9b371988 PH |
23896 | .code |
23897 | sasl_cram_md5: | |
23898 | driver = cyrus_sasl | |
23899 | public_name = CRAM-MD5 | |
4f578862 | 23900 | server_set_id = $auth1 |
168e428f | 23901 | |
9b371988 PH |
23902 | sasl_plain: |
23903 | driver = cyrus_sasl | |
23904 | public_name = PLAIN | |
e2f03231 | 23905 | server_set_id = $auth2 |
9b371988 | 23906 | .endd |
168e428f PH |
23907 | Cyrus SASL does implement the LOGIN authentication method, even though it is |
23908 | not a standard method. It is disabled by default in the source distribution, | |
23909 | but it is present in many binary distributions. | |
4f578862 PH |
23910 | .ecindex IIDcyrauth1 |
23911 | .ecindex IIDcyrauth2 | |
168e428f PH |
23912 | |
23913 | ||
23914 | ||
23915 | ||
3cb1b51e PH |
23916 | . //////////////////////////////////////////////////////////////////////////// |
23917 | . //////////////////////////////////////////////////////////////////////////// | |
3cb1b51e PH |
23918 | .chapter "The dovecot authenticator" "CHAPdovecot" |
23919 | .scindex IIDdcotauth1 "&(dovecot)& authenticator" | |
23920 | .scindex IIDdcotauth2 "authenticators" "&(dovecot)&" | |
23921 | This authenticator is an interface to the authentication facility of the | |
23922 | Dovecot POP/IMAP server, which can support a number of authentication methods. | |
23923 | If you are using Dovecot to authenticate POP/IMAP clients, it might be helpful | |
23924 | to use the same mechanisms for SMTP authentication. This is a server | |
23925 | authenticator only. There is only one option: | |
23926 | ||
23927 | .option server_socket dovecot string unset | |
23928 | ||
23929 | This option must specify the socket that is the interface to Dovecot | |
23930 | authentication. The &%public_name%& option must specify an authentication | |
23931 | mechanism that Dovecot is configured to support. You can have several | |
23932 | authenticators for different mechanisms. For example: | |
23933 | .code | |
23934 | dovecot_plain: | |
23935 | driver = dovecot | |
23936 | public_name = PLAIN | |
23937 | server_socket = /var/run/dovecot/auth-client | |
e2f03231 | 23938 | server_set_id = $auth2 |
3cb1b51e PH |
23939 | |
23940 | dovecot_ntlm: | |
23941 | driver = dovecot | |
23942 | public_name = NTLM | |
23943 | server_socket = /var/run/dovecot/auth-client | |
693ff309 | 23944 | server_set_id = $auth1 |
3cb1b51e PH |
23945 | .endd |
23946 | If the SMTP connection is encrypted, or if &$sender_host_address$& is equal to | |
23947 | &$received_ip_address$& (that is, the connection is local), the &"secured"& | |
23948 | option is passed in the Dovecot authentication command. If, for a TLS | |
23949 | connection, a client certificate has been verified, the &"valid-client-cert"& | |
595028e4 PH |
23950 | option is passed. When authentication succeeds, the identity of the user |
23951 | who authenticated is placed in &$auth1$&. | |
3cb1b51e PH |
23952 | .ecindex IIDdcotauth1 |
23953 | .ecindex IIDdcotauth2 | |
3cb1b51e PH |
23954 | |
23955 | ||
9b371988 PH |
23956 | . //////////////////////////////////////////////////////////////////////////// |
23957 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 23958 | |
4f578862 PH |
23959 | .chapter "The spa authenticator" "CHAPspa" |
23960 | .scindex IIDspaauth1 "&(spa)& authenticator" | |
23961 | .scindex IIDspaauth2 "authenticators" "&(spa)&" | |
9b371988 PH |
23962 | .cindex "authentication" "Microsoft Secure Password" |
23963 | .cindex "authentication" "NTLM" | |
23964 | .cindex "Microsoft Secure Password Authentication" | |
23965 | .cindex "NTLM authentication" | |
23966 | The &(spa)& authenticator provides client support for Microsoft's &'Secure | |
23967 | Password Authentication'& mechanism, | |
168e428f PH |
23968 | which is also sometimes known as NTLM (NT LanMan). The code for client side of |
23969 | this authenticator was contributed by Marc Prud'hommeaux, and much of it is | |
9b371988 | 23970 | taken from the Samba project (&url(http://www.samba.org)). The code for the |
168e428f PH |
23971 | server side was subsequently contributed by Tom Kistner. The mechanism works as |
23972 | follows: | |
23973 | ||
9b371988 PH |
23974 | .ilist |
23975 | After the AUTH command has been accepted, the client sends an SPA | |
168e428f | 23976 | authentication request based on the user name and optional domain. |
9b371988 PH |
23977 | .next |
23978 | The server sends back a challenge. | |
23979 | .next | |
23980 | The client builds a challenge response which makes use of the user's password | |
168e428f | 23981 | and sends it to the server, which then accepts or rejects it. |
9b371988 | 23982 | .endlist |
168e428f PH |
23983 | |
23984 | Encryption is used to protect the password in transit. | |
23985 | ||
23986 | ||
23987 | ||
f89d2485 | 23988 | .section "Using spa as a server" "SECID179" |
9b371988 PH |
23989 | .cindex "options" "&(spa)& authenticator (server)" |
23990 | The &(spa)& authenticator has just one server option: | |
168e428f | 23991 | |
9b371988 PH |
23992 | .option server_password spa string&!! unset |
23993 | .cindex "numerical variables (&$1$& &$2$& etc)" "in &(spa)& authenticator" | |
168e428f | 23994 | This option is expanded, and the result must be the cleartext password for the |
4f578862 PH |
23995 | authenticating user, whose name is at this point in &$auth1$&. For |
23996 | compatibility with previous releases of Exim, the user name is also placed in | |
23997 | &$1$&. However, the use of this variable for this purpose is now deprecated, as | |
23998 | it can lead to confusion in string expansions that also use numeric variables | |
23999 | for other things. For example: | |
9b371988 | 24000 | .code |
068aaea8 PH |
24001 | spa: |
24002 | driver = spa | |
24003 | public_name = NTLM | |
4f578862 PH |
24004 | server_password = \ |
24005 | ${lookup{$auth1}lsearch{/etc/exim/spa_clearpass}{$value}fail} | |
9b371988 | 24006 | .endd |
168e428f PH |
24007 | If the expansion is forced to fail, authentication fails. Any other expansion |
24008 | failure causes a temporary error code to be returned. | |
24009 | ||
24010 | ||
24011 | ||
24012 | ||
24013 | ||
f89d2485 | 24014 | .section "Using spa as a client" "SECID180" |
9b371988 PH |
24015 | .cindex "options" "&(spa)& authenticator (client)" |
24016 | The &(spa)& authenticator has the following client options: | |
168e428f PH |
24017 | |
24018 | ||
168e428f | 24019 | |
9b371988 | 24020 | .option client_domain spa string&!! unset |
168e428f PH |
24021 | This option specifies an optional domain for the authentication. |
24022 | ||
24023 | ||
9b371988 | 24024 | .option client_password spa string&!! unset |
168e428f PH |
24025 | This option specifies the user's password, and must be set. |
24026 | ||
24027 | ||
9b371988 PH |
24028 | .option client_username spa string&!! unset |
24029 | This option specifies the user name, and must be set. Here is an example of a | |
24030 | configuration of this authenticator for use with the mail servers at | |
24031 | &'msn.com'&: | |
24032 | .code | |
24033 | msn: | |
24034 | driver = spa | |
24035 | public_name = MSN | |
24036 | client_username = msn/msn_username | |
24037 | client_password = msn_plaintext_password | |
24038 | client_domain = DOMAIN_OR_UNSET | |
24039 | .endd | |
4f578862 PH |
24040 | .ecindex IIDspaauth1 |
24041 | .ecindex IIDspaauth2 | |
168e428f PH |
24042 | |
24043 | ||
24044 | ||
24045 | ||
24046 | ||
9b371988 PH |
24047 | . //////////////////////////////////////////////////////////////////////////// |
24048 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 24049 | |
9b371988 PH |
24050 | .chapter "Encrypted SMTP connections using TLS/SSL" "CHAPTLS" &&& |
24051 | "Encrypted SMTP connections" | |
4f578862 PH |
24052 | .scindex IIDencsmtp1 "encryption" "on SMTP connection" |
24053 | .scindex IIDencsmtp2 "SMTP" "encryption" | |
9b371988 PH |
24054 | .cindex "TLS" "on SMTP connection" |
24055 | .cindex "OpenSSL" | |
24056 | .cindex "GnuTLS" | |
168e428f PH |
24057 | Support for TLS (Transport Layer Security), formerly known as SSL (Secure |
24058 | Sockets Layer), is implemented by making use of the OpenSSL library or the | |
24059 | GnuTLS library (Exim requires GnuTLS release 1.0 or later). There is no | |
24060 | cryptographic code in the Exim distribution itself for implementing TLS. In | |
24061 | order to use this feature you must install OpenSSL or GnuTLS, and then build a | |
9b371988 PH |
24062 | version of Exim that includes TLS support (see section &<<SECTinctlsssl>>&). |
24063 | You also need to understand the basic concepts of encryption at a managerial | |
24064 | level, and in particular, the way that public keys, private keys, and | |
24065 | certificates are used. | |
168e428f | 24066 | |
068aaea8 | 24067 | RFC 3207 defines how SMTP connections can make use of encryption. Once a |
168e428f PH |
24068 | connection is established, the client issues a STARTTLS command. If the |
24069 | server accepts this, the client and the server negotiate an encryption | |
24070 | mechanism. If the negotiation succeeds, the data that subsequently passes | |
24071 | between them is encrypted. | |
24072 | ||
24073 | Exim's ACLs can detect whether the current SMTP session is encrypted or not, | |
24074 | and if so, what cipher suite is in use, whether the client supplied a | |
24075 | certificate, and whether or not that certificate was verified. This makes it | |
24076 | possible for an Exim server to deny or accept certain commands based on the | |
24077 | encryption state. | |
24078 | ||
9b371988 | 24079 | &*Warning*&: Certain types of firewall and certain anti-virus products can |
168e428f PH |
24080 | disrupt TLS connections. You need to turn off SMTP scanning for these products |
24081 | in order to get TLS to work. | |
24082 | ||
24083 | ||
24084 | ||
f89d2485 PH |
24085 | .section "Support for the legacy &""ssmtp""& (aka &""smtps""&) protocol" &&& |
24086 | "SECID284" | |
9b371988 PH |
24087 | .cindex "ssmtp protocol" |
24088 | .cindex "smtps protocol" | |
24089 | .cindex "SMTP" "ssmtp protocol" | |
24090 | .cindex "SMTP" "smtps protocol" | |
168e428f PH |
24091 | Early implementations of encrypted SMTP used a different TCP port from normal |
24092 | SMTP, and expected an encryption negotiation to start immediately, instead of | |
24093 | waiting for a STARTTLS command from the client using the standard SMTP | |
9b371988 PH |
24094 | port. The protocol was called &"ssmtp"& or &"smtps"&, and port 465 was |
24095 | allocated for this purpose. | |
168e428f | 24096 | |
f89d2485 | 24097 | This approach was abandoned when encrypted SMTP was standardized, but there are |
168e428f | 24098 | still some legacy clients that use it. Exim supports these clients by means of |
9b371988 | 24099 | the &%tls_on_connect_ports%& global option. Its value must be a list of port |
168e428f | 24100 | numbers; the most common use is expected to be: |
9b371988 PH |
24101 | .code |
24102 | tls_on_connect_ports = 465 | |
24103 | .endd | |
168e428f | 24104 | The port numbers specified by this option apply to all SMTP connections, both |
9b371988 PH |
24105 | via the daemon and via &'inetd'&. You still need to specify all the ports that |
24106 | the daemon uses (by setting &%daemon_smtp_ports%& or &%local_interfaces%& or | |
24107 | the &%-oX%& command line option) because &%tls_on_connect_ports%& does not add | |
24108 | an extra port &-- rather, it specifies different behaviour on a port that is | |
168e428f PH |
24109 | defined elsewhere. |
24110 | ||
9b371988 PH |
24111 | There is also a &%-tls-on-connect%& command line option. This overrides |
24112 | &%tls_on_connect_ports%&; it forces the legacy behaviour for all ports. | |
168e428f PH |
24113 | |
24114 | ||
24115 | ||
24116 | ||
24117 | ||
24118 | ||
9b371988 PH |
24119 | .section "OpenSSL vs GnuTLS" "SECTopenvsgnu" |
24120 | .cindex "TLS" "OpenSSL &'vs'& GnuTLS" | |
168e428f PH |
24121 | The first TLS support in Exim was implemented using OpenSSL. Support for GnuTLS |
24122 | followed later, when the first versions of GnuTLS were released. To build Exim | |
24123 | to use GnuTLS, you need to set | |
9b371988 PH |
24124 | .code |
24125 | USE_GNUTLS=yes | |
24126 | .endd | |
168e428f | 24127 | in Local/Makefile, in addition to |
9b371988 PH |
24128 | .code |
24129 | SUPPORT_TLS=yes | |
24130 | .endd | |
168e428f PH |
24131 | You must also set TLS_LIBS and TLS_INCLUDE appropriately, so that the |
24132 | include files and libraries for GnuTLS can be found. | |
24133 | ||
24134 | There are some differences in usage when using GnuTLS instead of OpenSSL: | |
24135 | ||
9b371988 PH |
24136 | .ilist |
24137 | The &%tls_verify_certificates%& option must contain the name of a file, not the | |
168e428f | 24138 | name of a directory (for OpenSSL it can be either). |
9b371988 PH |
24139 | .next |
24140 | The &%tls_dhparam%& option is ignored, because early versions of GnuTLS had no | |
168e428f PH |
24141 | facility for varying its Diffie-Hellman parameters. I understand that this has |
24142 | changed, but Exim has not been updated to provide this facility. | |
9b371988 | 24143 | .next |
f89d2485 | 24144 | .vindex "&$tls_peerdn$&" |
068aaea8 | 24145 | Distinguished Name (DN) strings reported by the OpenSSL library use a slash for |
168e428f | 24146 | separating fields; GnuTLS uses commas, in accordance with RFC 2253. This |
9b371988 PH |
24147 | affects the value of the &$tls_peerdn$& variable. |
24148 | .next | |
24149 | OpenSSL identifies cipher suites using hyphens as separators, for example: | |
168e428f PH |
24150 | DES-CBC3-SHA. GnuTLS uses underscores, for example: RSA_ARCFOUR_SHA. What is |
24151 | more, OpenSSL complains if underscores are present in a cipher list. To make | |
f89d2485 | 24152 | life simpler, Exim changes underscores to hyphens for OpenSSL and hyphens to |
168e428f | 24153 | underscores for GnuTLS when processing lists of cipher suites in the |
9b371988 | 24154 | &%tls_require_ciphers%& options (the global option and the &(smtp)& transport |
168e428f | 24155 | option). |
9b371988 PH |
24156 | .next |
24157 | The &%tls_require_ciphers%& options operate differently, as described in the | |
24158 | sections &<<SECTreqciphssl>>& and &<<SECTreqciphgnu>>&. | |
24159 | .endlist | |
168e428f | 24160 | |
068aaea8 | 24161 | |
f89d2485 | 24162 | .section "GnuTLS parameter computation" "SECID181" |
4cc45746 | 24163 | GnuTLS uses D-H parameters that may take a substantial amount of time |
3cb1b51e | 24164 | to compute. It is unreasonable to re-compute them for every TLS session. |
068aaea8 | 24165 | Therefore, Exim keeps this data in a file in its spool directory, called |
9b371988 | 24166 | &_gnutls-params_&. The file is owned by the Exim user and is readable only by |
c2fe5cfd | 24167 | its owner. Every Exim process that start up GnuTLS reads the D-H |
9b371988 PH |
24168 | parameters from this file. If the file does not exist, the first Exim process |
24169 | that needs it computes the data and writes it to a temporary file which is | |
24170 | renamed once it is complete. It does not matter if several Exim processes do | |
24171 | this simultaneously (apart from wasting a few resources). Once a file is in | |
24172 | place, new Exim processes immediately start using it. | |
24173 | ||
068aaea8 PH |
24174 | For maximum security, the parameters that are stored in this file should be |
24175 | recalculated periodically, the frequency depending on your paranoia level. | |
24176 | Arranging this is easy in principle; just delete the file when you want new | |
24177 | values to be computed. However, there may be a problem. The calculation of new | |
9b371988 PH |
24178 | parameters needs random numbers, and these are obtained from &_/dev/random_&. |
24179 | If the system is not very active, &_/dev/random_& may delay returning data | |
24180 | until enough randomness (entropy) is available. This may cause Exim to hang for | |
24181 | a substantial amount of time, causing timeouts on incoming connections. | |
068aaea8 | 24182 | |
068aaea8 | 24183 | The solution is to generate the parameters externally to Exim. They are stored |
9b371988 PH |
24184 | in &_gnutls-params_& in PEM format, which means that they can be generated |
24185 | externally using the &(certtool)& command that is part of GnuTLS. | |
068aaea8 | 24186 | |
068aaea8 PH |
24187 | To replace the parameters with new ones, instead of deleting the file |
24188 | and letting Exim re-create it, you can generate new parameters using | |
9b371988 | 24189 | &(certtool)& and, when this has been done, replace Exim's cache file by |
068aaea8 | 24190 | renaming. The relevant commands are something like this: |
9b371988 | 24191 | .code |
068aaea8 PH |
24192 | # rm -f new-params |
24193 | # touch new-params | |
24194 | # chown exim:exim new-params | |
24195 | # chmod 0400 new-params | |
24196 | # certtool --generate-privkey --bits 512 >new-params | |
24197 | # echo "" >>new-params | |
24198 | # certtool --generate-dh-params --bits 1024 >> new-params | |
24199 | # mv new-params gnutls-params | |
9b371988 | 24200 | .endd |
068aaea8 PH |
24201 | If Exim never has to generate the parameters itself, the possibility of |
24202 | stalling is removed. | |
168e428f PH |
24203 | |
24204 | ||
9b371988 PH |
24205 | .section "Requiring specific ciphers in OpenSSL" "SECTreqciphssl" |
24206 | .cindex "TLS" "requiring specific ciphers (OpenSSL)" | |
0a4e3112 | 24207 | .oindex "&%tls_require_ciphers%&" "OpenSSL" |
168e428f PH |
24208 | There is a function in the OpenSSL library that can be passed a list of cipher |
24209 | suites before the cipher negotiation takes place. This specifies which ciphers | |
24210 | are acceptable. The list is colon separated and may contain names like | |
9b371988 | 24211 | DES-CBC3-SHA. Exim passes the expanded value of &%tls_require_ciphers%& |
168e428f PH |
24212 | directly to this function call. The following quotation from the OpenSSL |
24213 | documentation specifies what forms of item are allowed in the cipher string: | |
24214 | ||
9b371988 PH |
24215 | .ilist |
24216 | It can consist of a single cipher suite such as RC4-SHA. | |
24217 | .next | |
24218 | It can represent a list of cipher suites containing a certain algorithm, | |
168e428f PH |
24219 | or cipher suites of a certain type. For example SHA1 represents all |
24220 | ciphers suites using the digest algorithm SHA1 and SSLv3 represents all | |
24221 | SSL v3 algorithms. | |
9b371988 PH |
24222 | .next |
24223 | Lists of cipher suites can be combined in a single cipher string using | |
168e428f PH |
24224 | the + character. This is used as a logical and operation. For example |
24225 | SHA1+DES represents all cipher suites containing the SHA1 and the DES | |
24226 | algorithms. | |
9b371988 | 24227 | .endlist |
168e428f | 24228 | |
9b371988 PH |
24229 | Each cipher string can be optionally preceded by one of the characters &`!`&, |
24230 | &`-`& or &`+`&. | |
24231 | .ilist | |
24232 | If &`!`& is used, the ciphers are permanently deleted from the list. The | |
168e428f PH |
24233 | ciphers deleted can never reappear in the list even if they are explicitly |
24234 | stated. | |
9b371988 PH |
24235 | .next |
24236 | If &`-`& is used, the ciphers are deleted from the list, but some or all | |
168e428f | 24237 | of the ciphers can be added again by later options. |
9b371988 PH |
24238 | .next |
24239 | If &`+`& is used, the ciphers are moved to the end of the list. This | |
24240 | option does not add any new ciphers; it just moves matching existing ones. | |
24241 | .endlist | |
24242 | ||
24243 | If none of these characters is present, the string is interpreted as | |
168e428f PH |
24244 | a list of ciphers to be appended to the current preference list. If the list |
24245 | includes any ciphers already present they will be ignored: that is, they will | |
9b371988 PH |
24246 | not be moved to the end of the list. |
24247 | .endlist | |
168e428f PH |
24248 | |
24249 | ||
24250 | ||
f89d2485 PH |
24251 | .section "Requiring specific ciphers or other parameters in GnuTLS" &&& |
24252 | "SECTreqciphgnu" | |
24253 | .cindex "GnuTLS" "specifying parameters for" | |
24254 | .cindex "TLS" "specifying ciphers (GnuTLS)" | |
24255 | .cindex "TLS" "specifying key exchange methods (GnuTLS)" | |
24256 | .cindex "TLS" "specifying MAC algorithms (GnuTLS)" | |
24257 | .cindex "TLS" "specifying protocols (GnuTLS)" | |
0a4e3112 | 24258 | .oindex "&%tls_require_ciphers%&" "GnuTLS" |
f89d2485 PH |
24259 | The GnuTLS library allows the caller to specify separate lists of permitted key |
24260 | exchange methods, main cipher algorithms, MAC algorithms, and protocols. | |
24261 | Unfortunately, these lists are numerical, and the library does not have a | |
24262 | function for turning names into numbers. Consequently, lists of recognized | |
24263 | names have to be built into the application. The permitted key exchange | |
24264 | methods, ciphers, and MAC algorithms may be used in any combination to form a | |
24265 | cipher suite. This is unlike OpenSSL, where complete cipher suite names are | |
24266 | passed to its control function. | |
24267 | ||
24268 | For compatibility with OpenSSL, the &%tls_require_ciphers%& option can be set | |
24269 | to complete cipher suite names such as RSA_ARCFOUR_SHA, but for GnuTLS this | |
24270 | option controls only the cipher algorithms. Exim searches each item in the | |
24271 | list for the name of an available algorithm. For example, if the list | |
24272 | contains RSA_AES_SHA, then AES is recognized, and the behaviour is exactly | |
24273 | the same as if just AES were given. | |
24274 | ||
0a4e3112 PH |
24275 | .oindex "&%gnutls_require_kx%&" |
24276 | .oindex "&%gnutls_require_mac%&" | |
24277 | .oindex "&%gnutls_require_protocols%&" | |
f89d2485 PH |
24278 | There are additional options called &%gnutls_require_kx%&, |
24279 | &%gnutls_require_mac%&, and &%gnutls_require_protocols%& that can be used to | |
24280 | restrict the key exchange methods, MAC algorithms, and protocols, respectively. | |
24281 | These options are ignored if OpenSSL is in use. | |
24282 | ||
24283 | All four options are available as global options, controlling how Exim | |
24284 | behaves as a server, and also as options of the &(smtp)& transport, controlling | |
24285 | how Exim behaves as a client. All the values are string expanded. After | |
24286 | expansion, the values must be colon-separated lists, though the separator | |
24287 | can be changed in the usual way. | |
24288 | ||
24289 | Each of the four lists starts out with a default set of algorithms. If the | |
24290 | first item in a list does &'not'& start with an exclamation mark, all the | |
24291 | default items are deleted. In this case, only those that are explicitly | |
24292 | specified can be used. If the first item in a list &'does'& start with an | |
24293 | exclamation mark, the defaults are left on the list. | |
168e428f | 24294 | |
9b371988 | 24295 | Then, any item that starts with an exclamation mark causes the relevant |
f89d2485 PH |
24296 | entry to be removed from the list, and any item that does not start with an |
24297 | exclamation mark causes a new entry to be added to the list. Unrecognized | |
24298 | items in the list are ignored. Thus: | |
9b371988 | 24299 | .code |
f89d2485 | 24300 | tls_require_ciphers = !ARCFOUR |
9b371988 | 24301 | .endd |
f89d2485 | 24302 | allows all the defaults except ARCFOUR, whereas |
9b371988 PH |
24303 | .code |
24304 | tls_require_ciphers = AES : 3DES | |
24305 | .endd | |
f89d2485 PH |
24306 | allows only cipher suites that use AES or 3DES. |
24307 | ||
24308 | For &%tls_require_ciphers%& the recognized names are AES_256, AES_128, AES | |
24309 | (both of the preceding), 3DES, ARCFOUR_128, ARCFOUR_40, and ARCFOUR (both of | |
24310 | the preceding). The default list does not contain all of these; it just has | |
24311 | AES_256, AES_128, 3DES, and ARCFOUR_128. | |
24312 | ||
24313 | For &%gnutls_require_kx%&, the recognized names are DHE_RSA, RSA (which | |
24314 | includes DHE_RSA), DHE_DSS, and DHE (which includes both DHE_RSA and | |
24315 | DHE_DSS). The default list contains RSA, DHE_DSS, DHE_RSA. | |
24316 | ||
24317 | For &%gnutls_require_mac%&, the recognized names are SHA (synonym SHA1), and | |
24318 | MD5. The default list contains SHA, MD5. | |
24319 | ||
24320 | For &%gnutls_require_protocols%&, the recognized names are TLS1 and SSL3. | |
24321 | The default list contains TLS1, SSL3. | |
24322 | ||
24323 | In a server, the order of items in these lists is unimportant. The server | |
24324 | advertises the availability of all the relevant cipher suites. However, in a | |
24325 | client, the order in the &%tls_require_ciphers%& list specifies a preference | |
24326 | order for the cipher algorithms. The first one in the client's list that is | |
168e428f PH |
24327 | also advertised by the server is tried first. The default order is as listed |
24328 | above. | |
24329 | ||
24330 | ||
24331 | ||
f89d2485 | 24332 | .section "Configuring an Exim server to use TLS" "SECID182" |
9b371988 | 24333 | .cindex "TLS" "configuring an Exim server" |
168e428f | 24334 | When Exim has been built with TLS support, it advertises the availability of |
9b371988 | 24335 | the STARTTLS command to client hosts that match &%tls_advertise_hosts%&, |
168e428f PH |
24336 | but not to any others. The default value of this option is unset, which means |
24337 | that STARTTLS is not advertised at all. This default is chosen because you | |
f89d2485 | 24338 | need to set some other options in order to make TLS available, and also it is |
168e428f PH |
24339 | sensible for systems that want to use TLS only as a client. |
24340 | ||
24341 | If a client issues a STARTTLS command and there is some configuration | |
24342 | problem in the server, the command is rejected with a 454 error. If the client | |
24343 | persists in trying to issue SMTP commands, all except QUIT are rejected | |
24344 | with the error | |
9b371988 PH |
24345 | .code |
24346 | 554 Security failure | |
24347 | .endd | |
168e428f PH |
24348 | If a STARTTLS command is issued within an existing TLS session, it is |
24349 | rejected with a 554 error code. | |
24350 | ||
9b371988 PH |
24351 | To enable TLS operations on a server, you must set &%tls_advertise_hosts%& to |
24352 | match some hosts. You can, of course, set it to * to match all hosts. | |
168e428f PH |
24353 | However, this is not all you need to do. TLS sessions to a server won't work |
24354 | without some further configuration at the server end. | |
24355 | ||
24356 | It is rumoured that all existing clients that support TLS/SSL use RSA | |
24357 | encryption. To make this work you need to set, in the server, | |
9b371988 PH |
24358 | .code |
24359 | tls_certificate = /some/file/name | |
24360 | tls_privatekey = /some/file/name | |
24361 | .endd | |
4f578862 PH |
24362 | These options are, in fact, expanded strings, so you can make them depend on |
24363 | the identity of the client that is connected if you wish. The first file | |
24364 | contains the server's X509 certificate, and the second contains the private key | |
24365 | that goes with it. These files need to be readable by the Exim user, and must | |
24366 | always be given as full path names. They can be the same file if both the | |
24367 | certificate and the key are contained within it. If &%tls_privatekey%& is not | |
24368 | set, or if its expansion is forced to fail or results in an empty string, this | |
24369 | is assumed to be the case. The certificate file may also contain intermediate | |
24370 | certificates that need to be sent to the client to enable it to authenticate | |
24371 | the server's certificate. | |
168e428f PH |
24372 | |
24373 | If you do not understand about certificates and keys, please try to find a | |
24374 | source of this background information, which is not Exim-specific. (There are a | |
9b371988 | 24375 | few comments below in section &<<SECTcerandall>>&.) |
168e428f | 24376 | |
9b371988 | 24377 | &*Note*&: These options do not apply when Exim is operating as a client &-- |
4f578862 PH |
24378 | they apply only in the case of a server. If you need to use a certificate in an |
24379 | Exim client, you must set the options of the same names in an &(smtp)& | |
24380 | transport. | |
168e428f | 24381 | |
4f578862 PH |
24382 | With just these options, an Exim server will be able to use TLS. It does not |
24383 | require the client to have a certificate (but see below for how to insist on | |
24384 | this). There is one other option that may be needed in other situations. If | |
9b371988 PH |
24385 | .code |
24386 | tls_dhparam = /some/file/name | |
24387 | .endd | |
168e428f PH |
24388 | is set, the SSL library is initialized for the use of Diffie-Hellman ciphers |
24389 | with the parameters contained in the file. This increases the set of cipher | |
24390 | suites that the server supports. See the command | |
9b371988 PH |
24391 | .code |
24392 | openssl dhparam | |
24393 | .endd | |
4f578862 PH |
24394 | for a way of generating this data. At present, &%tls_dhparam%& is used only |
24395 | when Exim is linked with OpenSSL. It is ignored if GnuTLS is being used. | |
168e428f PH |
24396 | |
24397 | The strings supplied for these three options are expanded every time a client | |
24398 | host connects. It is therefore possible to use different certificates and keys | |
24399 | for different hosts, if you so wish, by making use of the client's IP address | |
9b371988 | 24400 | in &$sender_host_address$& to control the expansion. If a string expansion is |
168e428f PH |
24401 | forced to fail, Exim behaves as if the option is not set. |
24402 | ||
9b371988 PH |
24403 | .cindex "cipher" "logging" |
24404 | .cindex "log" "TLS cipher" | |
f89d2485 | 24405 | .vindex "&$tls_cipher$&" |
9b371988 PH |
24406 | The variable &$tls_cipher$& is set to the cipher suite that was negotiated for |
24407 | an incoming TLS connection. It is included in the &'Received:'& header of an | |
24408 | incoming message (by default &-- you can, of course, change this), and it is | |
24409 | also included in the log line that records a message's arrival, keyed by | |
24410 | &"X="&, unless the &%tls_cipher%& log selector is turned off. The &%encrypted%& | |
24411 | condition can be used to test for specific cipher suites in ACLs. | |
7d0ab55c TF |
24412 | (For outgoing SMTP deliveries, &$tls_cipher$& is reset &-- see section |
24413 | &<<SECID185>>&.) | |
168e428f | 24414 | |
595028e4 PH |
24415 | Once TLS has been established, the ACLs that run for subsequent SMTP commands |
24416 | can check the name of the cipher suite and vary their actions accordingly. The | |
24417 | cipher suite names vary, depending on which TLS library is being used. For | |
24418 | example, OpenSSL uses the name DES-CBC3-SHA for the cipher suite which in other | |
24419 | contexts is known as TLS_RSA_WITH_3DES_EDE_CBC_SHA. Check the OpenSSL or GnuTLS | |
168e428f | 24420 | documentation for more details. |
168e428f PH |
24421 | |
24422 | ||
f89d2485 | 24423 | .section "Requesting and verifying client certificates" "SECID183" |
9b371988 PH |
24424 | .cindex "certificate" "verification of client" |
24425 | .cindex "TLS" "client certificate verification" | |
168e428f | 24426 | If you want an Exim server to request a certificate when negotiating a TLS |
9b371988 PH |
24427 | session with a client, you must set either &%tls_verify_hosts%& or |
24428 | &%tls_try_verify_hosts%&. You can, of course, set either of them to * to | |
168e428f PH |
24429 | apply to all TLS connections. For any host that matches one of these options, |
24430 | Exim requests a certificate as part of the setup of the TLS session. The | |
24431 | contents of the certificate are verified by comparing it with a list of | |
24432 | expected certificates. These must be available in a file or, | |
24433 | for OpenSSL only (not GnuTLS), a directory, identified by | |
9b371988 | 24434 | &%tls_verify_certificates%&. |
168e428f PH |
24435 | |
24436 | A file can contain multiple certificates, concatenated end to end. If a | |
24437 | directory is used | |
24438 | (OpenSSL only), | |
24439 | each certificate must be in a separate file, with a name (or a symbolic link) | |
9b371988 | 24440 | of the form <&'hash'&>.0, where <&'hash'&> is a hash value constructed from the |
168e428f | 24441 | certificate. You can compute the relevant hash by running the command |
9b371988 PH |
24442 | .code |
24443 | openssl x509 -hash -noout -in /cert/file | |
24444 | .endd | |
24445 | where &_/cert/file_& contains a single certificate. | |
168e428f | 24446 | |
9b371988 | 24447 | The difference between &%tls_verify_hosts%& and &%tls_try_verify_hosts%& is |
168e428f PH |
24448 | what happens if the client does not supply a certificate, or if the certificate |
24449 | does not match any of the certificates in the collection named by | |
9b371988 | 24450 | &%tls_verify_certificates%&. If the client matches &%tls_verify_hosts%&, the |
168e428f | 24451 | attempt to set up a TLS session is aborted, and the incoming connection is |
9b371988 | 24452 | dropped. If the client matches &%tls_try_verify_hosts%&, the (encrypted) SMTP |
168e428f PH |
24453 | session continues. ACLs that run for subsequent SMTP commands can detect the |
24454 | fact that no certificate was verified, and vary their actions accordingly. For | |
24455 | example, you can insist on a certificate before accepting a message for | |
24456 | relaying, but not when the message is destined for local delivery. | |
24457 | ||
f89d2485 | 24458 | .vindex "&$tls_peerdn$&" |
168e428f PH |
24459 | When a client supplies a certificate (whether it verifies or not), the value of |
24460 | the Distinguished Name of the certificate is made available in the variable | |
9b371988 | 24461 | &$tls_peerdn$& during subsequent processing of the message. |
168e428f | 24462 | |
9b371988 | 24463 | .cindex "log" "distinguished name" |
168e428f | 24464 | Because it is often a long text string, it is not included in the log line or |
9b371988 PH |
24465 | &'Received:'& header by default. You can arrange for it to be logged, keyed by |
24466 | &"DN="&, by setting the &%tls_peerdn%& log selector, and you can use | |
24467 | &%received_header_text%& to change the &'Received:'& header. When no | |
24468 | certificate is supplied, &$tls_peerdn$& is empty. | |
168e428f PH |
24469 | |
24470 | ||
f89d2485 | 24471 | .section "Revoked certificates" "SECID184" |
9b371988 PH |
24472 | .cindex "TLS" "revoked certificates" |
24473 | .cindex "revocation list" | |
24474 | .cindex "certificate" "revocation list" | |
168e428f PH |
24475 | Certificate issuing authorities issue Certificate Revocation Lists (CRLs) when |
24476 | certificates are revoked. If you have such a list, you can pass it to an Exim | |
9b371988 PH |
24477 | server using the global option called &%tls_crl%& and to an Exim client using |
24478 | an identically named option for the &(smtp)& transport. In each case, the value | |
24479 | of the option is expanded and must then be the name of a file that contains a | |
24480 | CRL in PEM format. | |
24481 | ||
24482 | ||
f89d2485 | 24483 | .section "Configuring an Exim client to use TLS" "SECID185" |
9b371988 PH |
24484 | .cindex "cipher" "logging" |
24485 | .cindex "log" "TLS cipher" | |
24486 | .cindex "log" "distinguished name" | |
24487 | .cindex "TLS" "configuring an Exim client" | |
24488 | The &%tls_cipher%& and &%tls_peerdn%& log selectors apply to outgoing SMTP | |
168e428f PH |
24489 | deliveries as well as to incoming, the latter one causing logging of the |
24490 | server certificate's DN. The remaining client configuration for TLS is all | |
9b371988 | 24491 | within the &(smtp)& transport. |
168e428f | 24492 | |
9b371988 | 24493 | It is not necessary to set any options to have TLS work in the &(smtp)& |
168e428f | 24494 | transport. If Exim is built with TLS support, and TLS is advertised by a |
9b371988 PH |
24495 | server, the &(smtp)& transport always tries to start a TLS session. However, |
24496 | this can be prevented by setting &%hosts_avoid_tls%& (an option of the | |
168e428f PH |
24497 | transport) to a list of server hosts for which TLS should not be used. |
24498 | ||
24499 | If you do not want Exim to attempt to send messages unencrypted when an attempt | |
24500 | to set up an encrypted connection fails in any way, you can set | |
9b371988 | 24501 | &%hosts_require_tls%& to a list of hosts for which encryption is mandatory. For |
168e428f PH |
24502 | those hosts, delivery is always deferred if an encrypted connection cannot be |
24503 | set up. If there are any other hosts for the address, they are tried in the | |
24504 | usual way. | |
24505 | ||
9b371988 | 24506 | When the server host is not in &%hosts_require_tls%&, Exim may try to deliver |
168e428f | 24507 | the message unencrypted. It always does this if the response to STARTTLS is |
9b371988 | 24508 | a 5&'xx'& code. For a temporary error code, or for a failure to negotiate a TLS |
168e428f | 24509 | session after a success response code, what happens is controlled by the |
9b371988 | 24510 | &%tls_tempfail_tryclear%& option of the &(smtp)& transport. If it is false, |
168e428f | 24511 | delivery to this host is deferred, and other hosts (if available) are tried. If |
9b371988 | 24512 | it is true, Exim attempts to deliver unencrypted after a 4&'xx'& response to |
168e428f PH |
24513 | STARTTLS, and if STARTTLS is accepted, but the subsequent TLS |
24514 | negotiation fails, Exim closes the current connection (because it is in an | |
24515 | unknown state), opens a new one to the same host, and then tries the delivery | |
24516 | unencrypted. | |
24517 | ||
9b371988 PH |
24518 | The &%tls_certificate%& and &%tls_privatekey%& options of the &(smtp)& |
24519 | transport provide the client with a certificate, which is passed to the server | |
24520 | if it requests it. If the server is Exim, it will request a certificate only if | |
07af267e | 24521 | &%tls_verify_hosts%& or &%tls_try_verify_hosts%& matches the client. |
168e428f | 24522 | |
07af267e NM |
24523 | If the &%tls_verify_certificates%& option is set on the &(smtp)& transport, it |
24524 | must name a file or, | |
168e428f PH |
24525 | for OpenSSL only (not GnuTLS), a directory, that contains a collection of |
24526 | expected server certificates. The client verifies the server's certificate | |
24527 | against this collection, taking into account any revoked certificates that are | |
9b371988 | 24528 | in the list defined by &%tls_crl%&. |
168e428f PH |
24529 | |
24530 | If | |
9b371988 | 24531 | &%tls_require_ciphers%& is set on the &(smtp)& transport, it must contain a |
168e428f | 24532 | list of permitted cipher suites. If either of these checks fails, delivery to |
9b371988 | 24533 | the current host is abandoned, and the &(smtp)& transport tries to deliver to |
168e428f PH |
24534 | alternative hosts, if any. |
24535 | ||
07af267e NM |
24536 | &*Note*&: |
24537 | These options must be set in the &(smtp)& transport for Exim to use TLS when it | |
24538 | is operating as a client. Exim does not assume that a server certificate (set | |
24539 | by the global options of the same name) should also be used when operating as a | |
24540 | client. | |
24541 | ||
f89d2485 PH |
24542 | .vindex "&$host$&" |
24543 | .vindex "&$host_address$&" | |
9b371988 PH |
24544 | All the TLS options in the &(smtp)& transport are expanded before use, with |
24545 | &$host$& and &$host_address$& containing the name and address of the server to | |
168e428f PH |
24546 | which the client is connected. Forced failure of an expansion causes Exim to |
24547 | behave as if the relevant option were unset. | |
24548 | ||
595028e4 PH |
24549 | .vindex &$tls_cipher$& |
24550 | .vindex &$tls_peerdn$& | |
24551 | Before an SMTP connection is established, the &$tls_cipher$& and &$tls_peerdn$& | |
24552 | variables are emptied. (Until the first connection, they contain the values | |
24553 | that were set when the message was received.) If STARTTLS is subsequently | |
24554 | successfully obeyed, these variables are set to the relevant values for the | |
24555 | outgoing connection. | |
595028e4 | 24556 | |
168e428f PH |
24557 | |
24558 | ||
9b371988 PH |
24559 | .section "Multiple messages on the same encrypted TCP/IP connection" &&& |
24560 | "SECTmulmessam" | |
24561 | .cindex "multiple SMTP deliveries with TLS" | |
24562 | .cindex "TLS" "multiple message deliveries" | |
168e428f PH |
24563 | Exim sends multiple messages down the same TCP/IP connection by starting up |
24564 | an entirely new delivery process for each message, passing the socket from | |
24565 | one process to the next. This implementation does not fit well with the use | |
24566 | of TLS, because there is quite a lot of state information associated with a TLS | |
24567 | connection, not just a socket identification. Passing all the state information | |
24568 | to a new process is not feasible. Consequently, Exim shuts down an existing TLS | |
24569 | session before passing the socket to a new process. The new process may then | |
24570 | try to start a new TLS session, and if successful, may try to re-authenticate | |
24571 | if AUTH is in use, before sending the next message. | |
24572 | ||
24573 | The RFC is not clear as to whether or not an SMTP session continues in clear | |
24574 | after TLS has been shut down, or whether TLS may be restarted again later, as | |
24575 | just described. However, if the server is Exim, this shutdown and | |
24576 | reinitialization works. It is not known which (if any) other servers operate | |
24577 | successfully if the client closes a TLS session and continues with unencrypted | |
24578 | SMTP, but there are certainly some that do not work. For such servers, Exim | |
24579 | should not pass the socket to another process, because the failure of the | |
24580 | subsequent attempt to use it would cause Exim to record a temporary host error, | |
24581 | and delay other deliveries to that host. | |
24582 | ||
24583 | To test for this case, Exim sends an EHLO command to the server after | |
24584 | closing down the TLS session. If this fails in any way, the connection is | |
24585 | closed instead of being passed to a new delivery process, but no retry | |
24586 | information is recorded. | |
24587 | ||
9b371988 PH |
24588 | There is also a manual override; you can set &%hosts_nopass_tls%& on the |
24589 | &(smtp)& transport to match those hosts for which Exim should not pass | |
168e428f PH |
24590 | connections to new processes if TLS has been used. |
24591 | ||
24592 | ||
24593 | ||
24594 | ||
9b371988 PH |
24595 | .section "Certificates and all that" "SECTcerandall" |
24596 | .cindex "certificate" "references to discussion" | |
168e428f PH |
24597 | In order to understand fully how TLS works, you need to know about |
24598 | certificates, certificate signing, and certificate authorities. This is not the | |
24599 | place to give a tutorial, especially as I do not know very much about it | |
24600 | myself. Some helpful introduction can be found in the FAQ for the SSL addition | |
24601 | to Apache, currently at | |
9b371988 PH |
24602 | .display |
24603 | &url(http://www.modssl.org/docs/2.7/ssl_faq.html#ToC24) | |
24604 | .endd | |
24605 | Other parts of the &'modssl'& documentation are also helpful, and have | |
168e428f | 24606 | links to further files. |
9b371988 | 24607 | Eric Rescorla's book, &'SSL and TLS'&, published by Addison-Wesley (ISBN |
168e428f PH |
24608 | 0-201-61598-3), contains both introductory and more in-depth descriptions. |
24609 | Some sample programs taken from the book are available from | |
9b371988 PH |
24610 | .display |
24611 | &url(http://www.rtfm.com/openssl-examples/) | |
24612 | .endd | |
168e428f | 24613 | |
168e428f | 24614 | |
f89d2485 | 24615 | .section "Certificate chains" "SECID186" |
9b371988 | 24616 | The file named by &%tls_certificate%& may contain more than one |
168e428f PH |
24617 | certificate. This is useful in the case where the certificate that is being |
24618 | sent is validated by an intermediate certificate which the other end does | |
24619 | not have. Multiple certificates must be in the correct order in the file. | |
24620 | First the host's certificate itself, then the first intermediate | |
24621 | certificate to validate the issuer of the host certificate, then the next | |
24622 | intermediate certificate to validate the issuer of the first intermediate | |
24623 | certificate, and so on, until finally (optionally) the root certificate. | |
24624 | The root certificate must already be trusted by the recipient for | |
24625 | validation to succeed, of course, but if it's not preinstalled, sending the | |
24626 | root certificate along with the rest makes it available for the user to | |
24627 | install if the receiving end is a client MUA that can interact with a user. | |
24628 | ||
24629 | ||
f89d2485 | 24630 | .section "Self-signed certificates" "SECID187" |
9b371988 PH |
24631 | .cindex "certificate" "self-signed" |
24632 | You can create a self-signed certificate using the &'req'& command provided | |
168e428f | 24633 | with OpenSSL, like this: |
9b371988 | 24634 | .code |
168e428f PH |
24635 | openssl req -x509 -newkey rsa:1024 -keyout file1 -out file2 \ |
24636 | -days 9999 -nodes | |
9b371988 PH |
24637 | .endd |
24638 | &_file1_& and &_file2_& can be the same file; the key and the certificate are | |
24639 | delimited and so can be identified independently. The &%-days%& option | |
24640 | specifies a period for which the certificate is valid. The &%-nodes%& option is | |
168e428f PH |
24641 | important: if you do not set it, the key is encrypted with a passphrase |
24642 | that you are prompted for, and any use that is made of the key causes more | |
24643 | prompting for the passphrase. This is not helpful if you are going to use | |
24644 | this certificate and key in an MTA, where prompting is not possible. | |
24645 | ||
24646 | A self-signed certificate made in this way is sufficient for testing, and | |
24647 | may be adequate for all your requirements if you are mainly interested in | |
24648 | encrypting transfers, and not in secure identification. | |
24649 | ||
24650 | However, many clients require that the certificate presented by the server be a | |
9b371988 | 24651 | user (also called &"leaf"& or &"site"&) certificate, and not a self-signed |
168e428f | 24652 | certificate. In this situation, the self-signed certificate described above |
9b371988 PH |
24653 | must be installed on the client host as a trusted root &'certification |
24654 | authority'& (CA), and the certificate used by Exim must be a user certificate | |
168e428f PH |
24655 | signed with that self-signed certificate. |
24656 | ||
24657 | For information on creating self-signed CA certificates and using them to sign | |
9b371988 PH |
24658 | user certificates, see the &'General implementation overview'& chapter of the |
24659 | Open-source PKI book, available online at | |
24660 | &url(http://ospkibook.sourceforge.net/). | |
4f578862 PH |
24661 | .ecindex IIDencsmtp1 |
24662 | .ecindex IIDencsmtp2 | |
168e428f PH |
24663 | |
24664 | ||
24665 | ||
9b371988 PH |
24666 | . //////////////////////////////////////////////////////////////////////////// |
24667 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 24668 | |
9b371988 | 24669 | .chapter "Access control lists" "CHAPACL" |
4f578862 | 24670 | .scindex IIDacl "&ACL;" "description" |
9b371988 PH |
24671 | .cindex "control of incoming mail" |
24672 | .cindex "message" "controlling incoming" | |
24673 | .cindex "policy control" "access control lists" | |
168e428f | 24674 | Access Control Lists (ACLs) are defined in a separate section of the run time |
9b371988 | 24675 | configuration file, headed by &"begin acl"&. Each ACL definition starts with a |
168e428f PH |
24676 | name, terminated by a colon. Here is a complete ACL section that contains just |
24677 | one very small ACL: | |
9b371988 PH |
24678 | .code |
24679 | begin acl | |
9b371988 PH |
24680 | small_acl: |
24681 | accept hosts = one.host.only | |
24682 | .endd | |
168e428f PH |
24683 | You can have as many lists as you like in the ACL section, and the order in |
24684 | which they appear does not matter. The lists are self-terminating. | |
24685 | ||
24686 | The majority of ACLs are used to control Exim's behaviour when it receives | |
24687 | certain SMTP commands. This applies both to incoming TCP/IP connections, and | |
9b371988 | 24688 | when a local process submits a message using SMTP by specifying the &%-bs%& |
168e428f PH |
24689 | option. The most common use is for controlling which recipients are accepted |
24690 | in incoming messages. In addition, you can define an ACL that is used to check | |
24691 | local non-SMTP messages. The default configuration file contains an example of | |
24692 | a realistic ACL for checking RCPT commands. This is discussed in chapter | |
9b371988 | 24693 | &<<CHAPdefconfil>>&. |
168e428f PH |
24694 | |
24695 | ||
f89d2485 | 24696 | .section "Testing ACLs" "SECID188" |
9b371988 PH |
24697 | The &%-bh%& command line option provides a way of testing your ACL |
24698 | configuration locally by running a fake SMTP session with which you interact. | |
24699 | The host &'relay-test.mail-abuse.org'& provides a service for checking your | |
24700 | relaying configuration (see section &<<SECTcheralcon>>& for more details). | |
168e428f PH |
24701 | |
24702 | ||
24703 | ||
f89d2485 | 24704 | .section "Specifying when ACLs are used" "SECID189" |
9b371988 | 24705 | .cindex "&ACL;" "options for specifying" |
168e428f PH |
24706 | In order to cause an ACL to be used, you have to name it in one of the relevant |
24707 | options in the main part of the configuration. These options are: | |
9b371988 PH |
24708 | .cindex "AUTH" "ACL for" |
24709 | .cindex "DATA" "ACLs for" | |
24710 | .cindex "ETRN" "ACL for" | |
24711 | .cindex "EXPN" "ACL for" | |
24712 | .cindex "HELO" "ACL for" | |
24713 | .cindex "EHLO" "ACL for" | |
24714 | .cindex "MAIL" "ACL for" | |
f89d2485 | 24715 | .cindex "QUIT, ACL for" |
9b371988 | 24716 | .cindex "RCPT" "ACL for" |
f89d2485 | 24717 | .cindex "STARTTLS, ACL for" |
9b371988 | 24718 | .cindex "VRFY" "ACL for" |
f89d2485 PH |
24719 | .cindex "SMTP" "connection, ACL for" |
24720 | .cindex "non-SMTP messages" "ACLs for" | |
24721 | .cindex "MIME content scanning" "ACL for" | |
9b371988 PH |
24722 | |
24723 | .table2 140pt | |
f89d2485 PH |
24724 | .irow &%acl_not_smtp%& "ACL for non-SMTP messages" |
24725 | .irow &%acl_not_smtp_mime%& "ACL for non-SMTP MIME parts" | |
24726 | .irow &%acl_not_smtp_start%& "ACL at start of non-SMTP message" | |
24727 | .irow &%acl_smtp_auth%& "ACL for AUTH" | |
24728 | .irow &%acl_smtp_connect%& "ACL for start of SMTP connection" | |
24729 | .irow &%acl_smtp_data%& "ACL after DATA is complete" | |
24730 | .irow &%acl_smtp_etrn%& "ACL for ETRN" | |
24731 | .irow &%acl_smtp_expn%& "ACL for EXPN" | |
24732 | .irow &%acl_smtp_helo%& "ACL for HELO or EHLO" | |
24733 | .irow &%acl_smtp_mail%& "ACL for MAIL" | |
24734 | .irow &%acl_smtp_mailauth%& "ACL for the AUTH parameter of MAIL" | |
24735 | .irow &%acl_smtp_mime%& "ACL for content-scanning MIME parts" | |
7d0ab55c | 24736 | .irow &%acl_smtp_notquit%& "ACL for non-QUIT terminations" |
f89d2485 PH |
24737 | .irow &%acl_smtp_predata%& "ACL at start of DATA command" |
24738 | .irow &%acl_smtp_quit%& "ACL for QUIT" | |
24739 | .irow &%acl_smtp_rcpt%& "ACL for RCPT" | |
24740 | .irow &%acl_smtp_starttls%& "ACL for STARTTLS" | |
24741 | .irow &%acl_smtp_vrfy%& "ACL for VRFY" | |
9b371988 | 24742 | .endtable |
168e428f PH |
24743 | |
24744 | For example, if you set | |
9b371988 PH |
24745 | .code |
24746 | acl_smtp_rcpt = small_acl | |
24747 | .endd | |
168e428f PH |
24748 | the little ACL defined above is used whenever Exim receives a RCPT command |
24749 | in an SMTP dialogue. The majority of policy tests on incoming messages can be | |
24750 | done when RCPT commands arrive. A rejection of RCPT should cause the | |
24751 | sending MTA to give up on the recipient address contained in the RCPT | |
24752 | command, whereas rejection at other times may cause the client MTA to keep on | |
24753 | trying to deliver the message. It is therefore recommended that you do as much | |
24754 | testing as possible at RCPT time. | |
24755 | ||
24756 | ||
f89d2485 PH |
24757 | .section "The non-SMTP ACLs" "SECID190" |
24758 | .cindex "non-SMTP messages" "ACLs for" | |
db9452a9 PH |
24759 | The non-SMTP ACLs apply to all non-interactive incoming messages, that is, they |
24760 | apply to batched SMTP as well as to non-SMTP messages. (Batched SMTP is not | |
24761 | really SMTP.) Many of the ACL conditions (for example, host tests, and tests on | |
24762 | the state of the SMTP connection such as encryption and authentication) are not | |
24763 | relevant and are forbidden in these ACLs. However, the sender and recipients | |
24764 | are known, so the &%senders%& and &%sender_domains%& conditions and the | |
24765 | &$sender_address$& and &$recipients$& variables can be used. Variables such as | |
24766 | &$authenticated_sender$& are also available. You can specify added header lines | |
24767 | in any of these ACLs. | |
24768 | ||
24769 | The &%acl_not_smtp_start%& ACL is run right at the start of receiving a | |
24770 | non-SMTP message, before any of the message has been read. (This is the | |
595028e4 PH |
24771 | analogue of the &%acl_smtp_predata%& ACL for SMTP input.) In the case of |
24772 | batched SMTP input, it runs after the DATA command has been reached. The | |
f89d2485 PH |
24773 | result of this ACL is ignored; it cannot be used to reject a message. If you |
24774 | really need to, you could set a value in an ACL variable here and reject based | |
24775 | on that in the &%acl_not_smtp%& ACL. However, this ACL can be used to set | |
24776 | controls, and in particular, it can be used to set | |
db9452a9 PH |
24777 | .code |
24778 | control = suppress_local_fixups | |
24779 | .endd | |
24780 | This cannot be used in the other non-SMTP ACLs because by the time they are | |
24781 | run, it is too late. | |
24782 | ||
24783 | The &%acl_not_smtp_mime%& ACL is available only when Exim is compiled with the | |
24784 | content-scanning extension. For details, see chapter &<<CHAPexiscan>>&. | |
24785 | ||
24786 | The &%acl_not_smtp%& ACL is run just before the &[local_scan()]& function. Any | |
168e428f | 24787 | kind of rejection is treated as permanent, because there is no way of sending a |
db9452a9 | 24788 | temporary error for these kinds of message. |
168e428f PH |
24789 | |
24790 | ||
f89d2485 PH |
24791 | .section "The SMTP connect ACL" "SECID191" |
24792 | .cindex "SMTP" "connection, ACL for" | |
0a4e3112 | 24793 | .oindex &%smtp_banner%& |
db9452a9 PH |
24794 | The ACL test specified by &%acl_smtp_connect%& happens at the start of an SMTP |
24795 | session, after the test specified by &%host_reject_connection%& (which is now | |
3cb1b51e PH |
24796 | an anomaly) and any TCP Wrappers testing (if configured). If the connection is |
24797 | accepted by an &%accept%& verb that has a &%message%& modifier, the contents of | |
24798 | the message override the banner message that is otherwise specified by the | |
24799 | &%smtp_banner%& option. | |
24800 | ||
24801 | ||
f89d2485 | 24802 | .section "The EHLO/HELO ACL" "SECID192" |
3cb1b51e PH |
24803 | .cindex "EHLO" "ACL for" |
24804 | .cindex "HELO" "ACL for" | |
24805 | The ACL test specified by &%acl_smtp_helo%& happens when the client issues an | |
24806 | EHLO or HELO command, after the tests specified by &%helo_accept_junk_hosts%&, | |
24807 | &%helo_allow_chars%&, &%helo_verify_hosts%&, and &%helo_try_verify_hosts%&. | |
24808 | Note that a client may issue more than one EHLO or HELO command in an SMTP | |
24809 | session, and indeed is required to issue a new EHLO or HELO after successfully | |
24810 | setting up encryption following a STARTTLS command. | |
24811 | ||
24812 | If the command is accepted by an &%accept%& verb that has a &%message%& | |
24813 | modifier, the message may not contain more than one line (it will be truncated | |
24814 | at the first newline and a panic logged if it does). Such a message cannot | |
24815 | affect the EHLO options that are listed on the second and subsequent lines of | |
24816 | an EHLO response. | |
168e428f PH |
24817 | |
24818 | ||
f89d2485 | 24819 | .section "The DATA ACLs" "SECID193" |
9b371988 | 24820 | .cindex "DATA" "ACLs for" |
168e428f PH |
24821 | Two ACLs are associated with the DATA command, because it is two-stage |
24822 | command, with two responses being sent to the client. | |
9b371988 | 24823 | When the DATA command is received, the ACL defined by &%acl_smtp_predata%& |
168e428f PH |
24824 | is obeyed. This gives you control after all the RCPT commands, but before |
24825 | the message itself is received. It offers the opportunity to give a negative | |
24826 | response to the DATA command before the data is transmitted. Header lines | |
24827 | added by MAIL or RCPT ACLs are not visible at this time, but any that | |
9b371988 | 24828 | are defined here are visible when the &%acl_smtp_data%& ACL is run. |
168e428f PH |
24829 | |
24830 | You cannot test the contents of the message, for example, to verify addresses | |
24831 | in the headers, at RCPT time or when the DATA command is received. Such | |
24832 | tests have to appear in the ACL that is run after the message itself has been | |
24833 | received, before the final response to the DATA command is sent. This is | |
9b371988 | 24834 | the ACL specified by &%acl_smtp_data%&, which is the second ACL that is |
168e428f PH |
24835 | associated with the DATA command. |
24836 | ||
24837 | For both of these ACLs, it is not possible to reject individual recipients. An | |
24838 | error response rejects the entire message. Unfortunately, it is known that some | |
9b371988 PH |
24839 | MTAs do not treat hard (5&'xx'&) responses to the DATA command (either |
24840 | before or after the data) correctly &-- they keep the message on their queues | |
168e428f PH |
24841 | and try again later, but that is their problem, though it does waste some of |
24842 | your resources. | |
24843 | ||
24844 | ||
f89d2485 | 24845 | .section "The SMTP MIME ACL" "SECID194" |
9b371988 PH |
24846 | The &%acl_smtp_mime%& option is available only when Exim is compiled with the |
24847 | content-scanning extension. For details, see chapter &<<CHAPexiscan>>&. | |
168e428f PH |
24848 | |
24849 | ||
9b371988 | 24850 | .section "The QUIT ACL" "SECTQUITACL" |
f89d2485 | 24851 | .cindex "QUIT, ACL for" |
068aaea8 PH |
24852 | The ACL for the SMTP QUIT command is anomalous, in that the outcome of the ACL |
24853 | does not affect the response code to QUIT, which is always 221. Thus, the ACL | |
24854 | does not in fact control any access. For this reason, the only verbs that are | |
9b371988 | 24855 | permitted are &%accept%& and &%warn%&. |
168e428f PH |
24856 | |
24857 | This ACL can be used for tasks such as custom logging at the end of an SMTP | |
24858 | session. For example, you can use ACL variables in other ACLs to count | |
24859 | messages, recipients, etc., and log the totals at QUIT time using one or | |
9b371988 | 24860 | more &%logwrite%& modifiers on a &%warn%& verb. |
168e428f | 24861 | |
9b371988 PH |
24862 | &*Warning*&: Only the &$acl_c$&&'x'& variables can be used for this, because |
24863 | the &$acl_m$&&'x'& variables are reset at the end of each incoming message. | |
068aaea8 | 24864 | |
9b371988 PH |
24865 | You do not need to have a final &%accept%&, but if you do, you can use a |
24866 | &%message%& modifier to specify custom text that is sent as part of the 221 | |
168e428f PH |
24867 | response to QUIT. |
24868 | ||
9b371988 | 24869 | This ACL is run only for a &"normal"& QUIT. For certain kinds of disastrous |
168e428f PH |
24870 | failure (for example, failure to open a log file, or when Exim is bombing out |
24871 | because it has detected an unrecoverable error), all SMTP commands from the | |
24872 | client are given temporary error responses until QUIT is received or the | |
24873 | connection is closed. In these special cases, the QUIT ACL does not run. | |
24874 | ||
24875 | ||
595028e4 | 24876 | .section "The not-QUIT ACL" "SECTNOTQUITACL" |
3ac82526 | 24877 | .vindex &$acl_smtp_notquit$& |
4f054c63 | 24878 | The not-QUIT ACL, specified by &%acl_smtp_notquit%&, is run in most cases when |
595028e4 PH |
24879 | an SMTP session ends without sending QUIT. However, when Exim itself is is bad |
24880 | trouble, such as being unable to write to its log files, this ACL is not run, | |
24881 | because it might try to do things (such as write to log files) that make the | |
24882 | situation even worse. | |
24883 | ||
24884 | Like the QUIT ACL, this ACL is provided to make it possible to do customized | |
24885 | logging or to gather statistics, and its outcome is ignored. The &%delay%& | |
24886 | modifier is forbidden in this ACL, and the only permitted verbs are &%accept%& | |
24887 | and &%warn%&. | |
24888 | ||
24889 | .vindex &$smtp_notquit_reason$& | |
24890 | When the not-QUIT ACL is running, the variable &$smtp_notquit_reason$& is set | |
24891 | to a string that indicates the reason for the termination of the SMTP | |
24892 | connection. The possible values are: | |
24893 | .table2 | |
24894 | .irow &`acl-drop`& "Another ACL issued a &%drop%& command" | |
24895 | .irow &`bad-commands`& "Too many unknown or non-mail commands" | |
24896 | .irow &`command-timeout`& "Timeout while reading SMTP commands" | |
24897 | .irow &`connection-lost`& "The SMTP connection has been lost" | |
24898 | .irow &`data-timeout`& "Timeout while reading message data" | |
24899 | .irow &`local-scan-error`& "The &[local_scan()]& function crashed" | |
24900 | .irow &`local-scan-timeout`& "The &[local_scan()]& function timed out" | |
24901 | .irow &`signal-exit`& "SIGTERM or SIGINT" | |
24902 | .irow &`synchronization-error`& "SMTP synchronization error" | |
24903 | .irow &`tls-failed`& "TLS failed to start" | |
24904 | .endtable | |
24905 | In most cases when an SMTP connection is closed without having received QUIT, | |
24906 | Exim sends an SMTP response message before actually closing the connection. | |
24907 | With the exception of the &`acl-drop`& case, the default message can be | |
24908 | overridden by the &%message%& modifier in the not-QUIT ACL. In the case of a | |
24909 | &%drop%& verb in another ACL, it is the message from the other ACL that is | |
24910 | used. | |
595028e4 PH |
24911 | |
24912 | ||
f89d2485 | 24913 | .section "Finding an ACL to use" "SECID195" |
9b371988 | 24914 | .cindex "&ACL;" "finding which to use" |
6083aca0 TF |
24915 | The value of an &%acl_smtp_%&&'xxx'& option is expanded before use, so |
24916 | you can use different ACLs in different circumstances. For example, | |
24917 | .code | |
24918 | acl_smtp_rcpt = ${if ={25}{$interface_port} \ | |
24919 | {acl_check_rcpt} {acl_check_rcpt_submit} } | |
24920 | .endd | |
24921 | In the default configuration file there are some example settings for | |
24922 | providing an RFC 4409 message submission service on port 587 and a | |
24923 | non-standard &"smtps"& service on port 465. You can use a string | |
24924 | expansion like this to choose an ACL for MUAs on these ports which is | |
24925 | more appropriate for this purpose than the default ACL on port 25. | |
24926 | ||
24927 | The expanded string does not have to be the name of an ACL in the | |
24928 | configuration file; there are other possibilities. Having expanded the | |
24929 | string, Exim searches for an ACL as follows: | |
168e428f | 24930 | |
9b371988 PH |
24931 | .ilist |
24932 | If the string begins with a slash, Exim uses it as a file name, and reads its | |
168e428f PH |
24933 | contents as an ACL. The lines are processed in the same way as lines in the |
24934 | Exim configuration file. In particular, continuation lines are supported, blank | |
9b371988 | 24935 | lines are ignored, as are lines whose first non-whitespace character is &"#"&. |
168e428f PH |
24936 | If the file does not exist or cannot be read, an error occurs (typically |
24937 | causing a temporary failure of whatever caused the ACL to be run). For example: | |
9b371988 | 24938 | .code |
168e428f PH |
24939 | acl_smtp_data = /etc/acls/\ |
24940 | ${lookup{$sender_host_address}lsearch\ | |
24941 | {/etc/acllist}{$value}{default}} | |
9b371988 | 24942 | .endd |
168e428f PH |
24943 | This looks up an ACL file to use on the basis of the host's IP address, falling |
24944 | back to a default if the lookup fails. If an ACL is successfully read from a | |
24945 | file, it is retained in memory for the duration of the Exim process, so that it | |
24946 | can be re-used without having to re-read the file. | |
9b371988 PH |
24947 | .next |
24948 | If the string does not start with a slash, and does not contain any spaces, | |
168e428f PH |
24949 | Exim searches the ACL section of the configuration for an ACL whose name |
24950 | matches the string. | |
9b371988 PH |
24951 | .next |
24952 | If no named ACL is found, or if the string contains spaces, Exim parses | |
168e428f PH |
24953 | the string as an inline ACL. This can save typing in cases where you just |
24954 | want to have something like | |
9b371988 PH |
24955 | .code |
24956 | acl_smtp_vrfy = accept | |
24957 | .endd | |
168e428f PH |
24958 | in order to allow free use of the VRFY command. Such a string may contain |
24959 | newlines; it is processed in the same way as an ACL that is read from a file. | |
9b371988 | 24960 | .endlist |
168e428f PH |
24961 | |
24962 | ||
24963 | ||
24964 | ||
f89d2485 | 24965 | .section "ACL return codes" "SECID196" |
9b371988 | 24966 | .cindex "&ACL;" "return codes" |
168e428f | 24967 | Except for the QUIT ACL, which does not affect the SMTP return code (see |
9b371988 PH |
24968 | section &<<SECTQUITACL>>& above), the result of running an ACL is either |
24969 | &"accept"& or &"deny"&, or, if some test cannot be completed (for example, if a | |
24970 | database is down), &"defer"&. These results cause 2&'xx'&, 5&'xx'&, and 4&'xx'& | |
24971 | return codes, respectively, to be used in the SMTP dialogue. A fourth return, | |
24972 | &"error"&, occurs when there is an error such as invalid syntax in the ACL. | |
24973 | This also causes a 4&'xx'& return code. | |
24974 | ||
24975 | For the non-SMTP ACL, &"defer"& and &"error"& are treated in the same way as | |
24976 | &"deny"&, because there is no mechanism for passing temporary errors to the | |
168e428f PH |
24977 | submitters of non-SMTP messages. |
24978 | ||
24979 | ||
9b371988 PH |
24980 | ACLs that are relevant to message reception may also return &"discard"&. This |
24981 | has the effect of &"accept"&, but causes either the entire message or an | |
168e428f PH |
24982 | individual recipient address to be discarded. In other words, it is a |
24983 | blackholing facility. Use it with care. | |
24984 | ||
9b371988 PH |
24985 | If the ACL for MAIL returns &"discard"&, all recipients are discarded, and no |
24986 | ACL is run for subsequent RCPT commands. The effect of &"discard"& in a | |
168e428f PH |
24987 | RCPT ACL is to discard just the one recipient address. If there are no |
24988 | recipients left when the message's data is received, the DATA ACL is not | |
9b371988 PH |
24989 | run. A &"discard"& return from the DATA or the non-SMTP ACL discards all the |
24990 | remaining recipients. The &"discard"& return is not permitted for the | |
24991 | &%acl_smtp_predata%& ACL. | |
168e428f | 24992 | |
168e428f | 24993 | |
9b371988 PH |
24994 | .cindex "&[local_scan()]& function" "when all recipients discarded" |
24995 | The &[local_scan()]& function is always run, even if there are no remaining | |
168e428f PH |
24996 | recipients; it may create new recipients. |
24997 | ||
24998 | ||
24999 | ||
f89d2485 | 25000 | .section "Unset ACL options" "SECID197" |
9b371988 PH |
25001 | .cindex "&ACL;" "unset options" |
25002 | The default actions when any of the &%acl_%&&'xxx'& options are unset are not | |
25003 | all the same. &*Note*&: These defaults apply only when the relevant ACL is | |
25004 | not defined at all. For any defined ACL, the default action when control | |
25005 | reaches the end of the ACL statements is &"deny"&. | |
168e428f | 25006 | |
db9452a9 PH |
25007 | For &%acl_smtp_quit%& and &%acl_not_smtp_start%& there is no default because |
25008 | these two are ACLs that are used only for their side effects. They cannot be | |
25009 | used to accept or reject anything. | |
db9452a9 | 25010 | |
9b371988 PH |
25011 | For &%acl_not_smtp%&, &%acl_smtp_auth%&, &%acl_smtp_connect%&, |
25012 | &%acl_smtp_data%&, &%acl_smtp_helo%&, &%acl_smtp_mail%&, &%acl_smtp_mailauth%&, | |
db9452a9 PH |
25013 | &%acl_smtp_mime%&, &%acl_smtp_predata%&, and &%acl_smtp_starttls%&, the action |
25014 | when the ACL is not defined is &"accept"&. | |
168e428f | 25015 | |
9b371988 PH |
25016 | For the others (&%acl_smtp_etrn%&, &%acl_smtp_expn%&, &%acl_smtp_rcpt%&, and |
25017 | &%acl_smtp_vrfy%&), the action when the ACL is not defined is &"deny"&. | |
25018 | This means that &%acl_smtp_rcpt%& must be defined in order to receive any | |
168e428f PH |
25019 | messages over an SMTP connection. For an example, see the ACL in the default |
25020 | configuration file. | |
25021 | ||
25022 | ||
25023 | ||
25024 | ||
f89d2485 | 25025 | .section "Data for message ACLs" "SECID198" |
9b371988 | 25026 | .cindex "&ACL;" "data for message ACL" |
f89d2485 PH |
25027 | .vindex &$domain$& |
25028 | .vindex &$local_part$& | |
25029 | .vindex &$sender_address$& | |
25030 | .vindex &$sender_host_address$& | |
25031 | .vindex &$smtp_command$& | |
068aaea8 PH |
25032 | When a MAIL or RCPT ACL, or either of the DATA ACLs, is running, the variables |
25033 | that contain information about the host and the message's sender (for example, | |
9b371988 PH |
25034 | &$sender_host_address$& and &$sender_address$&) are set, and can be used in ACL |
25035 | statements. In the case of RCPT (but not MAIL or DATA), &$domain$& and | |
4f578862 PH |
25036 | &$local_part$& are set from the argument address. The entire SMTP command |
25037 | is available in &$smtp_command$&. | |
168e428f PH |
25038 | |
25039 | When an ACL for the AUTH parameter of MAIL is running, the variables that | |
9b371988 PH |
25040 | contain information about the host are set, but &$sender_address$& is not yet |
25041 | set. Section &<<SECTauthparamail>>& contains a discussion of this parameter and | |
168e428f PH |
25042 | how it is used. |
25043 | ||
f89d2485 | 25044 | .vindex "&$message_size$&" |
9b371988 | 25045 | The &$message_size$& variable is set to the value of the SIZE parameter on |
168e428f PH |
25046 | the MAIL command at MAIL, RCPT and pre-data time, or to -1 if |
25047 | that parameter is not given. The value is updated to the true message size by | |
25048 | the time the final DATA ACL is run (after the message data has been | |
25049 | received). | |
25050 | ||
f89d2485 PH |
25051 | .vindex "&$rcpt_count$&" |
25052 | .vindex "&$recipients_count$&" | |
9b371988 PH |
25053 | The &$rcpt_count$& variable increases by one for each RCPT command received. |
25054 | The &$recipients_count$& variable increases by one each time a RCPT command is | |
068aaea8 PH |
25055 | accepted, so while an ACL for RCPT is being processed, it contains the number |
25056 | of previously accepted recipients. At DATA time (for both the DATA ACLs), | |
9b371988 PH |
25057 | &$rcpt_count$& contains the total number of RCPT commands, and |
25058 | &$recipients_count$& contains the total number of accepted recipients. | |
168e428f PH |
25059 | |
25060 | ||
25061 | ||
25062 | ||
25063 | ||
9b371988 PH |
25064 | .section "Data for non-message ACLs" "SECTdatfornon" |
25065 | .cindex "&ACL;" "data for non-message ACL" | |
f89d2485 PH |
25066 | .vindex &$smtp_command_argument$& |
25067 | .vindex &$smtp_command$& | |
168e428f | 25068 | When an ACL is being run for AUTH, EHLO, ETRN, EXPN, HELO, STARTTLS, or VRFY, |
9b371988 | 25069 | the remainder of the SMTP command line is placed in &$smtp_command_argument$&, |
4f578862 | 25070 | and the entire SMTP command is available in &$smtp_command$&. |
9b371988 PH |
25071 | These variables can be tested using a &%condition%& condition. For example, |
25072 | here is an ACL for use with AUTH, which insists that either the session is | |
25073 | encrypted, or the CRAM-MD5 authentication method is used. In other words, it | |
25074 | does not permit authentication methods that use cleartext passwords on | |
25075 | unencrypted connections. | |
25076 | .code | |
168e428f PH |
25077 | acl_check_auth: |
25078 | accept encrypted = * | |
25079 | accept condition = ${if eq{${uc:$smtp_command_argument}}\ | |
25080 | {CRAM-MD5}} | |
25081 | deny message = TLS encryption or CRAM-MD5 required | |
9b371988 | 25082 | .endd |
168e428f PH |
25083 | (Another way of applying this restriction is to arrange for the authenticators |
25084 | that use cleartext passwords not to be advertised when the connection is not | |
9b371988 | 25085 | encrypted. You can use the generic &%server_advertise_condition%& authenticator |
168e428f PH |
25086 | option to do this.) |
25087 | ||
25088 | ||
25089 | ||
f89d2485 | 25090 | .section "Format of an ACL" "SECID199" |
9b371988 | 25091 | .cindex "&ACL;" "format of" |
f89d2485 | 25092 | .cindex "&ACL;" "verbs, definition of" |
168e428f | 25093 | An individual ACL consists of a number of statements. Each statement starts |
9b371988 | 25094 | with a verb, optionally followed by a number of conditions and &"modifiers"&. |
168e428f PH |
25095 | Modifiers can change the way the verb operates, define error and log messages, |
25096 | set variables, insert delays, and vary the processing of accepted messages. | |
25097 | ||
25098 | If all the conditions are met, the verb is obeyed. The same condition may be | |
25099 | used (with different arguments) more than once in the same statement. This | |
9b371988 | 25100 | provides a means of specifying an &"and"& conjunction between conditions. For |
168e428f | 25101 | example: |
9b371988 PH |
25102 | .code |
25103 | deny dnslists = list1.example | |
25104 | dnslists = list2.example | |
25105 | .endd | |
168e428f PH |
25106 | If there are no conditions, the verb is always obeyed. Exim stops evaluating |
25107 | the conditions and modifiers when it reaches a condition that fails. What | |
25108 | happens then depends on the verb (and in one case, on a special modifier). Not | |
25109 | all the conditions make sense at every testing point. For example, you cannot | |
25110 | test a sender address in the ACL that is run for a VRFY command. | |
25111 | ||
25112 | ||
f89d2485 | 25113 | .section "ACL verbs" "SECID200" |
168e428f PH |
25114 | The ACL verbs are as follows: |
25115 | ||
9b371988 | 25116 | .ilist |
f89d2485 | 25117 | .cindex "&%accept%& ACL verb" |
9b371988 PH |
25118 | &%accept%&: If all the conditions are met, the ACL returns &"accept"&. If any |
25119 | of the conditions are not met, what happens depends on whether &%endpass%& | |
25120 | appears among the conditions (for syntax see below). If the failing condition | |
25121 | is before &%endpass%&, control is passed to the next ACL statement; if it is | |
25122 | after &%endpass%&, the ACL returns &"deny"&. Consider this statement, used to | |
25123 | check a RCPT command: | |
25124 | .code | |
25125 | accept domains = +local_domains | |
25126 | endpass | |
25127 | verify = recipient | |
25128 | .endd | |
25129 | If the recipient domain does not match the &%domains%& condition, control | |
25130 | passes to the next statement. If it does match, the recipient is verified, and | |
25131 | the command is accepted if verification succeeds. However, if verification | |
25132 | fails, the ACL yields &"deny"&, because the failing condition is after | |
25133 | &%endpass%&. | |
25134 | ||
3cb1b51e PH |
25135 | The &%endpass%& feature has turned out to be confusing to many people, so its |
25136 | use is not recommended nowadays. It is always possible to rewrite an ACL so | |
25137 | that &%endpass%& is not needed, and it is no longer used in the default | |
25138 | configuration. | |
25139 | ||
f89d2485 | 25140 | .cindex "&%message%& ACL modifier" "with &%accept%&" |
3cb1b51e PH |
25141 | If a &%message%& modifier appears on an &%accept%& statement, its action |
25142 | depends on whether or not &%endpass%& is present. In the absence of &%endpass%& | |
25143 | (when an &%accept%& verb either accepts or passes control to the next | |
25144 | statement), &%message%& can be used to vary the message that is sent when an | |
25145 | SMTP command is accepted. For example, in a RCPT ACL you could have: | |
25146 | .display | |
25147 | &`accept `&<&'some conditions'&> | |
595028e4 | 25148 | &` message = OK, I will allow you through today`& |
3cb1b51e PH |
25149 | .endd |
25150 | You can specify an SMTP response code, optionally followed by an &"extended | |
25151 | response code"& at the start of the message, but the first digit must be the | |
25152 | same as would be sent by default, which is 2 for an &%accept%& verb. | |
25153 | ||
25154 | If &%endpass%& is present in an &%accept%& statement, &%message%& specifies | |
25155 | an error message that is used when access is denied. This behaviour is retained | |
25156 | for backward compatibility, but current &"best practice"& is to avoid the use | |
25157 | of &%endpass%&. | |
3cb1b51e PH |
25158 | |
25159 | ||
9b371988 | 25160 | .next |
f89d2485 | 25161 | .cindex "&%defer%& ACL verb" |
3cb1b51e | 25162 | &%defer%&: If all the conditions are true, the ACL returns &"defer"& which, in |
9b371988 PH |
25163 | an SMTP session, causes a 4&'xx'& response to be given. For a non-SMTP ACL, |
25164 | &%defer%& is the same as &%deny%&, because there is no way of sending a | |
25165 | temporary error. For a RCPT command, &%defer%& is much the same as using a | |
25166 | &(redirect)& router and &`:defer:`& while verifying, but the &%defer%& verb can | |
168e428f | 25167 | be used in any ACL, and even for a recipient it might be a simpler approach. |
3cb1b51e PH |
25168 | |
25169 | ||
9b371988 | 25170 | .next |
f89d2485 | 25171 | .cindex "&%deny%& ACL verb" |
9b371988 PH |
25172 | &%deny%&: If all the conditions are met, the ACL returns &"deny"&. If any of |
25173 | the conditions are not met, control is passed to the next ACL statement. For | |
168e428f | 25174 | example, |
9b371988 PH |
25175 | .code |
25176 | deny dnslists = blackholes.mail-abuse.org | |
25177 | .endd | |
168e428f PH |
25178 | rejects commands from hosts that are on a DNS black list. |
25179 | ||
3cb1b51e | 25180 | |
9b371988 | 25181 | .next |
f89d2485 | 25182 | .cindex "&%discard%& ACL verb" |
9b371988 PH |
25183 | &%discard%&: This verb behaves like &%accept%&, except that it returns |
25184 | &"discard"& from the ACL instead of &"accept"&. It is permitted only on ACLs | |
3cb1b51e PH |
25185 | that are concerned with receiving messages. When all the conditions are true, |
25186 | the sending entity receives a &"success"& response. However, &%discard%& causes | |
25187 | recipients to be discarded. If it is used in an ACL for RCPT, just the one | |
25188 | recipient is discarded; if used for MAIL, DATA or in the non-SMTP ACL, all the | |
25189 | message's recipients are discarded. Recipients that are discarded before DATA | |
941c8a88 | 25190 | do not appear in the log line when the &%received_recipients%& log selector is set. |
3cb1b51e PH |
25191 | |
25192 | If the &%log_message%& modifier is set when &%discard%& operates, | |
9b371988 | 25193 | its contents are added to the line that is automatically written to the log. |
3cb1b51e | 25194 | The &%message%& modifier operates exactly as it does for &%accept%&. |
3cb1b51e | 25195 | |
9b371988 | 25196 | |
9b371988 | 25197 | .next |
f89d2485 | 25198 | .cindex "&%drop%& ACL verb" |
9b371988 PH |
25199 | &%drop%&: This verb behaves like &%deny%&, except that an SMTP connection is |
25200 | forcibly closed after the 5&'xx'& error message has been sent. For example: | |
25201 | .code | |
25202 | drop message = I don't take more than 20 RCPTs | |
25203 | condition = ${if > {$rcpt_count}{20}} | |
25204 | .endd | |
25205 | There is no difference between &%deny%& and &%drop%& for the connect-time ACL. | |
25206 | The connection is always dropped after sending a 550 response. | |
25207 | ||
25208 | .next | |
f89d2485 | 25209 | .cindex "&%require%& ACL verb" |
9b371988 PH |
25210 | &%require%&: If all the conditions are met, control is passed to the next ACL |
25211 | statement. If any of the conditions are not met, the ACL returns &"deny"&. For | |
168e428f | 25212 | example, when checking a RCPT command, |
9b371988 | 25213 | .code |
f89d2485 PH |
25214 | require message = Sender did not verify |
25215 | verify = sender | |
9b371988 | 25216 | .endd |
168e428f | 25217 | passes control to subsequent statements only if the message's sender can be |
595028e4 | 25218 | verified. Otherwise, it rejects the command. Note the positioning of the |
f89d2485 | 25219 | &%message%& modifier, before the &%verify%& condition. The reason for this is |
595028e4 | 25220 | discussed in section &<<SECTcondmodproc>>&. |
168e428f | 25221 | |
9b371988 | 25222 | .next |
f89d2485 | 25223 | .cindex "&%warn%& ACL verb" |
db9452a9 PH |
25224 | &%warn%&: If all the conditions are true, a line specified by the |
25225 | &%log_message%& modifier is written to Exim's main log. Control always passes | |
25226 | to the next ACL statement. If any condition is false, the log line is not | |
25227 | written. If an identical log line is requested several times in the same | |
25228 | message, only one copy is actually written to the log. If you want to force | |
25229 | duplicates to be written, use the &%logwrite%& modifier instead. | |
25230 | ||
25231 | If &%log_message%& is not present, a &%warn%& verb just checks its conditions | |
25232 | and obeys any &"immediate"& modifiers (such as &%control%&, &%set%&, | |
3cb1b51e PH |
25233 | &%logwrite%&, and &%add_header%&) that appear before the first failing |
25234 | condition. There is more about adding header lines in section | |
25235 | &<<SECTaddheadacl>>&. | |
9b371988 PH |
25236 | |
25237 | If any condition on a &%warn%& statement cannot be completed (that is, there is | |
db9452a9 | 25238 | some sort of defer), the log line specified by &%log_message%& is not written. |
f89d2485 PH |
25239 | This does not include the case of a forced failure from a lookup, which |
25240 | is considered to be a successful completion. After a defer, no further | |
3cb1b51e PH |
25241 | conditions or modifiers in the &%warn%& statement are processed. The incident |
25242 | is logged, and the ACL continues to be processed, from the next statement | |
25243 | onwards. | |
9b371988 | 25244 | |
168e428f | 25245 | |
f89d2485 | 25246 | .vindex "&$acl_verify_message$&" |
9b371988 PH |
25247 | When one of the &%warn%& conditions is an address verification that fails, the |
25248 | text of the verification failure message is in &$acl_verify_message$&. If you | |
25249 | want this logged, you must set it up explicitly. For example: | |
25250 | .code | |
25251 | warn !verify = sender | |
25252 | log_message = sender verify failed: $acl_verify_message | |
25253 | .endd | |
25254 | .endlist | |
168e428f | 25255 | |
9b371988 | 25256 | At the end of each ACL there is an implicit unconditional &%deny%&. |
168e428f PH |
25257 | |
25258 | As you can see from the examples above, the conditions and modifiers are | |
25259 | written one to a line, with the first one on the same line as the verb, and | |
25260 | subsequent ones on following lines. If you have a very long condition, you can | |
25261 | continue it onto several physical lines by the usual backslash continuation | |
25262 | mechanism. It is conventional to align the conditions vertically. | |
25263 | ||
25264 | ||
25265 | ||
9b371988 PH |
25266 | .section "ACL variables" "SECTaclvariables" |
25267 | .cindex "&ACL;" "variables" | |
168e428f PH |
25268 | There are some special variables that can be set during ACL processing. They |
25269 | can be used to pass information between different ACLs, different invocations | |
25270 | of the same ACL in the same SMTP connection, and between ACLs and the routers, | |
3cb1b51e PH |
25271 | transports, and filters that are used to deliver a message. The names of these |
25272 | variables must begin with &$acl_c$& or &$acl_m$&, followed either by a digit or | |
25273 | an underscore, but the remainder of the name can be any sequence of | |
25274 | alphanumeric characters and underscores that you choose. There is no limit on | |
25275 | the number of ACL variables. The two sets act as follows: | |
9b371988 | 25276 | .ilist |
3cb1b51e PH |
25277 | The values of those variables whose names begin with &$acl_c$& persist |
25278 | throughout an SMTP connection. They are never reset. Thus, a value that is set | |
25279 | while receiving one message is still available when receiving the next message | |
25280 | on the same SMTP connection. | |
25281 | .next | |
f89d2485 | 25282 | The values of those variables whose names begin with &$acl_m$& persist only |
3cb1b51e PH |
25283 | while a message is being received. They are reset afterwards. They are also |
25284 | reset by MAIL, RSET, EHLO, HELO, and after starting up a TLS session. | |
9b371988 | 25285 | .endlist |
168e428f PH |
25286 | |
25287 | When a message is accepted, the current values of all the ACL variables are | |
25288 | preserved with the message and are subsequently made available at delivery | |
db9452a9 | 25289 | time. The ACL variables are set by a modifier called &%set%&. For example: |
9b371988 PH |
25290 | .code |
25291 | accept hosts = whatever | |
25292 | set acl_m4 = some value | |
3cb1b51e PH |
25293 | accept authenticated = * |
25294 | set acl_c_auth = yes | |
9b371988 PH |
25295 | .endd |
25296 | &*Note*&: A leading dollar sign is not used when naming a variable that is to | |
168e428f | 25297 | be set. If you want to set a variable without taking any action, you can use a |
9b371988 | 25298 | &%warn%& verb without any other modifiers or conditions. |
168e428f | 25299 | |
3cb1b51e PH |
25300 | .oindex &%strict_acl_vars%& |
25301 | What happens if a syntactically valid but undefined ACL variable is | |
25302 | referenced depends on the setting of the &%strict_acl_vars%& option. If it is | |
25303 | false (the default), an empty string is substituted; if it is true, an | |
25304 | error is generated. | |
25305 | ||
25306 | Versions of Exim before 4.64 have a limited set of numbered variables, but | |
25307 | their names are compatible, so there is no problem with upgrading. | |
168e428f PH |
25308 | |
25309 | ||
f89d2485 | 25310 | .section "Condition and modifier processing" "SECTcondmodproc" |
9b371988 PH |
25311 | .cindex "&ACL;" "conditions; processing" |
25312 | .cindex "&ACL;" "modifiers; processing" | |
068aaea8 | 25313 | An exclamation mark preceding a condition negates its result. For example: |
9b371988 PH |
25314 | .code |
25315 | deny domains = *.dom.example | |
25316 | !verify = recipient | |
25317 | .endd | |
9b371988 PH |
25318 | causes the ACL to return &"deny"& if the recipient domain ends in |
25319 | &'dom.example'& and the recipient address cannot be verified. Sometimes | |
25320 | negation can be used on the right-hand side of a condition. For example, these | |
25321 | two statements are equivalent: | |
25322 | .code | |
068aaea8 PH |
25323 | deny hosts = !192.168.3.4 |
25324 | deny !hosts = 192.168.3.4 | |
9b371988 PH |
25325 | .endd |
25326 | However, for many conditions (&%verify%& being a good example), only left-hand | |
068aaea8 | 25327 | side negation of the whole condition is possible. |
168e428f PH |
25328 | |
25329 | The arguments of conditions and modifiers are expanded. A forced failure | |
25330 | of an expansion causes a condition to be ignored, that is, it behaves as if the | |
25331 | condition is true. Consider these two statements: | |
9b371988 | 25332 | .code |
168e428f PH |
25333 | accept senders = ${lookup{$host_name}lsearch\ |
25334 | {/some/file}{$value}fail} | |
25335 | accept senders = ${lookup{$host_name}lsearch\ | |
25336 | {/some/file}{$value}{}} | |
9b371988 | 25337 | .endd |
168e428f PH |
25338 | Each attempts to look up a list of acceptable senders. If the lookup succeeds, |
25339 | the returned list is searched, but if the lookup fails the behaviour is | |
9b371988 PH |
25340 | different in the two cases. The &%fail%& in the first statement causes the |
25341 | condition to be ignored, leaving no further conditions. The &%accept%& verb | |
168e428f PH |
25342 | therefore succeeds. The second statement, however, generates an empty list when |
25343 | the lookup fails. No sender can match an empty list, so the condition fails, | |
9b371988 | 25344 | and therefore the &%accept%& also fails. |
168e428f PH |
25345 | |
25346 | ACL modifiers appear mixed in with conditions in ACL statements. Some of them | |
25347 | specify actions that are taken as the conditions for a statement are checked; | |
25348 | others specify text for messages that are used when access is denied or a | |
9b371988 | 25349 | warning is generated. The &%control%& modifier affects the way an incoming |
168e428f PH |
25350 | message is handled. |
25351 | ||
25352 | The positioning of the modifiers in an ACL statement important, because the | |
25353 | processing of a verb ceases as soon as its outcome is known. Only those | |
25354 | modifiers that have already been encountered will take effect. For example, | |
9b371988 PH |
25355 | consider this use of the &%message%& modifier: |
25356 | .code | |
25357 | require message = Can't verify sender | |
25358 | verify = sender | |
25359 | message = Can't verify recipient | |
25360 | verify = recipient | |
25361 | message = This message cannot be used | |
25362 | .endd | |
168e428f | 25363 | If sender verification fails, Exim knows that the result of the statement is |
9b371988 PH |
25364 | &"deny"&, so it goes no further. The first &%message%& modifier has been seen, |
25365 | so its text is used as the error message. If sender verification succeeds, but | |
168e428f | 25366 | recipient verification fails, the second message is used. If recipient |
9b371988 | 25367 | verification succeeds, the third message becomes &"current"&, but is never used |
168e428f PH |
25368 | because there are no more conditions to cause failure. |
25369 | ||
9b371988 | 25370 | For the &%deny%& verb, on the other hand, it is always the last &%message%& |
168e428f | 25371 | modifier that is used, because all the conditions must be true for rejection to |
9b371988 | 25372 | happen. Specifying more than one &%message%& modifier does not make sense, and |
168e428f | 25373 | the message can even be specified after all the conditions. For example: |
9b371988 PH |
25374 | .code |
25375 | deny hosts = ... | |
25376 | !senders = *@my.domain.example | |
25377 | message = Invalid sender from client host | |
25378 | .endd | |
25379 | The &"deny"& result does not happen until the end of the statement is reached, | |
168e428f PH |
25380 | by which time Exim has set up the message. |
25381 | ||
25382 | ||
25383 | ||
9b371988 PH |
25384 | .section "ACL modifiers" "SECTACLmodi" |
25385 | .cindex "&ACL;" "modifiers; list of" | |
168e428f PH |
25386 | The ACL modifiers are as follows: |
25387 | ||
9b371988 | 25388 | .vlist |
4f578862 | 25389 | .vitem &*add_header*&&~=&~<&'text'&> |
db9452a9 | 25390 | This modifier specifies one or more header lines that are to be added to an |
4f578862 PH |
25391 | incoming message, assuming, of course, that the message is ultimately |
25392 | accepted. For details, see section &<<SECTaddheadacl>>&. | |
4f578862 | 25393 | |
f89d2485 PH |
25394 | .vitem &*continue*&&~=&~<&'text'&> |
25395 | .cindex "&%continue%& ACL modifier" | |
25396 | .cindex "database" "updating in ACL" | |
25397 | This modifier does nothing of itself, and processing of the ACL always | |
25398 | continues with the next condition or modifier. The value of &%continue%& is in | |
25399 | the side effects of expanding its argument. Typically this could be used to | |
25400 | update a database. It is really just a syntactic tidiness, to avoid having to | |
25401 | write rather ugly lines like this: | |
25402 | .display | |
25403 | &`condition = ${if eq{0}{`&<&'some expansion'&>&`}{true}{true}}`& | |
25404 | .endd | |
25405 | Instead, all you need is | |
25406 | .display | |
25407 | &`continue = `&<&'some expansion'&> | |
25408 | .endd | |
f89d2485 | 25409 | |
9b371988 | 25410 | .vitem &*control*&&~=&~<&'text'&> |
f89d2485 | 25411 | .cindex "&%control%& ACL modifier" |
168e428f PH |
25412 | This modifier affects the subsequent processing of the SMTP connection or of an |
25413 | incoming message that is accepted. The effect of the first type of control | |
25414 | lasts for the duration of the connection, whereas the effect of the second type | |
25415 | lasts only until the current message has been received. The message-specific | |
25416 | controls always apply to the whole message, not to individual recipients, | |
9b371988 PH |
25417 | even if the &%control%& modifier appears in a RCPT ACL. |
25418 | ||
168e428f | 25419 | As there are now quite a few controls that can be applied, they are described |
9b371988 PH |
25420 | separately in section &<<SECTcontrols>>&. The &%control%& modifier can be used |
25421 | in several different ways. For example: | |
25422 | ||
25423 | . ==== As this is a nested list, any displays it contains must be indented | |
f89d2485 PH |
25424 | . ==== as otherwise they are too far to the left. That comment applies only |
25425 | . ==== when xmlto and fop are used; formatting with sdop gets it right either | |
25426 | . ==== way. | |
9b371988 PH |
25427 | |
25428 | .ilist | |
25429 | It can be at the end of an &%accept%& statement: | |
25430 | .code | |
25431 | accept ...some conditions | |
25432 | control = queue_only | |
25433 | .endd | |
25434 | In this case, the control is applied when this statement yields &"accept"&, in | |
168e428f PH |
25435 | other words, when the conditions are all true. |
25436 | ||
9b371988 PH |
25437 | .next |
25438 | It can be in the middle of an &%accept%& statement: | |
25439 | .code | |
25440 | accept ...some conditions... | |
25441 | control = queue_only | |
25442 | ...some more conditions... | |
25443 | .endd | |
168e428f PH |
25444 | If the first set of conditions are true, the control is applied, even if the |
25445 | statement does not accept because one of the second set of conditions is false. | |
9b371988 PH |
25446 | In this case, some subsequent statement must yield &"accept"& for the control |
25447 | to be relevant. | |
168e428f | 25448 | |
9b371988 PH |
25449 | .next |
25450 | It can be used with &%warn%& to apply the control, leaving the | |
168e428f PH |
25451 | decision about accepting or denying to a subsequent verb. For |
25452 | example: | |
9b371988 PH |
25453 | .code |
25454 | warn ...some conditions... | |
25455 | control = freeze | |
25456 | accept ... | |
25457 | .endd | |
25458 | This example of &%warn%& does not contain &%message%&, &%log_message%&, or | |
25459 | &%logwrite%&, so it does not add anything to the message and does not write a | |
25460 | log entry. | |
25461 | ||
25462 | .next | |
25463 | If you want to apply a control unconditionally, you can use it with a | |
25464 | &%require%& verb. For example: | |
25465 | .code | |
8a7f259d | 25466 | require control = no_multiline_responses |
9b371988 PH |
25467 | .endd |
25468 | .endlist | |
25469 | ||
25470 | .vitem &*delay*&&~=&~<&'time'&> | |
f89d2485 PH |
25471 | .cindex "&%delay%& ACL modifier" |
25472 | .oindex "&%-bh%&" | |
f89d2485 PH |
25473 | This modifier may appear in any ACL. It causes Exim to wait for the time |
25474 | interval before proceeding. However, when testing Exim using the &%-bh%& | |
25475 | option, the delay is not actually imposed (an appropriate message is output | |
25476 | instead). The time is given in the usual Exim notation, and the delay happens | |
25477 | as soon as the modifier is processed. In an SMTP session, pending output is | |
25478 | flushed before the delay is imposed. | |
9b371988 PH |
25479 | |
25480 | Like &%control%&, &%delay%& can be used with &%accept%& or &%deny%&, for | |
25481 | example: | |
25482 | .code | |
25483 | deny ...some conditions... | |
25484 | delay = 30s | |
25485 | .endd | |
168e428f | 25486 | The delay happens if all the conditions are true, before the statement returns |
9b371988 PH |
25487 | &"deny"&. Compare this with: |
25488 | .code | |
25489 | deny delay = 30s | |
25490 | ...some conditions... | |
25491 | .endd | |
25492 | which waits for 30s before processing the conditions. The &%delay%& modifier | |
25493 | can also be used with &%warn%& and together with &%control%&: | |
25494 | .code | |
25495 | warn ...some conditions... | |
25496 | delay = 2m | |
25497 | control = freeze | |
25498 | accept ... | |
25499 | .endd | |
25500 | ||
f89d2485 PH |
25501 | If &%delay%& is encountered when the SMTP PIPELINING extension is in use, |
25502 | responses to several commands are no longer buffered and sent in one packet (as | |
25503 | they would normally be) because all output is flushed before imposing the | |
25504 | delay. This optimization is disabled so that a number of small delays do not | |
25505 | appear to the client as one large aggregated delay that might provoke an | |
25506 | unwanted timeout. You can, however, disable output flushing for &%delay%& by | |
25507 | using a &%control%& modifier to set &%no_delay_flush%&. | |
f89d2485 PH |
25508 | |
25509 | ||
9b371988 | 25510 | .vitem &*endpass*& |
f89d2485 | 25511 | .cindex "&%endpass%& ACL modifier" |
3cb1b51e PH |
25512 | This modifier, which has no argument, is recognized only in &%accept%& and |
25513 | &%discard%& statements. It marks the boundary between the conditions whose | |
25514 | failure causes control to pass to the next statement, and the conditions whose | |
25515 | failure causes the ACL to return &"deny"&. This concept has proved to be | |
25516 | confusing to some people, so the use of &%endpass%& is no longer recommended as | |
25517 | &"best practice"&. See the description of &%accept%& above for more details. | |
3cb1b51e | 25518 | |
168e428f | 25519 | |
9b371988 | 25520 | .vitem &*log_message*&&~=&~<&'text'&> |
f89d2485 | 25521 | .cindex "&%log_message%& ACL modifier" |
168e428f | 25522 | This modifier sets up a message that is used as part of the log message if the |
9b371988 PH |
25523 | ACL denies access or a &%warn%& statement's conditions are true. For example: |
25524 | .code | |
25525 | require log_message = wrong cipher suite $tls_cipher | |
25526 | encrypted = DES-CBC3-SHA | |
25527 | .endd | |
3cb1b51e PH |
25528 | &%log_message%& is also used when recipients are discarded by &%discard%&. For |
25529 | example: | |
25530 | .display | |
25531 | &`discard `&<&'some conditions'&> | |
25532 | &` log_message = Discarded $local_part@$domain because...`& | |
25533 | .endd | |
25534 | When access is denied, &%log_message%& adds to any underlying error message | |
25535 | that may exist because of a condition failure. For example, while verifying a | |
25536 | recipient address, a &':fail:'& redirection might have already set up a | |
25537 | message. | |
25538 | ||
25539 | The message may be defined before the conditions to which it applies, because | |
25540 | the string expansion does not happen until Exim decides that access is to be | |
25541 | denied. This means that any variables that are set by the condition are | |
25542 | available for inclusion in the message. For example, the &$dnslist_$&<&'xxx'&> | |
25543 | variables are set after a DNS black list lookup succeeds. If the expansion of | |
25544 | &%log_message%& fails, or if the result is an empty string, the modifier is | |
25545 | ignored. | |
9b371988 | 25546 | |
f89d2485 | 25547 | .vindex "&$acl_verify_message$&" |
9b371988 PH |
25548 | If you want to use a &%warn%& statement to log the result of an address |
25549 | verification, you can use &$acl_verify_message$& to include the verification | |
168e428f | 25550 | error message. |
9b371988 PH |
25551 | |
25552 | If &%log_message%& is used with a &%warn%& statement, &"Warning:"& is added to | |
25553 | the start of the logged message. If the same warning log message is requested | |
25554 | more than once while receiving a single email message, only one copy is | |
25555 | actually logged. If you want to log multiple copies, use &%logwrite%& instead | |
25556 | of &%log_message%&. In the absence of &%log_message%& and &%logwrite%&, nothing | |
f89d2485 | 25557 | is logged for a successful &%warn%& statement. |
9b371988 PH |
25558 | |
25559 | If &%log_message%& is not present and there is no underlying error message (for | |
25560 | example, from the failure of address verification), but &%message%& is present, | |
25561 | the &%message%& text is used for logging rejections. However, if any text for | |
168e428f | 25562 | logging contains newlines, only the first line is logged. In the absence of |
9b371988 | 25563 | both &%log_message%& and &%message%&, a default built-in message is used for |
168e428f PH |
25564 | logging rejections. |
25565 | ||
3cb1b51e | 25566 | |
3cb1b51e | 25567 | .vitem "&*log_reject_target*&&~=&~<&'log name list'&>" |
f89d2485 | 25568 | .cindex "&%log_reject_target%& ACL modifier" |
3cb1b51e PH |
25569 | .cindex "logging in ACL" "specifying which log" |
25570 | This modifier makes it possible to specify which logs are used for messages | |
25571 | about ACL rejections. Its argument is a colon-separated list of words that can | |
25572 | be &"main"&, &"reject"&, or &"panic"&. The default is &`main:reject`&. The list | |
25573 | may be empty, in which case a rejection is not logged at all. For example, this | |
25574 | ACL fragment writes no logging information when access is denied: | |
25575 | .display | |
25576 | &`deny `&<&'some conditions'&> | |
25577 | &` log_reject_target =`& | |
25578 | .endd | |
25579 | This modifier can be used in SMTP and non-SMTP ACLs. It applies to both | |
08dfc92a TF |
25580 | permanent and temporary rejections. Its effect lasts for the rest of the |
25581 | current ACL. | |
3cb1b51e PH |
25582 | |
25583 | ||
9b371988 | 25584 | .vitem &*logwrite*&&~=&~<&'text'&> |
f89d2485 | 25585 | .cindex "&%logwrite%& ACL modifier" |
9b371988 | 25586 | .cindex "logging in ACL" "immediate" |
168e428f | 25587 | This modifier writes a message to a log file as soon as it is encountered when |
9b371988 | 25588 | processing an ACL. (Compare &%log_message%&, which, except in the case of |
f89d2485 | 25589 | &%warn%& and &%discard%&, is used only if the ACL statement denies |
3cb1b51e PH |
25590 | access.) The &%logwrite%& modifier can be used to log special incidents in |
25591 | ACLs. For example: | |
9b371988 PH |
25592 | .display |
25593 | &`accept `&<&'some special conditions'&> | |
25594 | &` control = freeze`& | |
25595 | &` logwrite = froze message because ...`& | |
25596 | .endd | |
168e428f PH |
25597 | By default, the message is written to the main log. However, it may begin |
25598 | with a colon, followed by a comma-separated list of log names, and then | |
25599 | another colon, to specify exactly which logs are to be written. For | |
25600 | example: | |
9b371988 PH |
25601 | .code |
25602 | logwrite = :main,reject: text for main and reject logs | |
25603 | logwrite = :panic: text for panic log only | |
25604 | .endd | |
168e428f | 25605 | |
3cb1b51e | 25606 | |
9b371988 | 25607 | .vitem &*message*&&~=&~<&'text'&> |
f89d2485 | 25608 | .cindex "&%message%& ACL modifier" |
3cb1b51e PH |
25609 | This modifier sets up a text string that is expanded and used as a response |
25610 | message when an ACL statement terminates the ACL with an &"accept"&, &"deny"&, | |
25611 | or &"defer"& response. (In the case of the &%accept%& and &%discard%& verbs, | |
25612 | there is some complication if &%endpass%& is involved; see the description of | |
25613 | &%accept%& for details.) | |
25614 | ||
25615 | The expansion of the message happens at the time Exim decides that the ACL is | |
25616 | to end, not at the time it processes &%message%&. If the expansion fails, or | |
25617 | generates an empty string, the modifier is ignored. Here is an example where | |
25618 | &%message%& must be specified first, because the ACL ends with a rejection if | |
25619 | the &%hosts%& condition fails: | |
25620 | .code | |
25621 | require message = Host not recognized | |
25622 | hosts = 10.0.0.0/8 | |
25623 | .endd | |
25624 | (Once a condition has failed, no further conditions or modifiers are | |
25625 | processed.) | |
9b371988 | 25626 | |
5abeaa6e | 25627 | .cindex "SMTP" "error codes" |
0a4e3112 | 25628 | .oindex "&%smtp_banner%& |
3cb1b51e PH |
25629 | For ACLs that are triggered by SMTP commands, the message is returned as part |
25630 | of the SMTP response. The use of &%message%& with &%accept%& (or &%discard%&) | |
25631 | is meaningful only for SMTP, as no message is returned when a non-SMTP message | |
25632 | is accepted. In the case of the connect ACL, accepting with a message modifier | |
25633 | overrides the value of &%smtp_banner%&. For the EHLO/HELO ACL, a customized | |
25634 | accept message may not contain more than one line (otherwise it will be | |
25635 | truncated at the first newline and a panic logged), and it cannot affect the | |
25636 | EHLO options. | |
25637 | ||
25638 | When SMTP is involved, the message may begin with an overriding response code, | |
25639 | consisting of three digits optionally followed by an &"extended response code"& | |
25640 | of the form &'n.n.n'&, each code being followed by a space. For example: | |
25641 | .code | |
25642 | deny message = 599 1.2.3 Host not welcome | |
25643 | hosts = 192.168.34.0/24 | |
25644 | .endd | |
25645 | The first digit of the supplied response code must be the same as would be sent | |
25646 | by default. A panic occurs if it is not. Exim uses a 550 code when it denies | |
25647 | access, but for the predata ACL, note that the default success code is 354, not | |
25648 | 2&'xx'&. | |
25649 | ||
25650 | Notwithstanding the previous paragraph, for the QUIT ACL, unlike the others, | |
25651 | the message modifier cannot override the 221 response code. | |
25652 | ||
25653 | The text in a &%message%& modifier is literal; any quotes are taken as | |
25654 | literals, but because the string is expanded, backslash escapes are processed | |
25655 | anyway. If the message contains newlines, this gives rise to a multi-line SMTP | |
25656 | response. | |
5abeaa6e | 25657 | |
f89d2485 | 25658 | .vindex "&$acl_verify_message$&" |
9b371988 | 25659 | If &%message%& is used on a statement that verifies an address, the message |
168e428f PH |
25660 | specified overrides any message that is generated by the verification process. |
25661 | However, the original message is available in the variable | |
9b371988 PH |
25662 | &$acl_verify_message$&, so you can incorporate it into your message if you |
25663 | wish. In particular, if you want the text from &%:fail:%& items in &(redirect)& | |
25664 | routers to be passed back as part of the SMTP response, you should either not | |
25665 | use a &%message%& modifier, or make use of &$acl_verify_message$&. | |
168e428f | 25666 | |
4f578862 PH |
25667 | For compatibility with previous releases of Exim, a &%message%& modifier that |
25668 | is used with a &%warn%& verb behaves in a similar way to the &%add_header%& | |
25669 | modifier, but this usage is now deprecated. However, &%message%& acts only when | |
25670 | all the conditions are true, wherever it appears in an ACL command, whereas | |
25671 | &%add_header%& acts as soon as it is encountered. If &%message%& is used with | |
25672 | &%warn%& in an ACL that is not concerned with receiving a message, it has no | |
25673 | effect. | |
4f578862 | 25674 | |
3cb1b51e | 25675 | |
9b371988 | 25676 | .vitem &*set*&&~<&'acl_name'&>&~=&~<&'value'&> |
f89d2485 | 25677 | .cindex "&%set%& ACL modifier" |
168e428f | 25678 | This modifier puts a value into one of the ACL variables (see section |
9b371988 PH |
25679 | &<<SECTaclvariables>>&). |
25680 | .endlist | |
168e428f PH |
25681 | |
25682 | ||
25683 | ||
4f578862 PH |
25684 | |
25685 | ||
9b371988 | 25686 | .section "Use of the control modifier" "SECTcontrols" |
f89d2485 | 25687 | .cindex "&%control%& ACL modifier" |
9b371988 | 25688 | The &%control%& modifier supports the following settings: |
168e428f | 25689 | |
9b371988 | 25690 | .vlist |
4f578862 PH |
25691 | .vitem &*control&~=&~allow_auth_unadvertised*& |
25692 | This modifier allows a client host to use the SMTP AUTH command even when it | |
25693 | has not been advertised in response to EHLO. Furthermore, because there are | |
25694 | apparently some really broken clients that do this, Exim will accept AUTH after | |
25695 | HELO (rather than EHLO) when this control is set. It should be used only if you | |
25696 | really need it, and you should limit its use to those broken clients that do | |
25697 | not work without it. For example: | |
25698 | .code | |
25699 | warn hosts = 192.168.34.25 | |
25700 | control = allow_auth_unadvertised | |
25701 | .endd | |
25702 | Normally, when an Exim server receives an AUTH command, it checks the name of | |
25703 | the authentication mechanism that is given in the command to ensure that it | |
25704 | matches an advertised mechanism. When this control is set, the check that a | |
25705 | mechanism has been advertised is bypassed. Any configured mechanism can be used | |
25706 | by the client. This control is permitted only in the connection and HELO ACLs. | |
4f578862 PH |
25707 | |
25708 | ||
f89d2485 PH |
25709 | .vitem &*control&~=&~caseful_local_part*& &&& |
25710 | &*control&~=&~caselower_local_part*& | |
9b371988 PH |
25711 | .cindex "&ACL;" "case of local part in" |
25712 | .cindex "case of local parts" | |
f89d2485 | 25713 | .vindex "&$local_part$&" |
9b371988 PH |
25714 | These two controls are permitted only in the ACL specified by &%acl_smtp_rcpt%& |
25715 | (that is, during RCPT processing). By default, the contents of &$local_part$& | |
25716 | are lower cased before ACL processing. If &"caseful_local_part"& is specified, | |
25717 | any uppercase letters in the original local part are restored in &$local_part$& | |
25718 | for the rest of the ACL, or until a control that sets &"caselower_local_part"& | |
25719 | is encountered. | |
25720 | ||
168e428f PH |
25721 | These controls affect only the current recipient. Moreover, they apply only to |
25722 | local part handling that takes place directly in the ACL (for example, as a key | |
25723 | in lookups). If a test to verify the recipient is obeyed, the case-related | |
25724 | handling of the local part during the verification is controlled by the router | |
9b371988 PH |
25725 | configuration (see the &%caseful_local_part%& generic router option). |
25726 | ||
168e428f | 25727 | This facility could be used, for example, to add a spam score to local parts |
9b371988 | 25728 | containing upper case letters. For example, using &$acl_m4$& to accumulate the |
168e428f | 25729 | spam score: |
9b371988 | 25730 | .code |
168e428f PH |
25731 | warn control = caseful_local_part |
25732 | set acl_m4 = ${eval:\ | |
25733 | $acl_m4 + \ | |
25734 | ${if match{$local_part}{[A-Z]}{1}{0}}\ | |
25735 | } | |
25736 | control = caselower_local_part | |
9b371988 | 25737 | .endd |
168e428f PH |
25738 | Notice that we put back the lower cased version afterwards, assuming that |
25739 | is what is wanted for subsequent tests. | |
25740 | ||
f89d2485 PH |
25741 | .vitem &*control&~=&~enforce_sync*& &&& |
25742 | &*control&~=&~no_enforce_sync*& | |
9b371988 PH |
25743 | .cindex "SMTP" "synchronization checking" |
25744 | .cindex "synchronization checking in SMTP" | |
168e428f | 25745 | These controls make it possible to be selective about when SMTP synchronization |
9b371988 | 25746 | is enforced. The global option &%smtp_enforce_sync%& specifies the initial |
168e428f | 25747 | state of the switch (it is true by default). See the description of this option |
9b371988 PH |
25748 | in chapter &<<CHAPmainconfig>>& for details of SMTP synchronization checking. |
25749 | ||
168e428f PH |
25750 | The effect of these two controls lasts for the remainder of the SMTP |
25751 | connection. They can appear in any ACL except the one for the non-SMTP | |
25752 | messages. The most straightforward place to put them is in the ACL defined by | |
9b371988 | 25753 | &%acl_smtp_connect%&, which is run at the start of an incoming SMTP connection, |
168e428f PH |
25754 | before the first synchronization check. The expected use is to turn off the |
25755 | synchronization checks for badly-behaved hosts that you nevertheless need to | |
25756 | work with. | |
25757 | ||
068aaea8 | 25758 | |
9b371988 PH |
25759 | .vitem &*control&~=&~fakedefer/*&<&'message'&> |
25760 | .cindex "fake defer" | |
f89d2485 | 25761 | .cindex "defer, fake" |
9b371988 | 25762 | This control works in exactly the same way as &%fakereject%& (described below) |
068aaea8 | 25763 | except that it causes an SMTP 450 response after the message data instead of a |
9b371988 | 25764 | 550 response. You must take care when using &%fakedefer%& because it causes the |
068aaea8 | 25765 | messages to be duplicated when the sender retries. Therefore, you should not |
9b371988 | 25766 | use &%fakedefer%& if the message is to be delivered normally. |
068aaea8 | 25767 | |
9b371988 PH |
25768 | .vitem &*control&~=&~fakereject/*&<&'message'&> |
25769 | .cindex "fake rejection" | |
f89d2485 | 25770 | .cindex "rejection, fake" |
168e428f PH |
25771 | This control is permitted only for the MAIL, RCPT, and DATA ACLs, in other |
25772 | words, only when an SMTP message is being received. If Exim accepts the | |
25773 | message, instead the final 250 response, a 550 rejection message is sent. | |
25774 | However, Exim proceeds to deliver the message as normal. The control applies | |
25775 | only to the current message, not to any subsequent ones that may be received in | |
25776 | the same SMTP connection. | |
168e428f | 25777 | |
9b371988 PH |
25778 | The text for the 550 response is taken from the &%control%& modifier. If no |
25779 | message is supplied, the following is used: | |
25780 | .code | |
25781 | 550-Your message has been rejected but is being | |
25782 | 550-kept for evaluation. | |
25783 | 550-If it was a legitimate message, it may still be | |
25784 | 550 delivered to the target recipient(s). | |
25785 | .endd | |
f89d2485 | 25786 | This facility should be used with extreme caution. |
168e428f | 25787 | |
9b371988 PH |
25788 | .vitem &*control&~=&~freeze*& |
25789 | .cindex "frozen messages" "forcing in ACL" | |
168e428f PH |
25790 | This control is permitted only for the MAIL, RCPT, DATA, and non-SMTP ACLs, in |
25791 | other words, only when a message is being received. If the message is accepted, | |
25792 | it is placed on Exim's queue and frozen. The control applies only to the | |
25793 | current message, not to any subsequent ones that may be received in the same | |
25794 | SMTP connection. | |
25795 | ||
4f578862 PH |
25796 | This modifier can optionally be followed by &`/no_tell`&. If the global option |
25797 | &%freeze_tell%& is set, it is ignored for the current message (that is, nobody | |
25798 | is told about the freezing), provided all the &*control=freeze*& modifiers that | |
25799 | are obeyed for the current message have the &`/no_tell`& option. | |
4f578862 | 25800 | |
f89d2485 PH |
25801 | .vitem &*control&~=&~no_delay_flush*& |
25802 | .cindex "SMTP" "output flushing, disabling for delay" | |
25803 | Exim normally flushes SMTP output before implementing a delay in an ACL, to | |
25804 | avoid unexpected timeouts in clients when the SMTP PIPELINING extension is in | |
25805 | use. This control, as long as it is encountered before the &%delay%& modifier, | |
25806 | disables such output flushing. | |
25807 | ||
25808 | .vitem &*control&~=&~no_callout_flush*& | |
25809 | .cindex "SMTP" "output flushing, disabling for callout" | |
25810 | Exim normally flushes SMTP output before performing a callout in an ACL, to | |
25811 | avoid unexpected timeouts in clients when the SMTP PIPELINING extension is in | |
25812 | use. This control, as long as it is encountered before the &%verify%& condition | |
25813 | that causes the callout, disables such output flushing. | |
4f578862 | 25814 | |
9b371988 | 25815 | .vitem &*control&~=&~no_mbox_unspool*& |
168e428f PH |
25816 | This control is available when Exim is compiled with the content scanning |
25817 | extension. Content scanning may require a copy of the current message, or parts | |
9b371988 | 25818 | of it, to be written in &"mbox format"& to a spool file, for passing to a virus |
168e428f PH |
25819 | or spam scanner. Normally, such copies are deleted when they are no longer |
25820 | needed. If this control is set, the copies are not deleted. The control applies | |
25821 | only to the current message, not to any subsequent ones that may be received in | |
25822 | the same SMTP connection. It is provided for debugging purposes and is unlikely | |
25823 | to be useful in production. | |
25824 | ||
8a7f259d | 25825 | .vitem &*control&~=&~no_multiline_responses*& |
f89d2485 | 25826 | .cindex "multiline responses, suppressing" |
168e428f PH |
25827 | This control is permitted for any ACL except the one for non-SMTP messages. |
25828 | It seems that there are broken clients in use that cannot handle multiline | |
25829 | SMTP responses, despite the fact that RFC 821 defined them over 20 years ago. | |
9b371988 | 25830 | |
168e428f PH |
25831 | If this control is set, multiline SMTP responses from ACL rejections are |
25832 | suppressed. One way of doing this would have been to put out these responses as | |
25833 | one long line. However, RFC 2821 specifies a maximum of 512 bytes per response | |
9b371988 PH |
25834 | (&"use multiline responses for more"& it says &-- ha!), and some of the |
25835 | responses might get close to that. So this facility, which is after all only a | |
25836 | sop to broken clients, is implemented by doing two very easy things: | |
25837 | ||
25838 | .ilist | |
25839 | Extra information that is normally output as part of a rejection caused by | |
25840 | sender verification failure is omitted. Only the final line (typically &"sender | |
25841 | verification failed"&) is sent. | |
25842 | .next | |
25843 | If a &%message%& modifier supplies a multiline response, only the first | |
168e428f | 25844 | line is output. |
9b371988 PH |
25845 | .endlist |
25846 | ||
168e428f PH |
25847 | The setting of the switch can, of course, be made conditional on the |
25848 | calling host. Its effect lasts until the end of the SMTP connection. | |
25849 | ||
f89d2485 PH |
25850 | .vitem &*control&~=&~no_pipelining*& |
25851 | .cindex "PIPELINING" "suppressing advertising" | |
25852 | This control turns off the advertising of the PIPELINING extension to SMTP in | |
25853 | the current session. To be useful, it must be obeyed before Exim sends its | |
25854 | response to an EHLO command. Therefore, it should normally appear in an ACL | |
25855 | controlled by &%acl_smtp_connect%& or &%acl_smtp_helo%&. See also | |
25856 | &%pipelining_advertise_hosts%&. | |
f89d2485 | 25857 | |
9b371988 | 25858 | .vitem &*control&~=&~queue_only*& |
0a4e3112 | 25859 | .oindex "&%queue_only%&" |
9b371988 | 25860 | .cindex "queueing incoming messages" |
168e428f PH |
25861 | This control is permitted only for the MAIL, RCPT, DATA, and non-SMTP ACLs, in |
25862 | other words, only when a message is being received. If the message is accepted, | |
25863 | it is placed on Exim's queue and left there for delivery by a subsequent queue | |
25864 | runner. No immediate delivery process is started. In other words, it has the | |
9b371988 PH |
25865 | effect as the &%queue_only%& global option. However, the control applies only |
25866 | to the current message, not to any subsequent ones that may be received in the | |
168e428f PH |
25867 | same SMTP connection. |
25868 | ||
9b371988 PH |
25869 | .vitem &*control&~=&~submission/*&<&'options'&> |
25870 | .cindex "message" "submission" | |
25871 | .cindex "submission mode" | |
168e428f | 25872 | This control is permitted only for the MAIL, RCPT, and start of data ACLs (the |
9b371988 | 25873 | latter is the one defined by &%acl_smtp_predata%&). Setting it tells Exim that |
168e428f | 25874 | the current message is a submission from a local MUA. In this case, Exim |
9b371988 | 25875 | operates in &"submission mode"&, and applies certain fixups to the message if |
9c2b45c9 | 25876 | necessary. For example, it adds a &'Date:'& header line if one is not present. |
9b371988 | 25877 | This control is not permitted in the &%acl_smtp_data%& ACL, because that is too |
168e428f | 25878 | late (the message has already been created). |
168e428f | 25879 | |
9b371988 PH |
25880 | Chapter &<<CHAPmsgproc>>& describes the processing that Exim applies to |
25881 | messages. Section &<<SECTsubmodnon>>& covers the processing that happens in | |
25882 | submission mode; the available options for this control are described there. | |
25883 | The control applies only to the current message, not to any subsequent ones | |
25884 | that may be received in the same SMTP connection. | |
25885 | ||
9b371988 | 25886 | .vitem &*control&~=&~suppress_local_fixups*& |
f89d2485 | 25887 | .cindex "submission fixups, suppressing" |
068aaea8 | 25888 | This control applies to locally submitted (non TCP/IP) messages, and is the |
9c2b45c9 | 25889 | complement of &`control = submission`&. It disables the fixups that are |
9b371988 PH |
25890 | normally applied to locally-submitted messages. Specifically: |
25891 | ||
25892 | .ilist | |
25893 | Any &'Sender:'& header line is left alone (in this respect, it is a | |
25894 | dynamic version of &%local_sender_retain%&). | |
25895 | .next | |
25896 | No &'Message-ID:'&, &'From:'&, or &'Date:'& header lines are added. | |
25897 | .next | |
25898 | There is no check that &'From:'& corresponds to the actual sender. | |
25899 | .endlist ilist | |
25900 | ||
db9452a9 PH |
25901 | This control may be useful when a remotely-originated message is accepted, |
25902 | passed to some scanning program, and then re-submitted for delivery. It can be | |
25903 | used only in the &%acl_smtp_mail%&, &%acl_smtp_rcpt%&, &%acl_smtp_predata%&, | |
25904 | and &%acl_not_smtp_start%& ACLs, because it has to be set before the message's | |
25905 | data is read. | |
f89d2485 | 25906 | |
f89d2485 PH |
25907 | &*Note:*& This control applies only to the current message, not to any others |
25908 | that are being submitted at the same time using &%-bs%& or &%-bS%&. | |
9b371988 | 25909 | .endlist vlist |
068aaea8 | 25910 | |
f89d2485 PH |
25911 | |
25912 | .section "Summary of message fixup control" "SECTsummesfix" | |
068aaea8 PH |
25913 | All four possibilities for message fixups can be specified: |
25914 | ||
9b371988 PH |
25915 | .ilist |
25916 | Locally submitted, fixups applied: the default. | |
25917 | .next | |
9c2b45c9 NM |
25918 | Locally submitted, no fixups applied: use |
25919 | &`control = suppress_local_fixups`&. | |
9b371988 PH |
25920 | .next |
25921 | Remotely submitted, no fixups applied: the default. | |
25922 | .next | |
9c2b45c9 | 25923 | Remotely submitted, fixups applied: use &`control = submission`&. |
9b371988 | 25924 | .endlist |
9b371988 PH |
25925 | |
25926 | ||
25927 | ||
4f578862 | 25928 | .section "Adding header lines in ACLs" "SECTaddheadacl" |
9b371988 PH |
25929 | .cindex "header lines" "adding in an ACL" |
25930 | .cindex "header lines" "position of added lines" | |
f89d2485 | 25931 | .cindex "&%message%& ACL modifier" |
4f578862 PH |
25932 | The &%add_header%& modifier can be used to add one or more extra header lines |
25933 | to an incoming message, as in this example: | |
9b371988 | 25934 | .code |
4f578862 | 25935 | warn dnslists = sbl.spamhaus.org : \ |
168e428f | 25936 | dialup.mail-abuse.org |
4f578862 | 25937 | add_header = X-blacklisted-at: $dnslist_domain |
9b371988 | 25938 | .endd |
4f578862 PH |
25939 | The &%add_header%& modifier is permitted in the MAIL, RCPT, PREDATA, DATA, |
25940 | MIME, and non-SMTP ACLs (in other words, those that are concerned with | |
25941 | receiving a message). The message must ultimately be accepted for | |
25942 | &%add_header%& to have any significant effect. You can use &%add_header%& with | |
25943 | any ACL verb, including &%deny%& (though this is potentially useful only in a | |
25944 | RCPT ACL). | |
25945 | ||
25946 | If the data for the &%add_header%& modifier contains one or more newlines that | |
25947 | are not followed by a space or a tab, it is assumed to contain multiple header | |
9b371988 | 25948 | lines. Each one is checked for valid syntax; &`X-ACL-Warn:`& is added to the |
168e428f PH |
25949 | front of any line that is not a valid header line. |
25950 | ||
4f578862 PH |
25951 | Added header lines are accumulated during the MAIL, RCPT, and predata ACLs. |
25952 | They are added to the message before processing the DATA and MIME ACLs. | |
25953 | However, if an identical header line is requested more than once, only one copy | |
25954 | is actually added to the message. Further header lines may be accumulated | |
25955 | during the DATA and MIME ACLs, after which they are added to the message, again | |
25956 | with duplicates suppressed. Thus, it is possible to add two identical header | |
25957 | lines to an SMTP message, but only if one is added before DATA and one after. | |
25958 | In the case of non-SMTP messages, new headers are accumulated during the | |
db9452a9 PH |
25959 | non-SMTP ACLs, and are added to the message after all the ACLs have run. If a |
25960 | message is rejected after DATA or by the non-SMTP ACL, all added header lines | |
25961 | are included in the entry that is written to the reject log. | |
4f578862 PH |
25962 | |
25963 | .cindex "header lines" "added; visibility of" | |
25964 | Header lines are not visible in string expansions until they are added to the | |
25965 | message. It follows that header lines defined in the MAIL, RCPT, and predata | |
25966 | ACLs are not visible until the DATA ACL and MIME ACLs are run. Similarly, | |
25967 | header lines that are added by the DATA or MIME ACLs are not visible in those | |
25968 | ACLs. Because of this restriction, you cannot use header lines as a way of | |
25969 | passing data between (for example) the MAIL and RCPT ACLs. If you want to do | |
25970 | this, you can use ACL variables, as described in section | |
25971 | &<<SECTaclvariables>>&. | |
25972 | ||
25973 | The &%add_header%& modifier acts immediately it is encountered during the | |
25974 | processing of an ACL. Notice the difference between these two cases: | |
25975 | .display | |
25976 | &`accept add_header = ADDED: some text`& | |
25977 | &` `&<&'some condition'&> | |
25978 | ||
25979 | &`accept `&<&'some condition'&> | |
25980 | &` add_header = ADDED: some text`& | |
25981 | .endd | |
25982 | In the first case, the header line is always added, whether or not the | |
25983 | condition is true. In the second case, the header line is added only if the | |
25984 | condition is true. Multiple occurrences of &%add_header%& may occur in the same | |
25985 | ACL statement. All those that are encountered before a condition fails are | |
25986 | honoured. | |
25987 | ||
f89d2485 | 25988 | .cindex "&%warn%& ACL verb" |
4f578862 PH |
25989 | For compatibility with previous versions of Exim, a &%message%& modifier for a |
25990 | &%warn%& verb acts in the same way as &%add_header%&, except that it takes | |
25991 | effect only if all the conditions are true, even if it appears before some of | |
25992 | them. Furthermore, only the last occurrence of &%message%& is honoured. This | |
25993 | usage of &%message%& is now deprecated. If both &%add_header%& and &%message%& | |
25994 | are present on a &%warn%& verb, both are processed according to their | |
25995 | specifications. | |
25996 | ||
25997 | By default, new header lines are added to a message at the end of the existing | |
25998 | header lines. However, you can specify that any particular header line should | |
25999 | be added right at the start (before all the &'Received:'& lines), immediately | |
26000 | after the first block of &'Received:'& lines, or immediately before any line | |
26001 | that is not a &'Received:'& or &'Resent-something:'& header. | |
168e428f | 26002 | |
9b371988 PH |
26003 | This is done by specifying &":at_start:"&, &":after_received:"&, or |
26004 | &":at_start_rfc:"& (or, for completeness, &":at_end:"&) before the text of the | |
168e428f PH |
26005 | header line, respectively. (Header text cannot start with a colon, as there has |
26006 | to be a header name first.) For example: | |
9b371988 | 26007 | .code |
4f578862 PH |
26008 | warn add_header = \ |
26009 | :after_received:X-My-Header: something or other... | |
9b371988 | 26010 | .endd |
4f578862 PH |
26011 | If more than one header line is supplied in a single &%add_header%& modifier, |
26012 | each one is treated independently and can therefore be placed differently. If | |
26013 | you add more than one line at the start, or after the Received: block, they end | |
26014 | up in reverse order. | |
168e428f | 26015 | |
9b371988 | 26016 | &*Warning*&: This facility currently applies only to header lines that are |
168e428f PH |
26017 | added in an ACL. It does NOT work for header lines that are added in a |
26018 | system filter or in a router or transport. | |
168e428f | 26019 | |
168e428f PH |
26020 | |
26021 | ||
26022 | ||
9b371988 PH |
26023 | .section "ACL conditions" "SECTaclconditions" |
26024 | .cindex "&ACL;" "conditions; list of" | |
168e428f PH |
26025 | Some of conditions listed in this section are available only when Exim is |
26026 | compiled with the content-scanning extension. They are included here briefly | |
26027 | for completeness. More detailed descriptions can be found in the discussion on | |
9b371988 | 26028 | content scanning in chapter &<<CHAPexiscan>>&. |
168e428f PH |
26029 | |
26030 | Not all conditions are relevant in all circumstances. For example, testing | |
26031 | senders and recipients does not make sense in an ACL that is being run as the | |
26032 | result of the arrival of an ETRN command, and checks on message headers can be | |
9b371988 PH |
26033 | done only in the ACLs specified by &%acl_smtp_data%& and &%acl_not_smtp%&. You |
26034 | can use the same condition (with different parameters) more than once in the | |
26035 | same ACL statement. This provides a way of specifying an &"and"& conjunction. | |
26036 | The conditions are as follows: | |
26037 | ||
26038 | ||
26039 | .vlist | |
26040 | .vitem &*acl&~=&~*&<&'name&~of&~acl&~or&~ACL&~string&~or&~file&~name&~'&> | |
26041 | .cindex "&ACL;" "nested" | |
26042 | .cindex "&ACL;" "indirect" | |
f89d2485 | 26043 | .cindex "&%acl%& ACL condition" |
9b371988 PH |
26044 | The possible values of the argument are the same as for the |
26045 | &%acl_smtp_%&&'xxx'& options. The named or inline ACL is run. If it returns | |
26046 | &"accept"& the condition is true; if it returns &"deny"& the condition is | |
26047 | false. If it returns &"defer"&, the current ACL returns &"defer"& unless the | |
26048 | condition is on a &%warn%& verb. In that case, a &"defer"& return makes the | |
26049 | condition false. This means that further processing of the &%warn%& verb | |
26050 | ceases, but processing of the ACL continues. | |
26051 | ||
26052 | If the nested &%acl%& returns &"drop"& and the outer condition denies access, | |
26053 | the connection is dropped. If it returns &"discard"&, the verb must be | |
26054 | &%accept%& or &%discard%&, and the action is taken immediately &-- no further | |
26055 | conditions are tested. | |
26056 | ||
168e428f PH |
26057 | ACLs may be nested up to 20 deep; the limit exists purely to catch runaway |
26058 | loops. This condition allows you to use different ACLs in different | |
26059 | circumstances. For example, different ACLs can be used to handle RCPT commands | |
26060 | for different local users or different local domains. | |
26061 | ||
9b371988 | 26062 | .vitem &*authenticated&~=&~*&<&'string&~list'&> |
f89d2485 | 26063 | .cindex "&%authenticated%& ACL condition" |
9b371988 PH |
26064 | .cindex "authentication" "ACL checking" |
26065 | .cindex "&ACL;" "testing for authentication" | |
168e428f PH |
26066 | If the SMTP connection is not authenticated, the condition is false. Otherwise, |
26067 | the name of the authenticator is tested against the list. To test for | |
26068 | authentication by any authenticator, you can set | |
9b371988 PH |
26069 | .code |
26070 | authenticated = * | |
26071 | .endd | |
26072 | ||
26073 | .vitem &*condition&~=&~*&<&'string'&> | |
f89d2485 | 26074 | .cindex "&%condition%& ACL condition" |
9b371988 PH |
26075 | .cindex "customizing" "ACL condition" |
26076 | .cindex "&ACL;" "customized test" | |
f89d2485 | 26077 | .cindex "&ACL;" "testing, customized" |
168e428f PH |
26078 | This feature allows you to make up custom conditions. If the result of |
26079 | expanding the string is an empty string, the number zero, or one of the strings | |
9b371988 PH |
26080 | &"no"& or &"false"&, the condition is false. If the result is any non-zero |
26081 | number, or one of the strings &"yes"& or &"true"&, the condition is true. For | |
db9452a9 | 26082 | any other value, some error is assumed to have occurred, and the ACL returns |
3cb1b51e | 26083 | &"defer"&. However, if the expansion is forced to fail, the condition is |
db9452a9 | 26084 | ignored. The effect is to treat it as true, whether it is positive or |
3cb1b51e | 26085 | negative. |
168e428f | 26086 | |
9b371988 | 26087 | .vitem &*decode&~=&~*&<&'location'&> |
f89d2485 | 26088 | .cindex "&%decode%& ACL condition" |
168e428f | 26089 | This condition is available only when Exim is compiled with the |
3cb1b51e | 26090 | content-scanning extension, and it is allowed only in the ACL defined by |
9b371988 | 26091 | &%acl_smtp_mime%&. It causes the current MIME part to be decoded into a file. |
595028e4 | 26092 | If all goes well, the condition is true. It is false only if there are |
f89d2485 | 26093 | problems such as a syntax error or a memory shortage. For more details, see |
595028e4 | 26094 | chapter &<<CHAPexiscan>>&. |
168e428f | 26095 | |
9b371988 | 26096 | .vitem &*demime&~=&~*&<&'extension&~list'&> |
f89d2485 | 26097 | .cindex "&%demime%& ACL condition" |
068aaea8 | 26098 | This condition is available only when Exim is compiled with the |
9b371988 PH |
26099 | content-scanning extension. Its use is described in section |
26100 | &<<SECTdemimecond>>&. | |
26101 | ||
26102 | .vitem &*dnslists&~=&~*&<&'list&~of&~domain&~names&~and&~other&~data'&> | |
f89d2485 | 26103 | .cindex "&%dnslists%& ACL condition" |
9b371988 PH |
26104 | .cindex "DNS list" "in ACL" |
26105 | .cindex "black list (DNS)" | |
26106 | .cindex "&ACL;" "testing a DNS list" | |
168e428f | 26107 | This condition checks for entries in DNS black lists. These are also known as |
9b371988 PH |
26108 | &"RBL lists"&, after the original Realtime Blackhole List, but note that the |
26109 | use of the lists at &'mail-abuse.org'& now carries a charge. There are too many | |
168e428f | 26110 | different variants of this condition to describe briefly here. See sections |
595028e4 | 26111 | &<<SECTmorednslists>>&&--&<<SECTmorednslistslast>>& for details. |
168e428f | 26112 | |
9b371988 | 26113 | .vitem &*domains&~=&~*&<&'domain&~list'&> |
f89d2485 | 26114 | .cindex "&%domains%& ACL condition" |
9b371988 PH |
26115 | .cindex "domain" "ACL checking" |
26116 | .cindex "&ACL;" "testing a recipient domain" | |
f89d2485 | 26117 | .vindex "&$domain_data$&" |
168e428f PH |
26118 | This condition is relevant only after a RCPT command. It checks that the domain |
26119 | of the recipient address is in the domain list. If percent-hack processing is | |
26120 | enabled, it is done before this test is done. If the check succeeds with a | |
9b371988 PH |
26121 | lookup, the result of the lookup is placed in &$domain_data$& until the next |
26122 | &%domains%& test. | |
168e428f | 26123 | |
3cb1b51e PH |
26124 | &*Note carefully*& (because many people seem to fall foul of this): you cannot |
26125 | use &%domains%& in a DATA ACL. | |
3cb1b51e PH |
26126 | |
26127 | ||
9b371988 | 26128 | .vitem &*encrypted&~=&~*&<&'string&~list'&> |
f89d2485 | 26129 | .cindex "&%encrypted%& ACL condition" |
9b371988 PH |
26130 | .cindex "encryption" "checking in an ACL" |
26131 | .cindex "&ACL;" "testing for encryption" | |
168e428f PH |
26132 | If the SMTP connection is not encrypted, the condition is false. Otherwise, the |
26133 | name of the cipher suite in use is tested against the list. To test for | |
26134 | encryption without testing for any specific cipher suite(s), set | |
9b371988 PH |
26135 | .code |
26136 | encrypted = * | |
26137 | .endd | |
26138 | ||
3cb1b51e | 26139 | |
9b371988 | 26140 | .vitem &*hosts&~=&~*&<&'&~host&~list'&> |
f89d2485 | 26141 | .cindex "&%hosts%& ACL condition" |
9b371988 PH |
26142 | .cindex "host" "ACL checking" |
26143 | .cindex "&ACL;" "testing the client host" | |
168e428f PH |
26144 | This condition tests that the calling host matches the host list. If you have |
26145 | name lookups or wildcarded host names and IP addresses in the same host list, | |
26146 | you should normally put the IP addresses first. For example, you could have: | |
9b371988 PH |
26147 | .code |
26148 | accept hosts = 10.9.8.7 : dbm;/etc/friendly/hosts | |
26149 | .endd | |
3cb1b51e PH |
26150 | The lookup in this example uses the host name for its key. This is implied by |
26151 | the lookup type &"dbm"&. (For a host address lookup you would use &"net-dbm"& | |
26152 | and it wouldn't matter which way round you had these two items.) | |
3cb1b51e PH |
26153 | |
26154 | The reason for the problem with host names lies in the left-to-right way that | |
26155 | Exim processes lists. It can test IP addresses without doing any DNS lookups, | |
26156 | but when it reaches an item that requires a host name, it fails if it cannot | |
26157 | find a host name to compare with the pattern. If the above list is given in the | |
26158 | opposite order, the &%accept%& statement fails for a host whose name cannot be | |
26159 | found, even if its IP address is 10.9.8.7. | |
9b371988 | 26160 | |
168e428f PH |
26161 | If you really do want to do the name check first, and still recognize the IP |
26162 | address even if the name lookup fails, you can rewrite the ACL like this: | |
9b371988 PH |
26163 | .code |
26164 | accept hosts = dbm;/etc/friendly/hosts | |
26165 | accept hosts = 10.9.8.7 | |
26166 | .endd | |
168e428f | 26167 | The default action on failing to find the host name is to assume that the host |
9b371988 PH |
26168 | is not in the list, so the first &%accept%& statement fails. The second |
26169 | statement can then check the IP address. | |
168e428f | 26170 | |
f89d2485 | 26171 | .vindex "&$host_data$&" |
9b371988 PH |
26172 | If a &%hosts%& condition is satisfied by means of a lookup, the result |
26173 | of the lookup is made available in the &$host_data$& variable. This | |
26174 | allows you, for example, to set up a statement like this: | |
26175 | .code | |
26176 | deny hosts = net-lsearch;/some/file | |
26177 | message = $host_data | |
26178 | .endd | |
168e428f PH |
26179 | which gives a custom error message for each denied host. |
26180 | ||
9b371988 | 26181 | .vitem &*local_parts&~=&~*&<&'local&~part&~list'&> |
f89d2485 | 26182 | .cindex "&%local_parts%& ACL condition" |
9b371988 PH |
26183 | .cindex "local part" "ACL checking" |
26184 | .cindex "&ACL;" "testing a local part" | |
f89d2485 | 26185 | .vindex "&$local_part_data$&" |
168e428f PH |
26186 | This condition is relevant only after a RCPT command. It checks that the local |
26187 | part of the recipient address is in the list. If percent-hack processing is | |
26188 | enabled, it is done before this test. If the check succeeds with a lookup, the | |
9b371988 PH |
26189 | result of the lookup is placed in &$local_part_data$&, which remains set until |
26190 | the next &%local_parts%& test. | |
168e428f | 26191 | |
9b371988 | 26192 | .vitem &*malware&~=&~*&<&'option'&> |
f89d2485 | 26193 | .cindex "&%malware%& ACL condition" |
9b371988 PH |
26194 | .cindex "&ACL;" "virus scanning" |
26195 | .cindex "&ACL;" "scanning for viruses" | |
168e428f PH |
26196 | This condition is available only when Exim is compiled with the |
26197 | content-scanning extension. It causes the incoming message to be scanned for | |
9b371988 | 26198 | viruses. For details, see chapter &<<CHAPexiscan>>&. |
168e428f | 26199 | |
9b371988 | 26200 | .vitem &*mime_regex&~=&~*&<&'list&~of&~regular&~expressions'&> |
f89d2485 | 26201 | .cindex "&%mime_regex%& ACL condition" |
9b371988 | 26202 | .cindex "&ACL;" "testing by regex matching" |
168e428f | 26203 | This condition is available only when Exim is compiled with the |
3cb1b51e | 26204 | content-scanning extension, and it is allowed only in the ACL defined by |
9b371988 PH |
26205 | &%acl_smtp_mime%&. It causes the current MIME part to be scanned for a match |
26206 | with any of the regular expressions. For details, see chapter | |
26207 | &<<CHAPexiscan>>&. | |
168e428f | 26208 | |
9b371988 PH |
26209 | .vitem &*ratelimit&~=&~*&<&'parameters'&> |
26210 | .cindex "rate limiting" | |
068aaea8 | 26211 | This condition can be used to limit the rate at which a user or host submits |
9b371988 | 26212 | messages. Details are given in section &<<SECTratelimiting>>&. |
068aaea8 | 26213 | |
9b371988 | 26214 | .vitem &*recipients&~=&~*&<&'address&~list'&> |
f89d2485 | 26215 | .cindex "&%recipients%& ACL condition" |
9b371988 PH |
26216 | .cindex "recipient" "ACL checking" |
26217 | .cindex "&ACL;" "testing a recipient" | |
168e428f PH |
26218 | This condition is relevant only after a RCPT command. It checks the entire |
26219 | recipient address against a list of recipients. | |
26220 | ||
9b371988 | 26221 | .vitem &*regex&~=&~*&<&'list&~of&~regular&~expressions'&> |
f89d2485 | 26222 | .cindex "&%regex%& ACL condition" |
9b371988 | 26223 | .cindex "&ACL;" "testing by regex matching" |
168e428f | 26224 | This condition is available only when Exim is compiled with the |
068aaea8 PH |
26225 | content-scanning extension, and is available only in the DATA, MIME, and |
26226 | non-SMTP ACLs. It causes the incoming message to be scanned for a match with | |
9b371988 PH |
26227 | any of the regular expressions. For details, see chapter &<<CHAPexiscan>>&. |
26228 | ||
26229 | .vitem &*sender_domains&~=&~*&<&'domain&~list'&> | |
f89d2485 | 26230 | .cindex "&%sender_domains%& ACL condition" |
9b371988 PH |
26231 | .cindex "sender" "ACL checking" |
26232 | .cindex "&ACL;" "testing a sender domain" | |
f89d2485 PH |
26233 | .vindex "&$domain$&" |
26234 | .vindex "&$sender_address_domain$&" | |
168e428f | 26235 | This condition tests the domain of the sender of the message against the given |
9b371988 PH |
26236 | domain list. &*Note*&: The domain of the sender address is in |
26237 | &$sender_address_domain$&. It is &'not'& put in &$domain$& during the testing | |
26238 | of this condition. This is an exception to the general rule for testing domain | |
26239 | lists. It is done this way so that, if this condition is used in an ACL for a | |
26240 | RCPT command, the recipient's domain (which is in &$domain$&) can be used to | |
26241 | influence the sender checking. | |
26242 | ||
9b371988 | 26243 | &*Warning*&: It is a bad idea to use this condition on its own as a control on |
068aaea8 | 26244 | relaying, because sender addresses are easily, and commonly, forged. |
168e428f | 26245 | |
9b371988 | 26246 | .vitem &*senders&~=&~*&<&'address&~list'&> |
f89d2485 | 26247 | .cindex "&%senders%& ACL condition" |
9b371988 PH |
26248 | .cindex "sender" "ACL checking" |
26249 | .cindex "&ACL;" "testing a sender" | |
168e428f PH |
26250 | This condition tests the sender of the message against the given list. To test |
26251 | for a bounce message, which has an empty sender, set | |
9b371988 PH |
26252 | .code |
26253 | senders = : | |
26254 | .endd | |
9b371988 | 26255 | &*Warning*&: It is a bad idea to use this condition on its own as a control on |
068aaea8 | 26256 | relaying, because sender addresses are easily, and commonly, forged. |
168e428f | 26257 | |
9b371988 | 26258 | .vitem &*spam&~=&~*&<&'username'&> |
f89d2485 | 26259 | .cindex "&%spam%& ACL condition" |
9b371988 | 26260 | .cindex "&ACL;" "scanning for spam" |
168e428f PH |
26261 | This condition is available only when Exim is compiled with the |
26262 | content-scanning extension. It causes the incoming message to be scanned by | |
9b371988 PH |
26263 | SpamAssassin. For details, see chapter &<<CHAPexiscan>>&. |
26264 | ||
26265 | .vitem &*verify&~=&~certificate*& | |
f89d2485 | 26266 | .cindex "&%verify%& ACL condition" |
9b371988 PH |
26267 | .cindex "TLS" "client certificate verification" |
26268 | .cindex "certificate" "verification of client" | |
26269 | .cindex "&ACL;" "certificate verification" | |
26270 | .cindex "&ACL;" "testing a TLS certificate" | |
168e428f PH |
26271 | This condition is true in an SMTP session if the session is encrypted, and a |
26272 | certificate was received from the client, and the certificate was verified. The | |
9b371988 PH |
26273 | server requests a certificate only if the client matches &%tls_verify_hosts%& |
26274 | or &%tls_try_verify_hosts%& (see chapter &<<CHAPTLS>>&). | |
168e428f | 26275 | |
9b371988 PH |
26276 | .vitem &*verify&~=&~csa*& |
26277 | .cindex "CSA verification" | |
068aaea8 PH |
26278 | This condition checks whether the sending host (the client) is authorized to |
26279 | send email. Details of how this works are given in section | |
9b371988 | 26280 | &<<SECTverifyCSA>>&. |
9b371988 PH |
26281 | |
26282 | .vitem &*verify&~=&~header_sender/*&<&'options'&> | |
f89d2485 | 26283 | .cindex "&%verify%& ACL condition" |
9b371988 PH |
26284 | .cindex "&ACL;" "verifying sender in the header" |
26285 | .cindex "header lines" "verifying the sender in" | |
26286 | .cindex "sender" "verifying in header" | |
26287 | .cindex "verifying" "sender in header" | |
168e428f | 26288 | This condition is relevant only in an ACL that is run after a message has been |
9b371988 PH |
26289 | received, that is, in an ACL specified by &%acl_smtp_data%& or |
26290 | &%acl_not_smtp%&. It checks that there is a verifiable address in at least one | |
26291 | of the &'Sender:'&, &'Reply-To:'&, or &'From:'& header lines. Such an address | |
26292 | is loosely thought of as a &"sender"& address (hence the name of the test). | |
26293 | However, an address that appears in one of these headers need not be an address | |
26294 | that accepts bounce messages; only sender addresses in envelopes are required | |
26295 | to accept bounces. Therefore, if you use the callout option on this check, you | |
26296 | might want to arrange for a non-empty address in the MAIL command. | |
26297 | ||
168e428f | 26298 | Details of address verification and the options are given later, starting at |
9b371988 PH |
26299 | section &<<SECTaddressverification>>& (callouts are described in section |
26300 | &<<SECTcallver>>&). You can combine this condition with the &%senders%& | |
26301 | condition to restrict it to bounce messages only: | |
26302 | .code | |
26303 | deny senders = : | |
26304 | message = A valid sender header is required for bounces | |
26305 | !verify = header_sender | |
26306 | .endd | |
26307 | ||
26308 | .vitem &*verify&~=&~header_syntax*& | |
f89d2485 | 26309 | .cindex "&%verify%& ACL condition" |
9b371988 PH |
26310 | .cindex "&ACL;" "verifying header syntax" |
26311 | .cindex "header lines" "verifying syntax" | |
26312 | .cindex "verifying" "header syntax" | |
168e428f | 26313 | This condition is relevant only in an ACL that is run after a message has been |
9b371988 PH |
26314 | received, that is, in an ACL specified by &%acl_smtp_data%& or |
26315 | &%acl_not_smtp%&. It checks the syntax of all header lines that can contain | |
26316 | lists of addresses (&'Sender:'&, &'From:'&, &'Reply-To:'&, &'To:'&, &'Cc:'&, | |
26317 | and &'Bcc:'&). Unqualified addresses (local parts without domains) are | |
26318 | permitted only in locally generated messages and from hosts that match | |
26319 | &%sender_unqualified_hosts%& or &%recipient_unqualified_hosts%&, as | |
26320 | appropriate. | |
26321 | ||
168e428f PH |
26322 | Note that this condition is a syntax check only. However, a common spamming |
26323 | ploy used to be to send syntactically invalid headers such as | |
9b371988 PH |
26324 | .code |
26325 | To: @ | |
26326 | .endd | |
168e428f PH |
26327 | and this condition can be used to reject such messages, though they are not as |
26328 | common as they used to be. | |
26329 | ||
9b371988 | 26330 | .vitem &*verify&~=&~helo*& |
f89d2485 | 26331 | .cindex "&%verify%& ACL condition" |
9b371988 PH |
26332 | .cindex "&ACL;" "verifying HELO/EHLO" |
26333 | .cindex "HELO" "verifying" | |
26334 | .cindex "EHLO" "verifying" | |
26335 | .cindex "verifying" "EHLO" | |
26336 | .cindex "verifying" "HELO" | |
168e428f | 26337 | This condition is true if a HELO or EHLO command has been received from the |
3cb1b51e PH |
26338 | client host, and its contents have been verified. If there has been no previous |
26339 | attempt to verify the HELO/EHLO contents, it is carried out when this | |
9b371988 PH |
26340 | condition is encountered. See the description of the &%helo_verify_hosts%& and |
26341 | &%helo_try_verify_hosts%& options for details of how to request verification | |
068aaea8 PH |
26342 | independently of this condition. |
26343 | ||
3cb1b51e PH |
26344 | For SMTP input that does not come over TCP/IP (the &%-bs%& command line |
26345 | option), this condition is always true. | |
3cb1b51e PH |
26346 | |
26347 | ||
9b371988 PH |
26348 | .vitem &*verify&~=&~not_blind*& |
26349 | .cindex "verifying" "not blind" | |
f89d2485 | 26350 | .cindex "bcc recipients, verifying none" |
068aaea8 | 26351 | This condition checks that there are no blind (bcc) recipients in the message. |
9b371988 PH |
26352 | Every envelope recipient must appear either in a &'To:'& header line or in a |
26353 | &'Cc:'& header line for this condition to be true. Local parts are checked | |
26354 | case-sensitively; domains are checked case-insensitively. If &'Resent-To:'& or | |
26355 | &'Resent-Cc:'& header lines exist, they are also checked. This condition can be | |
068aaea8 | 26356 | used only in a DATA or non-SMTP ACL. |
068aaea8 | 26357 | |
9b371988 PH |
26358 | There are, of course, many legitimate messages that make use of blind (bcc) |
26359 | recipients. This check should not be used on its own for blocking messages. | |
068aaea8 | 26360 | |
168e428f | 26361 | |
9b371988 | 26362 | .vitem &*verify&~=&~recipient/*&<&'options'&> |
f89d2485 | 26363 | .cindex "&%verify%& ACL condition" |
9b371988 PH |
26364 | .cindex "&ACL;" "verifying recipient" |
26365 | .cindex "recipient" "verifying" | |
26366 | .cindex "verifying" "recipient" | |
f89d2485 | 26367 | .vindex "&$address_data$&" |
168e428f PH |
26368 | This condition is relevant only after a RCPT command. It verifies the current |
26369 | recipient. Details of address verification are given later, starting at section | |
9b371988 PH |
26370 | &<<SECTaddressverification>>&. After a recipient has been verified, the value |
26371 | of &$address_data$& is the last value that was set while routing the address. | |
26372 | This applies even if the verification fails. When an address that is being | |
26373 | verified is redirected to a single address, verification continues with the new | |
26374 | address, and in that case, the subsequent value of &$address_data$& is the | |
26375 | value for the child address. | |
26376 | ||
26377 | .vitem &*verify&~=&~reverse_host_lookup*& | |
f89d2485 | 26378 | .cindex "&%verify%& ACL condition" |
9b371988 PH |
26379 | .cindex "&ACL;" "verifying host reverse lookup" |
26380 | .cindex "host" "verifying reverse lookup" | |
168e428f PH |
26381 | This condition ensures that a verified host name has been looked up from the IP |
26382 | address of the client host. (This may have happened already if the host name | |
9b371988 | 26383 | was needed for checking a host list, or if the host matched &%host_lookup%&.) |
168e428f PH |
26384 | Verification ensures that the host name obtained from a reverse DNS lookup, or |
26385 | one of its aliases, does, when it is itself looked up in the DNS, yield the | |
26386 | original IP address. | |
9b371988 | 26387 | |
168e428f PH |
26388 | If this condition is used for a locally generated message (that is, when there |
26389 | is no client host involved), it always succeeds. | |
26390 | ||
9b371988 | 26391 | .vitem &*verify&~=&~sender/*&<&'options'&> |
f89d2485 | 26392 | .cindex "&%verify%& ACL condition" |
9b371988 PH |
26393 | .cindex "&ACL;" "verifying sender" |
26394 | .cindex "sender" "verifying" | |
26395 | .cindex "verifying" "sender" | |
168e428f | 26396 | This condition is relevant only after a MAIL or RCPT command, or after a |
9b371988 PH |
26397 | message has been received (the &%acl_smtp_data%& or &%acl_not_smtp%& ACLs). If |
26398 | the message's sender is empty (that is, this is a bounce message), the | |
26399 | condition is true. Otherwise, the sender address is verified. | |
26400 | ||
f89d2485 PH |
26401 | .vindex "&$address_data$&" |
26402 | .vindex "&$sender_address_data$&" | |
9b371988 PH |
26403 | If there is data in the &$address_data$& variable at the end of routing, its |
26404 | value is placed in &$sender_address_data$& at the end of verification. This | |
168e428f PH |
26405 | value can be used in subsequent conditions and modifiers in the same ACL |
26406 | statement. It does not persist after the end of the current statement. If you | |
26407 | want to preserve the value for longer, you can save it in an ACL variable. | |
9b371988 | 26408 | |
168e428f | 26409 | Details of verification are given later, starting at section |
9b371988 PH |
26410 | &<<SECTaddressverification>>&. Exim caches the result of sender verification, |
26411 | to avoid doing it more than once per message. | |
168e428f | 26412 | |
9b371988 | 26413 | .vitem &*verify&~=&~sender=*&<&'address'&>&*/*&<&'options'&> |
f89d2485 | 26414 | .cindex "&%verify%& ACL condition" |
168e428f PH |
26415 | This is a variation of the previous option, in which a modified address is |
26416 | verified as a sender. | |
9b371988 | 26417 | .endlist |
168e428f PH |
26418 | |
26419 | ||
26420 | ||
9b371988 PH |
26421 | .section "Using DNS lists" "SECTmorednslists" |
26422 | .cindex "DNS list" "in ACL" | |
26423 | .cindex "black list (DNS)" | |
26424 | .cindex "&ACL;" "testing a DNS list" | |
26425 | In its simplest form, the &%dnslists%& condition tests whether the calling host | |
168e428f | 26426 | is on at least one of a number of DNS lists by looking up the inverted IP |
30966db0 TF |
26427 | address in one or more DNS domains. (Note that DNS list domains are not mail |
26428 | domains, so the &`+`& syntax for named lists doesn't work - it is used for | |
26429 | special options instead.) For example, if the calling host's IP | |
168e428f | 26430 | address is 192.168.62.43, and the ACL statement is |
9b371988 | 26431 | .code |
168e428f PH |
26432 | deny dnslists = blackholes.mail-abuse.org : \ |
26433 | dialups.mail-abuse.org | |
9b371988 | 26434 | .endd |
168e428f | 26435 | the following records are looked up: |
9b371988 PH |
26436 | .code |
26437 | 43.62.168.192.blackholes.mail-abuse.org | |
26438 | 43.62.168.192.dialups.mail-abuse.org | |
26439 | .endd | |
168e428f | 26440 | As soon as Exim finds an existing DNS record, processing of the list stops. |
9b371988 PH |
26441 | Thus, multiple entries on the list provide an &"or"& conjunction. If you want |
26442 | to test that a host is on more than one list (an &"and"& conjunction), you can | |
26443 | use two separate conditions: | |
26444 | .code | |
26445 | deny dnslists = blackholes.mail-abuse.org | |
26446 | dnslists = dialups.mail-abuse.org | |
26447 | .endd | |
168e428f PH |
26448 | If a DNS lookup times out or otherwise fails to give a decisive answer, Exim |
26449 | behaves as if the host does not match the list item, that is, as if the DNS | |
26450 | record does not exist. If there are further items in the DNS list, they are | |
26451 | processed. | |
26452 | ||
9b371988 PH |
26453 | This is usually the required action when &%dnslists%& is used with &%deny%& |
26454 | (which is the most common usage), because it prevents a DNS failure from | |
26455 | blocking mail. However, you can change this behaviour by putting one of the | |
26456 | following special items in the list: | |
26457 | .display | |
26458 | &`+include_unknown `& behave as if the item is on the list | |
26459 | &`+exclude_unknown `& behave as if the item is not on the list (default) | |
26460 | &`+defer_unknown `& give a temporary error | |
26461 | .endd | |
26462 | .cindex "&`+include_unknown`&" | |
26463 | .cindex "&`+exclude_unknown`&" | |
26464 | .cindex "&`+defer_unknown`&" | |
168e428f | 26465 | Each of these applies to any subsequent items on the list. For example: |
9b371988 PH |
26466 | .code |
26467 | deny dnslists = +defer_unknown : foo.bar.example | |
26468 | .endd | |
168e428f PH |
26469 | Testing the list of domains stops as soon as a match is found. If you want to |
26470 | warn for one list and block for another, you can use two different statements: | |
9b371988 PH |
26471 | .code |
26472 | deny dnslists = blackholes.mail-abuse.org | |
26473 | warn message = X-Warn: sending host is on dialups list | |
26474 | dnslists = dialups.mail-abuse.org | |
26475 | .endd | |
168e428f PH |
26476 | DNS list lookups are cached by Exim for the duration of the SMTP session, |
26477 | so a lookup based on the IP address is done at most once for any incoming | |
26478 | connection. Exim does not share information between multiple incoming | |
26479 | connections (but your local name server cache should be active). | |
26480 | ||
26481 | ||
26482 | ||
f89d2485 | 26483 | .section "Specifying the IP address for a DNS list lookup" "SECID201" |
9b371988 | 26484 | .cindex "DNS list" "keyed by explicit IP address" |
168e428f PH |
26485 | By default, the IP address that is used in a DNS list lookup is the IP address |
26486 | of the calling host. However, you can specify another IP address by listing it | |
26487 | after the domain name, introduced by a slash. For example: | |
9b371988 PH |
26488 | .code |
26489 | deny dnslists = black.list.tld/192.168.1.2 | |
26490 | .endd | |
168e428f PH |
26491 | This feature is not very helpful with explicit IP addresses; it is intended for |
26492 | use with IP addresses that are looked up, for example, the IP addresses of the | |
26493 | MX hosts or nameservers of an email sender address. For an example, see section | |
9b371988 | 26494 | &<<SECTmulkeyfor>>& below. |
168e428f PH |
26495 | |
26496 | ||
26497 | ||
26498 | ||
f89d2485 | 26499 | .section "DNS lists keyed on domain names" "SECID202" |
9b371988 | 26500 | .cindex "DNS list" "keyed by domain name" |
168e428f | 26501 | There are some lists that are keyed on domain names rather than inverted IP |
9b371988 PH |
26502 | addresses (see for example the &'domain based zones'& link at |
26503 | &url(http://www.rfc-ignorant.org/)). No reversing of components is used | |
26504 | with these lists. You can change the name that is looked up in a DNS list by | |
26505 | listing it after the domain name, introduced by a slash. For example, | |
26506 | .code | |
26507 | deny message = Sender's domain is listed at $dnslist_domain | |
26508 | dnslists = dsn.rfc-ignorant.org/$sender_address_domain | |
26509 | .endd | |
168e428f PH |
26510 | This particular example is useful only in ACLs that are obeyed after the |
26511 | RCPT or DATA commands, when a sender address is available. If (for | |
9b371988 | 26512 | example) the message's sender is &'user@tld.example'& the name that is looked |
168e428f | 26513 | up by this example is |
9b371988 PH |
26514 | .code |
26515 | tld.example.dsn.rfc-ignorant.org | |
26516 | .endd | |
26517 | A single &%dnslists%& condition can contain entries for both names and IP | |
168e428f | 26518 | addresses. For example: |
9b371988 | 26519 | .code |
168e428f PH |
26520 | deny dnslists = sbl.spamhaus.org : \ |
26521 | dsn.rfc-ignorant.org/$sender_address_domain | |
9b371988 | 26522 | .endd |
168e428f PH |
26523 | The first item checks the sending host's IP address; the second checks a domain |
26524 | name. The whole condition is true if either of the DNS lookups succeeds. | |
26525 | ||
26526 | ||
26527 | ||
26528 | ||
9b371988 PH |
26529 | .section "Multiple explicit keys for a DNS list" "SECTmulkeyfor" |
26530 | .cindex "DNS list" "multiple keys for" | |
168e428f PH |
26531 | The syntax described above for looking up explicitly-defined values (either |
26532 | names or IP addresses) in a DNS blacklist is a simplification. After the domain | |
26533 | name for the DNS list, what follows the slash can in fact be a list of items. | |
26534 | As with all lists in Exim, the default separator is a colon. However, because | |
26535 | this is a sublist within the list of DNS blacklist domains, it is necessary | |
26536 | either to double the separators like this: | |
9b371988 PH |
26537 | .code |
26538 | dnslists = black.list.tld/name.1::name.2 | |
26539 | .endd | |
168e428f | 26540 | or to change the separator character, like this: |
9b371988 PH |
26541 | .code |
26542 | dnslists = black.list.tld/<;name.1;name.2 | |
26543 | .endd | |
168e428f PH |
26544 | If an item in the list is an IP address, it is inverted before the DNS |
26545 | blacklist domain is appended. If it is not an IP address, no inversion | |
26546 | occurs. Consider this condition: | |
9b371988 PH |
26547 | .code |
26548 | dnslists = black.list.tld/<;192.168.1.2;a.domain | |
26549 | .endd | |
168e428f | 26550 | The DNS lookups that occur are: |
9b371988 PH |
26551 | .code |
26552 | 2.1.168.192.black.list.tld | |
26553 | a.domain.black.list.tld | |
26554 | .endd | |
168e428f | 26555 | Once a DNS record has been found (that matches a specific IP return |
9b371988 PH |
26556 | address, if specified &-- see section &<<SECTaddmatcon>>&), no further lookups |
26557 | are done. If there is a temporary DNS error, the rest of the sublist of domains | |
26558 | or IP addresses is tried. A temporary error for the whole dnslists item occurs | |
168e428f PH |
26559 | only if no other DNS lookup in this sublist succeeds. In other words, a |
26560 | successful lookup for any of the items in the sublist overrides a temporary | |
26561 | error for a previous item. | |
26562 | ||
26563 | The ability to supply a list of items after the slash is in some sense just a | |
26564 | syntactic convenience. These two examples have the same effect: | |
9b371988 PH |
26565 | .code |
26566 | dnslists = black.list.tld/a.domain : black.list.tld/b.domain | |
26567 | dnslists = black.list.tld/a.domain::b.domain | |
26568 | .endd | |
168e428f PH |
26569 | However, when the data for the list is obtained from a lookup, the second form |
26570 | is usually much more convenient. Consider this example: | |
9b371988 PH |
26571 | .code |
26572 | deny message = The mail servers for the domain \ | |
26573 | $sender_address_domain \ | |
26574 | are listed at $dnslist_domain ($dnslist_value); \ | |
26575 | see $dnslist_text. | |
26576 | dnslists = sbl.spamhaus.org/<|${lookup dnsdb {>|a=<|\ | |
26577 | ${lookup dnsdb {>|mxh=\ | |
26578 | $sender_address_domain} }} } | |
26579 | .endd | |
26580 | Note the use of &`>|`& in the dnsdb lookup to specify the separator for | |
168e428f PH |
26581 | multiple DNS records. The inner dnsdb lookup produces a list of MX hosts |
26582 | and the outer dnsdb lookup finds the IP addresses for these hosts. The result | |
26583 | of expanding the condition might be something like this: | |
9b371988 PH |
26584 | .code |
26585 | dnslists = sbl.spahmaus.org/<|192.168.2.3|192.168.5.6|... | |
26586 | .endd | |
168e428f PH |
26587 | Thus, this example checks whether or not the IP addresses of the sender |
26588 | domain's mail servers are on the Spamhaus black list. | |
26589 | ||
595028e4 PH |
26590 | The key that was used for a successful DNS list lookup is put into the variable |
26591 | &$dnslist_matched$& (see section &<<SECID204>>&). | |
168e428f PH |
26592 | |
26593 | ||
26594 | ||
26595 | ||
f89d2485 | 26596 | .section "Data returned by DNS lists" "SECID203" |
9b371988 | 26597 | .cindex "DNS list" "data returned from" |
168e428f PH |
26598 | DNS lists are constructed using address records in the DNS. The original RBL |
26599 | just used the address 127.0.0.1 on the right hand side of each record, but the | |
26600 | RBL+ list and some other lists use a number of values with different meanings. | |
26601 | The values used on the RBL+ list are: | |
9b371988 | 26602 | .display |
168e428f PH |
26603 | 127.1.0.1 RBL |
26604 | 127.1.0.2 DUL | |
26605 | 127.1.0.3 DUL and RBL | |
26606 | 127.1.0.4 RSS | |
26607 | 127.1.0.5 RSS and RBL | |
26608 | 127.1.0.6 RSS and DUL | |
26609 | 127.1.0.7 RSS and DUL and RBL | |
9b371988 | 26610 | .endd |
3cb1b51e | 26611 | Section &<<SECTaddmatcon>>& below describes how you can distinguish between |
f89d2485 | 26612 | different values. Some DNS lists may return more than one address record; |
595028e4 PH |
26613 | see section &<<SECThanmuldnsrec>>& for details of how they are checked. |
26614 | ||
168e428f | 26615 | |
f89d2485 | 26616 | .section "Variables set from DNS lists" "SECID204" |
595028e4 | 26617 | .cindex "expansion" "variables, set from DNS list" |
9b371988 | 26618 | .cindex "DNS list" "variables set from" |
f89d2485 | 26619 | .vindex "&$dnslist_domain$&" |
595028e4 | 26620 | .vindex "&$dnslist_matched$&" |
f89d2485 PH |
26621 | .vindex "&$dnslist_text$&" |
26622 | .vindex "&$dnslist_value$&" | |
595028e4 PH |
26623 | When an entry is found in a DNS list, the variable &$dnslist_domain$& contains |
26624 | the name of the overall domain that matched (for example, | |
26625 | &`spamhaus.example`&), &$dnslist_matched$& contains the key within that domain | |
26626 | (for example, &`192.168.5.3`&), and &$dnslist_value$& contains the data from | |
26627 | the DNS record. When the key is an IP address, it is not reversed in | |
26628 | &$dnslist_matched$& (though it is, of course, in the actual lookup). In simple | |
26629 | cases, for example: | |
26630 | .code | |
26631 | deny dnslists = spamhaus.example | |
26632 | .endd | |
26633 | the key is also available in another variable (in this case, | |
26634 | &$sender_host_address$&). In more complicated cases, however, this is not true. | |
26635 | For example, using a data lookup (as described in section &<<SECTmulkeyfor>>&) | |
26636 | might generate a dnslists lookup like this: | |
26637 | .code | |
26638 | deny dnslists = spamhaus.example/<|192.168.1.2|192.168.6.7|... | |
26639 | .endd | |
26640 | If this condition succeeds, the value in &$dnslist_matched$& might be | |
26641 | &`192.168.6.7`& (for example). | |
595028e4 PH |
26642 | |
26643 | If more than one address record is returned by the DNS lookup, all the IP | |
26644 | addresses are included in &$dnslist_value$&, separated by commas and spaces. | |
26645 | The variable &$dnslist_text$& contains the contents of any associated TXT | |
26646 | record. For lists such as RBL+ the TXT record for a merged entry is often not | |
26647 | very meaningful. See section &<<SECTmordetinf>>& for a way of obtaining more | |
26648 | information. | |
168e428f | 26649 | |
3cb1b51e PH |
26650 | You can use the DNS list variables in &%message%& or &%log_message%& modifiers |
26651 | &-- although these appear before the condition in the ACL, they are not | |
26652 | expanded until after it has failed. For example: | |
9b371988 | 26653 | .code |
168e428f PH |
26654 | deny hosts = !+local_networks |
26655 | message = $sender_host_address is listed \ | |
26656 | at $dnslist_domain | |
26657 | dnslists = rbl-plus.mail-abuse.example | |
9b371988 | 26658 | .endd |
168e428f PH |
26659 | |
26660 | ||
26661 | ||
9b371988 PH |
26662 | .section "Additional matching conditions for DNS lists" "SECTaddmatcon" |
26663 | .cindex "DNS list" "matching specific returned data" | |
26664 | You can add an equals sign and an IP address after a &%dnslists%& domain name | |
26665 | in order to restrict its action to DNS records with a matching right hand side. | |
168e428f | 26666 | For example, |
9b371988 PH |
26667 | .code |
26668 | deny dnslists = rblplus.mail-abuse.org=127.0.0.2 | |
26669 | .endd | |
168e428f | 26670 | rejects only those hosts that yield 127.0.0.2. Without this additional data, |
595028e4 | 26671 | any address record is considered to be a match. For the moment, we assume |
f89d2485 | 26672 | that the DNS lookup returns just one record. Section &<<SECThanmuldnsrec>>& |
595028e4 | 26673 | describes how multiple records are handled. |
168e428f PH |
26674 | |
26675 | More than one IP address may be given for checking, using a comma as a | |
9b371988 PH |
26676 | separator. These are alternatives &-- if any one of them matches, the |
26677 | &%dnslists%& condition is true. For example: | |
26678 | .code | |
26679 | deny dnslists = a.b.c=127.0.0.2,127.0.0.3 | |
26680 | .endd | |
168e428f PH |
26681 | If you want to specify a constraining address list and also specify names or IP |
26682 | addresses to be looked up, the constraining address list must be specified | |
26683 | first. For example: | |
9b371988 | 26684 | .code |
168e428f PH |
26685 | deny dnslists = dsn.rfc-ignorant.org\ |
26686 | =127.0.0.2/$sender_address_domain | |
9b371988 | 26687 | .endd |
168e428f | 26688 | |
9b371988 PH |
26689 | If the character &`&&`& is used instead of &`=`&, the comparison for each |
26690 | listed IP address is done by a bitwise &"and"& instead of by an equality test. | |
26691 | In other words, the listed addresses are used as bit masks. The comparison is | |
168e428f PH |
26692 | true if all the bits in the mask are present in the address that is being |
26693 | tested. For example: | |
9b371988 PH |
26694 | .code |
26695 | dnslists = a.b.c&0.0.0.3 | |
26696 | .endd | |
26697 | matches if the address is &'x.x.x.'&3, &'x.x.x.'&7, &'x.x.x.'&11, etc. If you | |
168e428f PH |
26698 | want to test whether one bit or another bit is present (as opposed to both |
26699 | being present), you must use multiple values. For example: | |
9b371988 PH |
26700 | .code |
26701 | dnslists = a.b.c&0.0.0.1,0.0.0.2 | |
26702 | .endd | |
168e428f PH |
26703 | matches if the final component of the address is an odd number or two times |
26704 | an odd number. | |
26705 | ||
26706 | ||
26707 | ||
f89d2485 | 26708 | .section "Negated DNS matching conditions" "SECID205" |
9b371988 | 26709 | You can supply a negative list of IP addresses as part of a &%dnslists%& |
168e428f | 26710 | condition. Whereas |
9b371988 PH |
26711 | .code |
26712 | deny dnslists = a.b.c=127.0.0.2,127.0.0.3 | |
26713 | .endd | |
26714 | means &"deny if the host is in the black list at the domain &'a.b.c'& and the | |
26715 | IP address yielded by the list is either 127.0.0.2 or 127.0.0.3"&, | |
26716 | .code | |
26717 | deny dnslists = a.b.c!=127.0.0.2,127.0.0.3 | |
26718 | .endd | |
26719 | means &"deny if the host is in the black list at the domain &'a.b.c'& and the | |
26720 | IP address yielded by the list is not 127.0.0.2 and not 127.0.0.3"&. In other | |
168e428f | 26721 | words, the result of the test is inverted if an exclamation mark appears before |
9b371988 | 26722 | the &`=`& (or the &`&&`&) sign. |
168e428f | 26723 | |
9b371988 | 26724 | &*Note*&: This kind of negation is not the same as negation in a domain, |
168e428f PH |
26725 | host, or address list (which is why the syntax is different). |
26726 | ||
26727 | If you are using just one list, the negation syntax does not gain you much. The | |
26728 | previous example is precisely equivalent to | |
9b371988 PH |
26729 | .code |
26730 | deny dnslists = a.b.c | |
26731 | !dnslists = a.b.c=127.0.0.2,127.0.0.3 | |
26732 | .endd | |
168e428f PH |
26733 | However, if you are using multiple lists, the negation syntax is clearer. |
26734 | Consider this example: | |
9b371988 | 26735 | .code |
168e428f PH |
26736 | deny dnslists = sbl.spamhaus.org : \ |
26737 | list.dsbl.org : \ | |
26738 | dnsbl.njabl.org!=127.0.0.3 : \ | |
26739 | relays.ordb.org | |
9b371988 | 26740 | .endd |
168e428f | 26741 | Using only positive lists, this would have to be: |
9b371988 | 26742 | .code |
168e428f PH |
26743 | deny dnslists = sbl.spamhaus.org : \ |
26744 | list.dsbl.org | |
26745 | deny dnslists = dnsbl.njabl.org | |
26746 | !dnslists = dnsbl.njabl.org=127.0.0.3 | |
26747 | deny dnslists = relays.ordb.org | |
9b371988 | 26748 | .endd |
168e428f PH |
26749 | which is less clear, and harder to maintain. |
26750 | ||
26751 | ||
f89d2485 PH |
26752 | |
26753 | ||
f89d2485 PH |
26754 | .section "Handling multiple DNS records from a DNS list" "SECThanmuldnsrec" |
26755 | A DNS lookup for a &%dnslists%& condition may return more than one DNS record, | |
26756 | thereby providing more than one IP address. When an item in a &%dnslists%& list | |
26757 | is followed by &`=`& or &`&&`& and a list of IP addresses, in order to restrict | |
26758 | the match to specific results from the DNS lookup, there are two ways in which | |
26759 | the checking can be handled. For example, consider the condition: | |
26760 | .code | |
26761 | dnslists = a.b.c=127.0.0.1 | |
26762 | .endd | |
26763 | What happens if the DNS lookup for the incoming IP address yields both | |
26764 | 127.0.0.1 and 127.0.0.2 by means of two separate DNS records? Is the | |
26765 | condition true because at least one given value was found, or is it false | |
26766 | because at least one of the found values was not listed? And how does this | |
26767 | affect negated conditions? Both possibilities are provided for with the help of | |
26768 | additional separators &`==`& and &`=&&`&. | |
26769 | ||
26770 | .ilist | |
26771 | If &`=`& or &`&&`& is used, the condition is true if any one of the looked up | |
26772 | IP addresses matches one of the listed addresses. For the example above, the | |
26773 | condition is true because 127.0.0.1 matches. | |
26774 | .next | |
26775 | If &`==`& or &`=&&`& is used, the condition is true only if every one of the | |
26776 | looked up IP addresses matches one of the listed addresses. If the condition is | |
26777 | changed to: | |
26778 | .code | |
26779 | dnslists = a.b.c==127.0.0.1 | |
26780 | .endd | |
26781 | and the DNS lookup yields both 127.0.0.1 and 127.0.0.2, the condition is | |
26782 | false because 127.0.0.2 is not listed. You would need to have: | |
26783 | .code | |
26784 | dnslists = a.b.c==127.0.0.1,127.0.0.2 | |
26785 | .endd | |
26786 | for the condition to be true. | |
26787 | .endlist | |
26788 | ||
26789 | When &`!`& is used to negate IP address matching, it inverts the result, giving | |
26790 | the precise opposite of the behaviour above. Thus: | |
26791 | .ilist | |
26792 | If &`!=`& or &`!&&`& is used, the condition is true if none of the looked up IP | |
26793 | addresses matches one of the listed addresses. Consider: | |
26794 | .code | |
26795 | dnslists = a.b.c!&0.0.0.1 | |
26796 | .endd | |
26797 | If the DNS lookup yields both 127.0.0.1 and 127.0.0.2, the condition is | |
26798 | false because 127.0.0.1 matches. | |
26799 | .next | |
26800 | If &`!==`& or &`!=&&`& is used, the condition is true there is at least one | |
26801 | looked up IP address that does not match. Consider: | |
26802 | .code | |
26803 | dnslists = a.b.c!=&0.0.0.1 | |
26804 | .endd | |
26805 | If the DNS lookup yields both 127.0.0.1 and 127.0.0.2, the condition is | |
26806 | true, because 127.0.0.2 does not match. You would need to have: | |
26807 | .code | |
26808 | dnslists = a.b.c!=&0.0.0.1,0.0.0.2 | |
26809 | .endd | |
26810 | for the condition to be false. | |
26811 | .endlist | |
26812 | When the DNS lookup yields only a single IP address, there is no difference | |
26813 | between &`=`& and &`==`& and between &`&&`& and &`=&&`&. | |
f89d2485 PH |
26814 | |
26815 | ||
26816 | ||
26817 | ||
3cb1b51e PH |
26818 | .section "Detailed information from merged DNS lists" "SECTmordetinf" |
26819 | .cindex "DNS list" "information from merged" | |
26820 | When the facility for restricting the matching IP values in a DNS list is used, | |
26821 | the text from the TXT record that is set in &$dnslist_text$& may not reflect | |
26822 | the true reason for rejection. This happens when lists are merged and the IP | |
26823 | address in the A record is used to distinguish them; unfortunately there is | |
26824 | only one TXT record. One way round this is not to use merged lists, but that | |
26825 | can be inefficient because it requires multiple DNS lookups where one would do | |
26826 | in the vast majority of cases when the host of interest is not on any of the | |
26827 | lists. | |
26828 | ||
26829 | A less inefficient way of solving this problem is available. If | |
26830 | two domain names, comma-separated, are given, the second is used first to | |
26831 | do an initial check, making use of any IP value restrictions that are set. | |
26832 | If there is a match, the first domain is used, without any IP value | |
26833 | restrictions, to get the TXT record. As a byproduct of this, there is also | |
26834 | a check that the IP being tested is indeed on the first list. The first | |
26835 | domain is the one that is put in &$dnslist_domain$&. For example: | |
26836 | .code | |
26837 | reject message = \ | |
f89d2485 | 26838 | rejected because $sender_host_address is blacklisted \ |
3cb1b51e PH |
26839 | at $dnslist_domain\n$dnslist_text |
26840 | dnslists = \ | |
26841 | sbl.spamhaus.org,sbl-xbl.spamhaus.org=127.0.0.2 : \ | |
26842 | dul.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.10 | |
26843 | .endd | |
26844 | For the first blacklist item, this starts by doing a lookup in | |
26845 | &'sbl-xbl.spamhaus.org'& and testing for a 127.0.0.2 return. If there is a | |
26846 | match, it then looks in &'sbl.spamhaus.org'&, without checking the return | |
26847 | value, and as long as something is found, it looks for the corresponding TXT | |
26848 | record. If there is no match in &'sbl-xbl.spamhaus.org'&, nothing more is done. | |
26849 | The second blacklist item is processed similarly. | |
26850 | ||
26851 | If you are interested in more than one merged list, the same list must be | |
26852 | given several times, but because the results of the DNS lookups are cached, | |
26853 | the DNS calls themselves are not repeated. For example: | |
26854 | .code | |
26855 | reject dnslists = \ | |
26856 | http.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.2 : \ | |
26857 | socks.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.3 : \ | |
26858 | misc.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.4 : \ | |
26859 | dul.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.10 | |
26860 | .endd | |
26861 | In this case there is one lookup in &'dnsbl.sorbs.net'&, and if none of the IP | |
26862 | values matches (or if no record is found), this is the only lookup that is | |
26863 | done. Only if there is a match is one of the more specific lists consulted. | |
3cb1b51e | 26864 | |
168e428f PH |
26865 | |
26866 | ||
9b371988 PH |
26867 | .section "DNS lists and IPv6" "SECTmorednslistslast" |
26868 | .cindex "IPv6" "DNS black lists" | |
26869 | .cindex "DNS list" "IPv6 usage" | |
168e428f PH |
26870 | If Exim is asked to do a dnslist lookup for an IPv6 address, it inverts it |
26871 | nibble by nibble. For example, if the calling host's IP address is | |
26872 | 3ffe:ffff:836f:0a00:000a:0800:200a:c031, Exim might look up | |
9b371988 PH |
26873 | .code |
26874 | 1.3.0.c.a.0.0.2.0.0.8.0.a.0.0.0.0.0.a.0.f.6.3.8. | |
26875 | f.f.f.f.e.f.f.3.blackholes.mail-abuse.org | |
26876 | .endd | |
168e428f PH |
26877 | (split over two lines here to fit on the page). Unfortunately, some of the DNS |
26878 | lists contain wildcard records, intended for IPv4, that interact badly with | |
26879 | IPv6. For example, the DNS entry | |
9b371988 PH |
26880 | .code |
26881 | *.3.some.list.example. A 127.0.0.1 | |
26882 | .endd | |
168e428f PH |
26883 | is probably intended to put the entire 3.0.0.0/8 IPv4 network on the list. |
26884 | Unfortunately, it also matches the entire 3::/4 IPv6 network. | |
26885 | ||
26886 | You can exclude IPv6 addresses from DNS lookups by making use of a suitable | |
9b371988 PH |
26887 | &%condition%& condition, as in this example: |
26888 | .code | |
26889 | deny condition = ${if isip4{$sender_host_address}} | |
26890 | dnslists = some.list.example | |
26891 | .endd | |
26892 | ||
595028e4 | 26893 | .section "Rate limiting incoming messages" "SECTratelimiting" |
9b371988 PH |
26894 | .cindex "rate limiting" "client sending" |
26895 | .cindex "limiting client sending rates" | |
3cb1b51e | 26896 | .oindex "&%smtp_ratelimit_*%&" |
9b371988 PH |
26897 | The &%ratelimit%& ACL condition can be used to measure and control the rate at |
26898 | which clients can send email. This is more powerful than the | |
26899 | &%smtp_ratelimit_*%& options, because those options control the rate of | |
26900 | commands in a single SMTP session only, whereas the &%ratelimit%& condition | |
26901 | works across all connections (concurrent and sequential) from the same client | |
26902 | host. The syntax of the &%ratelimit%& condition is: | |
26903 | .display | |
26904 | &`ratelimit =`& <&'m'&> &`/`& <&'p'&> &`/`& <&'options'&> &`/`& <&'key'&> | |
26905 | .endd | |
26906 | If the average client sending rate is less than &'m'& messages per time | |
26907 | period &'p'& then the condition is false; otherwise it is true. | |
26908 | ||
9b371988 PH |
26909 | As a side-effect, the &%ratelimit%& condition sets the expansion variable |
26910 | &$sender_rate$& to the client's computed rate, &$sender_rate_limit$& to the | |
26911 | configured value of &'m'&, and &$sender_rate_period$& to the configured value | |
26912 | of &'p'&. | |
26913 | ||
26914 | The parameter &'p'& is the smoothing time constant, in the form of an Exim | |
26915 | time interval, for example, &`8h`& for eight hours. A larger time constant | |
26916 | means that it takes Exim longer to forget a client's past behaviour. The | |
26917 | parameter &'m'& is the maximum number of messages that a client is permitted to | |
26918 | send in each time interval. It also specifies the number of messages permitted | |
26919 | in a fast burst. By increasing both &'m'& and &'p'& but keeping &'m/p'& | |
26920 | constant, you can allow a client to send more messages in a burst without | |
c6ac190c | 26921 | changing its long-term sending rate limit. Conversely, if &'m'& and &'p'& are |
9b371988 PH |
26922 | both small, messages must be sent at an even rate. |
26923 | ||
26924 | There is a script in &_util/ratelimit.pl_& which extracts sending rates from | |
26925 | log files, to assist with choosing appropriate settings for &'m'& and &'p'& | |
26926 | when deploying the &%ratelimit%& ACL condition. The script prints usage | |
26927 | instructions when it is run with no arguments. | |
26928 | ||
068aaea8 | 26929 | The key is used to look up the data for calculating the client's average |
c6ac190c TF |
26930 | sending rate. This data is stored in Exim's spool directory, alongside the |
26931 | retry and other hints databases. The default key is &$sender_host_address$&, | |
26932 | which means Exim computes the sending rate of each client host IP address. | |
9b371988 PH |
26933 | By changing the key you can change how Exim identifies clients for the purpose |
26934 | of ratelimiting. For example, to limit the sending rate of each authenticated | |
26935 | user, independent of the computer they are sending from, set the key to | |
26936 | &$authenticated_id$&. You must ensure that the lookup key is meaningful; for | |
26937 | example, &$authenticated_id$& is only meaningful if the client has | |
c6ac190c | 26938 | authenticated (which you can check with the &%authenticated%& ACL condition). |
9b371988 | 26939 | |
c6ac190c TF |
26940 | The lookup key does not have to identify clients: If you want to limit the |
26941 | rate at which a recipient receives messages, you can use the key | |
26942 | &`$local_part@$domain`& with the &%per_rcpt%& option (see below) in a RCPT | |
26943 | ACL. | |
595028e4 | 26944 | |
c6ac190c | 26945 | Internally, Exim appends the smoothing constant &'p'& and the options onto the |
068aaea8 | 26946 | lookup key because they alter the meaning of the stored data. This is not true |
9b371988 | 26947 | for the limit &'m'&, so you can alter the configured maximum rate and Exim will |
068aaea8 PH |
26948 | still remember clients' past behaviour, but if you alter the other ratelimit |
26949 | parameters Exim forgets past behaviour. | |
26950 | ||
595028e4 | 26951 | Each &%ratelimit%& condition can have up to three options. One option |
068aaea8 | 26952 | specifies what Exim measures the rate of, and the second specifies how Exim |
595028e4 PH |
26953 | handles excessively fast clients. The third option can be &`noupdate`&, to |
26954 | disable updating of the ratelimiting database (see section &<<rearatdat>>&). | |
26955 | The options are separated by a slash, like the other parameters. They may | |
26956 | appear in any order. | |
068aaea8 | 26957 | |
595028e4 | 26958 | .section "Ratelimit options for what is being measured" "ratoptmea" |
9b371988 PH |
26959 | The &%per_conn%& option limits the client's connection rate. |
26960 | ||
26961 | The &%per_mail%& option limits the client's rate of sending messages. This is | |
26962 | the default if none of the &%per_*%& options is specified. | |
068aaea8 | 26963 | |
9b371988 PH |
26964 | The &%per_byte%& option limits the sender's email bandwidth. Note that it is |
26965 | best to use this option in the DATA ACL; if it is used in an earlier ACL it | |
c6ac190c TF |
26966 | relies on the SIZE parameter specified by the client in its MAIL command, |
26967 | which may be inaccurate or completely missing. You can follow the limit &'m'& | |
26968 | in the configuration with K, M, or G to specify limits in kilobytes, | |
26969 | megabytes, or gigabytes, respectively. | |
068aaea8 | 26970 | |
a843aaa6 NM |
26971 | The &%per_rcpt%& option causes Exim to limit the rate at which |
26972 | recipients are accepted. To be effective, it would need to be used in | |
26973 | either the &%acl_smtp_rcpt%& or the &%acl_not_smtp%& ACL. In the | |
26974 | &%acl_smtp_rcpt%& ACL, the number of recipients is incremented by one. | |
26975 | In the case of a locally submitted message in the &%acl_not_smtp%& ACL, | |
c6ac190c | 26976 | the number of recipients is incremented by the &%$recipients_count%& |
a843aaa6 NM |
26977 | for the entire message. Note that in either case the rate limiting |
26978 | engine will see a message with many recipients as a large high-speed | |
26979 | burst. | |
26980 | ||
9b371988 | 26981 | The &%per_cmd%& option causes Exim to recompute the rate every time the |
a843aaa6 NM |
26982 | condition is processed. This can be used to limit the SMTP command rate. |
26983 | This command is essentially an alias of &%per_rcpt%& to make it clear | |
26984 | that the effect is to limit the rate at which individual commands, | |
26985 | rather than recipients, are accepted. | |
068aaea8 | 26986 | |
595028e4 | 26987 | .section "Ratelimit options for handling fast clients" "ratophanfas" |
068aaea8 PH |
26988 | If a client's average rate is greater than the maximum, the rate limiting |
26989 | engine can react in two possible ways, depending on the presence of the | |
9b371988 PH |
26990 | &%strict%& or &%leaky%& options. This is independent of the other |
26991 | counter-measures (such as rejecting the message) that may be specified by the | |
26992 | rest of the ACL. The default mode is leaky, which avoids a sender's | |
26993 | over-aggressive retry rate preventing it from getting any email through. | |
068aaea8 | 26994 | |
c6ac190c TF |
26995 | The &%strict%& option means that the client's recorded rate is always |
26996 | updated. The effect of this is that Exim measures the client's average rate | |
26997 | of attempts to send email, which can be much higher than the maximum it is | |
26998 | actually allowed. If the client is over the limit it may be subjected to | |
26999 | counter-measures by the ACL until it slows down below the maximum rate. If | |
27000 | the client stops attempting to send email for the time specified in the &'p'& | |
27001 | parameter then its computed rate will decay exponentially to 37% of its peak | |
27002 | value. You can work out the time (the number of smoothing periods) that a | |
27003 | client is subjected to counter-measures after an over-limit burst with this | |
27004 | formula: | |
9b371988 | 27005 | .code |
9e6d33da | 27006 | ln(peakrate/maxrate) |
9b371988 | 27007 | .endd |
595028e4 PH |
27008 | The &%leaky%& (default) option means that the client's recorded rate is not |
27009 | updated if it is above the limit. The effect of this is that Exim measures the | |
27010 | client's average rate of successfully sent email, which cannot be greater than | |
27011 | the maximum allowed. If the client is over the limit it may suffer some | |
f89d2485 | 27012 | counter-measures (as specified in the ACL), but it will still be able to send |
3cb1b51e PH |
27013 | email at the configured maximum rate, whatever the rate of its attempts. This |
27014 | is generally the better choice if you have clients that retry automatically. | |
068aaea8 | 27015 | |
595028e4 | 27016 | .section "Using rate limiting" "useratlim" |
068aaea8 PH |
27017 | Exim's other ACL facilities are used to define what counter-measures are taken |
27018 | when the rate limit is exceeded. This might be anything from logging a warning | |
27019 | (for example, while measuring existing sending rates in order to define | |
27020 | policy), through time delays to slow down fast senders, up to rejecting the | |
27021 | message. For example: | |
9b371988 | 27022 | .code |
068aaea8 | 27023 | # Log all senders' rates |
db9452a9 PH |
27024 | warn ratelimit = 0 / 1h / strict |
27025 | log_message = Sender rate $sender_rate / $sender_rate_period | |
068aaea8 | 27026 | |
4f578862 PH |
27027 | # Slow down fast senders; note the need to truncate $sender_rate |
27028 | # at the decimal point. | |
db9452a9 PH |
27029 | warn ratelimit = 100 / 1h / per_rcpt / strict |
27030 | delay = ${eval: ${sg{$sender_rate}{[.].*}{}} - \ | |
27031 | $sender_rate_limit }s | |
068aaea8 PH |
27032 | |
27033 | # Keep authenticated users under control | |
db9452a9 PH |
27034 | deny authenticated = * |
27035 | ratelimit = 100 / 1d / strict / $authenticated_id | |
068aaea8 PH |
27036 | |
27037 | # System-wide rate limit | |
db9452a9 PH |
27038 | defer message = Sorry, too busy. Try again later. |
27039 | ratelimit = 10 / 1s / $primary_hostname | |
068aaea8 PH |
27040 | |
27041 | # Restrict incoming rate from each host, with a default | |
27042 | # set using a macro and special cases looked up in a table. | |
db9452a9 PH |
27043 | defer message = Sender rate exceeds $sender_rate_limit \ |
27044 | messages per $sender_rate_period | |
27045 | ratelimit = ${lookup {$sender_host_address} \ | |
27046 | cdb {DB/ratelimits.cdb} \ | |
27047 | {$value} {RATELIMIT} } | |
9b371988 PH |
27048 | .endd |
27049 | &*Warning*&: If you have a busy server with a lot of &%ratelimit%& tests, | |
27050 | especially with the &%per_rcpt%& option, you may suffer from a performance | |
068aaea8 PH |
27051 | bottleneck caused by locking on the ratelimit hints database. Apart from |
27052 | making your ACLs less complicated, you can reduce the problem by using a | |
9b371988 | 27053 | RAM disk for Exim's hints directory (usually &_/var/spool/exim/db/_&). However |
068aaea8 PH |
27054 | this means that Exim will lose its hints data after a reboot (including retry |
27055 | hints, the callout cache, and ratelimit data). | |
9b371988 PH |
27056 | |
27057 | ||
595028e4 PH |
27058 | .section "Reading ratelimit data without updating" "rearatdat" |
27059 | .cindex "rate limitint" "reading data without updating" | |
27060 | If the &%noupdate%& option is present on a &%ratelimit%& ACL condition, Exim | |
27061 | computes the rate and checks the limit as normal, but it does not update the | |
27062 | saved data. This means that, in relevant ACLs, it is possible to lookup the | |
27063 | existence of a specified (or auto-generated) ratelimit key without incrementing | |
27064 | the ratelimit counter for that key. In order for this to be useful, another ACL | |
27065 | entry must set the rate for the same key (otherwise it will always be zero). | |
27066 | For example: | |
27067 | .code | |
27068 | acl_check_connect: | |
f4cd9433 | 27069 | deny ratelimit = 100 / 5m / strict / per_cmd / noupdate |
595028e4 PH |
27070 | log_message = RATE: $sender_rate/$sender_rate_period \ |
27071 | (max $sender_rate_limit) | |
27072 | .endd | |
27073 | .display | |
27074 | &'... some other logic and tests...'& | |
27075 | .endd | |
27076 | .code | |
27077 | acl_check_mail: | |
27078 | warn ratelimit = 100 / 5m / strict / per_cmd | |
27079 | condition = ${if le{$sender_rate}{$sender_rate_limit}} | |
27080 | logwrite = RATE UPDATE: $sender_rate/$sender_rate_period \ | |
27081 | (max $sender_rate_limit) | |
27082 | .endd | |
27083 | In this example, the rate is tested and used to deny access (when it is too | |
27084 | high) in the connect ACL, but the actual computation of the remembered rate | |
27085 | happens later, on a per-command basis, in another ACL. | |
595028e4 PH |
27086 | |
27087 | ||
27088 | ||
9b371988 PH |
27089 | .section "Address verification" "SECTaddressverification" |
27090 | .cindex "verifying address" "options for" | |
27091 | .cindex "policy control" "address verification" | |
27092 | Several of the &%verify%& conditions described in section | |
3cb1b51e PH |
27093 | &<<SECTaclconditions>>& cause addresses to be verified. Section |
27094 | &<<SECTsenaddver>>& discusses the reporting of sender verification failures. | |
27095 | The verification conditions can be followed by options that modify the | |
27096 | verification process. The options are separated from the keyword and from each | |
27097 | other by slashes, and some of them contain parameters. For example: | |
9b371988 PH |
27098 | .code |
27099 | verify = sender/callout | |
27100 | verify = recipient/defer_ok/callout=10s,defer_ok | |
27101 | .endd | |
168e428f | 27102 | The first stage of address verification, which always happens, is to run the |
9b371988 | 27103 | address through the routers, in &"verify mode"&. Routers can detect the |
168e428f | 27104 | difference between verification and routing for delivery, and their actions can |
9b371988 PH |
27105 | be varied by a number of generic options such as &%verify%& and &%verify_only%& |
27106 | (see chapter &<<CHAProutergeneric>>&). If routing fails, verification fails. | |
168e428f PH |
27107 | The available options are as follows: |
27108 | ||
9b371988 PH |
27109 | .ilist |
27110 | If the &%callout%& option is specified, successful routing to one or more | |
27111 | remote hosts is followed by a &"callout"& to those hosts as an additional | |
27112 | check. Callouts and their sub-options are discussed in the next section. | |
27113 | .next | |
27114 | If there is a defer error while doing verification routing, the ACL | |
27115 | normally returns &"defer"&. However, if you include &%defer_ok%& in the | |
27116 | options, the condition is forced to be true instead. Note that this is a main | |
168e428f | 27117 | verification option as well as a suboption for callouts. |
9b371988 PH |
27118 | .next |
27119 | The &%no_details%& option is covered in section &<<SECTsenaddver>>&, which | |
068aaea8 | 27120 | discusses the reporting of sender address verification failures. |
9b371988 | 27121 | .next |
9b371988 | 27122 | The &%success_on_redirect%& option causes verification always to succeed |
068aaea8 PH |
27123 | immediately after a successful redirection. By default, if a redirection |
27124 | generates just one address, that address is also verified. See further | |
9b371988 PH |
27125 | discussion in section &<<SECTredirwhilveri>>&. |
27126 | .endlist | |
27127 | ||
27128 | .cindex "verifying address" "differentiating failures" | |
f89d2485 PH |
27129 | .vindex "&$recipient_verify_failure$&" |
27130 | .vindex "&$sender_verify_failure$&" | |
27131 | .vindex "&$acl_verify_message$&" | |
9b371988 PH |
27132 | After an address verification failure, &$acl_verify_message$& contains the |
27133 | error message that is associated with the failure. It can be preserved by | |
27134 | coding like this: | |
27135 | .code | |
27136 | warn !verify = sender | |
27137 | set acl_m0 = $acl_verify_message | |
27138 | .endd | |
068aaea8 PH |
27139 | If you are writing your own custom rejection message or log message when |
27140 | denying access, you can use this variable to include information about the | |
27141 | verification failure. | |
27142 | ||
9b371988 | 27143 | In addition, &$sender_verify_failure$& or &$recipient_verify_failure$& (as |
068aaea8 | 27144 | appropriate) contains one of the following words: |
168e428f | 27145 | |
9b371988 PH |
27146 | .ilist |
27147 | &%qualify%&: The address was unqualified (no domain), and the message | |
168e428f | 27148 | was neither local nor came from an exempted host. |
9b371988 PH |
27149 | .next |
27150 | &%route%&: Routing failed. | |
27151 | .next | |
27152 | &%mail%&: Routing succeeded, and a callout was attempted; rejection | |
168e428f PH |
27153 | occurred at or before the MAIL command (that is, on initial |
27154 | connection, HELO, or MAIL). | |
9b371988 PH |
27155 | .next |
27156 | &%recipient%&: The RCPT command in a callout was rejected. | |
27157 | .next | |
27158 | &%postmaster%&: The postmaster check in a callout was rejected. | |
27159 | .endlist | |
168e428f | 27160 | |
168e428f PH |
27161 | The main use of these variables is expected to be to distinguish between |
27162 | rejections of MAIL and rejections of RCPT in callouts. | |
27163 | ||
27164 | ||
27165 | ||
27166 | ||
9b371988 PH |
27167 | .section "Callout verification" "SECTcallver" |
27168 | .cindex "verifying address" "by callout" | |
27169 | .cindex "callout" "verification" | |
27170 | .cindex "SMTP" "callout verification" | |
168e428f PH |
27171 | For non-local addresses, routing verifies the domain, but is unable to do any |
27172 | checking of the local part. There are situations where some means of verifying | |
27173 | the local part is desirable. One way this can be done is to make an SMTP | |
9b371988 PH |
27174 | &'callback'& to a delivery host for the sender address or a &'callforward'& to |
27175 | a subsequent host for a recipient address, to see if the host accepts the | |
27176 | address. We use the term &'callout'& to cover both cases. Note that for a | |
27177 | sender address, the callback is not to the client host that is trying to | |
27178 | deliver the message, but to one of the hosts that accepts incoming mail for the | |
27179 | sender's domain. | |
068aaea8 | 27180 | |
068aaea8 | 27181 | Exim does not do callouts by default. If you want them to happen, you must |
9b371988 | 27182 | request them by setting appropriate options on the &%verify%& condition, as |
068aaea8 PH |
27183 | described below. This facility should be used with care, because it can add a |
27184 | lot of resource usage to the cost of verifying an address. However, Exim does | |
27185 | cache the results of callouts, which helps to reduce the cost. Details of | |
9b371988 | 27186 | caching are in section &<<SECTcallvercache>>&. |
168e428f PH |
27187 | |
27188 | Recipient callouts are usually used only between hosts that are controlled by | |
27189 | the same administration. For example, a corporate gateway host could use | |
068aaea8 PH |
27190 | callouts to check for valid recipients on an internal mailserver. A successful |
27191 | callout does not guarantee that a real delivery to the address would succeed; | |
27192 | on the other hand, a failing callout does guarantee that a delivery would fail. | |
168e428f | 27193 | |
9b371988 | 27194 | If the &%callout%& option is present on a condition that verifies an address, a |
168e428f | 27195 | second stage of verification occurs if the address is successfully routed to |
9b371988 PH |
27196 | one or more remote hosts. The usual case is routing by a &(dnslookup)& or a |
27197 | &(manualroute)& router, where the router specifies the hosts. However, if a | |
27198 | router that does not set up hosts routes to an &(smtp)& transport with a | |
27199 | &%hosts%& setting, the transport's hosts are used. If an &(smtp)& transport has | |
27200 | &%hosts_override%& set, its hosts are always used, whether or not the router | |
168e428f PH |
27201 | supplies a host list. |
27202 | ||
27203 | The port that is used is taken from the transport, if it is specified and is a | |
27204 | remote transport. (For routers that do verification only, no transport need be | |
27205 | specified.) Otherwise, the default SMTP port is used. If a remote transport | |
27206 | specifies an outgoing interface, this is used; otherwise the interface is not | |
3cb1b51e PH |
27207 | specified. Likewise, the text that is used for the HELO command is taken from |
27208 | the transport's &%helo_data%& option; if there is no transport, the value of | |
27209 | &$smtp_active_hostname$& is used. | |
168e428f PH |
27210 | |
27211 | For a sender callout check, Exim makes SMTP connections to the remote hosts, to | |
27212 | test whether a bounce message could be delivered to the sender address. The | |
27213 | following SMTP commands are sent: | |
9b371988 | 27214 | .display |
3cb1b51e | 27215 | &`HELO `&<&'local host name'&> |
9b371988 PH |
27216 | &`MAIL FROM:<>`& |
27217 | &`RCPT TO:`&<&'the address to be tested'&> | |
27218 | &`QUIT`& | |
27219 | .endd | |
27220 | LHLO is used instead of HELO if the transport's &%protocol%& option is | |
27221 | set to &"lmtp"&. | |
168e428f PH |
27222 | |
27223 | A recipient callout check is similar. By default, it also uses an empty address | |
27224 | for the sender. This default is chosen because most hosts do not make use of | |
27225 | the sender address when verifying a recipient. Using the same address means | |
27226 | that a single cache entry can be used for each recipient. Some sites, however, | |
27227 | do make use of the sender address when verifying. These are catered for by the | |
9b371988 | 27228 | &%use_sender%& and &%use_postmaster%& options, described in the next section. |
168e428f | 27229 | |
9b371988 PH |
27230 | If the response to the RCPT command is a 2&'xx'& code, the verification |
27231 | succeeds. If it is 5&'xx'&, the verification fails. For any other condition, | |
168e428f | 27232 | Exim tries the next host, if any. If there is a problem with all the remote |
9b371988 PH |
27233 | hosts, the ACL yields &"defer"&, unless the &%defer_ok%& parameter of the |
27234 | &%callout%& option is given, in which case the condition is forced to succeed. | |
168e428f | 27235 | |
f89d2485 PH |
27236 | .cindex "SMTP" "output flushing, disabling for callout" |
27237 | A callout may take a little time. For this reason, Exim normally flushes SMTP | |
27238 | output before performing a callout in an ACL, to avoid unexpected timeouts in | |
27239 | clients when the SMTP PIPELINING extension is in use. The flushing can be | |
27240 | disabled by using a &%control%& modifier to set &%no_callout_flush%&. | |
168e428f PH |
27241 | |
27242 | ||
27243 | ||
168e428f | 27244 | |
9b371988 PH |
27245 | .section "Additional parameters for callouts" "CALLaddparcall" |
27246 | .cindex "callout" "additional parameters for" | |
27247 | The &%callout%& option can be followed by an equals sign and a number of | |
27248 | optional parameters, separated by commas. For example: | |
27249 | .code | |
27250 | verify = recipient/callout=10s,defer_ok | |
27251 | .endd | |
27252 | The old syntax, which had &%callout_defer_ok%& and &%check_postmaster%& as | |
168e428f | 27253 | separate verify options, is retained for backwards compatibility, but is now |
9b371988 | 27254 | deprecated. The additional parameters for &%callout%& are as follows: |
168e428f PH |
27255 | |
27256 | ||
9b371988 PH |
27257 | .vlist |
27258 | .vitem <&'a&~time&~interval'&> | |
f89d2485 | 27259 | .cindex "callout" "timeout, specifying" |
168e428f PH |
27260 | This specifies the timeout that applies for the callout attempt to each host. |
27261 | For example: | |
9b371988 PH |
27262 | .code |
27263 | verify = sender/callout=5s | |
27264 | .endd | |
168e428f | 27265 | The default is 30 seconds. The timeout is used for each response from the |
f89d2485 | 27266 | remote host. It is also used for the initial connection, unless overridden by |
9b371988 | 27267 | the &%connect%& parameter. |
168e428f PH |
27268 | |
27269 | ||
9b371988 | 27270 | .vitem &*connect&~=&~*&<&'time&~interval'&> |
f89d2485 | 27271 | .cindex "callout" "connection timeout, specifying" |
168e428f PH |
27272 | This parameter makes it possible to set a different (usually smaller) timeout |
27273 | for making the SMTP connection. For example: | |
9b371988 PH |
27274 | .code |
27275 | verify = sender/callout=5s,connect=1s | |
27276 | .endd | |
168e428f PH |
27277 | If not specified, this timeout defaults to the general timeout value. |
27278 | ||
9b371988 | 27279 | .vitem &*defer_ok*& |
f89d2485 | 27280 | .cindex "callout" "defer, action on" |
168e428f PH |
27281 | When this parameter is present, failure to contact any host, or any other kind |
27282 | of temporary error, is treated as success by the ACL. However, the cache is not | |
27283 | updated in this circumstance. | |
27284 | ||
9b371988 PH |
27285 | .vitem &*fullpostmaster*& |
27286 | .cindex "callout" "full postmaster check" | |
27287 | This operates like the &%postmaster%& option (see below), but if the check for | |
27288 | &'postmaster@domain'& fails, it tries just &'postmaster'&, without a domain, in | |
068aaea8 | 27289 | accordance with the specification in RFC 2821. The RFC states that the |
9b371988 | 27290 | unqualified address &'postmaster'& should be accepted. |
9b371988 PH |
27291 | |
27292 | ||
27293 | .vitem &*mailfrom&~=&~*&<&'email&~address'&> | |
27294 | .cindex "callout" "sender when verifying header" | |
27295 | When verifying addresses in header lines using the &%header_sender%& | |
27296 | verification option, Exim behaves by default as if the addresses are envelope | |
27297 | sender addresses from a message. Callout verification therefore tests to see | |
27298 | whether a bounce message could be delivered, by using an empty address in the | |
27299 | MAIL command. However, it is arguable that these addresses might never be used | |
27300 | as envelope senders, and could therefore justifiably reject bounce messages | |
27301 | (empty senders). The &%mailfrom%& callout parameter allows you to specify what | |
27302 | address to use in the MAIL command. For example: | |
27303 | .code | |
27304 | require verify = header_sender/callout=mailfrom=abcd@x.y.z | |
27305 | .endd | |
27306 | This parameter is available only for the &%header_sender%& verification option. | |
27307 | ||
27308 | ||
27309 | .vitem &*maxwait&~=&~*&<&'time&~interval'&> | |
f89d2485 | 27310 | .cindex "callout" "overall timeout, specifying" |
168e428f PH |
27311 | This parameter sets an overall timeout for performing a callout verification. |
27312 | For example: | |
9b371988 PH |
27313 | .code |
27314 | verify = sender/callout=5s,maxwait=30s | |
27315 | .endd | |
168e428f PH |
27316 | This timeout defaults to four times the callout timeout for individual SMTP |
27317 | commands. The overall timeout applies when there is more than one host that can | |
27318 | be tried. The timeout is checked before trying the next host. This prevents | |
27319 | very long delays if there are a large number of hosts and all are timing out | |
27320 | (for example, when network connections are timing out). | |
27321 | ||
27322 | ||
9b371988 | 27323 | .vitem &*no_cache*& |
f89d2485 PH |
27324 | .cindex "callout" "cache, suppressing" |
27325 | .cindex "caching callout, suppressing" | |
168e428f PH |
27326 | When this parameter is given, the callout cache is neither read nor updated. |
27327 | ||
9b371988 PH |
27328 | .vitem &*postmaster*& |
27329 | .cindex "callout" "postmaster; checking" | |
f89d2485 | 27330 | When this parameter is set, a successful callout check is followed by a similar |
9b371988 PH |
27331 | check for the local part &'postmaster'& at the same domain. If this address is |
27332 | rejected, the callout fails (but see &%fullpostmaster%& above). The result of | |
27333 | the postmaster check is recorded in a cache record; if it is a failure, this is | |
068aaea8 PH |
27334 | used to fail subsequent callouts for the domain without a connection being |
27335 | made, until the cache record expires. | |
168e428f | 27336 | |
9b371988 | 27337 | .vitem &*postmaster_mailfrom&~=&~*&<&'email&~address'&> |
168e428f PH |
27338 | The postmaster check uses an empty sender in the MAIL command by default. |
27339 | You can use this parameter to do a postmaster check using a different address. | |
27340 | For example: | |
9b371988 PH |
27341 | .code |
27342 | require verify = sender/callout=postmaster_mailfrom=abc@x.y.z | |
27343 | .endd | |
27344 | If both &%postmaster%& and &%postmaster_mailfrom%& are present, the rightmost | |
27345 | one overrides. The &%postmaster%& parameter is equivalent to this example: | |
27346 | .code | |
27347 | require verify = sender/callout=postmaster_mailfrom= | |
27348 | .endd | |
27349 | &*Warning*&: The caching arrangements for postmaster checking do not take | |
168e428f PH |
27350 | account of the sender address. It is assumed that either the empty address or |
27351 | a fixed non-empty address will be used. All that Exim remembers is that the | |
27352 | postmaster check for the domain succeeded or failed. | |
27353 | ||
27354 | ||
9b371988 PH |
27355 | .vitem &*random*& |
27356 | .cindex "callout" "&""random""& check" | |
168e428f | 27357 | When this parameter is set, before doing the normal callout check, Exim does a |
9b371988 PH |
27358 | check for a &"random"& local part at the same domain. The local part is not |
27359 | really random &-- it is defined by the expansion of the option | |
27360 | &%callout_random_local_part%&, which defaults to | |
27361 | .code | |
27362 | $primary_host_name-$tod_epoch-testing | |
27363 | .endd | |
168e428f PH |
27364 | The idea here is to try to determine whether the remote host accepts all local |
27365 | parts without checking. If it does, there is no point in doing callouts for | |
9b371988 | 27366 | specific local parts. If the &"random"& check succeeds, the result is saved in |
168e428f PH |
27367 | a cache record, and used to force the current and subsequent callout checks to |
27368 | succeed without a connection being made, until the cache record expires. | |
27369 | ||
9b371988 PH |
27370 | .vitem &*use_postmaster*& |
27371 | .cindex "callout" "sender for recipient check" | |
168e428f | 27372 | This parameter applies to recipient callouts only. For example: |
9b371988 PH |
27373 | .code |
27374 | deny !verify = recipient/callout=use_postmaster | |
27375 | .endd | |
f89d2485 | 27376 | .vindex "&$qualify_domain$&" |
068aaea8 | 27377 | It causes a non-empty postmaster address to be used in the MAIL command when |
9b371988 PH |
27378 | performing the callout for the recipient, and also for a &"random"& check if |
27379 | that is configured. The local part of the address is &`postmaster`& and the | |
27380 | domain is the contents of &$qualify_domain$&. | |
168e428f | 27381 | |
9b371988 | 27382 | .vitem &*use_sender*& |
168e428f | 27383 | This option applies to recipient callouts only. For example: |
9b371988 PH |
27384 | .code |
27385 | require verify = recipient/callout=use_sender | |
27386 | .endd | |
168e428f PH |
27387 | It causes the message's actual sender address to be used in the MAIL |
27388 | command when performing the callout, instead of an empty address. There is no | |
27389 | need to use this option unless you know that the called hosts make use of the | |
27390 | sender when checking recipients. If used indiscriminately, it reduces the | |
27391 | usefulness of callout caching. | |
9b371988 | 27392 | .endlist |
168e428f PH |
27393 | |
27394 | If you use any of the parameters that set a non-empty sender for the MAIL | |
9b371988 PH |
27395 | command (&%mailfrom%&, &%postmaster_mailfrom%&, &%use_postmaster%&, or |
27396 | &%use_sender%&), you should think about possible loops. Recipient checking is | |
168e428f PH |
27397 | usually done between two hosts that are under the same management, and the host |
27398 | that receives the callouts is not normally configured to do callouts itself. | |
9b371988 | 27399 | Therefore, it is normally safe to use &%use_postmaster%& or &%use_sender%& in |
168e428f PH |
27400 | these circumstances. |
27401 | ||
27402 | However, if you use a non-empty sender address for a callout to an arbitrary | |
27403 | host, there is the likelihood that the remote host will itself initiate a | |
27404 | callout check back to your host. As it is checking what appears to be a message | |
27405 | sender, it is likely to use an empty address in MAIL, thus avoiding a | |
27406 | callout loop. However, to be on the safe side it would be best to set up your | |
27407 | own ACLs so that they do not do sender verification checks when the recipient | |
27408 | is the address you use for header sender or postmaster callout checking. | |
27409 | ||
27410 | Another issue to think about when using non-empty senders for callouts is | |
9b371988 PH |
27411 | caching. When you set &%mailfrom%& or &%use_sender%&, the cache record is keyed |
27412 | by the sender/recipient combination; thus, for any given recipient, many more | |
168e428f PH |
27413 | actual callouts are performed than when an empty sender or postmaster is used. |
27414 | ||
27415 | ||
27416 | ||
27417 | ||
9b371988 PH |
27418 | .section "Callout caching" "SECTcallvercache" |
27419 | .cindex "hints database" "callout cache" | |
f89d2485 | 27420 | .cindex "callout" "cache, description of" |
9b371988 | 27421 | .cindex "caching" "callout" |
168e428f | 27422 | Exim caches the results of callouts in order to reduce the amount of resources |
9b371988 PH |
27423 | used, unless you specify the &%no_cache%& parameter with the &%callout%& |
27424 | option. A hints database called &"callout"& is used for the cache. Two | |
27425 | different record types are used: one records the result of a callout check for | |
27426 | a specific address, and the other records information that applies to the | |
27427 | entire domain (for example, that it accepts the local part &'postmaster'&). | |
168e428f PH |
27428 | |
27429 | When an original callout fails, a detailed SMTP error message is given about | |
27430 | the failure. However, for subsequent failures use the cache data, this message | |
27431 | is not available. | |
27432 | ||
27433 | The expiry times for negative and positive address cache records are | |
9b371988 PH |
27434 | independent, and can be set by the global options &%callout_negative_expire%& |
27435 | (default 2h) and &%callout_positive_expire%& (default 24h), respectively. | |
168e428f PH |
27436 | |
27437 | If a host gives a negative response to an SMTP connection, or rejects any | |
27438 | commands up to and including | |
9b371988 PH |
27439 | .code |
27440 | MAIL FROM:<> | |
27441 | .endd | |
168e428f PH |
27442 | (but not including the MAIL command with a non-empty address), |
27443 | any callout attempt is bound to fail. Exim remembers such failures in a | |
27444 | domain cache record, which it uses to fail callouts for the domain without | |
27445 | making new connections, until the domain record times out. There are two | |
27446 | separate expiry times for domain cache records: | |
9b371988 PH |
27447 | &%callout_domain_negative_expire%& (default 3h) and |
27448 | &%callout_domain_positive_expire%& (default 7d). | |
168e428f PH |
27449 | |
27450 | Domain records expire when the negative expiry time is reached if callouts | |
27451 | cannot be made for the domain, or if the postmaster check failed. | |
27452 | Otherwise, they expire when the positive expiry time is reached. This | |
9b371988 | 27453 | ensures that, for example, a host that stops accepting &"random"& local parts |
168e428f PH |
27454 | will eventually be noticed. |
27455 | ||
27456 | The callout caching mechanism is based on the domain of the address that is | |
27457 | being tested. If the domain routes to several hosts, it is assumed that their | |
27458 | behaviour will be the same. | |
27459 | ||
27460 | ||
27461 | ||
9b371988 PH |
27462 | .section "Sender address verification reporting" "SECTsenaddver" |
27463 | .cindex "verifying" "suppressing error details" | |
3cb1b51e PH |
27464 | See section &<<SECTaddressverification>>& for a general discussion of |
27465 | verification. When sender verification fails in an ACL, the details of the | |
27466 | failure are given as additional output lines before the 550 response to the | |
27467 | relevant SMTP command (RCPT or DATA). For example, if sender callout is in use, | |
168e428f | 27468 | you might see: |
9b371988 PH |
27469 | .code |
27470 | MAIL FROM:<xyz@abc.example> | |
27471 | 250 OK | |
27472 | RCPT TO:<pqr@def.example> | |
27473 | 550-Verification failed for <xyz@abc.example> | |
27474 | 550-Called: 192.168.34.43 | |
27475 | 550-Sent: RCPT TO:<xyz@abc.example> | |
27476 | 550-Response: 550 Unknown local part xyz in <xyz@abc.example> | |
27477 | 550 Sender verification failed | |
27478 | .endd | |
168e428f PH |
27479 | If more than one RCPT command fails in the same way, the details are given |
27480 | only for the first of them. However, some administrators do not want to send | |
27481 | out this much information. You can suppress the details by adding | |
4f578862 | 27482 | &`/no_details`& to the ACL statement that requests sender verification. For |
168e428f | 27483 | example: |
9b371988 PH |
27484 | .code |
27485 | verify = sender/no_details | |
27486 | .endd | |
168e428f | 27487 | |
9b371988 PH |
27488 | .section "Redirection while verifying" "SECTredirwhilveri" |
27489 | .cindex "verifying" "redirection while" | |
27490 | .cindex "address redirection" "while verifying" | |
168e428f PH |
27491 | A dilemma arises when a local address is redirected by aliasing or forwarding |
27492 | during verification: should the generated addresses themselves be verified, | |
27493 | or should the successful expansion of the original address be enough to verify | |
068aaea8 | 27494 | it? By default, Exim takes the following pragmatic approach: |
168e428f | 27495 | |
9b371988 PH |
27496 | .ilist |
27497 | When an incoming address is redirected to just one child address, verification | |
168e428f PH |
27498 | continues with the child address, and if that fails to verify, the original |
27499 | verification also fails. | |
9b371988 PH |
27500 | .next |
27501 | When an incoming address is redirected to more than one child address, | |
168e428f | 27502 | verification does not continue. A success result is returned. |
9b371988 | 27503 | .endlist |
168e428f PH |
27504 | |
27505 | This seems the most reasonable behaviour for the common use of aliasing as a | |
27506 | way of redirecting different local parts to the same mailbox. It means, for | |
27507 | example, that a pair of alias entries of the form | |
9b371988 PH |
27508 | .code |
27509 | A.Wol: aw123 | |
27510 | aw123: :fail: Gone away, no forwarding address | |
27511 | .endd | |
168e428f PH |
27512 | work as expected, with both local parts causing verification failure. When a |
27513 | redirection generates more than one address, the behaviour is more like a | |
27514 | mailing list, where the existence of the alias itself is sufficient for | |
27515 | verification to succeed. | |
27516 | ||
068aaea8 PH |
27517 | It is possible, however, to change the default behaviour so that all successful |
27518 | redirections count as successful verifications, however many new addresses are | |
9b371988 PH |
27519 | generated. This is specified by the &%success_on_redirect%& verification |
27520 | option. For example: | |
27521 | .code | |
27522 | require verify = recipient/success_on_redirect/callout=10s | |
27523 | .endd | |
068aaea8 PH |
27524 | In this example, verification succeeds if a router generates a new address, and |
27525 | the callout does not occur, because no address was routed to a remote host. | |
27526 | ||
3cb1b51e PH |
27527 | When verification is being tested via the &%-bv%& option, the treatment of |
27528 | redirections is as just described, unless the &%-v%& or any debugging option is | |
27529 | also specified. In that case, full verification is done for every generated | |
27530 | address and a report is output for each of them. | |
068aaea8 PH |
27531 | |
27532 | ||
27533 | ||
9b371988 PH |
27534 | .section "Client SMTP authorization (CSA)" "SECTverifyCSA" |
27535 | .cindex "CSA" "verifying" | |
068aaea8 PH |
27536 | Client SMTP Authorization is a system that allows a site to advertise |
27537 | which machines are and are not permitted to send email. This is done by placing | |
27538 | special SRV records in the DNS; these are looked up using the client's HELO | |
27539 | domain. At the time of writing, CSA is still an Internet Draft. Client SMTP | |
27540 | Authorization checks in Exim are performed by the ACL condition: | |
9b371988 PH |
27541 | .code |
27542 | verify = csa | |
27543 | .endd | |
068aaea8 PH |
27544 | This fails if the client is not authorized. If there is a DNS problem, or if no |
27545 | valid CSA SRV record is found, or if the client is authorized, the condition | |
27546 | succeeds. These three cases can be distinguished using the expansion variable | |
9b371988 PH |
27547 | &$csa_status$&, which can take one of the values &"fail"&, &"defer"&, |
27548 | &"unknown"&, or &"ok"&. The condition does not itself defer because that would | |
068aaea8 PH |
27549 | be likely to cause problems for legitimate email. |
27550 | ||
068aaea8 | 27551 | The error messages produced by the CSA code include slightly more |
9b371988 | 27552 | detail. If &$csa_status$& is &"defer"&, this may be because of problems |
068aaea8 | 27553 | looking up the CSA SRV record, or problems looking up the CSA target |
9b371988 PH |
27554 | address record. There are four reasons for &$csa_status$& being &"fail"&: |
27555 | ||
27556 | .ilist | |
27557 | The client's host name is explicitly not authorized. | |
27558 | .next | |
27559 | The client's IP address does not match any of the CSA target IP addresses. | |
27560 | .next | |
27561 | The client's host name is authorized but it has no valid target IP addresses | |
068aaea8 | 27562 | (for example, the target's addresses are IPv6 and the client is using IPv4). |
9b371988 PH |
27563 | .next |
27564 | The client's host name has no CSA SRV record but a parent domain has asserted | |
068aaea8 | 27565 | that all subdomains must be explicitly authorized. |
9b371988 | 27566 | .endlist |
068aaea8 | 27567 | |
9b371988 | 27568 | The &%csa%& verification condition can take an argument which is the domain to |
068aaea8 | 27569 | use for the DNS query. The default is: |
9b371988 PH |
27570 | .code |
27571 | verify = csa/$sender_helo_name | |
27572 | .endd | |
068aaea8 PH |
27573 | This implementation includes an extension to CSA. If the query domain |
27574 | is an address literal such as [192.0.2.95], or if it is a bare IP | |
27575 | address, Exim searches for CSA SRV records in the reverse DNS as if | |
9b371988 | 27576 | the HELO domain was (for example) &'95.2.0.192.in-addr.arpa'&. Therefore it is |
068aaea8 | 27577 | meaningful to say: |
9b371988 PH |
27578 | .code |
27579 | verify = csa/$sender_host_address | |
27580 | .endd | |
068aaea8 PH |
27581 | In fact, this is the check that Exim performs if the client does not say HELO. |
27582 | This extension can be turned off by setting the main configuration option | |
9b371988 | 27583 | &%dns_csa_use_reverse%& to be false. |
068aaea8 | 27584 | |
068aaea8 PH |
27585 | If a CSA SRV record is not found for the domain itself, a search |
27586 | is performed through its parent domains for a record which might be | |
27587 | making assertions about subdomains. The maximum depth of this search is limited | |
9b371988 | 27588 | using the main configuration option &%dns_csa_search_limit%&, which is 5 by |
068aaea8 PH |
27589 | default. Exim does not look for CSA SRV records in a top level domain, so the |
27590 | default settings handle HELO domains as long as seven | |
9b371988 PH |
27591 | (&'hostname.five.four.three.two.one.com'&). This encompasses the vast majority |
27592 | of legitimate HELO domains. | |
068aaea8 | 27593 | |
9b371988 | 27594 | The &'dnsdb'& lookup also has support for CSA. Although &'dnsdb'& also supports |
068aaea8 | 27595 | direct SRV lookups, this is not sufficient because of the extra parent domain |
9b371988 | 27596 | search behaviour of CSA, and (as with PTR lookups) &'dnsdb'& also turns IP |
068aaea8 PH |
27597 | addresses into lookups in the reverse DNS space. The result of a successful |
27598 | lookup such as: | |
9b371988 | 27599 | .code |
068aaea8 | 27600 | ${lookup dnsdb {csa=$sender_helo_name}} |
9b371988 | 27601 | .endd |
068aaea8 | 27602 | has two space-separated fields: an authorization code and a target host name. |
9b371988 PH |
27603 | The authorization code can be &"Y"& for yes, &"N"& for no, &"X"& for explicit |
27604 | authorization required but absent, or &"?"& for unknown. | |
068aaea8 PH |
27605 | |
27606 | ||
27607 | ||
27608 | ||
9b371988 | 27609 | .section "Bounce address tag validation" "SECTverifyPRVS" |
f89d2485 | 27610 | .cindex "BATV, verifying" |
068aaea8 | 27611 | Bounce address tag validation (BATV) is a scheme whereby the envelope senders |
9b371988 | 27612 | of outgoing messages have a cryptographic, timestamped &"tag"& added to them. |
068aaea8 PH |
27613 | Genuine incoming bounce messages should therefore always be addressed to |
27614 | recipients that have a valid tag. This scheme is a way of detecting unwanted | |
9b371988 | 27615 | bounce messages caused by sender address forgeries (often called &"collateral |
4f578862 | 27616 | spam"&), because the recipients of such messages do not include valid tags. |
068aaea8 | 27617 | |
068aaea8 | 27618 | There are two expansion items to help with the implementation of the BATV |
9b371988 | 27619 | &"prvs"& (private signature) scheme in an Exim configuration. This scheme signs |
db9452a9 PH |
27620 | the original envelope sender address by using a simple key to add a hash of the |
27621 | address and some time-based randomizing information. The &%prvs%& expansion | |
27622 | item creates a signed address, and the &%prvscheck%& expansion item checks one. | |
27623 | The syntax of these expansion items is described in section | |
9b371988 | 27624 | &<<SECTexpansionitems>>&. |
068aaea8 | 27625 | |
068aaea8 PH |
27626 | As an example, suppose the secret per-address keys are stored in an MySQL |
27627 | database. A query to look up the key for an address could be defined as a macro | |
27628 | like this: | |
9b371988 | 27629 | .code |
068aaea8 PH |
27630 | PRVSCHECK_SQL = ${lookup mysql{SELECT secret FROM batv_prvs \ |
27631 | WHERE sender='${quote_mysql:$prvscheck_address}'\ | |
27632 | }{$value}} | |
9b371988 | 27633 | .endd |
068aaea8 | 27634 | Suppose also that the senders who make use of BATV are defined by an address |
9b371988 | 27635 | list called &%batv_senders%&. Then, in the ACL for RCPT commands, you could |
068aaea8 | 27636 | use this: |
9b371988 | 27637 | .code |
068aaea8 | 27638 | # Bounces: drop unsigned addresses for BATV senders |
f89d2485 | 27639 | deny message = This address does not send an unsigned reverse path |
068aaea8 PH |
27640 | senders = : |
27641 | recipients = +batv_senders | |
27642 | ||
27643 | # Bounces: In case of prvs-signed address, check signature. | |
27644 | deny message = Invalid reverse path signature. | |
27645 | senders = : | |
27646 | condition = ${prvscheck {$local_part@$domain}\ | |
27647 | {PRVSCHECK_SQL}{1}} | |
27648 | !condition = $prvscheck_result | |
9b371988 | 27649 | .endd |
068aaea8 PH |
27650 | The first statement rejects recipients for bounce messages that are addressed |
27651 | to plain BATV sender addresses, because it is known that BATV senders do not | |
27652 | send out messages with plain sender addresses. The second statement rejects | |
27653 | recipients that are prvs-signed, but with invalid signatures (either because | |
27654 | the key is wrong, or the signature has timed out). | |
27655 | ||
068aaea8 | 27656 | A non-prvs-signed address is not rejected by the second statement, because the |
9b371988 PH |
27657 | &%prvscheck%& expansion yields an empty string if its first argument is not a |
27658 | prvs-signed address, thus causing the &%condition%& condition to be false. If | |
27659 | the first argument is a syntactically valid prvs-signed address, the yield is | |
27660 | the third string (in this case &"1"&), whether or not the cryptographic and | |
27661 | timeout checks succeed. The &$prvscheck_result$& variable contains the result | |
27662 | of the checks (empty for failure, &"1"& for success). | |
27663 | ||
2e317712 TF |
27664 | There is one more issue you must consider when implementing prvs-signing: |
27665 | you have to ensure that the routers accept prvs-signed addresses and | |
4f578862 PH |
27666 | deliver them correctly. The easiest way to handle this is to use a &(redirect)& |
27667 | router to remove the signature with a configuration along these lines: | |
9b371988 | 27668 | .code |
068aaea8 PH |
27669 | batv_redirect: |
27670 | driver = redirect | |
27671 | data = ${prvscheck {$local_part@$domain}{PRVSCHECK_SQL}} | |
9b371988 PH |
27672 | .endd |
27673 | This works because, if the third argument of &%prvscheck%& is empty, the result | |
068aaea8 PH |
27674 | of the expansion of a prvs-signed address is the decoded value of the original |
27675 | address. This router should probably be the first of your routers that handles | |
27676 | local addresses. | |
27677 | ||
068aaea8 PH |
27678 | To create BATV-signed addresses in the first place, a transport of this form |
27679 | can be used: | |
9b371988 | 27680 | .code |
068aaea8 PH |
27681 | external_smtp_batv: |
27682 | driver = smtp | |
27683 | return_path = ${prvs {$return_path} \ | |
27684 | {${lookup mysql{SELECT \ | |
27685 | secret FROM batv_prvs WHERE \ | |
27686 | sender='${quote_mysql:$sender_address}'} \ | |
27687 | {$value}fail}}} | |
9b371988 | 27688 | .endd |
068aaea8 PH |
27689 | If no key can be found for the existing return path, no signing takes place. |
27690 | ||
27691 | ||
168e428f | 27692 | |
9b371988 PH |
27693 | .section "Using an ACL to control relaying" "SECTrelaycontrol" |
27694 | .cindex "&ACL;" "relay control" | |
27695 | .cindex "relaying" "control by ACL" | |
27696 | .cindex "policy control" "relay control" | |
27697 | An MTA is said to &'relay'& a message if it receives it from some host and | |
168e428f PH |
27698 | delivers it directly to another host as a result of a remote address contained |
27699 | within it. Redirecting a local address via an alias or forward file and then | |
27700 | passing the message on to another host is not relaying, | |
9b371988 PH |
27701 | .cindex "&""percent hack""&" |
27702 | but a redirection as a result of the &"percent hack"& is. | |
168e428f | 27703 | |
9b371988 | 27704 | Two kinds of relaying exist, which are termed &"incoming"& and &"outgoing"&. |
168e428f PH |
27705 | A host which is acting as a gateway or an MX backup is concerned with incoming |
27706 | relaying from arbitrary hosts to a specific set of domains. On the other hand, | |
27707 | a host which is acting as a smart host for a number of clients is concerned | |
27708 | with outgoing relaying from those clients to the Internet at large. Often the | |
27709 | same host is fulfilling both functions, | |
9b371988 PH |
27710 | . /// |
27711 | . as illustrated in the diagram below, | |
27712 | . /// | |
168e428f PH |
27713 | but in principle these two kinds of relaying are entirely independent. What is |
27714 | not wanted is the transmission of mail from arbitrary remote hosts through your | |
27715 | system to arbitrary domains. | |
27716 | ||
27717 | ||
27718 | You can implement relay control by means of suitable statements in the ACL that | |
27719 | runs for each RCPT command. For convenience, it is often easiest to use | |
27720 | Exim's named list facility to define the domains and hosts involved. For | |
27721 | example, suppose you want to do the following: | |
27722 | ||
9b371988 PH |
27723 | .ilist |
27724 | Deliver a number of domains to mailboxes on the local host (or process them | |
27725 | locally in some other way). Let's say these are &'my.dom1.example'& and | |
27726 | &'my.dom2.example'&. | |
27727 | .next | |
27728 | Relay mail for a number of other domains for which you are the secondary MX. | |
27729 | These might be &'friend1.example'& and &'friend2.example'&. | |
27730 | .next | |
27731 | Relay mail from the hosts on your local LAN, to whatever domains are involved. | |
168e428f | 27732 | Suppose your LAN is 192.168.45.0/24. |
9b371988 | 27733 | .endlist |
168e428f PH |
27734 | |
27735 | ||
27736 | In the main part of the configuration, you put the following definitions: | |
9b371988 PH |
27737 | .code |
27738 | domainlist local_domains = my.dom1.example : my.dom2.example | |
27739 | domainlist relay_domains = friend1.example : friend2.example | |
27740 | hostlist relay_hosts = 192.168.45.0/24 | |
27741 | .endd | |
168e428f PH |
27742 | Now you can use these definitions in the ACL that is run for every RCPT |
27743 | command: | |
9b371988 PH |
27744 | .code |
27745 | acl_check_rcpt: | |
27746 | accept domains = +local_domains : +relay_domains | |
27747 | accept hosts = +relay_hosts | |
27748 | .endd | |
168e428f PH |
27749 | The first statement accepts any RCPT command that contains an address in |
27750 | the local or relay domains. For any other domain, control passes to the second | |
27751 | statement, which accepts the command only if it comes from one of the relay | |
27752 | hosts. In practice, you will probably want to make your ACL more sophisticated | |
27753 | than this, for example, by including sender and recipient verification. The | |
27754 | default configuration includes a more comprehensive example, which is described | |
9b371988 | 27755 | in chapter &<<CHAPdefconfil>>&. |
168e428f PH |
27756 | |
27757 | ||
27758 | ||
9b371988 PH |
27759 | .section "Checking a relay configuration" "SECTcheralcon" |
27760 | .cindex "relaying" "checking control of" | |
168e428f PH |
27761 | You can check the relay characteristics of your configuration in the same way |
27762 | that you can test any ACL behaviour for an incoming SMTP connection, by using | |
9b371988 | 27763 | the &%-bh%& option to run a fake SMTP session with which you interact. |
168e428f PH |
27764 | |
27765 | For specifically testing for unwanted relaying, the host | |
9b371988 | 27766 | &'relay-test.mail-abuse.org'& provides a useful service. If you telnet to this |
168e428f PH |
27767 | host from the host on which Exim is running, using the normal telnet port, you |
27768 | will see a normal telnet connection message and then quite a long delay. Be | |
27769 | patient. The remote host is making an SMTP connection back to your host, and | |
27770 | trying a number of common probes to test for open relay vulnerability. The | |
27771 | results of the tests will eventually appear on your terminal. | |
4f578862 | 27772 | .ecindex IIDacl |
168e428f PH |
27773 | |
27774 | ||
27775 | ||
9b371988 PH |
27776 | . //////////////////////////////////////////////////////////////////////////// |
27777 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 27778 | |
9b371988 | 27779 | .chapter "Content scanning at ACL time" "CHAPexiscan" |
4f578862 | 27780 | .scindex IIDcosca "content scanning" "at ACL time" |
068aaea8 | 27781 | The extension of Exim to include content scanning at ACL time, formerly known |
9b371988 | 27782 | as &"exiscan"&, was originally implemented as a patch by Tom Kistner. The code |
068aaea8 PH |
27783 | was integrated into the main source for Exim release 4.50, and Tom continues to |
27784 | maintain it. Most of the wording of this chapter is taken from Tom's | |
27785 | specification. | |
27786 | ||
068aaea8 | 27787 | It is also possible to scan the content of messages at other times. The |
9b371988 | 27788 | &[local_scan()]& function (see chapter &<<CHAPlocalscan>>&) allows for content |
068aaea8 | 27789 | scanning after all the ACLs have run. A transport filter can be used to scan |
9b371988 PH |
27790 | messages at delivery time (see the &%transport_filter%& option, described in |
27791 | chapter &<<CHAPtransportgeneric>>&). | |
068aaea8 PH |
27792 | |
27793 | If you want to include the ACL-time content-scanning features when you compile | |
27794 | Exim, you need to arrange for WITH_CONTENT_SCAN to be defined in your | |
9b371988 PH |
27795 | &_Local/Makefile_&. When you do that, the Exim binary is built with: |
27796 | ||
27797 | .ilist | |
9b371988 PH |
27798 | Two additional ACLs (&%acl_smtp_mime%& and &%acl_not_smtp_mime%&) that are run |
27799 | for all MIME parts for SMTP and non-SMTP messages, respectively. | |
9b371988 PH |
27800 | .next |
27801 | Additional ACL conditions and modifiers: &%decode%&, &%malware%&, | |
27802 | &%mime_regex%&, &%regex%&, and &%spam%&. These can be used in the ACL that is | |
27803 | run at the end of message reception (the &%acl_smtp_data%& ACL). | |
27804 | .next | |
27805 | An additional control feature (&"no_mbox_unspool"&) that saves spooled copies | |
168e428f | 27806 | of messages, or parts of messages, for debugging purposes. |
9b371988 PH |
27807 | .next |
27808 | Additional expansion variables that are set in the new ACL and by the new | |
168e428f | 27809 | conditions. |
9b371988 PH |
27810 | .next |
27811 | Two new main configuration options: &%av_scanner%& and &%spamd_address%&. | |
27812 | .endlist | |
168e428f | 27813 | |
9b371988 PH |
27814 | There is another content-scanning configuration option for &_Local/Makefile_&, |
27815 | called WITH_OLD_DEMIME. If this is set, the old, deprecated &%demime%& ACL | |
168e428f PH |
27816 | condition is compiled, in addition to all the other content-scanning features. |
27817 | ||
27818 | Content-scanning is continually evolving, and new features are still being | |
27819 | added. While such features are still unstable and liable to incompatible | |
27820 | changes, they are made available in Exim by setting options whose names begin | |
9b371988 | 27821 | EXPERIMENTAL_ in &_Local/Makefile_&. Such features are not documented in |
168e428f | 27822 | this manual. You can find out about them by reading the file called |
9b371988 | 27823 | &_doc/experimental.txt_&. |
168e428f | 27824 | |
f89d2485 | 27825 | All the content-scanning facilities work on a MBOX copy of the message that is |
168e428f | 27826 | temporarily created in a file called: |
9b371988 PH |
27827 | .display |
27828 | <&'spool_directory'&>&`/scan/`&<&'message_id'&>/<&'message_id'&>&`.eml`& | |
27829 | .endd | |
27830 | The &_.eml_& extension is a friendly hint to virus scanners that they can | |
168e428f PH |
27831 | expect an MBOX-like structure inside that file. The file is created when the |
27832 | first content scanning facility is called. Subsequent calls to content | |
27833 | scanning conditions open the same file again. The directory is recursively | |
9b371988 PH |
27834 | removed when the &%acl_smtp_data%& ACL has finished running, unless |
27835 | .code | |
27836 | control = no_mbox_unspool | |
27837 | .endd | |
168e428f PH |
27838 | has been encountered. When the MIME ACL decodes files, they are put into the |
27839 | same directory by default. | |
27840 | ||
27841 | ||
27842 | ||
9b371988 PH |
27843 | .section "Scanning for viruses" "SECTscanvirus" |
27844 | .cindex "virus scanning" | |
27845 | .cindex "content scanning" "for viruses" | |
27846 | .cindex "content scanning" "the &%malware%& condition" | |
27847 | The &%malware%& ACL condition lets you connect virus scanner software to Exim. | |
27848 | It supports a &"generic"& interface to scanners called via the shell, and | |
27849 | specialized interfaces for &"daemon"& type virus scanners, which are resident | |
27850 | in memory and thus are much faster. | |
168e428f | 27851 | |
0a4e3112 | 27852 | .oindex "&%av_scanner%&" |
9b371988 | 27853 | You can set the &%av_scanner%& option in first part of the Exim configuration |
168e428f PH |
27854 | file to specify which scanner to use, together with any additional options that |
27855 | are needed. The basic syntax is as follows: | |
9b371988 PH |
27856 | .display |
27857 | &`av_scanner = <`&&'scanner-type'&&`>:<`&&'option1'&&`>:<`&&'option2'&&`>:[...]`& | |
27858 | .endd | |
27859 | If you do not set &%av_scanner%&, it defaults to | |
27860 | .code | |
27861 | av_scanner = sophie:/var/run/sophie | |
27862 | .endd | |
27863 | If the value of &%av_scanner%& starts with dollar character, it is expanded | |
27864 | before use. The following scanner types are supported in this release: | |
27865 | ||
27866 | .vlist | |
27867 | .vitem &%aveserver%& | |
27868 | .cindex "virus scanners" "Kaspersky" | |
168e428f | 27869 | This is the scanner daemon of Kaspersky Version 5. You can get a trial version |
9b371988 PH |
27870 | at &url(http://www.kaspersky.com). This scanner type takes one option, |
27871 | which is the path to the daemon's UNIX socket. The default is shown in this | |
27872 | example: | |
27873 | .code | |
27874 | av_scanner = aveserver:/var/run/aveserver | |
27875 | .endd | |
168e428f | 27876 | |
9b371988 PH |
27877 | .vitem &%clamd%& |
27878 | .cindex "virus scanners" "clamd" | |
168e428f | 27879 | This daemon-type scanner is GPL and free. You can get it at |
9b371988 PH |
27880 | &url(http://www.clamav.net/). Some older versions of clamd do not seem to |
27881 | unpack MIME containers, so it used to be recommended to unpack MIME attachments | |
27882 | in the MIME ACL. This no longer believed to be necessary. One option is | |
27883 | required: either the path and name of a UNIX socket file, or a hostname or IP | |
27884 | number, and a port, separated by space, as in the second of these examples: | |
27885 | .code | |
27886 | av_scanner = clamd:/opt/clamd/socket | |
27887 | av_scanner = clamd:192.168.2.100 1234 | |
27888 | .endd | |
27889 | If the option is unset, the default is &_/tmp/clamd_&. Thanks to David Saez for | |
168e428f PH |
27890 | contributing the code for this scanner. |
27891 | ||
9b371988 PH |
27892 | .vitem &%cmdline%& |
27893 | .cindex "virus scanners" "command line interface" | |
168e428f PH |
27894 | This is the keyword for the generic command line scanner interface. It can be |
27895 | used to attach virus scanners that are invoked from the shell. This scanner | |
27896 | type takes 3 mandatory options: | |
168e428f | 27897 | |
9b371988 PH |
27898 | .olist |
27899 | The full path and name of the scanner binary, with all command line options, | |
27900 | and a placeholder (&`%s`&) for the directory to scan. | |
27901 | ||
27902 | .next | |
27903 | A regular expression to match against the STDOUT and STDERR output of the | |
168e428f | 27904 | virus scanner. If the expression matches, a virus was found. You must make |
9b371988 PH |
27905 | absolutely sure that this expression matches on &"virus found"&. This is called |
27906 | the &"trigger"& expression. | |
168e428f | 27907 | |
9b371988 PH |
27908 | .next |
27909 | Another regular expression, containing exactly one pair of parentheses, to | |
168e428f | 27910 | match the name of the virus found in the scanners output. This is called the |
9b371988 PH |
27911 | &"name"& expression. |
27912 | .endlist olist | |
168e428f | 27913 | |
9b371988 PH |
27914 | For example, Sophos Sweep reports a virus on a line like this: |
27915 | .code | |
27916 | Virus 'W32/Magistr-B' found in file ./those.bat | |
27917 | .endd | |
3cb1b51e PH |
27918 | For the trigger expression, we can match the phrase &"found in file"&. For the |
27919 | name expression, we want to extract the W32/Magistr-B string, so we can match | |
27920 | for the single quotes left and right of it. Altogether, this makes the | |
168e428f | 27921 | configuration setting: |
9b371988 | 27922 | .code |
168e428f | 27923 | av_scanner = cmdline:\ |
3cb1b51e PH |
27924 | /path/to/sweep -ss -all -rec -archive %s:\ |
27925 | found in file:'(.+)' | |
9b371988 PH |
27926 | .endd |
27927 | .vitem &%drweb%& | |
27928 | .cindex "virus scanners" "DrWeb" | |
27929 | The DrWeb daemon scanner (&url(http://www.sald.com/)) interface takes one | |
168e428f | 27930 | argument, either a full path to a UNIX socket, or an IP address and port |
068aaea8 | 27931 | separated by white space, as in these examples: |
9b371988 PH |
27932 | .code |
27933 | av_scanner = drweb:/var/run/drwebd.sock | |
27934 | av_scanner = drweb:192.168.2.20 31337 | |
27935 | .endd | |
27936 | If you omit the argument, the default path &_/usr/local/drweb/run/drwebd.sock_& | |
168e428f PH |
27937 | is used. Thanks to Alex Miller for contributing the code for this scanner. |
27938 | ||
9b371988 PH |
27939 | .vitem &%fsecure%& |
27940 | .cindex "virus scanners" "F-Secure" | |
27941 | The F-Secure daemon scanner (&url(http://www.f-secure.com)) takes one | |
27942 | argument which is the path to a UNIX socket. For example: | |
27943 | .code | |
27944 | av_scanner = fsecure:/path/to/.fsav | |
27945 | .endd | |
27946 | If no argument is given, the default is &_/var/run/.fsav_&. Thanks to Johan | |
168e428f PH |
27947 | Thelmen for contributing the code for this scanner. |
27948 | ||
9b371988 PH |
27949 | .vitem &%kavdaemon%& |
27950 | .cindex "virus scanners" "Kaspersky" | |
168e428f | 27951 | This is the scanner daemon of Kaspersky Version 4. This version of the |
9b371988 | 27952 | Kaspersky scanner is outdated. Please upgrade (see &%aveserver%& above). This |
168e428f PH |
27953 | scanner type takes one option, which is the path to the daemon's UNIX socket. |
27954 | For example: | |
9b371988 PH |
27955 | .code |
27956 | av_scanner = kavdaemon:/opt/AVP/AvpCtl | |
27957 | .endd | |
27958 | The default path is &_/var/run/AvpCtl_&. | |
168e428f | 27959 | |
9b371988 PH |
27960 | .vitem &%mksd%& |
27961 | .cindex "virus scanners" "mksd" | |
168e428f PH |
27962 | This is a daemon type scanner that is aimed mainly at Polish users, though some |
27963 | parts of documentation are now available in English. You can get it at | |
9b371988 PH |
27964 | &url(http://linux.mks.com.pl/). The only option for this scanner type is |
27965 | the maximum number of processes used simultaneously to scan the attachments, | |
168e428f PH |
27966 | provided that the demime facility is employed and also provided that mksd has |
27967 | been run with at least the same number of child processes. For example: | |
9b371988 PH |
27968 | .code |
27969 | av_scanner = mksd:2 | |
27970 | .endd | |
168e428f PH |
27971 | You can safely omit this option (the default value is 1). |
27972 | ||
9b371988 PH |
27973 | .vitem &%sophie%& |
27974 | .cindex "virus scanners" "Sophos and Sophie" | |
27975 | Sophie is a daemon that uses Sophos' &%libsavi%& library to scan for viruses. | |
db9452a9 PH |
27976 | You can get Sophie at &url(http://www.clanfield.info/sophie/). The only option |
27977 | for this scanner type is the path to the UNIX socket that Sophie uses for | |
27978 | client communication. For example: | |
9b371988 PH |
27979 | .code |
27980 | av_scanner = sophie:/tmp/sophie | |
27981 | .endd | |
27982 | The default path is &_/var/run/sophie_&, so if you are using this, you can omit | |
168e428f | 27983 | the option. |
9b371988 PH |
27984 | .endlist |
27985 | ||
9b371988 PH |
27986 | When &%av_scanner%& is correctly set, you can use the &%malware%& condition in |
27987 | the DATA ACL. &*Note*&: You cannot use the &%malware%& condition in the MIME | |
27988 | ACL. | |
9b371988 PH |
27989 | |
27990 | The &%av_scanner%& option is expanded each time &%malware%& is called. This | |
27991 | makes it possible to use different scanners. See further below for an example. | |
27992 | The &%malware%& condition caches its results, so when you use it multiple times | |
27993 | for the same message, the actual scanning process is only carried out once. | |
27994 | However, using expandable items in &%av_scanner%& disables this caching, in | |
27995 | which case each use of the &%malware%& condition causes a new scan of the | |
27996 | message. | |
168e428f | 27997 | |
9b371988 | 27998 | The &%malware%& condition takes a right-hand argument that is expanded before |
168e428f PH |
27999 | use. It can then be one of |
28000 | ||
9b371988 PH |
28001 | .ilist |
28002 | &"true"&, &"*"&, or &"1"&, in which case the message is scanned for viruses. | |
168e428f PH |
28003 | The condition succeeds if a virus was found, and fail otherwise. This is the |
28004 | recommended usage. | |
9b371988 | 28005 | .next |
db9452a9 PH |
28006 | &"false"& or &"0"& or an empty string, in which case no scanning is done and |
28007 | the condition fails immediately. | |
9b371988 PH |
28008 | .next |
28009 | A regular expression, in which case the message is scanned for viruses. The | |
168e428f PH |
28010 | condition succeeds if a virus is found and its name matches the regular |
28011 | expression. This allows you to take special actions on certain types of virus. | |
9b371988 | 28012 | .endlist |
168e428f | 28013 | |
9b371988 | 28014 | You can append &`/defer_ok`& to the &%malware%& condition to accept messages |
db9452a9 PH |
28015 | even if there is a problem with the virus scanner. Otherwise, such a problem |
28016 | causes the ACL to defer. | |
168e428f | 28017 | |
f89d2485 | 28018 | .vindex "&$malware_name$&" |
168e428f | 28019 | When a virus is found, the condition sets up an expansion variable called |
9b371988 PH |
28020 | &$malware_name$& that contains the name of the virus. You can use it in a |
28021 | &%message%& modifier that specifies the error returned to the sender, and/or in | |
168e428f PH |
28022 | logging data. |
28023 | ||
28024 | If your virus scanner cannot unpack MIME and TNEF containers itself, you should | |
9b371988 PH |
28025 | use the &%demime%& condition (see section &<<SECTdemimecond>>&) before the |
28026 | &%malware%& condition. | |
168e428f PH |
28027 | |
28028 | Here is a very simple scanning example: | |
9b371988 PH |
28029 | .code |
28030 | deny message = This message contains malware ($malware_name) | |
168e428f PH |
28031 | demime = * |
28032 | malware = * | |
9b371988 | 28033 | .endd |
168e428f | 28034 | The next example accepts messages when there is a problem with the scanner: |
9b371988 PH |
28035 | .code |
28036 | deny message = This message contains malware ($malware_name) | |
168e428f PH |
28037 | demime = * |
28038 | malware = */defer_ok | |
9b371988 | 28039 | .endd |
168e428f PH |
28040 | The next example shows how to use an ACL variable to scan with both sophie and |
28041 | aveserver. It assumes you have set: | |
9b371988 PH |
28042 | .code |
28043 | av_scanner = $acl_m0 | |
28044 | .endd | |
168e428f | 28045 | in the main Exim configuration. |
9b371988 PH |
28046 | .code |
28047 | deny message = This message contains malware ($malware_name) | |
168e428f PH |
28048 | set acl_m0 = sophie |
28049 | malware = * | |
28050 | ||
9b371988 | 28051 | deny message = This message contains malware ($malware_name) |
168e428f PH |
28052 | set acl_m0 = aveserver |
28053 | malware = * | |
9b371988 | 28054 | .endd |
168e428f PH |
28055 | |
28056 | ||
9b371988 PH |
28057 | .section "Scanning with SpamAssassin" "SECTscanspamass" |
28058 | .cindex "content scanning" "for spam" | |
28059 | .cindex "spam scanning" | |
f89d2485 | 28060 | .cindex "SpamAssassin" |
9b371988 | 28061 | The &%spam%& ACL condition calls SpamAssassin's &%spamd%& daemon to get a spam |
168e428f | 28062 | score and a report for the message. You can get SpamAssassin at |
9b371988 PH |
28063 | &url(http://www.spamassassin.org), or, if you have a working Perl |
28064 | installation, you can use CPAN by running: | |
28065 | .code | |
28066 | perl -MCPAN -e 'install Mail::SpamAssassin' | |
28067 | .endd | |
168e428f PH |
28068 | SpamAssassin has its own set of configuration files. Please review its |
28069 | documentation to see how you can tweak it. The default installation should work | |
28070 | nicely, however. | |
28071 | ||
0a4e3112 | 28072 | .oindex "&%spamd_address%&" |
9b371988 | 28073 | After having installed and configured SpamAssassin, start the &%spamd%& daemon. |
168e428f | 28074 | By default, it listens on 127.0.0.1, TCP port 783. If you use another host or |
9b371988 PH |
28075 | port for &%spamd%&, you must set the &%spamd_address%& option in the global |
28076 | part of the Exim configuration as follows (example): | |
28077 | .code | |
28078 | spamd_address = 192.168.99.45 387 | |
28079 | .endd | |
168e428f | 28080 | You do not need to set this option if you use the default. As of version 2.60, |
9b371988 PH |
28081 | &%spamd%& also supports communication over UNIX sockets. If you want to use |
28082 | these, supply &%spamd_address%& with an absolute file name instead of a | |
168e428f | 28083 | address/port pair: |
9b371988 PH |
28084 | .code |
28085 | spamd_address = /var/run/spamd_socket | |
28086 | .endd | |
28087 | You can have multiple &%spamd%& servers to improve scalability. These can | |
28088 | reside on other hardware reachable over the network. To specify multiple | |
28089 | &%spamd%& servers, put multiple address/port pairs in the &%spamd_address%& | |
28090 | option, separated with colons: | |
28091 | .code | |
168e428f PH |
28092 | spamd_address = 192.168.2.10 783 : \ |
28093 | 192.168.2.11 783 : \ | |
28094 | 192.168.2.12 783 | |
9b371988 PH |
28095 | .endd |
28096 | Up to 32 &%spamd%& servers are supported. The servers are queried in a random | |
068aaea8 | 28097 | fashion. When a server fails to respond to the connection attempt, all other |
9b371988 | 28098 | servers are tried until one succeeds. If no server responds, the &%spam%& |
168e428f PH |
28099 | condition defers. |
28100 | ||
9b371988 PH |
28101 | &*Warning*&: It is not possible to use the UNIX socket connection method with |
28102 | multiple &%spamd%& servers. | |
168e428f | 28103 | |
8fde9903 NM |
28104 | The &%spamd_address%& variable is expanded before use if it starts with |
28105 | a dollar sign. In this case, the expansion may return a string that is | |
28106 | used as the list so that multiple spamd servers can be the result of an | |
28107 | expansion. | |
168e428f | 28108 | |
f89d2485 | 28109 | .section "Calling SpamAssassin from an Exim ACL" "SECID206" |
9b371988 PH |
28110 | Here is a simple example of the use of the &%spam%& condition in a DATA ACL: |
28111 | .code | |
28112 | deny message = This message was classified as SPAM | |
28113 | spam = joe | |
28114 | .endd | |
3cb1b51e PH |
28115 | The right-hand side of the &%spam%& condition specifies a name. This is |
28116 | relevant if you have set up multiple SpamAssassin profiles. If you do not want | |
28117 | to scan using a specific profile, but rather use the SpamAssassin system-wide | |
28118 | default profile, you can scan for an unknown name, or simply use &"nobody"&. | |
28119 | However, you must put something on the right-hand side. | |
28120 | ||
28121 | The name allows you to use per-domain or per-user antispam profiles in | |
28122 | principle, but this is not straightforward in practice, because a message may | |
28123 | have multiple recipients, not necessarily all in the same domain. Because the | |
28124 | &%spam%& condition has to be called from a DATA ACL in order to be able to | |
28125 | read the contents of the message, the variables &$local_part$& and &$domain$& | |
28126 | are not set. | |
28127 | ||
28128 | The right-hand side of the &%spam%& condition is expanded before being used, so | |
28129 | you can put lookups or conditions there. When the right-hand side evaluates to | |
28130 | &"0"& or &"false"&, no scanning is done and the condition fails immediately. | |
168e428f | 28131 | |
168e428f | 28132 | |
068aaea8 | 28133 | Scanning with SpamAssassin uses a lot of resources. If you scan every message, |
f89d2485 | 28134 | large ones may cause significant performance degradation. As most spam messages |
068aaea8 PH |
28135 | are quite small, it is recommended that you do not scan the big ones. For |
28136 | example: | |
9b371988 | 28137 | .code |
068aaea8 PH |
28138 | deny message = This message was classified as SPAM |
28139 | condition = ${if < {$message_size}{10K}} | |
28140 | spam = nobody | |
9b371988 | 28141 | .endd |
068aaea8 | 28142 | |
9b371988 | 28143 | The &%spam%& condition returns true if the threshold specified in the user's |
168e428f | 28144 | SpamAssassin profile has been matched or exceeded. If you want to use the |
9b371988 PH |
28145 | &%spam%& condition for its side effects (see the variables below), you can make |
28146 | it always return &"true"& by appending &`:true`& to the username. | |
168e428f | 28147 | |
9b371988 | 28148 | .cindex "spam scanning" "returned variables" |
c0712871 PH |
28149 | When the &%spam%& condition is run, it sets up a number of expansion |
28150 | variables. With the exception of &$spam_score_int$&, these are usable only | |
28151 | within ACLs; their values are not retained with the message and so cannot be | |
28152 | used at delivery time. | |
168e428f | 28153 | |
9b371988 PH |
28154 | .vlist |
28155 | .vitem &$spam_score$& | |
28156 | The spam score of the message, for example &"3.4"& or &"30.5"&. This is useful | |
168e428f PH |
28157 | for inclusion in log or reject messages. |
28158 | ||
9b371988 | 28159 | .vitem &$spam_score_int$& |
168e428f | 28160 | The spam score of the message, multiplied by ten, as an integer value. For |
b049e222 TF |
28161 | example &"34"& or &"305"&. It may appear to disagree with &$spam_score$& |
28162 | because &$spam_score$& is rounded and &$spam_score_int$& is truncated. | |
28163 | The integer value is useful for numeric comparisons in | |
c0712871 PH |
28164 | conditions. This variable is special; its value is saved with the message, and |
28165 | written to Exim's spool file. This means that it can be used during the whole | |
28166 | life of the message on your Exim system, in particular, in routers or | |
28167 | transports during the later delivery phase. | |
168e428f | 28168 | |
9b371988 PH |
28169 | .vitem &$spam_bar$& |
28170 | A string consisting of a number of &"+"& or &"-"& characters, representing the | |
168e428f | 28171 | integer part of the spam score value. A spam score of 4.4 would have a |
9b371988 PH |
28172 | &$spam_bar$& value of &"++++"&. This is useful for inclusion in warning |
28173 | headers, since MUAs can match on such strings. | |
168e428f | 28174 | |
9b371988 | 28175 | .vitem &$spam_report$& |
168e428f PH |
28176 | A multiline text table, containing the full SpamAssassin report for the |
28177 | message. Useful for inclusion in headers or reject messages. | |
9b371988 | 28178 | .endlist |
168e428f | 28179 | |
8fde9903 NM |
28180 | The &%spam%& condition caches its results unless expansion in |
28181 | spamd_address was used. If you call it again with the same user name, it | |
28182 | does not scan again, but rather returns the same values as before. | |
168e428f | 28183 | |
8fde9903 NM |
28184 | The &%spam%& condition returns DEFER if there is any error while running |
28185 | the message through SpamAssassin or if the expansion of spamd_address | |
28186 | failed. If you want to treat DEFER as FAIL (to pass on to the next ACL | |
28187 | statement block), append &`/defer_ok`& to the right-hand side of the | |
28188 | spam condition, like this: | |
9b371988 PH |
28189 | .code |
28190 | deny message = This message was classified as SPAM | |
28191 | spam = joe/defer_ok | |
28192 | .endd | |
28193 | This causes messages to be accepted even if there is a problem with &%spamd%&. | |
168e428f | 28194 | |
9b371988 | 28195 | Here is a longer, commented example of the use of the &%spam%& |
168e428f | 28196 | condition: |
9b371988 PH |
28197 | .code |
28198 | # put headers in all messages (no matter if spam or not) | |
db9452a9 PH |
28199 | warn spam = nobody:true |
28200 | add_header = X-Spam-Score: $spam_score ($spam_bar) | |
28201 | add_header = X-Spam-Report: $spam_report | |
9b371988 PH |
28202 | |
28203 | # add second subject line with *SPAM* marker when message | |
28204 | # is over threshold | |
db9452a9 PH |
28205 | warn spam = nobody |
28206 | add_header = Subject: *SPAM* $h_Subject: | |
9b371988 PH |
28207 | |
28208 | # reject spam at high scores (> 12) | |
28209 | deny message = This message scored $spam_score spam points. | |
28210 | spam = nobody:true | |
28211 | condition = ${if >{$spam_score_int}{120}{1}{0}} | |
28212 | .endd | |
28213 | ||
28214 | ||
28215 | ||
28216 | .section "Scanning MIME parts" "SECTscanmimepart" | |
28217 | .cindex "content scanning" "MIME parts" | |
28218 | .cindex "MIME content scanning" | |
0a4e3112 PH |
28219 | .oindex "&%acl_smtp_mime%&" |
28220 | .oindex "&%acl_not_smtp_mime%&" | |
9b371988 PH |
28221 | The &%acl_smtp_mime%& global option specifies an ACL that is called once for |
28222 | each MIME part of an SMTP message, including multipart types, in the sequence | |
28223 | of their position in the message. Similarly, the &%acl_not_smtp_mime%& option | |
068aaea8 PH |
28224 | specifies an ACL that is used for the MIME parts of non-SMTP messages. These |
28225 | options may both refer to the same ACL if you want the same processing in both | |
28226 | cases. | |
28227 | ||
595028e4 PH |
28228 | These ACLs are called (possibly many times) just before the &%acl_smtp_data%& |
28229 | ACL in the case of an SMTP message, or just before the &%acl_not_smtp%& ACL in | |
28230 | the case of a non-SMTP message. However, a MIME ACL is called only if the | |
7d0ab55c | 28231 | message contains a &'Content-Type:'& header line. When a call to a MIME |
595028e4 PH |
28232 | ACL does not yield &"accept"&, ACL processing is aborted and the appropriate |
28233 | result code is sent to the client. In the case of an SMTP message, the | |
28234 | &%acl_smtp_data%& ACL is not called when this happens. | |
9b371988 PH |
28235 | |
28236 | You cannot use the &%malware%& or &%spam%& conditions in a MIME ACL; these can | |
28237 | only be used in the DATA or non-SMTP ACLs. However, you can use the &%regex%& | |
28238 | condition to match against the raw MIME part. You can also use the | |
28239 | &%mime_regex%& condition to match against the decoded MIME part (see section | |
28240 | &<<SECTscanregex>>&). | |
168e428f | 28241 | |
068aaea8 | 28242 | At the start of a MIME ACL, a number of variables are set from the header |
168e428f PH |
28243 | information for the relevant MIME part. These are described below. The contents |
28244 | of the MIME part are not by default decoded into a disk file except for MIME | |
9b371988 | 28245 | parts whose content-type is &"message/rfc822"&. If you want to decode a MIME |
f89d2485 PH |
28246 | part into a disk file, you can use the &%decode%& condition. The general |
28247 | syntax is: | |
9b371988 PH |
28248 | .display |
28249 | &`decode = [/`&<&'path'&>&`/]`&<&'filename'&> | |
28250 | .endd | |
168e428f PH |
28251 | The right hand side is expanded before use. After expansion, |
28252 | the value can be: | |
28253 | ||
9b371988 PH |
28254 | .olist |
28255 | &"0"& or &"false"&, in which case no decoding is done. | |
28256 | .next | |
28257 | The string &"default"&. In that case, the file is put in the temporary | |
28258 | &"default"& directory <&'spool_directory'&>&_/scan/_&<&'message_id'&>&_/_& with | |
28259 | a sequential file name consisting of the message id and a sequence number. The | |
28260 | full path and name is available in &$mime_decoded_filename$& after decoding. | |
28261 | .next | |
28262 | A full path name starting with a slash. If the full name is an existing | |
168e428f PH |
28263 | directory, it is used as a replacement for the default directory. The filename |
28264 | is then sequentially assigned. If the path does not exist, it is used as | |
28265 | the full path and file name. | |
9b371988 PH |
28266 | .next |
28267 | If the string does not start with a slash, it is used as the | |
168e428f | 28268 | filename, and the default path is then used. |
9b371988 | 28269 | .endlist |
595028e4 PH |
28270 | The &%decode%& condition normally succeeds. It is only false for syntax |
28271 | errors or unusual circumstances such as memory shortages. You can easily decode | |
28272 | a file with its original, proposed filename using | |
9b371988 PH |
28273 | .code |
28274 | decode = $mime_filename | |
28275 | .endd | |
28276 | However, you should keep in mind that &$mime_filename$& might contain | |
168e428f PH |
28277 | anything. If you place files outside of the default path, they are not |
28278 | automatically unlinked. | |
28279 | ||
28280 | For RFC822 attachments (these are messages attached to messages, with a | |
9b371988 PH |
28281 | content-type of &"message/rfc822"&), the ACL is called again in the same manner |
28282 | as for the primary message, only that the &$mime_is_rfc822$& expansion | |
168e428f PH |
28283 | variable is set (see below). Attached messages are always decoded to disk |
28284 | before being checked, and the files are unlinked once the check is done. | |
28285 | ||
9b371988 | 28286 | The MIME ACL supports the &%regex%& and &%mime_regex%& conditions. These can be |
168e428f | 28287 | used to match regular expressions against raw and decoded MIME parts, |
9b371988 | 28288 | respectively. They are described in section &<<SECTscanregex>>&. |
168e428f | 28289 | |
9b371988 | 28290 | .cindex "MIME content scanning" "returned variables" |
168e428f PH |
28291 | The following list describes all expansion variables that are |
28292 | available in the MIME ACL: | |
28293 | ||
9b371988 PH |
28294 | .vlist |
28295 | .vitem &$mime_boundary$& | |
28296 | If the current part is a multipart (see &$mime_is_multipart$&) below, it should | |
168e428f | 28297 | have a boundary string, which is stored in this variable. If the current part |
9b371988 PH |
28298 | has no boundary parameter in the &'Content-Type:'& header, this variable |
28299 | contains the empty string. | |
168e428f | 28300 | |
9b371988 | 28301 | .vitem &$mime_charset$& |
168e428f | 28302 | This variable contains the character set identifier, if one was found in the |
9b371988 PH |
28303 | &'Content-Type:'& header. Examples for charset identifiers are: |
28304 | .code | |
28305 | us-ascii | |
28306 | gb2312 (Chinese) | |
28307 | iso-8859-1 | |
28308 | .endd | |
168e428f PH |
28309 | Please note that this value is not normalized, so you should do matches |
28310 | case-insensitively. | |
28311 | ||
9b371988 PH |
28312 | .vitem &$mime_content_description$& |
28313 | This variable contains the normalized content of the &'Content-Description:'& | |
168e428f PH |
28314 | header. It can contain a human-readable description of the parts content. Some |
28315 | implementations repeat the filename for attachments here, but they are usually | |
28316 | only used for display purposes. | |
28317 | ||
9b371988 PH |
28318 | .vitem &$mime_content_disposition$& |
28319 | This variable contains the normalized content of the &'Content-Disposition:'& | |
28320 | header. You can expect strings like &"attachment"& or &"inline"& here. | |
168e428f | 28321 | |
9b371988 PH |
28322 | .vitem &$mime_content_id$& |
28323 | This variable contains the normalized content of the &'Content-ID:'& header. | |
168e428f PH |
28324 | This is a unique ID that can be used to reference a part from another part. |
28325 | ||
9b371988 PH |
28326 | .vitem &$mime_content_size$& |
28327 | This variable is set only after the &%decode%& modifier (see above) has been | |
168e428f PH |
28328 | successfully run. It contains the size of the decoded part in kilobytes. The |
28329 | size is always rounded up to full kilobytes, so only a completely empty part | |
9b371988 | 28330 | has a &$mime_content_size$& of zero. |
168e428f | 28331 | |
9b371988 | 28332 | .vitem &$mime_content_transfer_encoding$& |
168e428f | 28333 | This variable contains the normalized content of the |
9b371988 PH |
28334 | &'Content-transfer-encoding:'& header. This is a symbolic name for an encoding |
28335 | type. Typical values are &"base64"& and &"quoted-printable"&. | |
168e428f | 28336 | |
9b371988 PH |
28337 | .vitem &$mime_content_type$& |
28338 | If the MIME part has a &'Content-Type:'& header, this variable contains its | |
28339 | value, lowercased, and without any options (like &"name"& or &"charset"&). Here | |
168e428f | 28340 | are some examples of popular MIME types, as they may appear in this variable: |
9b371988 PH |
28341 | .code |
28342 | text/plain | |
28343 | text/html | |
28344 | application/octet-stream | |
28345 | image/jpeg | |
28346 | audio/midi | |
28347 | .endd | |
28348 | If the MIME part has no &'Content-Type:'& header, this variable contains the | |
168e428f PH |
28349 | empty string. |
28350 | ||
9b371988 PH |
28351 | .vitem &$mime_decoded_filename$& |
28352 | This variable is set only after the &%decode%& modifier (see above) has been | |
168e428f PH |
28353 | successfully run. It contains the full path and file name of the file |
28354 | containing the decoded data. | |
9b371988 | 28355 | .endlist |
168e428f | 28356 | |
9b371988 PH |
28357 | .cindex "RFC 2047" |
28358 | .vlist | |
28359 | .vitem &$mime_filename$& | |
168e428f PH |
28360 | This is perhaps the most important of the MIME variables. It contains a |
28361 | proposed filename for an attachment, if one was found in either the | |
9b371988 PH |
28362 | &'Content-Type:'& or &'Content-Disposition:'& headers. The filename will be |
28363 | RFC2047 decoded, but no additional sanity checks are done. If no filename was | |
28364 | found, this variable contains the empty string. | |
168e428f | 28365 | |
9b371988 PH |
28366 | .vitem &$mime_is_coverletter$& |
28367 | This variable attempts to differentiate the &"cover letter"& of an e-mail from | |
f89d2485 | 28368 | attached data. It can be used to clamp down on flashy or unnecessarily encoded |
168e428f | 28369 | content in the cover letter, while not restricting attachments at all. |
9b371988 | 28370 | |
168e428f PH |
28371 | The variable contains 1 (true) for a MIME part believed to be part of the |
28372 | cover letter, and 0 (false) for an attachment. At present, the algorithm is as | |
28373 | follows: | |
168e428f | 28374 | |
9b371988 PH |
28375 | .olist |
28376 | The outermost MIME part of a message is always a cover letter. | |
28377 | ||
28378 | .next | |
28379 | If a multipart/alternative or multipart/related MIME part is a cover letter, | |
d1e83bff | 28380 | so are all MIME subparts within that multipart. |
168e428f | 28381 | |
9b371988 PH |
28382 | .next |
28383 | If any other multipart is a cover letter, the first subpart is a cover letter, | |
168e428f PH |
28384 | and the rest are attachments. |
28385 | ||
9b371988 PH |
28386 | .next |
28387 | All parts contained within an attachment multipart are attachments. | |
28388 | .endlist olist | |
28389 | ||
28390 | As an example, the following will ban &"HTML mail"& (including that sent with | |
168e428f PH |
28391 | alternative plain text), while allowing HTML files to be attached. HTML |
28392 | coverletter mail attached to non-HMTL coverletter mail will also be allowed: | |
9b371988 PH |
28393 | .code |
28394 | deny message = HTML mail is not accepted here | |
28395 | !condition = $mime_is_rfc822 | |
28396 | condition = $mime_is_coverletter | |
28397 | condition = ${if eq{$mime_content_type}{text/html}{1}{0}} | |
28398 | .endd | |
28399 | .vitem &$mime_is_multipart$& | |
168e428f | 28400 | This variable has the value 1 (true) when the current part has the main type |
9b371988 | 28401 | &"multipart"&, for example &"multipart/alternative"& or &"multipart/mixed"&. |
168e428f PH |
28402 | Since multipart entities only serve as containers for other parts, you may not |
28403 | want to carry out specific actions on them. | |
28404 | ||
9b371988 | 28405 | .vitem &$mime_is_rfc822$& |
168e428f PH |
28406 | This variable has the value 1 (true) if the current part is not a part of the |
28407 | checked message itself, but part of an attached message. Attached message | |
28408 | decoding is fully recursive. | |
28409 | ||
9b371988 | 28410 | .vitem &$mime_part_count$& |
168e428f PH |
28411 | This variable is a counter that is raised for each processed MIME part. It |
28412 | starts at zero for the very first part (which is usually a multipart). The | |
28413 | counter is per-message, so it is reset when processing RFC822 attachments (see | |
9b371988 | 28414 | &$mime_is_rfc822$&). The counter stays set after &%acl_smtp_mime%& is |
168e428f PH |
28415 | complete, so you can use it in the DATA ACL to determine the number of MIME |
28416 | parts of a message. For non-MIME messages, this variable contains the value -1. | |
9b371988 | 28417 | .endlist |
168e428f PH |
28418 | |
28419 | ||
28420 | ||
9b371988 PH |
28421 | .section "Scanning with regular expressions" "SECTscanregex" |
28422 | .cindex "content scanning" "with regular expressions" | |
28423 | .cindex "regular expressions" "content scanning with" | |
168e428f PH |
28424 | You can specify your own custom regular expression matches on the full body of |
28425 | the message, or on individual MIME parts. | |
28426 | ||
9b371988 | 28427 | The &%regex%& condition takes one or more regular expressions as arguments and |
168e428f | 28428 | matches them against the full message (when called in the DATA ACL) or a raw |
9b371988 | 28429 | MIME part (when called in the MIME ACL). The &%regex%& condition matches |
168e428f | 28430 | linewise, with a maximum line length of 32K characters. That means you cannot |
9b371988 | 28431 | have multiline matches with the &%regex%& condition. |
168e428f | 28432 | |
9b371988 | 28433 | The &%mime_regex%& condition can be called only in the MIME ACL. It matches up |
168e428f | 28434 | to 32K of decoded content (the whole content at once, not linewise). If the |
9b371988 PH |
28435 | part has not been decoded with the &%decode%& modifier earlier in the ACL, it |
28436 | is decoded automatically when &%mime_regex%& is executed (using default path | |
28437 | and filename values). If the decoded data is larger than 32K, only the first | |
28438 | 32K characters are checked. | |
168e428f PH |
28439 | |
28440 | The regular expressions are passed as a colon-separated list. To include a | |
28441 | literal colon, you must double it. Since the whole right-hand side string is | |
28442 | expanded before being used, you must also escape dollar signs and backslashes | |
9b371988 | 28443 | with more backslashes, or use the &`\N`& facility to disable expansion. |
168e428f | 28444 | Here is a simple example that contains two regular expressions: |
9b371988 PH |
28445 | .code |
28446 | deny message = contains blacklisted regex ($regex_match_string) | |
28447 | regex = [Mm]ortgage : URGENT BUSINESS PROPOSAL | |
28448 | .endd | |
168e428f | 28449 | The conditions returns true if any one of the regular expressions matches. The |
9b371988 | 28450 | &$regex_match_string$& expansion variable is then set up and contains the |
168e428f PH |
28451 | matching regular expression. |
28452 | ||
9b371988 | 28453 | &*Warning*&: With large messages, these conditions can be fairly |
168e428f PH |
28454 | CPU-intensive. |
28455 | ||
28456 | ||
28457 | ||
28458 | ||
9b371988 PH |
28459 | .section "The demime condition" "SECTdemimecond" |
28460 | .cindex "content scanning" "MIME checking" | |
28461 | .cindex "MIME content scanning" | |
28462 | The &%demime%& ACL condition provides MIME unpacking, sanity checking and file | |
068aaea8 | 28463 | extension blocking. It is usable only in the DATA and non-SMTP ACLs. The |
9b371988 PH |
28464 | &%demime%& condition uses a simpler interface to MIME decoding than the MIME |
28465 | ACL functionality, but provides no additional facilities. Please note that this | |
068aaea8 | 28466 | condition is deprecated and kept only for backward compatibility. You must set |
9b371988 PH |
28467 | the WITH_OLD_DEMIME option in &_Local/Makefile_& at build time to be able to |
28468 | use the &%demime%& condition. | |
168e428f | 28469 | |
9b371988 | 28470 | The &%demime%& condition unpacks MIME containers in the message. It detects |
168e428f PH |
28471 | errors in MIME containers and can match file extensions found in the message |
28472 | against a list. Using this facility produces files containing the unpacked MIME | |
28473 | parts of the message in the temporary scan directory. If you do antivirus | |
f89d2485 | 28474 | scanning, it is recommended that you use the &%demime%& condition before the |
9b371988 | 28475 | antivirus (&%malware%&) condition. |
168e428f | 28476 | |
9b371988 PH |
28477 | On the right-hand side of the &%demime%& condition you can pass a |
28478 | colon-separated list of file extensions that it should match against. For | |
28479 | example: | |
28480 | .code | |
28481 | deny message = Found blacklisted file attachment | |
28482 | demime = vbs:com:bat:pif:prf:lnk | |
28483 | .endd | |
168e428f | 28484 | If one of the file extensions is found, the condition is true, otherwise it is |
9b371988 PH |
28485 | false. If there is a temporary error while demimeing (for example, &"disk |
28486 | full"&), the condition defers, and the message is temporarily rejected (unless | |
28487 | the condition is on a &%warn%& verb). | |
168e428f PH |
28488 | |
28489 | The right-hand side is expanded before being treated as a list, so you can have | |
9b371988 PH |
28490 | conditions and lookups there. If it expands to an empty string, &"false"&, or |
28491 | zero (&"0"&), no demimeing is done and the condition is false. | |
168e428f | 28492 | |
9b371988 | 28493 | The &%demime%& condition set the following variables: |
168e428f | 28494 | |
9b371988 PH |
28495 | .vlist |
28496 | .vitem &$demime_errorlevel$& | |
f89d2485 | 28497 | .vindex "&$demime_errorlevel$&" |
168e428f PH |
28498 | When an error is detected in a MIME container, this variable contains the |
28499 | severity of the error, as an integer number. The higher the value, the more | |
068aaea8 PH |
28500 | severe the error (the current maximum value is 3). If this variable is unset or |
28501 | zero, no error occurred. | |
168e428f | 28502 | |
9b371988 | 28503 | .vitem &$demime_reason$& |
f89d2485 | 28504 | .vindex "&$demime_reason$&" |
9b371988 | 28505 | When &$demime_errorlevel$& is greater than zero, this variable contains a |
168e428f | 28506 | human-readable text string describing the MIME error that occurred. |
9b371988 | 28507 | .endlist |
168e428f | 28508 | |
9b371988 PH |
28509 | .vlist |
28510 | .vitem &$found_extension$& | |
f89d2485 | 28511 | .vindex "&$found_extension$&" |
9b371988 PH |
28512 | When the &%demime%& condition is true, this variable contains the file |
28513 | extension it found. | |
28514 | .endlist | |
168e428f | 28515 | |
9b371988 PH |
28516 | Both &$demime_errorlevel$& and &$demime_reason$& are set by the first call of |
28517 | the &%demime%& condition, and are not changed on subsequent calls. | |
168e428f | 28518 | |
9b371988 PH |
28519 | If you do not want to check for file extensions, but rather use the &%demime%& |
28520 | condition for unpacking or error checking purposes, pass &"*"& as the | |
168e428f PH |
28521 | right-hand side value. Here is a more elaborate example of how to use this |
28522 | facility: | |
9b371988 PH |
28523 | .code |
28524 | # Reject messages with serious MIME container errors | |
28525 | deny message = Found MIME error ($demime_reason). | |
28526 | demime = * | |
28527 | condition = ${if >{$demime_errorlevel}{2}{1}{0}} | |
168e428f | 28528 | |
9b371988 PH |
28529 | # Reject known virus spreading file extensions. |
28530 | # Accepting these is pretty much braindead. | |
28531 | deny message = contains $found_extension file (blacklisted). | |
28532 | demime = com:vbs:bat:pif:scr | |
168e428f | 28533 | |
9b371988 PH |
28534 | # Freeze .exe and .doc files. Postmaster can |
28535 | # examine them and eventually thaw them. | |
28536 | deny log_message = Another $found_extension file. | |
28537 | demime = exe:doc | |
28538 | control = freeze | |
28539 | .endd | |
4f578862 | 28540 | .ecindex IIDcosca |
168e428f PH |
28541 | |
28542 | ||
28543 | ||
28544 | ||
9b371988 PH |
28545 | . //////////////////////////////////////////////////////////////////////////// |
28546 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 28547 | |
9b371988 PH |
28548 | .chapter "Adding a local scan function to Exim" "CHAPlocalscan" &&& |
28549 | "Local scan function" | |
4f578862 | 28550 | .scindex IIDlosca "&[local_scan()]& function" "description of" |
9b371988 PH |
28551 | .cindex "customizing" "input scan using C function" |
28552 | .cindex "policy control" "by local scan function" | |
168e428f PH |
28553 | In these days of email worms, viruses, and ever-increasing spam, some sites |
28554 | want to apply a lot of checking to messages before accepting them. | |
28555 | ||
9b371988 | 28556 | The content scanning extension (chapter &<<CHAPexiscan>>&) has facilities for |
168e428f | 28557 | passing messages to external virus and spam scanning software. You can also do |
9b371988 | 28558 | a certain amount in Exim itself through string expansions and the &%condition%& |
168e428f | 28559 | condition in the ACL that runs after the SMTP DATA command or the ACL for |
9b371988 | 28560 | non-SMTP messages (see chapter &<<CHAPACL>>&), but this has its limitations. |
168e428f PH |
28561 | |
28562 | To allow for further customization to a site's own requirements, there is the | |
28563 | possibility of linking Exim with a private message scanning function, written | |
28564 | in C. If you want to run code that is written in something other than C, you | |
28565 | can of course use a little C stub to call it. | |
28566 | ||
28567 | The local scan function is run once for every incoming message, at the point | |
28568 | when Exim is just about to accept the message. | |
28569 | It can therefore be used to control non-SMTP messages from local processes as | |
28570 | well as messages arriving via SMTP. | |
28571 | ||
28572 | Exim applies a timeout to calls of the local scan function, and there is an | |
9b371988 PH |
28573 | option called &%local_scan_timeout%& for setting it. The default is 5 minutes. |
28574 | Zero means &"no timeout"&. | |
168e428f PH |
28575 | Exim also sets up signal handlers for SIGSEGV, SIGILL, SIGFPE, and SIGBUS |
28576 | before calling the local scan function, so that the most common types of crash | |
28577 | are caught. If the timeout is exceeded or one of those signals is caught, the | |
28578 | incoming message is rejected with a temporary error if it is an SMTP message. | |
28579 | For a non-SMTP message, the message is dropped and Exim ends with a non-zero | |
28580 | code. The incident is logged on the main and reject logs. | |
28581 | ||
28582 | ||
28583 | ||
f89d2485 | 28584 | .section "Building Exim to use a local scan function" "SECID207" |
9b371988 | 28585 | .cindex "&[local_scan()]& function" "building Exim to use" |
168e428f PH |
28586 | To make use of the local scan function feature, you must tell Exim where your |
28587 | function is before building Exim, by setting LOCAL_SCAN_SOURCE in your | |
9b371988 | 28588 | &_Local/Makefile_&. A recommended place to put it is in the &_Local_& |
168e428f | 28589 | directory, so you might set |
9b371988 PH |
28590 | .code |
28591 | LOCAL_SCAN_SOURCE=Local/local_scan.c | |
28592 | .endd | |
28593 | for example. The function must be called &[local_scan()]&. It is called by | |
168e428f PH |
28594 | Exim after it has received a message, when the success return code is about to |
28595 | be sent. This is after all the ACLs have been run. The return code from your | |
28596 | function controls whether the message is actually accepted or not. There is a | |
28597 | commented template function (that just accepts the message) in the file | |
28598 | _src/local_scan.c_. | |
28599 | ||
28600 | If you want to make use of Exim's run time configuration file to set options | |
9b371988 PH |
28601 | for your &[local_scan()]& function, you must also set |
28602 | .code | |
28603 | LOCAL_SCAN_HAS_OPTIONS=yes | |
28604 | .endd | |
28605 | in &_Local/Makefile_& (see section &<<SECTconoptloc>>& below). | |
168e428f PH |
28606 | |
28607 | ||
28608 | ||
28609 | ||
9b371988 PH |
28610 | .section "API for local_scan()" "SECTapiforloc" |
28611 | .cindex "&[local_scan()]& function" "API description" | |
168e428f | 28612 | You must include this line near the start of your code: |
9b371988 PH |
28613 | .code |
28614 | #include "local_scan.h" | |
28615 | .endd | |
168e428f PH |
28616 | This header file defines a number of variables and other values, and the |
28617 | prototype for the function itself. Exim is coded to use unsigned char values | |
28618 | almost exclusively, and one of the things this header defines is a shorthand | |
9b371988 | 28619 | for &`unsigned char`& called &`uschar`&. |
168e428f PH |
28620 | It also contains the following macro definitions, to simplify casting character |
28621 | strings and pointers to character strings: | |
9b371988 PH |
28622 | .code |
28623 | #define CS (char *) | |
28624 | #define CCS (const char *) | |
28625 | #define CSS (char **) | |
28626 | #define US (unsigned char *) | |
28627 | #define CUS (const unsigned char *) | |
28628 | #define USS (unsigned char **) | |
28629 | .endd | |
28630 | The function prototype for &[local_scan()]& is: | |
28631 | .code | |
28632 | extern int local_scan(int fd, uschar **return_text); | |
28633 | .endd | |
168e428f PH |
28634 | The arguments are as follows: |
28635 | ||
9b371988 PH |
28636 | .ilist |
28637 | &%fd%& is a file descriptor for the file that contains the body of the message | |
168e428f | 28638 | (the -D file). The file is open for reading and writing, but updating it is not |
9b371988 PH |
28639 | recommended. &*Warning*&: You must &'not'& close this file descriptor. |
28640 | ||
168e428f PH |
28641 | The descriptor is positioned at character 19 of the file, which is the first |
28642 | character of the body itself, because the first 19 characters are the message | |
9b371988 | 28643 | id followed by &`-D`& and a newline. If you rewind the file, you should use the |
168e428f PH |
28644 | macro SPOOL_DATA_START_OFFSET to reset to the start of the data, just in |
28645 | case this changes in some future version. | |
9b371988 PH |
28646 | .next |
28647 | &%return_text%& is an address which you can use to return a pointer to a text | |
168e428f | 28648 | string at the end of the function. The value it points to on entry is NULL. |
9b371988 | 28649 | .endlist |
168e428f | 28650 | |
9b371988 | 28651 | The function must return an &%int%& value which is one of the following macros: |
168e428f | 28652 | |
9b371988 PH |
28653 | .vlist |
28654 | .vitem &`LOCAL_SCAN_ACCEPT`& | |
f89d2485 | 28655 | .vindex "&$local_scan_data$&" |
168e428f | 28656 | The message is accepted. If you pass back a string of text, it is saved with |
9b371988 | 28657 | the message, and made available in the variable &$local_scan_data$&. No |
168e428f PH |
28658 | newlines are permitted (if there are any, they are turned into spaces) and the |
28659 | maximum length of text is 1000 characters. | |
28660 | ||
9b371988 | 28661 | .vitem &`LOCAL_SCAN_ACCEPT_FREEZE`& |
168e428f PH |
28662 | This behaves as LOCAL_SCAN_ACCEPT, except that the accepted message is |
28663 | queued without immediate delivery, and is frozen. | |
28664 | ||
9b371988 | 28665 | .vitem &`LOCAL_SCAN_ACCEPT_QUEUE`& |
168e428f PH |
28666 | This behaves as LOCAL_SCAN_ACCEPT, except that the accepted message is |
28667 | queued without immediate delivery. | |
28668 | ||
9b371988 | 28669 | .vitem &`LOCAL_SCAN_REJECT`& |
168e428f | 28670 | The message is rejected; the returned text is used as an error message which is |
9b371988 PH |
28671 | passed back to the sender and which is also logged. Newlines are permitted &-- |
28672 | they cause a multiline response for SMTP rejections, but are converted to | |
28673 | &`\n`& in log lines. If no message is given, &"Administrative prohibition"& is | |
28674 | used. | |
168e428f | 28675 | |
9b371988 | 28676 | .vitem &`LOCAL_SCAN_TEMPREJECT`& |
168e428f | 28677 | The message is temporarily rejected; the returned text is used as an error |
9b371988 PH |
28678 | message as for LOCAL_SCAN_REJECT. If no message is given, &"Temporary local |
28679 | problem"& is used. | |
168e428f | 28680 | |
9b371988 | 28681 | .vitem &`LOCAL_SCAN_REJECT_NOLOGHDR`& |
168e428f PH |
28682 | This behaves as LOCAL_SCAN_REJECT, except that the header of the rejected |
28683 | message is not written to the reject log. It has the effect of unsetting the | |
9b371988 PH |
28684 | &%rejected_header%& log selector for just this rejection. If |
28685 | &%rejected_header%& is already unset (see the discussion of the | |
28686 | &%log_selection%& option in section &<<SECTlogselector>>&), this code is the | |
28687 | same as LOCAL_SCAN_REJECT. | |
168e428f | 28688 | |
9b371988 | 28689 | .vitem &`LOCAL_SCAN_TEMPREJECT_NOLOGHDR`& |
168e428f PH |
28690 | This code is a variation of LOCAL_SCAN_TEMPREJECT in the same way that |
28691 | LOCAL_SCAN_REJECT_NOLOGHDR is a variation of LOCAL_SCAN_REJECT. | |
9b371988 | 28692 | .endlist |
168e428f PH |
28693 | |
28694 | If the message is not being received by interactive SMTP, rejections are | |
9b371988 PH |
28695 | reported by writing to &%stderr%& or by sending an email, as configured by the |
28696 | &%-oe%& command line options. | |
168e428f PH |
28697 | |
28698 | ||
28699 | ||
9b371988 PH |
28700 | .section "Configuration options for local_scan()" "SECTconoptloc" |
28701 | .cindex "&[local_scan()]& function" "configuration options" | |
168e428f | 28702 | It is possible to have option settings in the main configuration file |
9b371988 | 28703 | that set values in static variables in the &[local_scan()]& module. If you |
168e428f | 28704 | want to do this, you must have the line |
9b371988 PH |
28705 | .code |
28706 | LOCAL_SCAN_HAS_OPTIONS=yes | |
28707 | .endd | |
28708 | in your &_Local/Makefile_& when you build Exim. (This line is in | |
28709 | &_OS/Makefile-Default_&, commented out). Then, in the &[local_scan()]& source | |
28710 | file, you must define static variables to hold the option values, and a table | |
28711 | to define them. | |
28712 | ||
28713 | The table must be a vector called &%local_scan_options%&, of type | |
28714 | &`optionlist`&. Each entry is a triplet, consisting of a name, an option type, | |
168e428f | 28715 | and a pointer to the variable that holds the value. The entries must appear in |
9b371988 PH |
28716 | alphabetical order. Following &%local_scan_options%& you must also define a |
28717 | variable called &%local_scan_options_count%& that contains the number of | |
168e428f | 28718 | entries in the table. Here is a short example, showing two kinds of option: |
9b371988 PH |
28719 | .code |
28720 | static int my_integer_option = 42; | |
28721 | static uschar *my_string_option = US"a default string"; | |
28722 | ||
28723 | optionlist local_scan_options[] = { | |
28724 | { "my_integer", opt_int, &my_integer_option }, | |
28725 | { "my_string", opt_stringptr, &my_string_option } | |
28726 | }; | |
28727 | ||
28728 | int local_scan_options_count = | |
28729 | sizeof(local_scan_options)/sizeof(optionlist); | |
28730 | .endd | |
168e428f PH |
28731 | The values of the variables can now be changed from Exim's runtime |
28732 | configuration file by including a local scan section as in this example: | |
9b371988 PH |
28733 | .code |
28734 | begin local_scan | |
28735 | my_integer = 99 | |
28736 | my_string = some string of text... | |
28737 | .endd | |
168e428f PH |
28738 | The available types of option data are as follows: |
28739 | ||
9b371988 PH |
28740 | .vlist |
28741 | .vitem &*opt_bool*& | |
168e428f | 28742 | This specifies a boolean (true/false) option. The address should point to a |
9b371988 PH |
28743 | variable of type &`BOOL`&, which will be set to TRUE or FALSE, which are macros |
28744 | that are defined as &"1"& and &"0"&, respectively. If you want to detect | |
168e428f PH |
28745 | whether such a variable has been set at all, you can initialize it to |
28746 | TRUE_UNSET. (BOOL variables are integers underneath, so can hold more than two | |
28747 | values.) | |
28748 | ||
9b371988 | 28749 | .vitem &*opt_fixed*& |
168e428f | 28750 | This specifies a fixed point number, such as is used for load averages. |
9b371988 | 28751 | The address should point to a variable of type &`int`&. The value is stored |
168e428f PH |
28752 | multiplied by 1000, so, for example, 1.4142 is truncated and stored as 1414. |
28753 | ||
9b371988 | 28754 | .vitem &*opt_int*& |
168e428f | 28755 | This specifies an integer; the address should point to a variable of type |
9b371988 | 28756 | &`int`&. The value may be specified in any of the integer formats accepted by |
168e428f PH |
28757 | Exim. |
28758 | ||
9b371988 PH |
28759 | .vitem &*opt_mkint*& |
28760 | This is the same as &%opt_int%&, except that when such a value is output in a | |
28761 | &%-bP%& listing, if it is an exact number of kilobytes or megabytes, it is | |
168e428f PH |
28762 | printed with the suffix K or M. |
28763 | ||
9b371988 | 28764 | .vitem &*opt_octint*& |
f89d2485 | 28765 | This also specifies an integer, but the value is always interpreted as an |
168e428f PH |
28766 | octal integer, whether or not it starts with the digit zero, and it is |
28767 | always output in octal. | |
28768 | ||
9b371988 | 28769 | .vitem &*opt_stringptr*& |
168e428f | 28770 | This specifies a string value; the address must be a pointer to a |
9b371988 | 28771 | variable that points to a string (for example, of type &`uschar *`&). |
168e428f | 28772 | |
9b371988 | 28773 | .vitem &*opt_time*& |
168e428f | 28774 | This specifies a time interval value. The address must point to a variable of |
9b371988 PH |
28775 | type &`int`&. The value that is placed there is a number of seconds. |
28776 | .endlist | |
168e428f | 28777 | |
9b371988 PH |
28778 | If the &%-bP%& command line option is followed by &`local_scan`&, Exim prints |
28779 | out the values of all the &[local_scan()]& options. | |
168e428f PH |
28780 | |
28781 | ||
28782 | ||
f89d2485 | 28783 | .section "Available Exim variables" "SECID208" |
9b371988 PH |
28784 | .cindex "&[local_scan()]& function" "available Exim variables" |
28785 | The header &_local_scan.h_& gives you access to a number of C variables. These | |
168e428f | 28786 | are the only ones that are guaranteed to be maintained from release to release. |
595028e4 PH |
28787 | Note, however, that you can obtain the value of any Exim expansion variable, |
28788 | including &$recipients$&, by calling &'expand_string()'&. The exported | |
28789 | C variables are as follows: | |
168e428f | 28790 | |
9b371988 | 28791 | .vlist |
595028e4 | 28792 | .vitem &*int&~body_linecount*& |
595028e4 PH |
28793 | This variable contains the number of lines in the message's body. |
28794 | ||
28795 | .vitem &*int&~body_zerocount*& | |
28796 | This variable contains the number of binary zero bytes in the message's body. | |
595028e4 | 28797 | |
9b371988 | 28798 | .vitem &*unsigned&~int&~debug_selector*& |
168e428f PH |
28799 | This variable is set to zero when no debugging is taking place. Otherwise, it |
28800 | is a bitmap of debugging selectors. Two bits are identified for use in | |
9b371988 PH |
28801 | &[local_scan()]&; they are defined as macros: |
28802 | ||
28803 | .ilist | |
28804 | The &`D_v`& bit is set when &%-v%& was present on the command line. This is a | |
28805 | testing option that is not privileged &-- any caller may set it. All the | |
168e428f PH |
28806 | other selector bits can be set only by admin users. |
28807 | ||
9b371988 PH |
28808 | .next |
28809 | The &`D_local_scan`& bit is provided for use by &[local_scan()]&; it is set | |
28810 | by the &`+local_scan`& debug selector. It is not included in the default set | |
168e428f | 28811 | of debugging bits. |
9b371988 | 28812 | .endlist ilist |
168e428f | 28813 | |
9b371988 PH |
28814 | Thus, to write to the debugging output only when &`+local_scan`& has been |
28815 | selected, you should use code like this: | |
28816 | .code | |
28817 | if ((debug_selector & D_local_scan) != 0) | |
28818 | debug_printf("xxx", ...); | |
28819 | .endd | |
28820 | .vitem &*uschar&~*expand_string_message*& | |
28821 | After a failing call to &'expand_string()'& (returned value NULL), the | |
28822 | variable &%expand_string_message%& contains the error message, zero-terminated. | |
28823 | ||
28824 | .vitem &*header_line&~*header_list*& | |
28825 | A pointer to a chain of header lines. The &%header_line%& structure is | |
28826 | discussed below. | |
28827 | ||
28828 | .vitem &*header_line&~*header_last*& | |
168e428f PH |
28829 | A pointer to the last of the header lines. |
28830 | ||
9b371988 PH |
28831 | .vitem &*uschar&~*headers_charset*& |
28832 | The value of the &%headers_charset%& configuration option. | |
168e428f | 28833 | |
9b371988 | 28834 | .vitem &*BOOL&~host_checking*& |
168e428f | 28835 | This variable is TRUE during a host checking session that is initiated by the |
9b371988 | 28836 | &%-bh%& command line option. |
168e428f | 28837 | |
9b371988 | 28838 | .vitem &*uschar&~*interface_address*& |
168e428f PH |
28839 | The IP address of the interface that received the message, as a string. This |
28840 | is NULL for locally submitted messages. | |
28841 | ||
9b371988 | 28842 | .vitem &*int&~interface_port*& |
3cb1b51e PH |
28843 | The port on which this message was received. When testing with the &%-bh%& |
28844 | command line option, the value of this variable is -1 unless a port has been | |
28845 | specified via the &%-oMi%& option. | |
168e428f | 28846 | |
9b371988 | 28847 | .vitem &*uschar&~*message_id*& |
d1e83bff | 28848 | This variable contains Exim's message id for the incoming message (the value of |
9b371988 | 28849 | &$message_exim_id$&) as a zero-terminated string. |
168e428f | 28850 | |
9b371988 | 28851 | .vitem &*uschar&~*received_protocol*& |
168e428f PH |
28852 | The name of the protocol by which the message was received. |
28853 | ||
9b371988 | 28854 | .vitem &*int&~recipients_count*& |
168e428f PH |
28855 | The number of accepted recipients. |
28856 | ||
9b371988 PH |
28857 | .vitem &*recipient_item&~*recipients_list*& |
28858 | .cindex "recipient" "adding in local scan" | |
28859 | .cindex "recipient" "removing in local scan" | |
28860 | The list of accepted recipients, held in a vector of length | |
28861 | &%recipients_count%&. The &%recipient_item%& structure is discussed below. You | |
28862 | can add additional recipients by calling &'receive_add_recipient()'& (see | |
f89d2485 PH |
28863 | below). You can delete recipients by removing them from the vector and |
28864 | adjusting the value in &%recipients_count%&. In particular, by setting | |
9b371988 PH |
28865 | &%recipients_count%& to zero you remove all recipients. If you then return the |
28866 | value &`LOCAL_SCAN_ACCEPT`&, the message is accepted, but immediately | |
28867 | blackholed. To replace the recipients, you can set &%recipients_count%& to zero | |
28868 | and then call &'receive_add_recipient()'& as often as needed. | |
28869 | ||
28870 | .vitem &*uschar&~*sender_address*& | |
168e428f PH |
28871 | The envelope sender address. For bounce messages this is the empty string. |
28872 | ||
9b371988 | 28873 | .vitem &*uschar&~*sender_host_address*& |
168e428f PH |
28874 | The IP address of the sending host, as a string. This is NULL for |
28875 | locally-submitted messages. | |
28876 | ||
9b371988 | 28877 | .vitem &*uschar&~*sender_host_authenticated*& |
168e428f PH |
28878 | The name of the authentication mechanism that was used, or NULL if the message |
28879 | was not received over an authenticated SMTP connection. | |
28880 | ||
9b371988 | 28881 | .vitem &*uschar&~*sender_host_name*& |
168e428f PH |
28882 | The name of the sending host, if known. |
28883 | ||
9b371988 | 28884 | .vitem &*int&~sender_host_port*& |
168e428f PH |
28885 | The port on the sending host. |
28886 | ||
9b371988 | 28887 | .vitem &*BOOL&~smtp_input*& |
168e428f PH |
28888 | This variable is TRUE for all SMTP input, including BSMTP. |
28889 | ||
9b371988 | 28890 | .vitem &*BOOL&~smtp_batched_input*& |
168e428f PH |
28891 | This variable is TRUE for BSMTP input. |
28892 | ||
9b371988 | 28893 | .vitem &*int&~store_pool*& |
168e428f | 28894 | The contents of this variable control which pool of memory is used for new |
9b371988 PH |
28895 | requests. See section &<<SECTmemhanloc>>& for details. |
28896 | .endlist | |
168e428f PH |
28897 | |
28898 | ||
f89d2485 | 28899 | .section "Structure of header lines" "SECID209" |
9b371988 PH |
28900 | The &%header_line%& structure contains the members listed below. |
28901 | You can add additional header lines by calling the &'header_add()'& function | |
168e428f | 28902 | (see below). You can cause header lines to be ignored (deleted) by setting |
9b371988 | 28903 | their type to *. |
168e428f PH |
28904 | |
28905 | ||
9b371988 PH |
28906 | .vlist |
28907 | .vitem &*struct&~header_line&~*next*& | |
168e428f PH |
28908 | A pointer to the next header line, or NULL for the last line. |
28909 | ||
9b371988 | 28910 | .vitem &*int&~type*& |
168e428f | 28911 | A code identifying certain headers that Exim recognizes. The codes are printing |
9b371988 PH |
28912 | characters, and are documented in chapter &<<CHAPspool>>& of this manual. |
28913 | Notice in particular that any header line whose type is * is not transmitted | |
28914 | with the message. This flagging is used for header lines that have been | |
28915 | rewritten, or are to be removed (for example, &'Envelope-sender:'& header | |
28916 | lines.) Effectively, * means &"deleted"&. | |
168e428f | 28917 | |
9b371988 | 28918 | .vitem &*int&~slen*& |
168e428f PH |
28919 | The number of characters in the header line, including the terminating and any |
28920 | internal newlines. | |
28921 | ||
9b371988 | 28922 | .vitem &*uschar&~*text*& |
168e428f PH |
28923 | A pointer to the text of the header. It always ends with a newline, followed by |
28924 | a zero byte. Internal newlines are preserved. | |
9b371988 | 28925 | .endlist |
168e428f PH |
28926 | |
28927 | ||
28928 | ||
f89d2485 | 28929 | .section "Structure of recipient items" "SECID210" |
9b371988 | 28930 | The &%recipient_item%& structure contains these members: |
168e428f | 28931 | |
9b371988 PH |
28932 | .vlist |
28933 | .vitem &*uschar&~*address*& | |
168e428f PH |
28934 | This is a pointer to the recipient address as it was received. |
28935 | ||
9b371988 | 28936 | .vitem &*int&~pno*& |
168e428f | 28937 | This is used in later Exim processing when top level addresses are created by |
9b371988 PH |
28938 | the &%one_time%& option. It is not relevant at the time &[local_scan()]& is run |
28939 | and must always contain -1 at this stage. | |
168e428f | 28940 | |
9b371988 | 28941 | .vitem &*uschar&~*errors_to*& |
168e428f PH |
28942 | If this value is not NULL, bounce messages caused by failing to deliver to the |
28943 | recipient are sent to the address it contains. In other words, it overrides the | |
9b371988 PH |
28944 | envelope sender for this one recipient. (Compare the &%errors_to%& generic |
28945 | router option.) If a &[local_scan()]& function sets an &%errors_to%& field to | |
28946 | an unqualified address, Exim qualifies it using the domain from | |
28947 | &%qualify_recipient%&. When &[local_scan()]& is called, the &%errors_to%& field | |
28948 | is NULL for all recipients. | |
28949 | .endlist | |
168e428f PH |
28950 | |
28951 | ||
28952 | ||
f89d2485 | 28953 | .section "Available Exim functions" "SECID211" |
9b371988 PH |
28954 | .cindex "&[local_scan()]& function" "available Exim functions" |
28955 | The header &_local_scan.h_& gives you access to a number of Exim functions. | |
168e428f PH |
28956 | These are the only ones that are guaranteed to be maintained from release to |
28957 | release: | |
28958 | ||
9b371988 PH |
28959 | .vlist |
28960 | .vitem "&*pid_t&~child_open(uschar&~**argv,&~uschar&~**envp,&~int&~newumask,&&& | |
28961 | &~int&~*infdptr,&~int&~*outfdptr, &~&~BOOL&~make_leader)*&" | |
168e428f PH |
28962 | |
28963 | This function creates a child process that runs the command specified by | |
9b371988 PH |
28964 | &%argv%&. The environment for the process is specified by &%envp%&, which can |
28965 | be NULL if no environment variables are to be passed. A new umask is supplied | |
28966 | for the process in &%newumask%&. | |
28967 | ||
168e428f | 28968 | Pipes to the standard input and output of the new process are set up |
9b371988 | 28969 | and returned to the caller via the &%infdptr%& and &%outfdptr%& arguments. The |
168e428f | 28970 | standard error is cloned to the standard output. If there are any file |
9b371988 | 28971 | descriptors &"in the way"& in the new process, they are closed. If the final |
168e428f | 28972 | argument is TRUE, the new process is made into a process group leader. |
9b371988 | 28973 | |
168e428f PH |
28974 | The function returns the pid of the new process, or -1 if things go wrong. |
28975 | ||
9b371988 | 28976 | .vitem &*int&~child_close(pid_t&~pid,&~int&~timeout)*& |
168e428f PH |
28977 | This function waits for a child process to terminate, or for a timeout (in |
28978 | seconds) to expire. A timeout value of zero means wait as long as it takes. The | |
28979 | return value is as follows: | |
9b371988 PH |
28980 | |
28981 | .ilist | |
28982 | >= 0 | |
28983 | ||
28984 | The process terminated by a normal exit and the value is the process | |
28985 | ending status. | |
28986 | ||
28987 | .next | |
28988 | < 0 and > &--256 | |
28989 | ||
168e428f PH |
28990 | The process was terminated by a signal and the value is the negation of the |
28991 | signal number. | |
28992 | ||
9b371988 PH |
28993 | .next |
28994 | &--256 | |
168e428f | 28995 | |
9b371988 PH |
28996 | The process timed out. |
28997 | .next | |
28998 | &--257 | |
168e428f | 28999 | |
9b371988 PH |
29000 | The was some other error in wait(); &%errno%& is still set. |
29001 | .endlist | |
168e428f | 29002 | |
9b371988 | 29003 | .vitem &*pid_t&~child_open_exim(int&~*fd)*& |
168e428f | 29004 | This function provide you with a means of submitting a new message to |
9b371988 | 29005 | Exim. (Of course, you can also call &_/usr/sbin/sendmail_& yourself if you |
168e428f PH |
29006 | want, but this packages it all up for you.) The function creates a pipe, |
29007 | forks a subprocess that is running | |
9b371988 PH |
29008 | .code |
29009 | exim -t -oem -oi -f <> | |
29010 | .endd | |
29011 | and returns to you (via the &`int *`& argument) a file descriptor for the pipe | |
168e428f PH |
29012 | that is connected to the standard input. The yield of the function is the PID |
29013 | of the subprocess. You can then write a message to the file descriptor, with | |
9b371988 PH |
29014 | recipients in &'To:'&, &'Cc:'&, and/or &'Bcc:'& header lines. |
29015 | ||
29016 | When you have finished, call &'child_close()'& to wait for the process to | |
168e428f PH |
29017 | finish and to collect its ending status. A timeout value of zero is usually |
29018 | fine in this circumstance. Unless you have made a mistake with the recipient | |
29019 | addresses, you should get a return code of zero. | |
29020 | ||
4f578862 | 29021 | |
4f578862 PH |
29022 | .vitem &*pid_t&~child_open_exim2(int&~*fd,&~uschar&~*sender,&~uschar&~&&& |
29023 | *sender_authentication)*& | |
29024 | This function is a more sophisticated version of &'child_open()'&. The command | |
29025 | that it runs is: | |
29026 | .display | |
29027 | &`exim -t -oem -oi -f `&&'sender'&&` -oMas `&&'sender_authentication'& | |
29028 | .endd | |
29029 | The third argument may be NULL, in which case the &%-oMas%& option is omitted. | |
4f578862 PH |
29030 | |
29031 | ||
9b371988 PH |
29032 | .vitem &*void&~debug_printf(char&~*,&~...)*& |
29033 | This is Exim's debugging function, with arguments as for &'(printf()'&. The | |
168e428f | 29034 | output is written to the standard error stream. If no debugging is selected, |
9b371988 PH |
29035 | calls to &'debug_printf()'& have no effect. Normally, you should make calls |
29036 | conditional on the &`local_scan`& debug selector by coding like this: | |
29037 | .code | |
29038 | if ((debug_selector & D_local_scan) != 0) | |
29039 | debug_printf("xxx", ...); | |
29040 | .endd | |
4f578862 | 29041 | |
9b371988 | 29042 | .vitem &*uschar&~*expand_string(uschar&~*string)*& |
168e428f PH |
29043 | This is an interface to Exim's string expansion code. The return value is the |
29044 | expanded string, or NULL if there was an expansion failure. | |
9b371988 | 29045 | The C variable &%expand_string_message%& contains an error message after an |
168e428f PH |
29046 | expansion failure. If expansion does not change the string, the return value is |
29047 | the pointer to the input string. Otherwise, the return value points to a new | |
9b371988 PH |
29048 | block of memory that was obtained by a call to &'store_get()'&. See section |
29049 | &<<SECTmemhanloc>>& below for a discussion of memory handling. | |
168e428f | 29050 | |
9b371988 | 29051 | .vitem &*void&~header_add(int&~type,&~char&~*format,&~...)*& |
168e428f PH |
29052 | This function allows you to an add additional header line at the end of the |
29053 | existing ones. The first argument is the type, and should normally be a space | |
29054 | character. The second argument is a format string and any number of | |
9b371988 PH |
29055 | substitution arguments as for &[sprintf()]&. You may include internal newlines |
29056 | if you want, and you must ensure that the string ends with a newline. | |
168e428f | 29057 | |
9b371988 PH |
29058 | .vitem "&*void&~header_add_at_position(BOOL&~after,&~uschar&~*name,&~&&& |
29059 | BOOL&~topnot,&~int&~type,&~char&~*format, &~&~...)*&" | |
168e428f | 29060 | This function adds a new header line at a specified point in the header |
9b371988 PH |
29061 | chain. The header itself is specified as for &'header_add()'&. |
29062 | ||
29063 | If &%name%& is NULL, the new header is added at the end of the chain if | |
29064 | &%after%& is true, or at the start if &%after%& is false. If &%name%& is not | |
29065 | NULL, the header lines are searched for the first non-deleted header that | |
29066 | matches the name. If one is found, the new header is added before it if | |
29067 | &%after%& is false. If &%after%& is true, the new header is added after the | |
29068 | found header and any adjacent subsequent ones with the same name (even if | |
29069 | marked &"deleted"&). If no matching non-deleted header is found, the &%topnot%& | |
29070 | option controls where the header is added. If it is true, addition is at the | |
29071 | top; otherwise at the bottom. Thus, to add a header after all the &'Received:'& | |
29072 | headers, or at the top if there are no &'Received:'& headers, you could use | |
29073 | .code | |
29074 | header_add_at_position(TRUE, US"Received", TRUE, | |
29075 | ' ', "X-xxx: ..."); | |
29076 | .endd | |
29077 | Normally, there is always at least one non-deleted &'Received:'& header, but | |
29078 | there may not be if &%received_header_text%& expands to an empty string. | |
29079 | ||
29080 | ||
29081 | .vitem &*void&~header_remove(int&~occurrence,&~uschar&~*name)*& | |
29082 | This function removes header lines. If &%occurrence%& is zero or negative, all | |
168e428f PH |
29083 | occurrences of the header are removed. If occurrence is greater than zero, that |
29084 | particular instance of the header is removed. If no header(s) can be found that | |
29085 | match the specification, the function does nothing. | |
29086 | ||
29087 | ||
9b371988 PH |
29088 | .vitem "&*BOOL&~header_testname(header_line&~*hdr,&~uschar&~*name,&~&&& |
29089 | int&~length,&~BOOL&~notdel)*&" | |
168e428f | 29090 | This function tests whether the given header has the given name. It is not just |
068aaea8 | 29091 | a string comparison, because white space is permitted between the name and the |
9b371988 PH |
29092 | colon. If the &%notdel%& argument is true, a false return is forced for all |
29093 | &"deleted"& headers; otherwise they are not treated specially. For example: | |
29094 | .code | |
29095 | if (header_testname(h, US"X-Spam", 6, TRUE)) ... | |
29096 | .endd | |
29097 | .vitem &*uschar&~*lss_b64encode(uschar&~*cleartext,&~int&~length)*& | |
29098 | .cindex "base64 encoding" "functions for &[local_scan()]& use" | |
168e428f PH |
29099 | This function base64-encodes a string, which is passed by address and length. |
29100 | The text may contain bytes of any value, including zero. The result is passed | |
9b371988 | 29101 | back in dynamic memory that is obtained by calling &'store_get()'&. It is |
168e428f PH |
29102 | zero-terminated. |
29103 | ||
9b371988 | 29104 | .vitem &*int&~lss_b64decode(uschar&~*codetext,&~uschar&~**cleartext)*& |
168e428f PH |
29105 | This function decodes a base64-encoded string. Its arguments are a |
29106 | zero-terminated base64-encoded string and the address of a variable that is set | |
29107 | to point to the result, which is in dynamic memory. The length of the decoded | |
29108 | string is the yield of the function. If the input is invalid base64 data, the | |
29109 | yield is -1. A zero byte is added to the end of the output string to make it | |
29110 | easy to interpret as a C string (assuming it contains no zeros of its own). The | |
29111 | added zero byte is not included in the returned count. | |
29112 | ||
9b371988 | 29113 | .vitem &*int&~lss_match_domain(uschar&~*domain,&~uschar&~*list)*& |
168e428f PH |
29114 | This function checks for a match in a domain list. Domains are always |
29115 | matched caselessly. The return value is one of the following: | |
9b371988 PH |
29116 | .display |
29117 | &`OK `& match succeeded | |
29118 | &`FAIL `& match failed | |
29119 | &`DEFER `& match deferred | |
29120 | .endd | |
168e428f PH |
29121 | DEFER is usually caused by some kind of lookup defer, such as the |
29122 | inability to contact a database. | |
29123 | ||
9b371988 PH |
29124 | .vitem "&*int&~lss_match_local_part(uschar&~*localpart,&~uschar&~*list,&~&&& |
29125 | BOOL&~caseless)*&" | |
168e428f PH |
29126 | This function checks for a match in a local part list. The third argument |
29127 | controls case-sensitivity. The return values are as for | |
9b371988 | 29128 | &'lss_match_domain()'&. |
168e428f | 29129 | |
9b371988 PH |
29130 | .vitem "&*int&~lss_match_address(uschar&~*address,&~uschar&~*list,&~&&& |
29131 | BOOL&~caseless)*&" | |
168e428f PH |
29132 | This function checks for a match in an address list. The third argument |
29133 | controls the case-sensitivity of the local part match. The domain is always | |
9b371988 | 29134 | matched caselessly. The return values are as for &'lss_match_domain()'&. |
168e428f | 29135 | |
9b371988 PH |
29136 | .vitem "&*int&~lss_match_host(uschar&~*host_name,&~uschar&~*host_address,&~&&& |
29137 | uschar&~*list)*&" | |
168e428f PH |
29138 | This function checks for a match in a host list. The most common usage is |
29139 | expected to be | |
9b371988 PH |
29140 | .code |
29141 | lss_match_host(sender_host_name, sender_host_address, ...) | |
29142 | .endd | |
f89d2485 | 29143 | .vindex "&$sender_host_address$&" |
068aaea8 | 29144 | An empty address field matches an empty item in the host list. If the host name |
9b371988 | 29145 | is NULL, the name corresponding to &$sender_host_address$& is automatically |
068aaea8 | 29146 | looked up if a host name is required to match an item in the list. The return |
9b371988 | 29147 | values are as for &'lss_match_domain()'&, but in addition, &'lss_match_host()'& |
068aaea8 PH |
29148 | returns ERROR in the case when it had to look up a host name, but the lookup |
29149 | failed. | |
168e428f | 29150 | |
9b371988 PH |
29151 | .vitem "&*void&~log_write(unsigned&~int&~selector,&~int&~which,&~char&~&&& |
29152 | *format,&~...)*&" | |
168e428f | 29153 | This function writes to Exim's log files. The first argument should be zero (it |
9b371988 PH |
29154 | is concerned with &%log_selector%&). The second argument can be &`LOG_MAIN`& or |
29155 | &`LOG_REJECT`& or &`LOG_PANIC`& or the inclusive &"or"& of any combination of | |
29156 | them. It specifies to which log or logs the message is written. The remaining | |
168e428f PH |
29157 | arguments are a format and relevant insertion arguments. The string should not |
29158 | contain any newlines, not even at the end. | |
29159 | ||
29160 | ||
9b371988 | 29161 | .vitem &*void&~receive_add_recipient(uschar&~*address,&~int&~pno)*& |
168e428f PH |
29162 | This function adds an additional recipient to the message. The first argument |
29163 | is the recipient address. If it is unqualified (has no domain), it is qualified | |
9b371988 PH |
29164 | with the &%qualify_recipient%& domain. The second argument must always be -1. |
29165 | ||
29166 | This function does not allow you to specify a private &%errors_to%& address (as | |
29167 | described with the structure of &%recipient_item%& above), because it pre-dates | |
168e428f PH |
29168 | the addition of that field to the structure. However, it is easy to add such a |
29169 | value afterwards. For example: | |
9b371988 | 29170 | .code |
db9452a9 PH |
29171 | receive_add_recipient(US"monitor@mydom.example", -1); |
29172 | recipients_list[recipients_count-1].errors_to = | |
29173 | US"postmaster@mydom.example"; | |
9b371988 | 29174 | .endd |
168e428f | 29175 | |
9b371988 | 29176 | .vitem &*BOOL&~receive_remove_recipient(uschar&~*recipient)*& |
168e428f PH |
29177 | This is a convenience function to remove a named recipient from the list of |
29178 | recipients. It returns true if a recipient was removed, and false if no | |
29179 | matching recipient could be found. The argument must be a complete email | |
29180 | address. | |
9b371988 | 29181 | .endlist |
168e428f PH |
29182 | |
29183 | ||
9b371988 PH |
29184 | .cindex "RFC 2047" |
29185 | .vlist | |
29186 | .vitem "&*uschar&~rfc2047_decode(uschar&~*string,&~BOOL&~lencheck,&&& | |
29187 | &~uschar&~*target,&~int&~zeroval,&~int&~*lenptr, &~&~uschar&~**error)*&" | |
168e428f | 29188 | This function decodes strings that are encoded according to RFC 2047. Typically |
9b371988 | 29189 | these are the contents of header lines. First, each &"encoded word"& is decoded |
168e428f | 29190 | from the Q or B encoding into a byte-string. Then, if provided with the name of |
9b371988 | 29191 | a charset encoding, and if the &[iconv()]& function is available, an attempt is |
168e428f PH |
29192 | made to translate the result to the named character set. If this fails, the |
29193 | binary string is returned with an error message. | |
9b371988 PH |
29194 | |
29195 | The first argument is the string to be decoded. If &%lencheck%& is TRUE, the | |
168e428f PH |
29196 | maximum MIME word length is enforced. The third argument is the target |
29197 | encoding, or NULL if no translation is wanted. | |
9b371988 PH |
29198 | |
29199 | .cindex "binary zero" "in RFC 2047 decoding" | |
29200 | .cindex "RFC 2047" "binary zero in" | |
168e428f | 29201 | If a binary zero is encountered in the decoded string, it is replaced by the |
9b371988 | 29202 | contents of the &%zeroval%& argument. For use with Exim headers, the value must |
168e428f | 29203 | not be 0 because header lines are handled as zero-terminated strings. |
9b371988 | 29204 | |
168e428f | 29205 | The function returns the result of processing the string, zero-terminated; if |
9b371988 PH |
29206 | &%lenptr%& is not NULL, the length of the result is set in the variable to |
29207 | which it points. When &%zeroval%& is 0, &%lenptr%& should not be NULL. | |
29208 | ||
29209 | If an error is encountered, the function returns NULL and uses the &%error%& | |
29210 | argument to return an error message. The variable pointed to by &%error%& is | |
29211 | set to NULL if there is no error; it may be set non-NULL even when the function | |
168e428f PH |
29212 | returns a non-NULL value if decoding was successful, but there was a problem |
29213 | with translation. | |
29214 | ||
29215 | ||
9b371988 PH |
29216 | .vitem &*int&~smtp_fflush(void)*& |
29217 | This function is used in conjunction with &'smtp_printf()'&, as described | |
168e428f PH |
29218 | below. |
29219 | ||
9b371988 PH |
29220 | .vitem &*void&~smtp_printf(char&~*,&~...)*& |
29221 | The arguments of this function are like &[printf()]&; it writes to the SMTP | |
168e428f PH |
29222 | output stream. You should use this function only when there is an SMTP output |
29223 | stream, that is, when the incoming message is being received via interactive | |
9b371988 PH |
29224 | SMTP. This is the case when &%smtp_input%& is TRUE and &%smtp_batched_input%& |
29225 | is FALSE. If you want to test for an incoming message from another host (as | |
29226 | opposed to a local process that used the &%-bs%& command line option), you can | |
29227 | test the value of &%sender_host_address%&, which is non-NULL when a remote host | |
168e428f | 29228 | is involved. |
9b371988 PH |
29229 | |
29230 | If an SMTP TLS connection is established, &'smtp_printf()'& uses the TLS | |
168e428f | 29231 | output function, so it can be used for all forms of SMTP connection. |
9b371988 PH |
29232 | |
29233 | Strings that are written by &'smtp_printf()'& from within &[local_scan()]& | |
168e428f PH |
29234 | must start with an appropriate response code: 550 if you are going to return |
29235 | LOCAL_SCAN_REJECT, 451 if you are going to return | |
29236 | LOCAL_SCAN_TEMPREJECT, and 250 otherwise. Because you are writing the | |
29237 | initial lines of a multi-line response, the code must be followed by a hyphen | |
29238 | to indicate that the line is not the final response line. You must also ensure | |
29239 | that the lines you write terminate with CRLF. For example: | |
9b371988 PH |
29240 | .code |
29241 | smtp_printf("550-this is some extra info\r\n"); | |
29242 | return LOCAL_SCAN_REJECT; | |
29243 | .endd | |
168e428f | 29244 | Note that you can also create multi-line responses by including newlines in |
9b371988 PH |
29245 | the data returned via the &%return_text%& argument. The added value of using |
29246 | &'smtp_printf()'& is that, for instance, you could introduce delays between | |
168e428f | 29247 | multiple output lines. |
9b371988 PH |
29248 | |
29249 | The &'smtp_printf()'& function does not return any error indication, because it | |
168e428f PH |
29250 | does not automatically flush pending output, and therefore does not test |
29251 | the state of the stream. (In the main code of Exim, flushing and error | |
29252 | detection is done when Exim is ready for the next SMTP input command.) If | |
29253 | you want to flush the output and check for an error (for example, the | |
9b371988 | 29254 | dropping of a TCP/IP connection), you can call &'smtp_fflush()'&, which has no |
168e428f PH |
29255 | arguments. It flushes the output stream, and returns a non-zero value if there |
29256 | is an error. | |
29257 | ||
9b371988 | 29258 | .vitem &*void&~*store_get(int)*& |
168e428f PH |
29259 | This function accesses Exim's internal store (memory) manager. It gets a new |
29260 | chunk of memory whose size is given by the argument. Exim bombs out if it ever | |
29261 | runs out of memory. See the next section for a discussion of memory handling. | |
29262 | ||
9b371988 PH |
29263 | .vitem &*void&~*store_get_perm(int)*& |
29264 | This function is like &'store_get()'&, but it always gets memory from the | |
168e428f PH |
29265 | permanent pool. See the next section for a discussion of memory handling. |
29266 | ||
9b371988 | 29267 | .vitem &*uschar&~*string_copy(uschar&~*string)*& |
168e428f PH |
29268 | See below. |
29269 | ||
9b371988 | 29270 | .vitem &*uschar&~*string_copyn(uschar&~*string,&~int&~length)*& |
168e428f PH |
29271 | See below. |
29272 | ||
9b371988 | 29273 | .vitem &*uschar&~*string_sprintf(char&~*format,&~...)*& |
168e428f PH |
29274 | These three functions create strings using Exim's dynamic memory facilities. |
29275 | The first makes a copy of an entire string. The second copies up to a maximum | |
29276 | number of characters, indicated by the second argument. The third uses a format | |
29277 | and insertion arguments to create a new string. In each case, the result is a | |
29278 | pointer to a new string in the current memory pool. See the next section for | |
29279 | more discussion. | |
9b371988 | 29280 | .endlist |
168e428f PH |
29281 | |
29282 | ||
29283 | ||
9b371988 PH |
29284 | .section "More about Exim's memory handling" "SECTmemhanloc" |
29285 | .cindex "&[local_scan()]& function" "memory handling" | |
168e428f PH |
29286 | No function is provided for freeing memory, because that is never needed. |
29287 | The dynamic memory that Exim uses when receiving a message is automatically | |
29288 | recycled if another message is received by the same process (this applies only | |
9b371988 PH |
29289 | to incoming SMTP connections &-- other input methods can supply only one |
29290 | message at a time). After receiving the last message, a reception process | |
29291 | terminates. | |
168e428f PH |
29292 | |
29293 | Because it is recycled, the normal dynamic memory cannot be used for holding | |
29294 | data that must be preserved over a number of incoming messages on the same SMTP | |
29295 | connection. However, Exim in fact uses two pools of dynamic memory; the second | |
29296 | one is not recycled, and can be used for this purpose. | |
29297 | ||
29298 | If you want to allocate memory that remains available for subsequent messages | |
29299 | in the same SMTP connection, you should set | |
9b371988 PH |
29300 | .code |
29301 | store_pool = POOL_PERM | |
29302 | .endd | |
168e428f PH |
29303 | before calling the function that does the allocation. There is no need to |
29304 | restore the value if you do not need to; however, if you do want to revert to | |
9b371988 | 29305 | the normal pool, you can either restore the previous value of &%store_pool%& or |
168e428f PH |
29306 | set it explicitly to POOL_MAIN. |
29307 | ||
29308 | The pool setting applies to all functions that get dynamic memory, including | |
9b371988 PH |
29309 | &'expand_string()'&, &'store_get()'&, and the &'string_xxx()'& functions. |
29310 | There is also a convenience function called &'store_get_perm()'& that gets a | |
168e428f | 29311 | block of memory from the permanent pool while preserving the value of |
9b371988 | 29312 | &%store_pool%&. |
4f578862 | 29313 | .ecindex IIDlosca |
168e428f PH |
29314 | |
29315 | ||
29316 | ||
29317 | ||
9b371988 PH |
29318 | . //////////////////////////////////////////////////////////////////////////// |
29319 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 29320 | |
9b371988 | 29321 | .chapter "System-wide message filtering" "CHAPsystemfilter" |
4f578862 PH |
29322 | .scindex IIDsysfil1 "filter" "system filter" |
29323 | .scindex IIDsysfil2 "filtering all mail" | |
29324 | .scindex IIDsysfil3 "system filter" | |
168e428f PH |
29325 | The previous chapters (on ACLs and the local scan function) describe checks |
29326 | that can be applied to messages before they are accepted by a host. There is | |
29327 | also a mechanism for checking messages once they have been received, but before | |
9b371988 | 29328 | they are delivered. This is called the &'system filter'&. |
168e428f PH |
29329 | |
29330 | The system filter operates in a similar manner to users' filter files, but it | |
29331 | is run just once per message (however many recipients the message has). | |
9b371988 | 29332 | It should not normally be used as a substitute for routing, because &%deliver%& |
168e428f PH |
29333 | commands in a system router provide new envelope recipient addresses. |
29334 | The system filter must be an Exim filter. It cannot be a Sieve filter. | |
29335 | ||
29336 | The system filter is run at the start of a delivery attempt, before any routing | |
29337 | is done. If a message fails to be completely delivered at the first attempt, | |
29338 | the system filter is run again at the start of every retry. | |
29339 | If you want your filter to do something only once per message, you can make use | |
9b371988 PH |
29340 | of the &%first_delivery%& condition in an &%if%& command in the filter to |
29341 | prevent it happening on retries. | |
29342 | ||
f89d2485 PH |
29343 | .vindex "&$domain$&" |
29344 | .vindex "&$local_part$&" | |
9b371988 PH |
29345 | &*Warning*&: Because the system filter runs just once, variables that are |
29346 | specific to individual recipient addresses, such as &$local_part$& and | |
29347 | &$domain$&, are not set, and the &"personal"& condition is not meaningful. If | |
29348 | you want to run a centrally-specified filter for each recipient address | |
29349 | independently, you can do so by setting up a suitable &(redirect)& router, as | |
29350 | described in section &<<SECTperaddfil>>& below. | |
29351 | ||
29352 | ||
f89d2485 | 29353 | .section "Specifying a system filter" "SECID212" |
9b371988 PH |
29354 | .cindex "uid (user id)" "system filter" |
29355 | .cindex "gid (group id)" "system filter" | |
168e428f | 29356 | The name of the file that contains the system filter must be specified by |
9b371988 PH |
29357 | setting &%system_filter%&. If you want the filter to run under a uid and gid |
29358 | other than root, you must also set &%system_filter_user%& and | |
29359 | &%system_filter_group%& as appropriate. For example: | |
29360 | .code | |
29361 | system_filter = /etc/mail/exim.filter | |
29362 | system_filter_user = exim | |
29363 | .endd | |
168e428f | 29364 | If a system filter generates any deliveries directly to files or pipes (via the |
9b371988 PH |
29365 | &%save%& or &%pipe%& commands), transports to handle these deliveries must be |
29366 | specified by setting &%system_filter_file_transport%& and | |
29367 | &%system_filter_pipe_transport%&, respectively. Similarly, | |
29368 | &%system_filter_reply_transport%& must be set to handle any messages generated | |
29369 | by the &%reply%& command. | |
168e428f PH |
29370 | |
29371 | ||
f89d2485 | 29372 | .section "Testing a system filter" "SECID213" |
168e428f | 29373 | You can run simple tests of a system filter in the same way as for a user |
9b371988 | 29374 | filter, but you should use &%-bF%& rather than &%-bf%&, so that features that |
168e428f PH |
29375 | are permitted only in system filters are recognized. |
29376 | ||
29377 | If you want to test the combined effect of a system filter and a user filter, | |
9b371988 | 29378 | you can use both &%-bF%& and &%-bf%& on the same command line. |
168e428f PH |
29379 | |
29380 | ||
29381 | ||
f89d2485 | 29382 | .section "Contents of a system filter" "SECID214" |
168e428f | 29383 | The language used to specify system filters is the same as for users' filter |
9b371988 PH |
29384 | files. It is described in the separate end-user document &'Exim's interface to |
29385 | mail filtering'&. However, there are some additional features that are | |
168e428f | 29386 | available only in system filters; these are described in subsequent sections. |
9b371988 | 29387 | If they are encountered in a user's filter file or when testing with &%-bf%&, |
168e428f PH |
29388 | they cause errors. |
29389 | ||
9b371988 | 29390 | .cindex "frozen messages" "manual thaw; testing in filter" |
168e428f | 29391 | There are two special conditions which, though available in users' filter |
9b371988 | 29392 | files, are designed for use in system filters. The condition &%first_delivery%& |
168e428f | 29393 | is true only for the first attempt at delivering a message, and |
9b371988 | 29394 | &%manually_thawed%& is true only if the message has been frozen, and |
168e428f | 29395 | subsequently thawed by an admin user. An explicit forced delivery counts as a |
9b371988 | 29396 | manual thaw, but thawing as a result of the &%auto_thaw%& setting does not. |
168e428f | 29397 | |
9b371988 PH |
29398 | &*Warning*&: If a system filter uses the &%first_delivery%& condition to |
29399 | specify an &"unseen"& (non-significant) delivery, and that delivery does not | |
168e428f PH |
29400 | succeed, it will not be tried again. |
29401 | If you want Exim to retry an unseen delivery until it succeeds, you should | |
29402 | arrange to set it up every time the filter runs. | |
29403 | ||
9b371988 PH |
29404 | When a system filter finishes running, the values of the variables &$n0$& &-- |
29405 | &$n9$& are copied into &$sn0$& &-- &$sn9$& and are thereby made available to | |
29406 | users' filter files. Thus a system filter can, for example, set up &"scores"& | |
29407 | to which users' filter files can refer. | |
168e428f PH |
29408 | |
29409 | ||
29410 | ||
f89d2485 PH |
29411 | .section "Additional variable for system filters" "SECID215" |
29412 | .vindex "&$recipients$&" | |
9b371988 | 29413 | The expansion variable &$recipients$&, containing a list of all the recipients |
168e428f PH |
29414 | of the message (separated by commas and white space), is available in system |
29415 | filters. It is not available in users' filters for privacy reasons. | |
29416 | ||
29417 | ||
29418 | ||
f89d2485 | 29419 | .section "Defer, freeze, and fail commands for system filters" "SECID216" |
9b371988 PH |
29420 | .cindex "freezing messages" |
29421 | .cindex "message" "freezing" | |
29422 | .cindex "message" "forced failure" | |
29423 | .cindex "&%fail%&" "in system filter" | |
29424 | .cindex "&%freeze%& in system filter" | |
29425 | .cindex "&%defer%& in system filter" | |
29426 | There are three extra commands (&%defer%&, &%freeze%& and &%fail%&) which are | |
29427 | always available in system filters, but are not normally enabled in users' | |
29428 | filters. (See the &%allow_defer%&, &%allow_freeze%& and &%allow_fail%& options | |
29429 | for the &(redirect)& router.) These commands can optionally be followed by the | |
29430 | word &%text%& and a string containing an error message, for example: | |
29431 | .code | |
29432 | fail text "this message looks like spam to me" | |
29433 | .endd | |
29434 | The keyword &%text%& is optional if the next character is a double quote. | |
29435 | ||
29436 | The &%defer%& command defers delivery of the original recipients of the | |
29437 | message. The &%fail%& command causes all the original recipients to be failed, | |
29438 | and a bounce message to be created. The &%freeze%& command suspends all | |
29439 | delivery attempts for the original recipients. In all cases, any new deliveries | |
29440 | that are specified by the filter are attempted as normal after the filter has | |
29441 | run. | |
29442 | ||
29443 | The &%freeze%& command is ignored if the message has been manually unfrozen and | |
168e428f PH |
29444 | not manually frozen since. This means that automatic freezing by a system |
29445 | filter can be used as a way of checking out suspicious messages. If a message | |
29446 | is found to be all right, manually unfreezing it allows it to be delivered. | |
29447 | ||
9b371988 PH |
29448 | .cindex "log" "&%fail%& command log line" |
29449 | .cindex "&%fail%&" "log line; reducing" | |
168e428f PH |
29450 | The text given with a fail command is used as part of the bounce message as |
29451 | well as being written to the log. If the message is quite long, this can fill | |
29452 | up a lot of log space when such failures are common. To reduce the size of the | |
29453 | log message, Exim interprets the text in a special way if it starts with the | |
9b371988 | 29454 | two characters &`<<`& and contains &`>>`& later. The text between these two |
168e428f PH |
29455 | strings is written to the log, and the rest of the text is used in the bounce |
29456 | message. For example: | |
9b371988 | 29457 | .code |
168e428f PH |
29458 | fail "<<filter test 1>>Your message is rejected \ |
29459 | because it contains attachments that we are \ | |
29460 | not prepared to receive." | |
9b371988 PH |
29461 | .endd |
29462 | ||
29463 | .cindex "loop" "caused by &%fail%&" | |
29464 | Take great care with the &%fail%& command when basing the decision to fail on | |
29465 | the contents of the message, because the bounce message will of course include | |
29466 | the contents of the original message and will therefore trigger the &%fail%& | |
29467 | command again (causing a mail loop) unless steps are taken to prevent this. | |
29468 | Testing the &%error_message%& condition is one way to prevent this. You could | |
29469 | use, for example | |
29470 | .code | |
29471 | if $message_body contains "this is spam" and not error_message | |
29472 | then fail text "spam is not wanted here" endif | |
29473 | .endd | |
168e428f PH |
29474 | though of course that might let through unwanted bounce messages. The |
29475 | alternative is clever checking of the body and/or headers to detect bounces | |
29476 | generated by the filter. | |
29477 | ||
29478 | The interpretation of a system filter file ceases after a | |
9b371988 PH |
29479 | &%defer%&, |
29480 | &%freeze%&, or &%fail%& command is obeyed. However, any deliveries that were | |
29481 | set up earlier in the filter file are honoured, so you can use a sequence such | |
29482 | as | |
29483 | .code | |
29484 | mail ... | |
29485 | freeze | |
29486 | .endd | |
168e428f PH |
29487 | to send a specified message when the system filter is freezing (or deferring or |
29488 | failing) a message. The normal deliveries for the message do not, of course, | |
29489 | take place. | |
29490 | ||
29491 | ||
29492 | ||
9b371988 PH |
29493 | .section "Adding and removing headers in a system filter" "SECTaddremheasys" |
29494 | .cindex "header lines" "adding; in system filter" | |
29495 | .cindex "header lines" "removing; in system filter" | |
29496 | .cindex "filter" "header lines; adding/removing" | |
168e428f | 29497 | Two filter commands that are available only in system filters are: |
9b371988 PH |
29498 | .code |
29499 | headers add <string> | |
29500 | headers remove <string> | |
29501 | .endd | |
29502 | The argument for the &%headers add%& is a string that is expanded and then | |
29503 | added to the end of the message's headers. It is the responsibility of the | |
29504 | filter maintainer to make sure it conforms to RFC 2822 syntax. Leading white | |
29505 | space is ignored, and if the string is otherwise empty, or if the expansion is | |
29506 | forced to fail, the command has no effect. | |
29507 | ||
29508 | You can use &"\n"& within the string, followed by white space, to specify | |
168e428f | 29509 | continued header lines. More than one header may be added in one command by |
9b371988 | 29510 | including &"\n"& within the string without any following white space. For |
168e428f | 29511 | example: |
9b371988 | 29512 | .code |
168e428f PH |
29513 | headers add "X-header-1: ....\n \ |
29514 | continuation of X-header-1 ...\n\ | |
29515 | X-header-2: ...." | |
9b371988 | 29516 | .endd |
168e428f PH |
29517 | Note that the header line continuation white space after the first newline must |
29518 | be placed before the backslash that continues the input string, because white | |
29519 | space after input continuations is ignored. | |
29520 | ||
9b371988 | 29521 | The argument for &%headers remove%& is a colon-separated list of header names. |
168e428f | 29522 | This command applies only to those headers that are stored with the message; |
9b371988 PH |
29523 | those that are added at delivery time (such as &'Envelope-To:'& and |
29524 | &'Return-Path:'&) cannot be removed by this means. If there is more than one | |
168e428f PH |
29525 | header with the same name, they are all removed. |
29526 | ||
9b371988 | 29527 | The &%headers%& command in a system filter makes an immediate change to the set |
168e428f PH |
29528 | of header lines that was received with the message (with possible additions |
29529 | from ACL processing). Subsequent commands in the system filter operate on the | |
29530 | modified set, which also forms the basis for subsequent message delivery. | |
29531 | Unless further modified during routing or transporting, this set of headers is | |
29532 | used for all recipients of the message. | |
29533 | ||
29534 | During routing and transporting, the variables that refer to the contents of | |
29535 | header lines refer only to those lines that are in this set. Thus, header lines | |
29536 | that are added by a system filter are visible to users' filter files and to all | |
29537 | routers and transports. This contrasts with the manipulation of header lines by | |
29538 | routers and transports, which is not immediate, but which instead is saved up | |
9b371988 PH |
29539 | until the message is actually being written (see section |
29540 | &<<SECTheadersaddrem>>&). | |
168e428f PH |
29541 | |
29542 | If the message is not delivered at the first attempt, header lines that were | |
29543 | added by the system filter are stored with the message, and so are still | |
29544 | present at the next delivery attempt. Header lines that were removed are still | |
9b371988 PH |
29545 | present, but marked &"deleted"& so that they are not transported with the |
29546 | message. For this reason, it is usual to make the &%headers%& command | |
29547 | conditional on &%first_delivery%& so that the set of header lines is not | |
29548 | modified more than once. | |
168e428f PH |
29549 | |
29550 | Because header modification in a system filter acts immediately, you have to | |
29551 | use an indirect approach if you want to modify the contents of a header line. | |
29552 | For example: | |
9b371988 PH |
29553 | .code |
29554 | headers add "Old-Subject: $h_subject:" | |
29555 | headers remove "Subject" | |
29556 | headers add "Subject: new subject (was: $h_old-subject:)" | |
29557 | headers remove "Old-Subject" | |
29558 | .endd | |
168e428f PH |
29559 | |
29560 | ||
29561 | ||
f89d2485 | 29562 | .section "Setting an errors address in a system filter" "SECID217" |
9b371988 PH |
29563 | .cindex "envelope sender" |
29564 | In a system filter, if a &%deliver%& command is followed by | |
29565 | .code | |
29566 | errors_to <some address> | |
29567 | .endd | |
168e428f PH |
29568 | in order to change the envelope sender (and hence the error reporting) for that |
29569 | delivery, any address may be specified. (In a user filter, only the current | |
29570 | user's address can be set.) For example, if some mail is being monitored, you | |
29571 | might use | |
9b371988 PH |
29572 | .code |
29573 | unseen deliver monitor@spying.example errors_to root@local.example | |
29574 | .endd | |
168e428f PH |
29575 | to take a copy which would not be sent back to the normal error reporting |
29576 | address if its delivery failed. | |
29577 | ||
29578 | ||
29579 | ||
9b371988 | 29580 | .section "Per-address filtering" "SECTperaddfil" |
f89d2485 PH |
29581 | .vindex "&$domain$&" |
29582 | .vindex "&$local_part$&" | |
168e428f PH |
29583 | In contrast to the system filter, which is run just once per message for each |
29584 | delivery attempt, it is also possible to set up a system-wide filtering | |
29585 | operation that runs once for each recipient address. In this case, variables | |
9b371988 | 29586 | such as &$local_part$& and &$domain$& can be used, and indeed, the choice of |
168e428f PH |
29587 | filter file could be made dependent on them. This is an example of a router |
29588 | which implements such a filter: | |
9b371988 PH |
29589 | .code |
29590 | central_filter: | |
29591 | check_local_user | |
29592 | driver = redirect | |
29593 | domains = +local_domains | |
29594 | file = /central/filters/$local_part | |
29595 | no_verify | |
29596 | allow_filter | |
29597 | allow_freeze | |
29598 | .endd | |
168e428f | 29599 | The filter is run in a separate process under its own uid. Therefore, either |
9b371988 PH |
29600 | &%check_local_user%& must be set (as above), in which case the filter is run as |
29601 | the local user, or the &%user%& option must be used to specify which user to | |
29602 | use. If both are set, &%user%& overrides. | |
168e428f PH |
29603 | |
29604 | Care should be taken to ensure that none of the commands in the filter file | |
29605 | specify a significant delivery if the message is to go on to be delivered to | |
29606 | its intended recipient. The router will not then claim to have dealt with the | |
29607 | address, so it will be passed on to subsequent routers to be delivered in the | |
29608 | normal way. | |
4f578862 PH |
29609 | .ecindex IIDsysfil1 |
29610 | .ecindex IIDsysfil2 | |
29611 | .ecindex IIDsysfil3 | |
168e428f PH |
29612 | |
29613 | ||
29614 | ||
29615 | ||
29616 | ||
29617 | ||
9b371988 PH |
29618 | . //////////////////////////////////////////////////////////////////////////// |
29619 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 29620 | |
9b371988 | 29621 | .chapter "Message processing" "CHAPmsgproc" |
4f578862 | 29622 | .scindex IIDmesproc "message" "general processing" |
168e428f PH |
29623 | Exim performs various transformations on the sender and recipient addresses of |
29624 | all messages that it handles, and also on the messages' header lines. Some of | |
29625 | these are optional and configurable, while others always take place. All of | |
29626 | this processing, except rewriting as a result of routing, and the addition or | |
29627 | removal of header lines while delivering, happens when a message is received, | |
29628 | before it is placed on Exim's queue. | |
29629 | ||
29630 | Some of the automatic processing takes place by default only for | |
9b371988 PH |
29631 | &"locally-originated"& messages. This adjective is used to describe messages |
29632 | that are not received over TCP/IP, but instead are passed to an Exim process on | |
29633 | its standard input. This includes the interactive &"local SMTP"& case that is | |
29634 | set up by the &%-bs%& command line option. | |
168e428f | 29635 | |
9b371988 | 29636 | &*Note*&: Messages received over TCP/IP on the loopback interface (127.0.0.1 |
168e428f PH |
29637 | or ::1) are not considered to be locally-originated. Exim does not treat the |
29638 | loopback interface specially in any way. | |
29639 | ||
29640 | If you want the loopback interface to be treated specially, you must ensure | |
29641 | that there are appropriate entries in your ACLs. | |
29642 | ||
29643 | ||
29644 | ||
29645 | ||
9b371988 PH |
29646 | .section "Submission mode for non-local messages" "SECTsubmodnon" |
29647 | .cindex "message" "submission" | |
29648 | .cindex "submission mode" | |
068aaea8 | 29649 | Processing that happens automatically for locally-originated messages (unless |
9b371988 PH |
29650 | &%suppress_local_fixups%& is set) can also be requested for messages that are |
29651 | received over TCP/IP. The term &"submission mode"& is used to describe this | |
f89d2485 | 29652 | state. Submission mode is set by the modifier |
9b371988 PH |
29653 | .code |
29654 | control = submission | |
29655 | .endd | |
068aaea8 | 29656 | in a MAIL, RCPT, or pre-data ACL for an incoming message (see sections |
9b371988 PH |
29657 | &<<SECTACLmodi>>& and &<<SECTcontrols>>&). This makes Exim treat the message as |
29658 | a local submission, and is normally used when the source of the message is | |
29659 | known to be an MUA running on a client host (as opposed to an MTA). For | |
29660 | example, to set submission mode for messages originating on the IPv4 loopback | |
29661 | interface, you could include the following in the MAIL ACL: | |
29662 | .code | |
29663 | warn hosts = 127.0.0.1 | |
29664 | control = submission | |
29665 | .endd | |
0a4e3112 | 29666 | .cindex "&%sender_retain%& submission option" |
168e428f PH |
29667 | There are some options that can be used when setting submission mode. A slash |
29668 | is used to separate options. For example: | |
9b371988 PH |
29669 | .code |
29670 | control = submission/sender_retain | |
29671 | .endd | |
29672 | Specifying &%sender_retain%& has the effect of setting &%local_sender_retain%& | |
29673 | true and &%local_from_check%& false for the current incoming message. The first | |
29674 | of these allows an existing &'Sender:'& header in the message to remain, and | |
29675 | the second suppresses the check to ensure that &'From:'& matches the | |
29676 | authenticated sender. With this setting, Exim still fixes up messages by adding | |
29677 | &'Date:'& and &'Message-ID:'& header lines if they are missing, but makes no | |
29678 | attempt to check sender authenticity in header lines. | |
29679 | ||
29680 | When &%sender_retain%& is not set, a submission mode setting may specify a | |
29681 | domain to be used when generating a &'From:'& or &'Sender:'& header line. For | |
29682 | example: | |
29683 | .code | |
29684 | control = submission/domain=some.domain | |
29685 | .endd | |
168e428f | 29686 | The domain may be empty. How this value is used is described in sections |
9b371988 PH |
29687 | &<<SECTthefrohea>>& and &<<SECTthesenhea>>&. There is also a &%name%& option |
29688 | that allows you to specify the user's full name for inclusion in a created | |
29689 | &'Sender:'& or &'From:'& header line. For example: | |
29690 | .code | |
068aaea8 PH |
29691 | accept authenticated = * |
29692 | control = submission/domain=wonderland.example/\ | |
29693 | name=${lookup {$authenticated_id} \ | |
29694 | lsearch {/etc/exim/namelist}} | |
9b371988 PH |
29695 | .endd |
29696 | Because the name may contain any characters, including slashes, the &%name%& | |
068aaea8 | 29697 | option must be given last. The remainder of the string is used as the name. For |
9b371988 PH |
29698 | the example above, if &_/etc/exim/namelist_& contains: |
29699 | .code | |
068aaea8 | 29700 | bigegg: Humpty Dumpty |
9b371988 PH |
29701 | .endd |
29702 | then when the sender has authenticated as &'bigegg'&, the generated &'Sender:'& | |
068aaea8 | 29703 | line would be: |
9b371988 | 29704 | .code |
068aaea8 | 29705 | Sender: Humpty Dumpty <bigegg@wonderland.example> |
9b371988 PH |
29706 | .endd |
29707 | .cindex "return path" "in submission mode" | |
068aaea8 | 29708 | By default, submission mode forces the return path to the same address as is |
9b371988 PH |
29709 | used to create the &'Sender:'& header. However, if &%sender_retain%& is |
29710 | specified, the return path is also left unchanged. | |
068aaea8 | 29711 | |
9b371988 | 29712 | &*Note*&: The changes caused by submission mode take effect after the predata |
068aaea8 PH |
29713 | ACL. This means that any sender checks performed before the fix-ups use the |
29714 | untrusted sender address specified by the user, not the trusted sender address | |
29715 | specified by submission mode. Although this might be slightly unexpected, it | |
29716 | does mean that you can configure ACL checks to spot that a user is trying to | |
29717 | spoof another's address. | |
168e428f | 29718 | |
9b371988 PH |
29719 | .section "Line endings" "SECTlineendings" |
29720 | .cindex "line endings" | |
29721 | .cindex "carriage return" | |
29722 | .cindex "linefeed" | |
168e428f PH |
29723 | RFC 2821 specifies that CRLF (two characters: carriage-return, followed by |
29724 | linefeed) is the line ending for messages transmitted over the Internet using | |
29725 | SMTP over TCP/IP. However, within individual operating systems, different | |
29726 | conventions are used. For example, Unix-like systems use just LF, but others | |
29727 | use CRLF or just CR. | |
29728 | ||
29729 | Exim was designed for Unix-like systems, and internally, it stores messages | |
29730 | using the system's convention of a single LF as a line terminator. When | |
29731 | receiving a message, all line endings are translated to this standard format. | |
29732 | Originally, it was thought that programs that passed messages directly to an | |
29733 | MTA within an operating system would use that system's convention. Experience | |
29734 | has shown that this is not the case; for example, there are Unix applications | |
29735 | that use CRLF in this circumstance. For this reason, and for compatibility with | |
29736 | other MTAs, the way Exim handles line endings for all messages is now as | |
29737 | follows: | |
29738 | ||
9b371988 PH |
29739 | .ilist |
29740 | LF not preceded by CR is treated as a line ending. | |
29741 | .next | |
29742 | CR is treated as a line ending; if it is immediately followed by LF, the LF | |
168e428f | 29743 | is ignored. |
9b371988 PH |
29744 | .next |
29745 | The sequence &"CR, dot, CR"& does not terminate an incoming SMTP message, | |
168e428f PH |
29746 | nor a local message in the state where a line containing only a dot is a |
29747 | terminator. | |
9b371988 PH |
29748 | .next |
29749 | If a bare CR is encountered within a header line, an extra space is added after | |
168e428f PH |
29750 | the line terminator so as not to end the header line. The reasoning behind this |
29751 | is that bare CRs in header lines are most likely either to be mistakes, or | |
29752 | people trying to play silly games. | |
9b371988 PH |
29753 | .next |
29754 | If the first header line received in a message ends with CRLF, a subsequent | |
168e428f PH |
29755 | bare LF in a header line is treated in the same way as a bare CR in a header |
29756 | line. | |
9b371988 | 29757 | .endlist |
168e428f PH |
29758 | |
29759 | ||
29760 | ||
29761 | ||
29762 | ||
f89d2485 | 29763 | .section "Unqualified addresses" "SECID218" |
9b371988 PH |
29764 | .cindex "unqualified addresses" |
29765 | .cindex "address" "qualification" | |
168e428f PH |
29766 | By default, Exim expects every envelope address it receives from an external |
29767 | host to be fully qualified. Unqualified addresses cause negative responses to | |
29768 | SMTP commands. However, because SMTP is used as a means of transporting | |
29769 | messages from MUAs running on personal workstations, there is sometimes a | |
29770 | requirement to accept unqualified addresses from specific hosts or IP networks. | |
29771 | ||
29772 | Exim has two options that separately control which hosts may send unqualified | |
f89d2485 | 29773 | sender or recipient addresses in SMTP commands, namely |
9b371988 | 29774 | &%sender_unqualified_hosts%& and &%recipient_unqualified_hosts%&. In both |
168e428f | 29775 | cases, if an unqualified address is accepted, it is qualified by adding the |
9b371988 | 29776 | value of &%qualify_domain%& or &%qualify_recipient%&, as appropriate. |
168e428f | 29777 | |
0a4e3112 PH |
29778 | .oindex "&%qualify_domain%&" |
29779 | .oindex "&%qualify_recipient%&" | |
168e428f | 29780 | Unqualified addresses in header lines are automatically qualified for messages |
9b371988 | 29781 | that are locally originated, unless the &%-bnq%& option is given on the command |
168e428f PH |
29782 | line. For messages received over SMTP, unqualified addresses in header lines |
29783 | are qualified only if unqualified addresses are permitted in SMTP commands. In | |
29784 | other words, such qualification is also controlled by | |
9b371988 | 29785 | &%sender_unqualified_hosts%& and &%recipient_unqualified_hosts%&, |
168e428f PH |
29786 | |
29787 | ||
29788 | ||
29789 | ||
f89d2485 | 29790 | .section "The UUCP From line" "SECID219" |
9b371988 PH |
29791 | .cindex "&""From""& line" |
29792 | .cindex "UUCP" "&""From""& line" | |
29793 | .cindex "sender" "address" | |
0a4e3112 PH |
29794 | .oindex "&%uucp_from_pattern%&" |
29795 | .oindex "&%uucp_from_sender%&" | |
9b371988 PH |
29796 | .cindex "envelope sender" |
29797 | .cindex "Sendmail compatibility" "&""From""& line" | |
168e428f PH |
29798 | Messages that have come from UUCP (and some other applications) often begin |
29799 | with a line containing the envelope sender and a timestamp, following the word | |
9b371988 PH |
29800 | &"From"&. Examples of two common formats are: |
29801 | .code | |
29802 | From a.oakley@berlin.mus Fri Jan 5 12:35 GMT 1996 | |
29803 | From f.butler@berlin.mus Fri, 7 Jan 97 14:00:00 GMT | |
29804 | .endd | |
168e428f PH |
29805 | This line precedes the RFC 2822 header lines. For compatibility with Sendmail, |
29806 | Exim recognizes such lines at the start of messages that are submitted to it | |
29807 | via the command line (that is, on the standard input). It does not recognize | |
29808 | such lines in incoming SMTP messages, unless the sending host matches | |
9b371988 PH |
29809 | &%ignore_fromline_hosts%& or the &%-bs%& option was used for a local message |
29810 | and &%ignore_fromline_local%& is set. The recognition is controlled by a | |
29811 | regular expression that is defined by the &%uucp_from_pattern%& option, whose | |
29812 | default value matches the two common cases shown above and puts the address | |
29813 | that follows &"From"& into &$1$&. | |
29814 | ||
29815 | .cindex "numerical variables (&$1$& &$2$& etc)" "in &""From ""& line handling" | |
29816 | When the caller of Exim for a non-SMTP message that contains a &"From"& line is | |
29817 | a trusted user, the message's sender address is constructed by expanding the | |
29818 | contents of &%uucp_sender_address%&, whose default value is &"$1"&. This is | |
29819 | then parsed as an RFC 2822 address. If there is no domain, the local part is | |
29820 | qualified with &%qualify_domain%& unless it is the empty string. However, if | |
29821 | the command line &%-f%& option is used, it overrides the &"From"& line. | |
29822 | ||
29823 | If the caller of Exim is not trusted, the &"From"& line is recognized, but the | |
168e428f | 29824 | sender address is not changed. This is also the case for incoming SMTP messages |
9b371988 | 29825 | that are permitted to contain &"From"& lines. |
168e428f | 29826 | |
9b371988 | 29827 | Only one &"From"& line is recognized. If there is more than one, the second is |
168e428f | 29828 | treated as a data line that starts the body of the message, as it is not valid |
9b371988 PH |
29829 | as a header line. This also happens if a &"From"& line is present in an |
29830 | incoming SMTP message from a source that is not permitted to send them. | |
168e428f PH |
29831 | |
29832 | ||
29833 | ||
f89d2485 | 29834 | .section "Resent- header lines" "SECID220" |
9b371988 | 29835 | .cindex "&%Resent-%& header lines" |
168e428f | 29836 | RFC 2822 makes provision for sets of header lines starting with the string |
9b371988 PH |
29837 | &`Resent-`& to be added to a message when it is resent by the original |
29838 | recipient to somebody else. These headers are &'Resent-Date:'&, | |
29839 | &'Resent-From:'&, &'Resent-Sender:'&, &'Resent-To:'&, &'Resent-Cc:'&, | |
29840 | &'Resent-Bcc:'& and &'Resent-Message-ID:'&. The RFC says: | |
168e428f | 29841 | |
9b371988 PH |
29842 | .blockquote |
29843 | &'Resent fields are strictly informational. They MUST NOT be used in the normal | |
29844 | processing of replies or other such automatic actions on messages.'& | |
29845 | .endblockquote | |
168e428f PH |
29846 | |
29847 | This leaves things a bit vague as far as other processing actions such as | |
9b371988 | 29848 | address rewriting are concerned. Exim treats &%Resent-%& header lines as |
168e428f PH |
29849 | follows: |
29850 | ||
9b371988 PH |
29851 | .ilist |
29852 | A &'Resent-From:'& line that just contains the login id of the submitting user | |
29853 | is automatically rewritten in the same way as &'From:'& (see below). | |
29854 | .next | |
29855 | If there's a rewriting rule for a particular header line, it is also applied to | |
29856 | &%Resent-%& header lines of the same type. For example, a rule that rewrites | |
29857 | &'From:'& also rewrites &'Resent-From:'&. | |
29858 | .next | |
29859 | For local messages, if &'Sender:'& is removed on input, &'Resent-Sender:'& is | |
29860 | also removed. | |
29861 | .next | |
29862 | For a locally-submitted message, | |
29863 | if there are any &%Resent-%& header lines but no &'Resent-Date:'&, | |
29864 | &'Resent-From:'&, or &'Resent-Message-Id:'&, they are added as necessary. It is | |
29865 | the contents of &'Resent-Message-Id:'& (rather than &'Message-Id:'&) which are | |
168e428f | 29866 | included in log lines in this case. |
9b371988 PH |
29867 | .next |
29868 | The logic for adding &'Sender:'& is duplicated for &'Resent-Sender:'& when any | |
29869 | &%Resent-%& header lines are present. | |
29870 | .endlist | |
168e428f | 29871 | |
168e428f PH |
29872 | |
29873 | ||
29874 | ||
f89d2485 | 29875 | .section "The Auto-Submitted: header line" "SECID221" |
4f578862 PH |
29876 | Whenever Exim generates an autoreply, a bounce, or a delay warning message, it |
29877 | includes the header line: | |
9b371988 PH |
29878 | .code |
29879 | Auto-Submitted: auto-replied | |
29880 | .endd | |
9b371988 | 29881 | |
f89d2485 | 29882 | .section "The Bcc: header line" "SECID222" |
9b371988 PH |
29883 | .cindex "&'Bcc:'& header line" |
29884 | If Exim is called with the &%-t%& option, to take recipient addresses from a | |
29885 | message's header, it removes any &'Bcc:'& header line that may exist (after | |
29886 | extracting its addresses). If &%-t%& is not present on the command line, any | |
29887 | existing &'Bcc:'& is not removed. | |
29888 | ||
29889 | ||
f89d2485 | 29890 | .section "The Date: header line" "SECID223" |
9b371988 | 29891 | .cindex "&'Date:'& header line" |
9b371988 | 29892 | If a locally-generated or submission-mode message has no &'Date:'& header line, |
068aaea8 | 29893 | Exim adds one, using the current date and time, unless the |
9b371988 | 29894 | &%suppress_local_fixups%& control has been specified. |
168e428f | 29895 | |
f89d2485 | 29896 | .section "The Delivery-date: header line" "SECID224" |
9b371988 | 29897 | .cindex "&'Delivery-date:'& header line" |
0a4e3112 | 29898 | .oindex "&%delivery_date_remove%&" |
9b371988 | 29899 | &'Delivery-date:'& header lines are not part of the standard RFC 2822 header |
168e428f | 29900 | set. Exim can be configured to add them to the final delivery of messages. (See |
9b371988 PH |
29901 | the generic &%delivery_date_add%& transport option.) They should not be present |
29902 | in messages in transit. If the &%delivery_date_remove%& configuration option is | |
29903 | set (the default), Exim removes &'Delivery-date:'& header lines from incoming | |
168e428f PH |
29904 | messages. |
29905 | ||
29906 | ||
f89d2485 | 29907 | .section "The Envelope-to: header line" "SECID225" |
9b371988 | 29908 | .cindex "&'Envelope-to:'& header line" |
0a4e3112 | 29909 | .oindex "&%envelope_to_remove%&" |
9b371988 | 29910 | &'Envelope-to:'& header lines are not part of the standard RFC 2822 header set. |
168e428f | 29911 | Exim can be configured to add them to the final delivery of messages. (See the |
9b371988 PH |
29912 | generic &%envelope_to_add%& transport option.) They should not be present in |
29913 | messages in transit. If the &%envelope_to_remove%& configuration option is set | |
29914 | (the default), Exim removes &'Envelope-to:'& header lines from incoming | |
168e428f PH |
29915 | messages. |
29916 | ||
29917 | ||
9b371988 PH |
29918 | .section "The From: header line" "SECTthefrohea" |
29919 | .cindex "&'From:'& header line" | |
29920 | .cindex "Sendmail compatibility" "&""From""& line" | |
29921 | .cindex "message" "submission" | |
29922 | .cindex "submission mode" | |
29923 | If a submission-mode message does not contain a &'From:'& header line, Exim | |
29924 | adds one if either of the following conditions is true: | |
168e428f | 29925 | |
9b371988 PH |
29926 | .ilist |
29927 | The envelope sender address is not empty (that is, this is not a bounce | |
168e428f | 29928 | message). The added header line copies the envelope sender address. |
9b371988 | 29929 | .next |
f89d2485 | 29930 | .vindex "&$authenticated_id$&" |
9b371988 PH |
29931 | The SMTP session is authenticated and &$authenticated_id$& is not empty. |
29932 | .olist | |
f89d2485 | 29933 | .vindex "&$qualify_domain$&" |
068aaea8 | 29934 | If no domain is specified by the submission control, the local part is |
9b371988 PH |
29935 | &$authenticated_id$& and the domain is &$qualify_domain$&. |
29936 | .next | |
29937 | If a non-empty domain is specified by the submission control, the local | |
3cb1b51e | 29938 | part is &$authenticated_id$&, and the domain is the specified domain. |
9b371988 PH |
29939 | .next |
29940 | If an empty domain is specified by the submission control, | |
29941 | &$authenticated_id$& is assumed to be the complete address. | |
29942 | .endlist | |
29943 | .endlist | |
168e428f PH |
29944 | |
29945 | A non-empty envelope sender takes precedence. | |
29946 | ||
9b371988 PH |
29947 | If a locally-generated incoming message does not contain a &'From:'& header |
29948 | line, and the &%suppress_local_fixups%& control is not set, Exim adds one | |
29949 | containing the sender's address. The calling user's login name and full name | |
29950 | are used to construct the address, as described in section &<<SECTconstr>>&. | |
29951 | They are obtained from the password data by calling &[getpwuid()]& (but see the | |
29952 | &%unknown_login%& configuration option). The address is qualified with | |
29953 | &%qualify_domain%&. | |
168e428f PH |
29954 | |
29955 | For compatibility with Sendmail, if an incoming, non-SMTP message has a | |
9b371988 | 29956 | &'From:'& header line containing just the unqualified login name of the calling |
168e428f | 29957 | user, this is replaced by an address containing the user's login name and full |
9b371988 | 29958 | name as described in section &<<SECTconstr>>&. |
168e428f PH |
29959 | |
29960 | ||
f89d2485 | 29961 | .section "The Message-ID: header line" "SECID226" |
9b371988 PH |
29962 | .cindex "&'Message-ID:'& header line" |
29963 | .cindex "message" "submission" | |
0a4e3112 | 29964 | .oindex "&%message_id_header_text%&" |
168e428f | 29965 | If a locally-generated or submission-mode incoming message does not contain a |
9b371988 PH |
29966 | &'Message-ID:'& or &'Resent-Message-ID:'& header line, and the |
29967 | &%suppress_local_fixups%& control is not set, Exim adds a suitable header line | |
29968 | to the message. If there are any &'Resent-:'& headers in the message, it | |
29969 | creates &'Resent-Message-ID:'&. The id is constructed from Exim's internal | |
29970 | message id, preceded by the letter E to ensure it starts with a letter, and | |
29971 | followed by @ and the primary host name. Additional information can be included | |
29972 | in this header line by setting the &%message_id_header_text%& and/or | |
29973 | &%message_id_header_domain%& options. | |
9b371988 PH |
29974 | |
29975 | ||
f89d2485 | 29976 | .section "The Received: header line" "SECID227" |
9b371988 PH |
29977 | .cindex "&'Received:'& header line" |
29978 | A &'Received:'& header line is added at the start of every message. The | |
29979 | contents are defined by the &%received_header_text%& configuration option, and | |
29980 | Exim automatically adds a semicolon and a timestamp to the configured string. | |
29981 | ||
29982 | The &'Received:'& header is generated as soon as the message's header lines | |
29983 | have been received. At this stage, the timestamp in the &'Received:'& header | |
29984 | line is the time that the message started to be received. This is the value | |
29985 | that is seen by the DATA ACL and by the &[local_scan()]& function. | |
29986 | ||
29987 | Once a message is accepted, the timestamp in the &'Received:'& header line is | |
168e428f PH |
29988 | changed to the time of acceptance, which is (apart from a small delay while the |
29989 | -H spool file is written) the earliest time at which delivery could start. | |
29990 | ||
29991 | ||
f89d2485 | 29992 | .section "The References: header line" "SECID228" |
4f578862 PH |
29993 | .cindex "&'References:'& header line" |
29994 | Messages created by the &(autoreply)& transport include a &'References:'& | |
29995 | header line. This is constructed according to the rules that are described in | |
29996 | section 3.64 of RFC 2822 (which states that replies should contain such a | |
29997 | header line), and section 3.14 of RFC 3834 (which states that automatic | |
29998 | responses are not different in this respect). However, because some mail | |
29999 | processing software does not cope well with very long header lines, no more | |
30000 | than 12 message IDs are copied from the &'References:'& header line in the | |
30001 | incoming message. If there are more than 12, the first one and then the final | |
30002 | 11 are copied, before adding the message ID of the incoming message. | |
4f578862 PH |
30003 | |
30004 | ||
168e428f | 30005 | |
f89d2485 | 30006 | .section "The Return-path: header line" "SECID229" |
9b371988 | 30007 | .cindex "&'Return-path:'& header line" |
0a4e3112 | 30008 | .oindex "&%return_path_remove%&" |
9b371988 PH |
30009 | &'Return-path:'& header lines are defined as something an MTA may insert when |
30010 | it does the final delivery of messages. (See the generic &%return_path_add%& | |
168e428f | 30011 | transport option.) Therefore, they should not be present in messages in |
9b371988 PH |
30012 | transit. If the &%return_path_remove%& configuration option is set (the |
30013 | default), Exim removes &'Return-path:'& header lines from incoming messages. | |
168e428f PH |
30014 | |
30015 | ||
30016 | ||
9b371988 PH |
30017 | .section "The Sender: header line" "SECTthesenhea" |
30018 | .cindex "&'Sender:'& header line" | |
30019 | .cindex "message" "submission" | |
168e428f | 30020 | For a locally-originated message from an untrusted user, Exim may remove an |
9b371988 PH |
30021 | existing &'Sender:'& header line, and it may add a new one. You can modify |
30022 | these actions by setting the &%local_sender_retain%& option true, the | |
30023 | &%local_from_check%& option false, or by using the &%suppress_local_fixups%& | |
068aaea8 | 30024 | control setting. |
168e428f | 30025 | |
9b371988 PH |
30026 | When a local message is received from an untrusted user and |
30027 | &%local_from_check%& is true (the default), and the &%suppress_local_fixups%& | |
30028 | control has not been set, a check is made to see if the address given in the | |
30029 | &'From:'& header line is the correct (local) sender of the message. The address | |
30030 | that is expected has the login name as the local part and the value of | |
30031 | &%qualify_domain%& as the domain. Prefixes and suffixes for the local part can | |
30032 | be permitted by setting &%local_from_prefix%& and &%local_from_suffix%& | |
30033 | appropriately. If &'From:'& does not contain the correct sender, a &'Sender:'& | |
30034 | line is added to the message. | |
9b371988 PH |
30035 | |
30036 | If you set &%local_from_check%& false, this checking does not occur. However, | |
30037 | the removal of an existing &'Sender:'& line still happens, unless you also set | |
30038 | &%local_sender_retain%& to be true. It is not possible to set both of these | |
168e428f PH |
30039 | options true at the same time. |
30040 | ||
9b371988 PH |
30041 | .cindex "submission mode" |
30042 | By default, no processing of &'Sender:'& header lines is done for messages | |
168e428f | 30043 | received over TCP/IP or for messages submitted by trusted users. However, when |
9b371988 | 30044 | a message is received over TCP/IP in submission mode, and &%sender_retain%& is |
168e428f PH |
30045 | not specified on the submission control, the following processing takes place: |
30046 | ||
f89d2485 | 30047 | .vindex "&$authenticated_id$&" |
9b371988 PH |
30048 | First, any existing &'Sender:'& lines are removed. Then, if the SMTP session is |
30049 | authenticated, and &$authenticated_id$& is not empty, a sender address is | |
168e428f PH |
30050 | created as follows: |
30051 | ||
9b371988 | 30052 | .ilist |
f89d2485 | 30053 | .vindex "&$qualify_domain$&" |
068aaea8 | 30054 | If no domain is specified by the submission control, the local part is |
9b371988 PH |
30055 | &$authenticated_id$& and the domain is &$qualify_domain$&. |
30056 | .next | |
30057 | If a non-empty domain is specified by the submission control, the local part | |
3cb1b51e | 30058 | is &$authenticated_id$&, and the domain is the specified domain. |
9b371988 PH |
30059 | .next |
30060 | If an empty domain is specified by the submission control, | |
30061 | &$authenticated_id$& is assumed to be the complete address. | |
30062 | .endlist | |
30063 | ||
30064 | This address is compared with the address in the &'From:'& header line. If they | |
30065 | are different, a &'Sender:'& header line containing the created address is | |
30066 | added. Prefixes and suffixes for the local part in &'From:'& can be permitted | |
30067 | by setting &%local_from_prefix%& and &%local_from_suffix%& appropriately. | |
30068 | ||
9b371988 PH |
30069 | .cindex "return path" "created from &'Sender:'&" |
30070 | &*Note*&: Whenever a &'Sender:'& header line is created, the return path for | |
30071 | the message (the envelope sender address) is changed to be the same address, | |
30072 | except in the case of submission mode when &%sender_retain%& is specified. | |
9b371988 PH |
30073 | |
30074 | ||
30075 | ||
30076 | .section "Adding and removing header lines in routers and transports" &&& | |
30077 | "SECTheadersaddrem" | |
30078 | .cindex "header lines" "adding; in router or transport" | |
30079 | .cindex "header lines" "removing; in router or transport" | |
168e428f PH |
30080 | When a message is delivered, the addition and removal of header lines can be |
30081 | specified in a system filter, or on any of the routers and transports that | |
9b371988 | 30082 | process the message. Section &<<SECTaddremheasys>>& contains details about |
068aaea8 | 30083 | modifying headers in a system filter. Header lines can also be added in an ACL |
4f578862 | 30084 | as a message is received (see section &<<SECTaddheadacl>>&). |
168e428f PH |
30085 | |
30086 | In contrast to what happens in a system filter, header modifications that are | |
30087 | specified on routers and transports apply only to the particular recipient | |
30088 | addresses that are being processed by those routers and transports. These | |
30089 | changes do not actually take place until a copy of the message is being | |
30090 | transported. Therefore, they do not affect the basic set of header lines, and | |
30091 | they do not affect the values of the variables that refer to header lines. | |
30092 | ||
9b371988 | 30093 | &*Note*&: In particular, this means that any expansions in the configuration of |
068aaea8 PH |
30094 | the transport cannot refer to the modified header lines, because such |
30095 | expansions all occur before the message is actually transported. | |
30096 | ||
9b371988 | 30097 | For both routers and transports, the result of expanding a &%headers_add%& |
168e428f | 30098 | option must be in the form of one or more RFC 2822 header lines, separated by |
9b371988 PH |
30099 | newlines (coded as &"\n"&). For example: |
30100 | .code | |
168e428f PH |
30101 | headers_add = X-added-header: added by $primary_hostname\n\ |
30102 | X-added-second: another added header line | |
9b371988 | 30103 | .endd |
168e428f PH |
30104 | Exim does not check the syntax of these added header lines. |
30105 | ||
9b371988 | 30106 | The result of expanding &%headers_remove%& must consist of a colon-separated |
168e428f PH |
30107 | list of header names. This is confusing, because header names themselves are |
30108 | often terminated by colons. In this case, the colons are the list separators, | |
30109 | not part of the names. For example: | |
9b371988 PH |
30110 | .code |
30111 | headers_remove = return-receipt-to:acknowledge-to | |
30112 | .endd | |
30113 | When &%headers_add%& or &%headers_remove%& is specified on a router, its value | |
30114 | is expanded at routing time, and then associated with all addresses that are | |
168e428f PH |
30115 | accepted by that router, and also with any new addresses that it generates. If |
30116 | an address passes through several routers as a result of aliasing or | |
30117 | forwarding, the changes are cumulative. | |
30118 | ||
0a4e3112 | 30119 | .oindex "&%unseen%&" |
168e428f | 30120 | However, this does not apply to multiple routers that result from the use of |
9b371988 PH |
30121 | the &%unseen%& option. Any header modifications that were specified by the |
30122 | &"unseen"& router or its predecessors apply only to the &"unseen"& delivery. | |
168e428f | 30123 | |
9b371988 | 30124 | Addresses that end up with different &%headers_add%& or &%headers_remove%& |
168e428f PH |
30125 | settings cannot be delivered together in a batch, so a transport is always |
30126 | dealing with a set of addresses that have the same header-processing | |
30127 | requirements. | |
30128 | ||
30129 | The transport starts by writing the original set of header lines that arrived | |
30130 | with the message, possibly modified by the system filter. As it writes out | |
30131 | these lines, it consults the list of header names that were attached to the | |
9b371988 PH |
30132 | recipient address(es) by &%headers_remove%& options in routers, and it also |
30133 | consults the transport's own &%headers_remove%& option. Header lines whose | |
30134 | names are on either of these lists are not written out. If there are multiple | |
168e428f PH |
30135 | instances of any listed header, they are all skipped. |
30136 | ||
30137 | After the remaining original header lines have been written, new header | |
9b371988 | 30138 | lines that were specified by routers' &%headers_add%& options are written, in |
168e428f | 30139 | the order in which they were attached to the address. These are followed by any |
9b371988 | 30140 | header lines specified by the transport's &%headers_add%& option. |
168e428f PH |
30141 | |
30142 | This way of handling header line modifications in routers and transports has | |
30143 | the following consequences: | |
30144 | ||
9b371988 PH |
30145 | .ilist |
30146 | The original set of header lines, possibly modified by the system filter, | |
30147 | remains &"visible"&, in the sense that the &$header_$&&'xxx'& variables refer | |
30148 | to it, at all times. | |
30149 | .next | |
30150 | Header lines that are added by a router's | |
30151 | &%headers_add%& option are not accessible by means of the &$header_$&&'xxx'& | |
168e428f | 30152 | expansion syntax in subsequent routers or the transport. |
9b371988 PH |
30153 | .next |
30154 | Conversely, header lines that are specified for removal by &%headers_remove%& | |
30155 | in a router remain visible to subsequent routers and the transport. | |
30156 | .next | |
30157 | Headers added to an address by &%headers_add%& in a router cannot be removed by | |
168e428f | 30158 | a later router or by a transport. |
9b371988 PH |
30159 | .next |
30160 | An added header can refer to the contents of an original header that is to be | |
168e428f | 30161 | removed, even it has the same name as the added header. For example: |
9b371988 PH |
30162 | .code |
30163 | headers_remove = subject | |
30164 | headers_add = Subject: new subject (was: $h_subject:) | |
30165 | .endd | |
30166 | .endlist | |
168e428f | 30167 | |
9b371988 PH |
30168 | &*Warning*&: The &%headers_add%& and &%headers_remove%& options cannot be used |
30169 | for a &(redirect)& router that has the &%one_time%& option set. | |
168e428f | 30170 | |
168e428f PH |
30171 | |
30172 | ||
30173 | ||
30174 | ||
9b371988 PH |
30175 | .section "Constructed addresses" "SECTconstr" |
30176 | .cindex "address" "constructed" | |
30177 | .cindex "constructed address" | |
168e428f PH |
30178 | When Exim constructs a sender address for a locally-generated message, it uses |
30179 | the form | |
9b371988 PH |
30180 | .display |
30181 | <&'user name'&>&~&~<&'login'&&`@`&&'qualify_domain'&> | |
30182 | .endd | |
168e428f | 30183 | For example: |
9b371988 PH |
30184 | .code |
30185 | Zaphod Beeblebrox <zaphod@end.univ.example> | |
30186 | .endd | |
30187 | The user name is obtained from the &%-F%& command line option if set, or | |
30188 | otherwise by looking up the calling user by &[getpwuid()]& and extracting the | |
30189 | &"gecos"& field from the password entry. If the &"gecos"& field contains an | |
168e428f PH |
30190 | ampersand character, this is replaced by the login name with the first letter |
30191 | upper cased, as is conventional in a number of operating systems. See the | |
9b371988 PH |
30192 | &%gecos_name%& option for a way to tailor the handling of the &"gecos"& field. |
30193 | The &%unknown_username%& option can be used to specify user names in cases when | |
168e428f PH |
30194 | there is no password file entry. |
30195 | ||
9b371988 | 30196 | .cindex "RFC 2047" |
168e428f PH |
30197 | In all cases, the user name is made to conform to RFC 2822 by quoting all or |
30198 | parts of it if necessary. In addition, if it contains any non-printing | |
30199 | characters, it is encoded as described in RFC 2047, which defines a way of | |
d1e83bff | 30200 | including non-ASCII characters in header lines. The value of the |
9b371988 | 30201 | &%headers_charset%& option specifies the name of the encoding that is used (the |
d1e83bff | 30202 | characters are assumed to be in this encoding). The setting of |
9b371988 PH |
30203 | &%print_topbitchars%& controls whether characters with the top bit set (that |
30204 | is, with codes greater than 127) count as printing characters or not. | |
168e428f PH |
30205 | |
30206 | ||
30207 | ||
f89d2485 | 30208 | .section "Case of local parts" "SECID230" |
9b371988 PH |
30209 | .cindex "case of local parts" |
30210 | .cindex "local part" "case of" | |
168e428f PH |
30211 | RFC 2822 states that the case of letters in the local parts of addresses cannot |
30212 | be assumed to be non-significant. Exim preserves the case of local parts of | |
30213 | addresses, but by default it uses a lower-cased form when it is routing, | |
30214 | because on most Unix systems, usernames are in lower case and case-insensitive | |
30215 | routing is required. However, any particular router can be made to use the | |
9b371988 | 30216 | original case for local parts by setting the &%caseful_local_part%& generic |
168e428f PH |
30217 | router option. |
30218 | ||
9b371988 | 30219 | .cindex "mixed-case login names" |
168e428f PH |
30220 | If you must have mixed-case user names on your system, the best way to proceed, |
30221 | assuming you want case-independent handling of incoming email, is to set up | |
30222 | your first router to convert incoming local parts in your domains to the | |
30223 | correct case by means of a file lookup. For example: | |
9b371988 | 30224 | .code |
168e428f PH |
30225 | correct_case: |
30226 | driver = redirect | |
30227 | domains = +local_domains | |
30228 | data = ${lookup{$local_part}cdb\ | |
30229 | {/etc/usercased.cdb}{$value}fail}\ | |
30230 | @$domain | |
9b371988 | 30231 | .endd |
168e428f | 30232 | For this router, the local part is forced to lower case by the default action |
9b371988 PH |
30233 | (&%caseful_local_part%& is not set). The lower-cased local part is used to look |
30234 | up a new local part in the correct case. If you then set &%caseful_local_part%& | |
168e428f PH |
30235 | on any subsequent routers which process your domains, they will operate on |
30236 | local parts with the correct case in a case-sensitive manner. | |
30237 | ||
30238 | ||
30239 | ||
f89d2485 | 30240 | .section "Dots in local parts" "SECID231" |
9b371988 PH |
30241 | .cindex "dot" "in local part" |
30242 | .cindex "local part" "dots in" | |
168e428f PH |
30243 | RFC 2822 forbids empty components in local parts. That is, an unquoted local |
30244 | part may not begin or end with a dot, nor have two consecutive dots in the | |
30245 | middle. However, it seems that many MTAs do not enforce this, so Exim permits | |
30246 | empty components for compatibility. | |
30247 | ||
30248 | ||
30249 | ||
f89d2485 | 30250 | .section "Rewriting addresses" "SECID232" |
9b371988 | 30251 | .cindex "rewriting" "addresses" |
168e428f PH |
30252 | Rewriting of sender and recipient addresses, and addresses in headers, can |
30253 | happen automatically, or as the result of configuration options, as described | |
9b371988 PH |
30254 | in chapter &<<CHAPrewrite>>&. The headers that may be affected by this are |
30255 | &'Bcc:'&, &'Cc:'&, &'From:'&, &'Reply-To:'&, &'Sender:'&, and &'To:'&. | |
168e428f PH |
30256 | |
30257 | Automatic rewriting includes qualification, as mentioned above. The other case | |
30258 | in which it can happen is when an incomplete non-local domain is given. The | |
30259 | routing process may cause this to be expanded into the full domain name. For | |
30260 | example, a header such as | |
9b371988 PH |
30261 | .code |
30262 | To: hare@teaparty | |
30263 | .endd | |
168e428f | 30264 | might get rewritten as |
9b371988 PH |
30265 | .code |
30266 | To: hare@teaparty.wonderland.fict.example | |
30267 | .endd | |
168e428f PH |
30268 | Rewriting as a result of routing is the one kind of message processing that |
30269 | does not happen at input time, as it cannot be done until the address has | |
30270 | been routed. | |
30271 | ||
9b371988 | 30272 | Strictly, one should not do &'any'& deliveries of a message until all its |
168e428f PH |
30273 | addresses have been routed, in case any of the headers get changed as a |
30274 | result of routing. However, doing this in practice would hold up many | |
30275 | deliveries for unreasonable amounts of time, just because one address could not | |
30276 | immediately be routed. Exim therefore does not delay other deliveries when | |
30277 | routing of one or more addresses is deferred. | |
4f578862 PH |
30278 | .ecindex IIDmesproc |
30279 | ||
168e428f PH |
30280 | |
30281 | ||
9b371988 PH |
30282 | . //////////////////////////////////////////////////////////////////////////// |
30283 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 30284 | |
9b371988 | 30285 | .chapter "SMTP processing" "CHAPSMTP" |
4f578862 PH |
30286 | .scindex IIDsmtpproc1 "SMTP" "processing details" |
30287 | .scindex IIDsmtpproc2 "LMTP" "processing details" | |
168e428f PH |
30288 | Exim supports a number of different ways of using the SMTP protocol, and its |
30289 | LMTP variant, which is an interactive protocol for transferring messages into a | |
30290 | closed mail store application. This chapter contains details of how SMTP is | |
30291 | processed. For incoming mail, the following are available: | |
30292 | ||
9b371988 PH |
30293 | .ilist |
30294 | SMTP over TCP/IP (Exim daemon or &'inetd'&); | |
30295 | .next | |
30296 | SMTP over the standard input and output (the &%-bs%& option); | |
30297 | .next | |
30298 | Batched SMTP on the standard input (the &%-bS%& option). | |
30299 | .endlist | |
168e428f PH |
30300 | |
30301 | For mail delivery, the following are available: | |
30302 | ||
9b371988 PH |
30303 | .ilist |
30304 | SMTP over TCP/IP (the &(smtp)& transport); | |
30305 | .next | |
30306 | LMTP over TCP/IP (the &(smtp)& transport with the &%protocol%& option set to | |
30307 | &"lmtp"&); | |
30308 | .next | |
30309 | LMTP over a pipe to a process running in the local host (the &(lmtp)& | |
168e428f | 30310 | transport); |
9b371988 PH |
30311 | .next |
30312 | Batched SMTP to a file or pipe (the &(appendfile)& and &(pipe)& transports with | |
30313 | the &%use_bsmtp%& option set). | |
30314 | .endlist | |
168e428f | 30315 | |
9b371988 | 30316 | &'Batched SMTP'& is the name for a process in which batches of messages are |
168e428f PH |
30317 | stored in or read from files (or pipes), in a format in which SMTP commands are |
30318 | used to contain the envelope information. | |
30319 | ||
30320 | ||
30321 | ||
9b371988 PH |
30322 | .section "Outgoing SMTP and LMTP over TCP/IP" "SECToutSMTPTCP" |
30323 | .cindex "SMTP" "outgoing over TCP/IP" | |
30324 | .cindex "outgoing SMTP over TCP/IP" | |
30325 | .cindex "LMTP" "over TCP/IP" | |
30326 | .cindex "outgoing LMTP over TCP/IP" | |
30327 | .cindex "EHLO" | |
30328 | .cindex "HELO" | |
30329 | .cindex "SIZE option on MAIL command" | |
30330 | Outgoing SMTP and LMTP over TCP/IP is implemented by the &(smtp)& transport. | |
30331 | The &%protocol%& option selects which protocol is to be used, but the actual | |
168e428f PH |
30332 | processing is the same in both cases. |
30333 | ||
30334 | If, in response to its EHLO command, Exim is told that the SIZE | |
9b371988 PH |
30335 | parameter is supported, it adds SIZE=<&'n'&> to each subsequent MAIL |
30336 | command. The value of <&'n'&> is the message size plus the value of the | |
30337 | &%size_addition%& option (default 1024) to allow for additions to the message | |
168e428f | 30338 | such as per-transport header lines, or changes made in a |
9b371988 PH |
30339 | .cindex "transport" "filter" |
30340 | .cindex "filter" "transport filter" | |
30341 | transport filter. If &%size_addition%& is set negative, the use of SIZE is | |
168e428f PH |
30342 | suppressed. |
30343 | ||
30344 | If the remote server advertises support for PIPELINING, Exim uses the | |
30345 | pipelining extension to SMTP (RFC 2197) to reduce the number of TCP/IP packets | |
30346 | required for the transaction. | |
30347 | ||
30348 | If the remote server advertises support for the STARTTLS command, and Exim | |
30349 | was built to support TLS encryption, it tries to start a TLS session unless the | |
9b371988 | 30350 | server matches &%hosts_avoid_tls%&. See chapter &<<CHAPTLS>>& for more details. |
168e428f PH |
30351 | |
30352 | If the remote server advertises support for the AUTH command, Exim scans | |
30353 | the authenticators configuration for any suitable client settings, as described | |
9b371988 | 30354 | in chapter &<<CHAPSMTPAUTH>>&. |
168e428f | 30355 | |
9b371988 PH |
30356 | .cindex "carriage return" |
30357 | .cindex "linefeed" | |
168e428f PH |
30358 | Responses from the remote host are supposed to be terminated by CR followed by |
30359 | LF. However, there are known to be hosts that do not send CR characters, so in | |
30360 | order to be able to interwork with such hosts, Exim treats LF on its own as a | |
30361 | line terminator. | |
30362 | ||
30363 | If a message contains a number of different addresses, all those with the same | |
30364 | characteristics (for example, the same envelope sender) that resolve to the | |
30365 | same set of hosts, in the same order, are sent in a single SMTP transaction, | |
30366 | even if they are for different domains, unless there are more than the setting | |
5a1a5845 NM |
30367 | of the &%max_rcpt%&s option in the &(smtp)& transport allows, in which case |
30368 | they are split into groups containing no more than &%max_rcpt%&s addresses | |
9b371988 PH |
30369 | each. If &%remote_max_parallel%& is greater than one, such groups may be sent |
30370 | in parallel sessions. The order of hosts with identical MX values is not | |
168e428f PH |
30371 | significant when checking whether addresses can be batched in this way. |
30372 | ||
9b371988 | 30373 | When the &(smtp)& transport suffers a temporary failure that is not |
168e428f PH |
30374 | message-related, Exim updates its transport-specific database, which contains |
30375 | records indexed by host name that remember which messages are waiting for each | |
30376 | particular host. It also updates the retry database with new retry times. | |
30377 | ||
9b371988 | 30378 | .cindex "hints database" "retry keys" |
168e428f PH |
30379 | Exim's retry hints are based on host name plus IP address, so if one address of |
30380 | a multi-homed host is broken, it will soon be skipped most of the time. | |
30381 | See the next section for more detail about error handling. | |
30382 | ||
9b371988 PH |
30383 | .cindex "SMTP" "passed connection" |
30384 | .cindex "SMTP" "batching over TCP/IP" | |
168e428f PH |
30385 | When a message is successfully delivered over a TCP/IP SMTP connection, Exim |
30386 | looks in the hints database for the transport to see if there are any queued | |
30387 | messages waiting for the host to which it is connected. If it finds one, it | |
9b371988 PH |
30388 | creates a new Exim process using the &%-MC%& option (which can only be used by |
30389 | a process running as root or the Exim user) and passes the TCP/IP socket to it | |
30390 | so that it can deliver another message using the same socket. The new process | |
30391 | does only those deliveries that are routed to the connected host, and may in | |
30392 | turn pass the socket on to a third process, and so on. | |
168e428f | 30393 | |
9b371988 | 30394 | The &%connection_max_messages%& option of the &(smtp)& transport can be used to |
168e428f PH |
30395 | limit the number of messages sent down a single TCP/IP connection. |
30396 | ||
9b371988 | 30397 | .cindex "asterisk" "after IP address" |
168e428f PH |
30398 | The second and subsequent messages delivered down an existing connection are |
30399 | identified in the main log by the addition of an asterisk after the closing | |
30400 | square bracket of the IP address. | |
30401 | ||
30402 | ||
30403 | ||
30404 | ||
9b371988 PH |
30405 | .section "Errors in outgoing SMTP" "SECToutSMTPerr" |
30406 | .cindex "error" "in outgoing SMTP" | |
30407 | .cindex "SMTP" "errors in outgoing" | |
30408 | .cindex "host" "error" | |
168e428f PH |
30409 | Three different kinds of error are recognized for outgoing SMTP: host errors, |
30410 | message errors, and recipient errors. | |
30411 | ||
9b371988 PH |
30412 | .vlist |
30413 | .vitem "&*Host errors*&" | |
30414 | A host error is not associated with a particular message or with a | |
168e428f | 30415 | particular recipient of a message. The host errors are: |
168e428f | 30416 | |
9b371988 PH |
30417 | .ilist |
30418 | Connection refused or timed out, | |
30419 | .next | |
30420 | Any error response code on connection, | |
30421 | .next | |
30422 | Any error response code to EHLO or HELO, | |
30423 | .next | |
30424 | Loss of connection at any time, except after &"."&, | |
30425 | .next | |
30426 | I/O errors at any time, | |
30427 | .next | |
30428 | Timeouts during the session, other than in response to MAIL, RCPT or | |
30429 | the &"."& at the end of the data. | |
30430 | .endlist ilist | |
168e428f | 30431 | |
168e428f PH |
30432 | For a host error, a permanent error response on connection, or in response to |
30433 | EHLO, causes all addresses routed to the host to be failed. Any other host | |
30434 | error causes all addresses to be deferred, and retry data to be created for the | |
30435 | host. It is not tried again, for any message, until its retry time arrives. If | |
30436 | the current set of addresses are not all delivered in this run (to some | |
30437 | alternative host), the message is added to the list of those waiting for this | |
30438 | host, so if it is still undelivered when a subsequent successful delivery is | |
30439 | made to the host, it will be sent down the same SMTP connection. | |
30440 | ||
9b371988 PH |
30441 | .vitem "&*Message errors*&" |
30442 | .cindex "message" "error" | |
168e428f PH |
30443 | A message error is associated with a particular message when sent to a |
30444 | particular host, but not with a particular recipient of the message. The | |
30445 | message errors are: | |
168e428f | 30446 | |
9b371988 PH |
30447 | .ilist |
30448 | Any error response code to MAIL, DATA, or the &"."& that terminates | |
30449 | the data, | |
30450 | .next | |
30451 | Timeout after MAIL, | |
30452 | .next | |
30453 | Timeout or loss of connection after the &"."& that terminates the data. A | |
168e428f PH |
30454 | timeout after the DATA command itself is treated as a host error, as is loss of |
30455 | connection at any other time. | |
9b371988 PH |
30456 | .endlist ilist |
30457 | ||
30458 | For a message error, a permanent error response (5&'xx'&) causes all addresses | |
168e428f | 30459 | to be failed, and a delivery error report to be returned to the sender. A |
9b371988 | 30460 | temporary error response (4&'xx'&), or one of the timeouts, causes all |
168e428f PH |
30461 | addresses to be deferred. Retry data is not created for the host, but instead, |
30462 | a retry record for the combination of host plus message id is created. The | |
30463 | message is not added to the list of those waiting for this host. This ensures | |
30464 | that the failing message will not be sent to this host again until the retry | |
30465 | time arrives. However, other messages that are routed to the host are not | |
30466 | affected, so if it is some property of the message that is causing the error, | |
30467 | it will not stop the delivery of other mail. | |
9b371988 | 30468 | |
168e428f | 30469 | If the remote host specified support for the SIZE parameter in its response |
9b371988 | 30470 | to EHLO, Exim adds SIZE=&'nnn'& to the MAIL command, so an |
168e428f PH |
30471 | over-large message will cause a message error because the error arrives as a |
30472 | response to MAIL. | |
30473 | ||
9b371988 PH |
30474 | .vitem "&*Recipient errors*&" |
30475 | .cindex "recipient" "error" | |
168e428f PH |
30476 | A recipient error is associated with a particular recipient of a message. The |
30477 | recipient errors are: | |
9b371988 PH |
30478 | |
30479 | .ilist | |
30480 | Any error response to RCPT, | |
30481 | .next | |
30482 | Timeout after RCPT. | |
30483 | .endlist | |
30484 | ||
30485 | For a recipient error, a permanent error response (5&'xx'&) causes the | |
168e428f | 30486 | recipient address to be failed, and a bounce message to be returned to the |
9b371988 | 30487 | sender. A temporary error response (4&'xx'&) or a timeout causes the failing |
168e428f PH |
30488 | address to be deferred, and routing retry data to be created for it. This is |
30489 | used to delay processing of the address in subsequent queue runs, until its | |
30490 | routing retry time arrives. This applies to all messages, but because it | |
30491 | operates only in queue runs, one attempt will be made to deliver a new message | |
30492 | to the failing address before the delay starts to operate. This ensures that, | |
30493 | if the failure is really related to the message rather than the recipient | |
9b371988 | 30494 | (&"message too big for this recipient"& is a possible example), other messages |
168e428f PH |
30495 | have a chance of getting delivered. If a delivery to the address does succeed, |
30496 | the retry information gets cleared, so all stuck messages get tried again, and | |
30497 | the retry clock is reset. | |
9b371988 | 30498 | |
168e428f PH |
30499 | The message is not added to the list of those waiting for this host. Use of the |
30500 | host for other messages is unaffected, and except in the case of a timeout, | |
30501 | other recipients are processed independently, and may be successfully delivered | |
30502 | in the current SMTP session. After a timeout it is of course impossible to | |
30503 | proceed with the session, so all addresses get deferred. However, those other | |
30504 | than the one that failed do not suffer any subsequent retry delays. Therefore, | |
30505 | if one recipient is causing trouble, the others have a chance of getting | |
30506 | through when a subsequent delivery attempt occurs before the failing | |
30507 | recipient's retry time. | |
9b371988 | 30508 | .endlist |
168e428f PH |
30509 | |
30510 | In all cases, if there are other hosts (or IP addresses) available for the | |
30511 | current set of addresses (for example, from multiple MX records), they are | |
30512 | tried in this run for any undelivered addresses, subject of course to their | |
30513 | own retry data. In other words, recipient error retry data does not take effect | |
30514 | until the next delivery attempt. | |
30515 | ||
30516 | Some hosts have been observed to give temporary error responses to every | |
9b371988 | 30517 | MAIL command at certain times (&"insufficient space"& has been seen). It |
168e428f PH |
30518 | would be nice if such circumstances could be recognized, and defer data for the |
30519 | host itself created, but this is not possible within the current Exim design. | |
30520 | What actually happens is that retry data for every (host, message) combination | |
30521 | is created. | |
30522 | ||
30523 | The reason that timeouts after MAIL and RCPT are treated specially is that | |
30524 | these can sometimes arise as a result of the remote host's verification | |
30525 | procedures. Exim makes this assumption, and treats them as if a temporary error | |
9b371988 | 30526 | response had been received. A timeout after &"."& is treated specially because |
168e428f PH |
30527 | it is known that some broken implementations fail to recognize the end of the |
30528 | message if the last character of the last line is a binary zero. Thus, it is | |
30529 | helpful to treat this case as a message error. | |
30530 | ||
30531 | Timeouts at other times are treated as host errors, assuming a problem with the | |
30532 | host, or the connection to it. If a timeout after MAIL, RCPT, | |
9b371988 | 30533 | or &"."& is really a connection problem, the assumption is that at the next try |
168e428f PH |
30534 | the timeout is likely to occur at some other point in the dialogue, causing it |
30535 | then to be treated as a host error. | |
30536 | ||
30537 | There is experimental evidence that some MTAs drop the connection after the | |
9b371988 PH |
30538 | terminating &"."& if they do not like the contents of the message for some |
30539 | reason, in contravention of the RFC, which indicates that a 5&'xx'& response | |
168e428f PH |
30540 | should be given. That is why Exim treats this case as a message rather than a |
30541 | host error, in order not to delay other messages to the same host. | |
30542 | ||
30543 | ||
30544 | ||
30545 | ||
f89d2485 | 30546 | .section "Incoming SMTP messages over TCP/IP" "SECID233" |
9b371988 PH |
30547 | .cindex "SMTP" "incoming over TCP/IP" |
30548 | .cindex "incoming SMTP over TCP/IP" | |
30549 | .cindex "inetd" | |
30550 | .cindex "daemon" | |
168e428f | 30551 | Incoming SMTP messages can be accepted in one of two ways: by running a |
9b371988 PH |
30552 | listening daemon, or by using &'inetd'&. In the latter case, the entry in |
30553 | &_/etc/inetd.conf_& should be like this: | |
30554 | .code | |
30555 | smtp stream tcp nowait exim /opt/exim/bin/exim in.exim -bs | |
30556 | .endd | |
168e428f | 30557 | Exim distinguishes between this case and the case of a locally running user |
9b371988 | 30558 | agent using the &%-bs%& option by checking whether or not the standard input is |
168e428f PH |
30559 | a socket. When it is, either the port must be privileged (less than 1024), or |
30560 | the caller must be root or the Exim user. If any other user passes a socket | |
30561 | with an unprivileged port number, Exim prints a message on the standard error | |
30562 | stream and exits with an error code. | |
30563 | ||
30564 | By default, Exim does not make a log entry when a remote host connects or | |
9b371988 | 30565 | disconnects (either via the daemon or &'inetd'&), unless the disconnection is |
168e428f | 30566 | unexpected. It can be made to write such log entries by setting the |
9b371988 | 30567 | &%smtp_connection%& log selector. |
168e428f | 30568 | |
9b371988 PH |
30569 | .cindex "carriage return" |
30570 | .cindex "linefeed" | |
168e428f PH |
30571 | Commands from the remote host are supposed to be terminated by CR followed by |
30572 | LF. However, there are known to be hosts that do not send CR characters. In | |
30573 | order to be able to interwork with such hosts, Exim treats LF on its own as a | |
30574 | line terminator. | |
30575 | Furthermore, because common code is used for receiving messages from all | |
30576 | sources, a CR on its own is also interpreted as a line terminator. However, the | |
9b371988 | 30577 | sequence &"CR, dot, CR"& does not terminate incoming SMTP data. |
168e428f | 30578 | |
9b371988 PH |
30579 | .cindex "EHLO" "invalid data" |
30580 | .cindex "HELO" "invalid data" | |
168e428f PH |
30581 | One area that sometimes gives rise to problems concerns the EHLO or |
30582 | HELO commands. Some clients send syntactically invalid versions of these | |
30583 | commands, which Exim rejects by default. (This is nothing to do with verifying | |
9b371988 PH |
30584 | the data that is sent, so &%helo_verify_hosts%& is not relevant.) You can tell |
30585 | Exim not to apply a syntax check by setting &%helo_accept_junk_hosts%& to | |
168e428f PH |
30586 | match the broken hosts that send invalid commands. |
30587 | ||
9b371988 PH |
30588 | .cindex "SIZE option on MAIL command" |
30589 | .cindex "MAIL" "SIZE option" | |
168e428f | 30590 | The amount of disk space available is checked whenever SIZE is received on |
9b371988 PH |
30591 | a MAIL command, independently of whether &%message_size_limit%& or |
30592 | &%check_spool_space%& is configured, unless &%smtp_check_spool_space%& is set | |
168e428f | 30593 | false. A temporary error is given if there is not enough space. If |
9b371988 | 30594 | &%check_spool_space%& is set, the check is for that amount of space plus the |
168e428f PH |
30595 | value given with SIZE, that is, it checks that the addition of the incoming |
30596 | message will not reduce the space below the threshold. | |
30597 | ||
30598 | When a message is successfully received, Exim includes the local message id in | |
9b371988 PH |
30599 | its response to the final &"."& that terminates the data. If the remote host |
30600 | logs this text it can help with tracing what has happened to a message. | |
168e428f PH |
30601 | |
30602 | The Exim daemon can limit the number of simultaneous incoming connections it is | |
9b371988 | 30603 | prepared to handle (see the &%smtp_accept_max%& option). It can also limit the |
168e428f | 30604 | number of simultaneous incoming connections from a single remote host (see the |
9b371988 | 30605 | &%smtp_accept_max_per_host%& option). Additional connection attempts are |
168e428f PH |
30606 | rejected using the SMTP temporary error code 421. |
30607 | ||
30608 | The Exim daemon does not rely on the SIGCHLD signal to detect when a | |
30609 | subprocess has finished, as this can get lost at busy times. Instead, it looks | |
30610 | for completed subprocesses every time it wakes up. Provided there are other | |
30611 | things happening (new incoming calls, starts of queue runs), completed | |
30612 | processes will be noticed and tidied away. On very quiet systems you may | |
9b371988 PH |
30613 | sometimes see a &"defunct"& Exim process hanging about. This is not a problem; |
30614 | it will be noticed when the daemon next wakes up. | |
168e428f PH |
30615 | |
30616 | When running as a daemon, Exim can reserve some SMTP slots for specific hosts, | |
30617 | and can also be set up to reject SMTP calls from non-reserved hosts at times of | |
9b371988 PH |
30618 | high system load &-- for details see the &%smtp_accept_reserve%&, |
30619 | &%smtp_load_reserve%&, and &%smtp_reserve_hosts%& options. The load check | |
30620 | applies in both the daemon and &'inetd'& cases. | |
168e428f PH |
30621 | |
30622 | Exim normally starts a delivery process for each message received, though this | |
9b371988 PH |
30623 | can be varied by means of the &%-odq%& command line option and the |
30624 | &%queue_only%&, &%queue_only_file%&, and &%queue_only_load%& options. The | |
30625 | number of simultaneously running delivery processes started in this way from | |
30626 | SMTP input can be limited by the &%smtp_accept_queue%& and | |
30627 | &%smtp_accept_queue_per_connection%& options. When either limit is reached, | |
168e428f PH |
30628 | subsequently received messages are just put on the input queue without starting |
30629 | a delivery process. | |
30630 | ||
9b371988 PH |
30631 | The controls that involve counts of incoming SMTP calls (&%smtp_accept_max%&, |
30632 | &%smtp_accept_queue%&, &%smtp_accept_reserve%&) are not available when Exim is | |
30633 | started up from the &'inetd'& daemon, because in that case each connection is | |
168e428f | 30634 | handled by an entirely independent Exim process. Control by load average is, |
9b371988 | 30635 | however, available with &'inetd'&. |
168e428f PH |
30636 | |
30637 | Exim can be configured to verify addresses in incoming SMTP commands as they | |
9b371988 PH |
30638 | are received. See chapter &<<CHAPACL>>& for details. It can also be configured |
30639 | to rewrite addresses at this time &-- before any syntax checking is done. See | |
30640 | section &<<SECTrewriteS>>&. | |
168e428f PH |
30641 | |
30642 | Exim can also be configured to limit the rate at which a client host submits | |
30643 | MAIL and RCPT commands in a single SMTP session. See the | |
9b371988 | 30644 | &%smtp_ratelimit_hosts%& option. |
168e428f PH |
30645 | |
30646 | ||
30647 | ||
f89d2485 | 30648 | .section "Unrecognized SMTP commands" "SECID234" |
9b371988 PH |
30649 | .cindex "SMTP" "unrecognized commands" |
30650 | If Exim receives more than &%smtp_max_unknown_commands%& unrecognized SMTP | |
168e428f PH |
30651 | commands during a single SMTP connection, it drops the connection after sending |
30652 | the error response to the last command. The default value for | |
9b371988 | 30653 | &%smtp_max_unknown_commands%& is 3. This is a defence against some kinds of |
168e428f PH |
30654 | abuse that subvert web servers into making connections to SMTP ports; in these |
30655 | circumstances, a number of non-SMTP lines are sent first. | |
30656 | ||
30657 | ||
f89d2485 | 30658 | .section "Syntax and protocol errors in SMTP commands" "SECID235" |
9b371988 PH |
30659 | .cindex "SMTP" "syntax errors" |
30660 | .cindex "SMTP" "protocol errors" | |
168e428f PH |
30661 | A syntax error is detected if an SMTP command is recognized, but there is |
30662 | something syntactically wrong with its data, for example, a malformed email | |
30663 | address in a RCPT command. Protocol errors include invalid command | |
30664 | sequencing such as RCPT before MAIL. If Exim receives more than | |
9b371988 | 30665 | &%smtp_max_synprot_errors%& such commands during a single SMTP connection, it |
168e428f | 30666 | drops the connection after sending the error response to the last command. The |
9b371988 | 30667 | default value for &%smtp_max_synprot_errors%& is 3. This is a defence against |
168e428f PH |
30668 | broken clients that loop sending bad commands (yes, it has been seen). |
30669 | ||
30670 | ||
30671 | ||
f89d2485 | 30672 | .section "Use of non-mail SMTP commands" "SECID236" |
9b371988 PH |
30673 | .cindex "SMTP" "non-mail commands" |
30674 | The &"non-mail"& SMTP commands are those other than MAIL, RCPT, and | |
168e428f PH |
30675 | DATA. Exim counts such commands, and drops the connection if there are too |
30676 | many of them in a single SMTP session. This action catches some | |
30677 | denial-of-service attempts and things like repeated failing AUTHs, or a mad | |
9b371988 PH |
30678 | client looping sending EHLO. The global option &%smtp_accept_max_nonmail%& |
30679 | defines what &"too many"& means. Its default value is 10. | |
168e428f PH |
30680 | |
30681 | When a new message is expected, one occurrence of RSET is not counted. This | |
30682 | allows a client to send one RSET between messages (this is not necessary, | |
f89d2485 | 30683 | but some clients do it). Exim also allows one uncounted occurrence of HELO |
168e428f PH |
30684 | or EHLO, and one occurrence of STARTTLS between messages. After |
30685 | starting up a TLS session, another EHLO is expected, and so it too is not | |
30686 | counted. | |
30687 | ||
30688 | The first occurrence of AUTH in a connection, or immediately following | |
30689 | STARTTLS is also not counted. Otherwise, all commands other than MAIL, | |
30690 | RCPT, DATA, and QUIT are counted. | |
30691 | ||
30692 | You can control which hosts are subject to the limit set by | |
9b371988 PH |
30693 | &%smtp_accept_max_nonmail%& by setting |
30694 | &%smtp_accept_max_nonmail_hosts%&. The default value is &`*`&, which makes | |
168e428f PH |
30695 | the limit apply to all hosts. This option means that you can exclude any |
30696 | specific badly-behaved hosts that you have to live with. | |
30697 | ||
30698 | ||
30699 | ||
30700 | ||
f89d2485 | 30701 | .section "The VRFY and EXPN commands" "SECID237" |
168e428f | 30702 | When Exim receives a VRFY or EXPN command on a TCP/IP connection, it |
9b371988 | 30703 | runs the ACL specified by &%acl_smtp_vrfy%& or &%acl_smtp_expn%& (as |
168e428f PH |
30704 | appropriate) in order to decide whether the command should be accepted or not. |
30705 | If no ACL is defined, the command is rejected. | |
30706 | ||
9b371988 | 30707 | .cindex "VRFY" "processing" |
168e428f | 30708 | When VRFY is accepted, it runs exactly the same code as when Exim is |
9b371988 | 30709 | called with the &%-bv%& option. |
168e428f | 30710 | |
9b371988 | 30711 | .cindex "EXPN" "processing" |
168e428f | 30712 | When EXPN is accepted, a single-level expansion of the address is done. |
9b371988 PH |
30713 | EXPN is treated as an &"address test"& (similar to the &%-bt%& option) rather |
30714 | than a verification (the &%-bv%& option). If an unqualified local part is given | |
30715 | as the argument to EXPN, it is qualified with &%qualify_domain%&. Rejections | |
168e428f PH |
30716 | of VRFY and EXPN commands are logged on the main and reject logs, and |
30717 | VRFY verification failures are logged on the main log for consistency with | |
30718 | RCPT failures. | |
30719 | ||
30720 | ||
30721 | ||
9b371988 PH |
30722 | .section "The ETRN command" "SECTETRN" |
30723 | .cindex "ETRN" "processing" | |
168e428f PH |
30724 | RFC 1985 describes an SMTP command called ETRN that is designed to |
30725 | overcome the security problems of the TURN command (which has fallen into | |
30726 | disuse). When Exim receives an ETRN command on a TCP/IP connection, it runs | |
9b371988 | 30727 | the ACL specified by &%acl_smtp_etrn%& in order to decide whether the command |
168e428f PH |
30728 | should be accepted or not. If no ACL is defined, the command is rejected. |
30729 | ||
9b371988 | 30730 | The ETRN command is concerned with &"releasing"& messages that are awaiting |
168e428f PH |
30731 | delivery to certain hosts. As Exim does not organize its message queue by host, |
30732 | the only form of ETRN that is supported by default is the one where the | |
9b371988 | 30733 | text starts with the &"#"& prefix, in which case the remainder of the text is |
168e428f | 30734 | specific to the SMTP server. A valid ETRN command causes a run of Exim with |
9b371988 | 30735 | the &%-R%& option to happen, with the remainder of the ETRN text as its |
168e428f | 30736 | argument. For example, |
9b371988 PH |
30737 | .code |
30738 | ETRN #brigadoon | |
30739 | .endd | |
168e428f | 30740 | runs the command |
9b371988 PH |
30741 | .code |
30742 | exim -R brigadoon | |
30743 | .endd | |
168e428f | 30744 | which causes a delivery attempt on all messages with undelivered addresses |
9b371988 | 30745 | containing the text &"brigadoon"&. When &%smtp_etrn_serialize%& is set (the |
168e428f PH |
30746 | default), Exim prevents the simultaneous execution of more than one queue run |
30747 | for the same argument string as a result of an ETRN command. This stops | |
30748 | a misbehaving client from starting more than one queue runner at once. | |
30749 | ||
9b371988 | 30750 | .cindex "hints database" "ETRN serialization" |
168e428f PH |
30751 | Exim implements the serialization by means of a hints database in which a |
30752 | record is written whenever a process is started by ETRN, and deleted when | |
30753 | the process completes. However, Exim does not keep the SMTP session waiting for | |
30754 | the ETRN process to complete. Once ETRN is accepted, the client is sent | |
9b371988 PH |
30755 | a &"success"& return code. Obviously there is scope for hints records to get |
30756 | left lying around if there is a system or program crash. To guard against this, | |
30757 | Exim ignores any records that are more than six hours old. | |
168e428f | 30758 | |
0a4e3112 | 30759 | .oindex "&%smtp_etrn_command%&" |
9b371988 | 30760 | For more control over what ETRN does, the &%smtp_etrn_command%& option can |
168e428f PH |
30761 | used. This specifies a command that is run whenever ETRN is received, |
30762 | whatever the form of its argument. For | |
30763 | example: | |
9b371988 PH |
30764 | .code |
30765 | smtp_etrn_command = /etc/etrn_command $domain \ | |
30766 | $sender_host_address | |
30767 | .endd | |
f89d2485 | 30768 | .vindex "&$domain$&" |
168e428f | 30769 | The string is split up into arguments which are independently expanded. The |
9b371988 | 30770 | expansion variable &$domain$& is set to the argument of the ETRN command, |
168e428f PH |
30771 | and no syntax checking is done on the contents of this argument. Exim does not |
30772 | wait for the command to complete, so its status code is not checked. Exim runs | |
30773 | under its own uid and gid when receiving incoming SMTP, so it is not possible | |
30774 | for it to change them before running the command. | |
30775 | ||
30776 | ||
30777 | ||
f89d2485 | 30778 | .section "Incoming local SMTP" "SECID238" |
9b371988 | 30779 | .cindex "SMTP" "local incoming" |
168e428f PH |
30780 | Some user agents use SMTP to pass messages to their local MTA using the |
30781 | standard input and output, as opposed to passing the envelope on the command | |
30782 | line and writing the message to the standard input. This is supported by the | |
9b371988 | 30783 | &%-bs%& option. This form of SMTP is handled in the same way as incoming |
168e428f PH |
30784 | messages over TCP/IP (including the use of ACLs), except that the envelope |
30785 | sender given in a MAIL command is ignored unless the caller is trusted. In | |
30786 | an ACL you can detect this form of SMTP input by testing for an empty host | |
30787 | identification. It is common to have this as the first line in the ACL that | |
30788 | runs for RCPT commands: | |
9b371988 PH |
30789 | .code |
30790 | accept hosts = : | |
30791 | .endd | |
168e428f PH |
30792 | This accepts SMTP messages from local processes without doing any other tests. |
30793 | ||
30794 | ||
30795 | ||
9b371988 PH |
30796 | .section "Outgoing batched SMTP" "SECTbatchSMTP" |
30797 | .cindex "SMTP" "batched outgoing" | |
30798 | .cindex "batched SMTP output" | |
30799 | Both the &(appendfile)& and &(pipe)& transports can be used for handling | |
30800 | batched SMTP. Each has an option called &%use_bsmtp%& which causes messages to | |
30801 | be output in BSMTP format. No SMTP responses are possible for this form of | |
30802 | delivery. All it is doing is using SMTP commands as a way of transmitting the | |
30803 | envelope along with the message. | |
168e428f PH |
30804 | |
30805 | The message is written to the file or pipe preceded by the SMTP commands | |
30806 | MAIL and RCPT, and followed by a line containing a single dot. Lines in | |
30807 | the message that start with a dot have an extra dot added. The SMTP command | |
9b371988 | 30808 | HELO is not normally used. If it is required, the &%message_prefix%& option |
168e428f PH |
30809 | can be used to specify it. |
30810 | ||
9b371988 | 30811 | Because &(appendfile)& and &(pipe)& are both local transports, they accept only |
168e428f | 30812 | one recipient address at a time by default. However, you can arrange for them |
9b371988 | 30813 | to handle several addresses at once by setting the &%batch_max%& option. When |
168e428f | 30814 | this is done for BSMTP, messages may contain multiple RCPT commands. See |
9b371988 | 30815 | chapter &<<CHAPbatching>>& for more details. |
168e428f | 30816 | |
f89d2485 | 30817 | .vindex "&$host$&" |
168e428f PH |
30818 | When one or more addresses are routed to a BSMTP transport by a router that |
30819 | sets up a host list, the name of the first host on the list is available to the | |
9b371988 | 30820 | transport in the variable &$host$&. Here is an example of such a transport and |
168e428f | 30821 | router: |
9b371988 PH |
30822 | .code |
30823 | begin routers | |
30824 | route_append: | |
30825 | driver = manualroute | |
30826 | transport = smtp_appendfile | |
30827 | route_list = domain.example batch.host.example | |
168e428f | 30828 | |
9b371988 PH |
30829 | begin transports |
30830 | smtp_appendfile: | |
30831 | driver = appendfile | |
30832 | directory = /var/bsmtp/$host | |
30833 | batch_max = 1000 | |
30834 | use_bsmtp | |
30835 | user = exim | |
30836 | .endd | |
30837 | This causes messages addressed to &'domain.example'& to be written in BSMTP | |
30838 | format to &_/var/bsmtp/batch.host.example_&, with only a single copy of each | |
168e428f PH |
30839 | message (unless there are more than 1000 recipients). |
30840 | ||
30841 | ||
30842 | ||
9b371988 PH |
30843 | .section "Incoming batched SMTP" "SECTincomingbatchedSMTP" |
30844 | .cindex "SMTP" "batched incoming" | |
30845 | .cindex "batched SMTP input" | |
30846 | The &%-bS%& command line option causes Exim to accept one or more messages by | |
168e428f PH |
30847 | reading SMTP on the standard input, but to generate no responses. If the caller |
30848 | is trusted, the senders in the MAIL commands are believed; otherwise the | |
30849 | sender is always the caller of Exim. Unqualified senders and receivers are not | |
30850 | rejected (there seems little point) but instead just get qualified. HELO | |
30851 | and EHLO act as RSET; VRFY, EXPN, ETRN and HELP, act | |
30852 | as NOOP; QUIT quits. | |
30853 | ||
30854 | No policy checking is done for BSMTP input. That is, no ACL is run at anytime. | |
30855 | In this respect it is like non-SMTP local input. | |
30856 | ||
9b371988 | 30857 | If an error is detected while reading a message, including a missing &"."& at |
168e428f PH |
30858 | the end, Exim gives up immediately. It writes details of the error to the |
30859 | standard output in a stylized way that the calling program should be able to | |
30860 | make some use of automatically, for example: | |
9b371988 PH |
30861 | .code |
30862 | 554 Unexpected end of file | |
30863 | Transaction started in line 10 | |
30864 | Error detected in line 14 | |
30865 | .endd | |
168e428f PH |
30866 | It writes a more verbose version, for human consumption, to the standard error |
30867 | file, for example: | |
9b371988 PH |
30868 | .code |
30869 | An error was detected while processing a file of BSMTP input. | |
30870 | The error message was: | |
168e428f | 30871 | |
9b371988 | 30872 | 501 '>' missing at end of address |
168e428f | 30873 | |
9b371988 PH |
30874 | The SMTP transaction started in line 10. |
30875 | The error was detected in line 12. | |
30876 | The SMTP command at fault was: | |
168e428f | 30877 | |
9b371988 | 30878 | rcpt to:<malformed@in.com.plete |
168e428f | 30879 | |
9b371988 PH |
30880 | 1 previous message was successfully processed. |
30881 | The rest of the batch was abandoned. | |
30882 | .endd | |
168e428f PH |
30883 | The return code from Exim is zero only if there were no errors. It is 1 if some |
30884 | messages were accepted before an error was detected, and 2 if no messages were | |
30885 | accepted. | |
4f578862 PH |
30886 | .ecindex IIDsmtpproc1 |
30887 | .ecindex IIDsmtpproc2 | |
168e428f PH |
30888 | |
30889 | ||
30890 | ||
9b371988 PH |
30891 | . //////////////////////////////////////////////////////////////////////////// |
30892 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 30893 | |
9b371988 PH |
30894 | .chapter "Customizing bounce and warning messages" "CHAPemsgcust" &&& |
30895 | "Customizing messages" | |
168e428f PH |
30896 | When a message fails to be delivered, or remains on the queue for more than a |
30897 | configured amount of time, Exim sends a message to the original sender, or | |
30898 | to an alternative configured address. The text of these messages is built into | |
30899 | the code of Exim, but it is possible to change it, either by adding a single | |
30900 | string, or by replacing each of the paragraphs by text supplied in a file. | |
30901 | ||
9b371988 PH |
30902 | The &'From:'& and &'To:'& header lines are automatically generated; you can |
30903 | cause a &'Reply-To:'& line to be added by setting the &%errors_reply_to%& | |
30904 | option. Exim also adds the line | |
30905 | .code | |
30906 | Auto-Submitted: auto-generated | |
30907 | .endd | |
168e428f PH |
30908 | to all warning and bounce messages, |
30909 | ||
30910 | ||
f89d2485 | 30911 | .section "Customizing bounce messages" "SECID239" |
9b371988 PH |
30912 | .cindex "customizing" "bounce message" |
30913 | .cindex "bounce message" "customizing" | |
30914 | If &%bounce_message_text%& is set, its contents are included in the default | |
30915 | message immediately after &"This message was created automatically by mail | |
30916 | delivery software."& The string is not expanded. It is not used if | |
30917 | &%bounce_message_file%& is set. | |
168e428f | 30918 | |
9b371988 | 30919 | When &%bounce_message_file%& is set, it must point to a template file for |
168e428f PH |
30920 | constructing error messages. The file consists of a series of text items, |
30921 | separated by lines consisting of exactly four asterisks. If the file cannot be | |
30922 | opened, default text is used and a message is written to the main and panic | |
30923 | logs. If any text item in the file is empty, default text is used for that | |
30924 | item. | |
30925 | ||
f89d2485 PH |
30926 | .vindex "&$bounce_recipient$&" |
30927 | .vindex "&$bounce_return_size_limit$&" | |
168e428f | 30928 | Each item of text that is read from the file is expanded, and there are two |
9b371988 PH |
30929 | expansion variables which can be of use here: &$bounce_recipient$& is set to |
30930 | the recipient of an error message while it is being created, and | |
30931 | &$bounce_return_size_limit$& contains the value of the &%return_size_limit%& | |
068aaea8 | 30932 | option, rounded to a whole number. |
168e428f PH |
30933 | |
30934 | The items must appear in the file in the following order: | |
30935 | ||
9b371988 PH |
30936 | .ilist |
30937 | The first item is included in the headers, and should include at least a | |
30938 | &'Subject:'& header. Exim does not check the syntax of these headers. | |
30939 | .next | |
30940 | The second item forms the start of the error message. After it, Exim lists the | |
168e428f | 30941 | failing addresses with their error messages. |
9b371988 PH |
30942 | .next |
30943 | The third item is used to introduce any text from pipe transports that is to be | |
168e428f | 30944 | returned to the sender. It is omitted if there is no such text. |
9b371988 PH |
30945 | .next |
30946 | The fourth item is used to introduce the copy of the message that is returned | |
168e428f | 30947 | as part of the error report. |
9b371988 PH |
30948 | .next |
30949 | The fifth item is added after the fourth one if the returned message is | |
30950 | truncated because it is bigger than &%return_size_limit%&. | |
30951 | .next | |
30952 | The sixth item is added after the copy of the original message. | |
30953 | .endlist | |
30954 | ||
30955 | The default state (&%bounce_message_file%& unset) is equivalent to the | |
30956 | following file, in which the sixth item is empty. The &'Subject:'& and some | |
30957 | other lines have been split in order to fit them on the page: | |
30958 | .code | |
30959 | Subject: Mail delivery failed | |
30960 | ${if eq{$sender_address}{$bounce_recipient} | |
30961 | {: returning message to sender}} | |
30962 | **** | |
30963 | This message was created automatically by mail delivery software. | |
30964 | ||
30965 | A message ${if eq{$sender_address}{$bounce_recipient} | |
30966 | {that you sent }{sent by | |
30967 | ||
30968 | <$sender_address> | |
30969 | ||
30970 | }}could not be delivered to all of its recipients. | |
3cb1b51e | 30971 | This is a permanent error. The following address(es) failed: |
9b371988 PH |
30972 | **** |
30973 | The following text was generated during the delivery attempt(s): | |
30974 | **** | |
30975 | ------ This is a copy of the message, including all the headers. | |
30976 | ------ | |
30977 | **** | |
30978 | ------ The body of the message is $message_size characters long; | |
30979 | only the first | |
30980 | ------ $bounce_return_size_limit or so are included here. | |
30981 | **** | |
30982 | .endd | |
30983 | .section "Customizing warning messages" "SECTcustwarn" | |
30984 | .cindex "customizing" "warning message" | |
30985 | .cindex "warning of delay" "customizing the message" | |
30986 | The option &%warn_message_file%& can be pointed at a template file for use when | |
168e428f PH |
30987 | warnings about message delays are created. In this case there are only three |
30988 | text sections: | |
30989 | ||
9b371988 PH |
30990 | .ilist |
30991 | The first item is included in the headers, and should include at least a | |
30992 | &'Subject:'& header. Exim does not check the syntax of these headers. | |
30993 | .next | |
30994 | The second item forms the start of the warning message. After it, Exim lists | |
168e428f | 30995 | the delayed addresses. |
9b371988 PH |
30996 | .next |
30997 | The third item then ends the message. | |
30998 | .endlist | |
30999 | ||
31000 | The default state is equivalent to the following file, except that some lines | |
31001 | have been split here, in order to fit them on the page: | |
31002 | .code | |
31003 | Subject: Warning: message $message_exim_id delayed | |
31004 | $warn_message_delay | |
31005 | **** | |
31006 | This message was created automatically by mail delivery software. | |
31007 | ||
31008 | A message ${if eq{$sender_address}{$warn_message_recipients} | |
31009 | {that you sent }{sent by | |
31010 | ||
31011 | <$sender_address> | |
31012 | ||
31013 | }}has not been delivered to all of its recipients after | |
31014 | more than $warn_message_delay on the queue on $primary_hostname. | |
31015 | ||
31016 | The message identifier is: $message_exim_id | |
31017 | The subject of the message is: $h_subject | |
31018 | The date of the message is: $h_date | |
31019 | ||
31020 | The following address(es) have not yet been delivered: | |
31021 | **** | |
31022 | No action is required on your part. Delivery attempts will | |
31023 | continue for some time, and this warning may be repeated at | |
31024 | intervals if the message remains undelivered. Eventually the | |
31025 | mail delivery software will give up, and when that happens, | |
31026 | the message will be returned to you. | |
31027 | .endd | |
f89d2485 PH |
31028 | .vindex "&$warn_message_delay$&" |
31029 | .vindex "&$warn_message_recipients$&" | |
9b371988 | 31030 | However, in the default state the subject and date lines are omitted if no |
168e428f | 31031 | appropriate headers exist. During the expansion of this file, |
9b371988 PH |
31032 | &$warn_message_delay$& is set to the delay time in one of the forms &"<&'n'&> |
31033 | minutes"& or &"<&'n'&> hours"&, and &$warn_message_recipients$& contains a list | |
31034 | of recipients for the warning message. There may be more than one if there are | |
31035 | multiple addresses with different &%errors_to%& settings on the routers that | |
168e428f PH |
31036 | handled them. |
31037 | ||
31038 | ||
31039 | ||
31040 | ||
9b371988 PH |
31041 | . //////////////////////////////////////////////////////////////////////////// |
31042 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 31043 | |
9b371988 | 31044 | .chapter "Some common configuration settings" "CHAPcomconreq" |
168e428f PH |
31045 | This chapter discusses some configuration settings that seem to be fairly |
31046 | common. More examples and discussion can be found in the Exim book. | |
31047 | ||
31048 | ||
31049 | ||
f89d2485 | 31050 | .section "Sending mail to a smart host" "SECID240" |
9b371988 PH |
31051 | .cindex "smart host" "example router" |
31052 | If you want to send all mail for non-local domains to a &"smart host"&, you | |
31053 | should replace the default &(dnslookup)& router with a router which does the | |
168e428f | 31054 | routing explicitly: |
9b371988 PH |
31055 | .code |
31056 | send_to_smart_host: | |
31057 | driver = manualroute | |
31058 | route_list = !+local_domains smart.host.name | |
31059 | transport = remote_smtp | |
31060 | .endd | |
168e428f | 31061 | You can use the smart host's IP address instead of the name if you wish. |
168e428f PH |
31062 | If you are using Exim only to submit messages to a smart host, and not for |
31063 | receiving incoming messages, you can arrange for it to do the submission | |
9b371988 PH |
31064 | synchronously by setting the &%mua_wrapper%& option (see chapter |
31065 | &<<CHAPnonqueueing>>&). | |
168e428f PH |
31066 | |
31067 | ||
31068 | ||
31069 | ||
9b371988 PH |
31070 | .section "Using Exim to handle mailing lists" "SECTmailinglists" |
31071 | .cindex "mailing lists" | |
168e428f PH |
31072 | Exim can be used to run simple mailing lists, but for large and/or complicated |
31073 | requirements, the use of additional specialized mailing list software such as | |
31074 | Majordomo or Mailman is recommended. | |
31075 | ||
9b371988 | 31076 | The &(redirect)& router can be used to handle mailing lists where each list |
168e428f | 31077 | is maintained in a separate file, which can therefore be managed by an |
9b371988 | 31078 | independent manager. The &%domains%& router option can be used to run these |
168e428f | 31079 | lists in a separate domain from normal mail. For example: |
9b371988 PH |
31080 | .code |
31081 | lists: | |
31082 | driver = redirect | |
31083 | domains = lists.example | |
31084 | file = /usr/lists/$local_part | |
31085 | forbid_pipe | |
31086 | forbid_file | |
31087 | errors_to = $local_part-request@lists.example | |
31088 | no_more | |
31089 | .endd | |
31090 | This router is skipped for domains other than &'lists.example'&. For addresses | |
168e428f | 31091 | in that domain, it looks for a file that matches the local part. If there is no |
9b371988 | 31092 | such file, the router declines, but because &%no_more%& is set, no subsequent |
168e428f PH |
31093 | routers are tried, and so the whole delivery fails. |
31094 | ||
9b371988 | 31095 | The &%forbid_pipe%& and &%forbid_file%& options prevent a local part from being |
168e428f PH |
31096 | expanded into a file name or a pipe delivery, which is usually inappropriate in |
31097 | a mailing list. | |
31098 | ||
0a4e3112 | 31099 | .oindex "&%errors_to%&" |
9b371988 | 31100 | The &%errors_to%& option specifies that any delivery errors caused by addresses |
168e428f PH |
31101 | taken from a mailing list are to be sent to the given address rather than the |
31102 | original sender of the message. However, before acting on this, Exim verifies | |
31103 | the error address, and ignores it if verification fails. | |
31104 | ||
31105 | For example, using the configuration above, mail sent to | |
9b371988 PH |
31106 | &'dicts@lists.example'& is passed on to those addresses contained in |
31107 | &_/usr/lists/dicts_&, with error reports directed to | |
31108 | &'dicts-request@lists.example'&, provided that this address can be verified. | |
31109 | There could be a file called &_/usr/lists/dicts-request_& containing | |
168e428f | 31110 | the address(es) of this particular list's manager(s), but other approaches, |
9b371988 PH |
31111 | such as setting up an earlier router (possibly using the &%local_part_prefix%& |
31112 | or &%local_part_suffix%& options) to handle addresses of the form | |
31113 | &%owner-%&&'xxx'& or &%xxx-%&&'request'&, are also possible. | |
168e428f PH |
31114 | |
31115 | ||
31116 | ||
f89d2485 | 31117 | .section "Syntax errors in mailing lists" "SECID241" |
9b371988 | 31118 | .cindex "mailing lists" "syntax errors in" |
168e428f PH |
31119 | If an entry in redirection data contains a syntax error, Exim normally defers |
31120 | delivery of the original address. That means that a syntax error in a mailing | |
31121 | list holds up all deliveries to the list. This may not be appropriate when a | |
31122 | list is being maintained automatically from data supplied by users, and the | |
31123 | addresses are not rigorously checked. | |
31124 | ||
9b371988 | 31125 | If the &%skip_syntax_errors%& option is set, the &(redirect)& router just skips |
168e428f | 31126 | entries that fail to parse, noting the incident in the log. If in addition |
9b371988 | 31127 | &%syntax_errors_to%& is set to a verifiable address, a message is sent to it |
168e428f | 31128 | whenever a broken address is skipped. It is usually appropriate to set |
9b371988 | 31129 | &%syntax_errors_to%& to the same address as &%errors_to%&. |
168e428f PH |
31130 | |
31131 | ||
31132 | ||
f89d2485 | 31133 | .section "Re-expansion of mailing lists" "SECID242" |
9b371988 | 31134 | .cindex "mailing lists" "re-expansion of" |
168e428f PH |
31135 | Exim remembers every individual address to which a message has been delivered, |
31136 | in order to avoid duplication, but it normally stores only the original | |
31137 | recipient addresses with a message. If all the deliveries to a mailing list | |
31138 | cannot be done at the first attempt, the mailing list is re-expanded when the | |
31139 | delivery is next tried. This means that alterations to the list are taken into | |
31140 | account at each delivery attempt, so addresses that have been added to | |
31141 | the list since the message arrived will therefore receive a copy of the | |
31142 | message, even though it pre-dates their subscription. | |
31143 | ||
9b371988 PH |
31144 | If this behaviour is felt to be undesirable, the &%one_time%& option can be set |
31145 | on the &(redirect)& router. If this is done, any addresses generated by the | |
168e428f | 31146 | router that fail to deliver at the first attempt are added to the message as |
9b371988 PH |
31147 | &"top level"& addresses, and the parent address that generated them is marked |
31148 | &"delivered"&. Thus, expansion of the mailing list does not happen again at the | |
168e428f PH |
31149 | subsequent delivery attempts. The disadvantage of this is that if any of the |
31150 | failing addresses are incorrect, correcting them in the file has no effect on | |
31151 | pre-existing messages. | |
31152 | ||
31153 | The original top-level address is remembered with each of the generated | |
31154 | addresses, and is output in any log messages. However, any intermediate parent | |
31155 | addresses are not recorded. This makes a difference to the log only if the | |
9b371988 | 31156 | &%all_parents%& selector is set, but for mailing lists there is normally only |
168e428f PH |
31157 | one level of expansion anyway. |
31158 | ||
31159 | ||
31160 | ||
f89d2485 | 31161 | .section "Closed mailing lists" "SECID243" |
9b371988 | 31162 | .cindex "mailing lists" "closed" |
168e428f PH |
31163 | The examples so far have assumed open mailing lists, to which anybody may |
31164 | send mail. It is also possible to set up closed lists, where mail is accepted | |
31165 | from specified senders only. This is done by making use of the generic | |
9b371988 | 31166 | &%senders%& option to restrict the router that handles the list. |
168e428f PH |
31167 | |
31168 | The following example uses the same file as a list of recipients and as a list | |
31169 | of permitted senders. It requires three routers: | |
9b371988 | 31170 | .code |
168e428f PH |
31171 | lists_request: |
31172 | driver = redirect | |
31173 | domains = lists.example | |
31174 | local_part_suffix = -request | |
31175 | file = /usr/lists/$local_part$local_part_suffix | |
31176 | no_more | |
31177 | ||
31178 | lists_post: | |
31179 | driver = redirect | |
31180 | domains = lists.example | |
31181 | senders = ${if exists {/usr/lists/$local_part}\ | |
31182 | {lsearch;/usr/lists/$local_part}{*}} | |
31183 | file = /usr/lists/$local_part | |
31184 | forbid_pipe | |
31185 | forbid_file | |
31186 | errors_to = $local_part-request@lists.example | |
31187 | no_more | |
31188 | ||
31189 | lists_closed: | |
31190 | driver = redirect | |
31191 | domains = lists.example | |
31192 | allow_fail | |
31193 | data = :fail: $local_part@lists.example is a closed mailing list | |
9b371988 PH |
31194 | .endd |
31195 | All three routers have the same &%domains%& setting, so for any other domains, | |
168e428f | 31196 | they are all skipped. The first router runs only if the local part ends in |
9b371988 | 31197 | &%-request%&. It handles messages to the list manager(s) by means of an open |
168e428f PH |
31198 | mailing list. |
31199 | ||
9b371988 | 31200 | The second router runs only if the &%senders%& precondition is satisfied. It |
168e428f PH |
31201 | checks for the existence of a list that corresponds to the local part, and then |
31202 | checks that the sender is on the list by means of a linear search. It is | |
31203 | necessary to check for the existence of the file before trying to search it, | |
31204 | because otherwise Exim thinks there is a configuration error. If the file does | |
9b371988 | 31205 | not exist, the expansion of &%senders%& is *, which matches all senders. This |
168e428f | 31206 | means that the router runs, but because there is no list, declines, and |
9b371988 PH |
31207 | &%no_more%& ensures that no further routers are run. The address fails with an |
31208 | &"unrouteable address"& error. | |
168e428f PH |
31209 | |
31210 | The third router runs only if the second router is skipped, which happens when | |
31211 | a mailing list exists, but the sender is not on it. This router forcibly fails | |
31212 | the address, giving a suitable error message. | |
31213 | ||
31214 | ||
31215 | ||
31216 | ||
4f578862 PH |
31217 | .section "Variable Envelope Return Paths (VERP)" "SECTverp" |
31218 | .cindex "VERP" | |
31219 | .cindex "Variable Envelope Return Paths" | |
31220 | .cindex "envelope sender" | |
31221 | Variable Envelope Return Paths &-- see &url(http://cr.yp.to/proto/verp.txt) &-- | |
31222 | are a way of helping mailing list administrators discover which subscription | |
31223 | address is the cause of a particular delivery failure. The idea is to encode | |
31224 | the original recipient address in the outgoing envelope sender address, so that | |
31225 | if the message is forwarded by another host and then subsequently bounces, the | |
31226 | original recipient can be extracted from the recipient address of the bounce. | |
31227 | ||
31228 | .oindex &%errors_to%& | |
31229 | .oindex &%return_path%& | |
31230 | Envelope sender addresses can be modified by Exim using two different | |
31231 | facilities: the &%errors_to%& option on a router (as shown in previous mailing | |
31232 | list examples), or the &%return_path%& option on a transport. The second of | |
31233 | these is effective only if the message is successfully delivered to another | |
31234 | host; it is not used for errors detected on the local host (see the description | |
31235 | of &%return_path%& in chapter &<<CHAPtransportgeneric>>&). Here is an example | |
31236 | of the use of &%return_path%& to implement VERP on an &(smtp)& transport: | |
31237 | .code | |
31238 | verp_smtp: | |
31239 | driver = smtp | |
31240 | max_rcpt = 1 | |
31241 | return_path = \ | |
31242 | ${if match {$return_path}{^(.+?)-request@your.dom.example\$}\ | |
3cb1b51e | 31243 | {$1-request+$local_part=$domain@your.dom.example}fail} |
4f578862 PH |
31244 | .endd |
31245 | This has the effect of rewriting the return path (envelope sender) on outgoing | |
31246 | SMTP messages, if the local part of the original return path ends in | |
31247 | &"-request"&, and the domain is &'your.dom.example'&. The rewriting inserts the | |
31248 | local part and domain of the recipient into the return path. Suppose, for | |
31249 | example, that a message whose return path has been set to | |
31250 | &'somelist-request@your.dom.example'& is sent to | |
31251 | &'subscriber@other.dom.example'&. In the transport, the return path is | |
31252 | rewritten as | |
31253 | .code | |
3cb1b51e | 31254 | somelist-request+subscriber=other.dom.example@your.dom.example |
4f578862 | 31255 | .endd |
f89d2485 | 31256 | .vindex "&$local_part$&" |
db9452a9 PH |
31257 | For this to work, you must tell Exim to send multiple copies of messages that |
31258 | have more than one recipient, so that each copy has just one recipient. This is | |
4f578862 PH |
31259 | achieved by setting &%max_rcpt%& to 1. Without this, a single copy of a message |
31260 | might be sent to several different recipients in the same domain, in which case | |
31261 | &$local_part$& is not available in the transport, because it is not unique. | |
31262 | ||
31263 | Unless your host is doing nothing but mailing list deliveries, you should | |
31264 | probably use a separate transport for the VERP deliveries, so as not to use | |
db9452a9 PH |
31265 | extra resources in making one-per-recipient copies for other deliveries. This |
31266 | can easily be done by expanding the &%transport%& option in the router: | |
4f578862 PH |
31267 | .code |
31268 | dnslookup: | |
31269 | driver = dnslookup | |
31270 | domains = ! +local_domains | |
31271 | transport = \ | |
31272 | ${if match {$return_path}{^(.+?)-request@your.dom.example\$}\ | |
31273 | {verp_smtp}{remote_smtp}} | |
31274 | no_more | |
31275 | .endd | |
31276 | If you want to change the return path using &%errors_to%& in a router instead | |
31277 | of using &%return_path%& in the transport, you need to set &%errors_to%& on all | |
31278 | routers that handle mailing list addresses. This will ensure that all delivery | |
31279 | errors, including those detected on the local host, are sent to the VERP | |
31280 | address. | |
31281 | ||
31282 | On a host that does no local deliveries and has no manual routing, only the | |
31283 | &(dnslookup)& router needs to be changed. A special transport is not needed for | |
31284 | SMTP deliveries. Every mailing list recipient has its own return path value, | |
31285 | and so Exim must hand them to the transport one at a time. Here is an example | |
31286 | of a &(dnslookup)& router that implements VERP: | |
31287 | .code | |
31288 | verp_dnslookup: | |
31289 | driver = dnslookup | |
31290 | domains = ! +local_domains | |
31291 | transport = remote_smtp | |
31292 | errors_to = \ | |
31293 | ${if match {$return_path}{^(.+?)-request@your.dom.example\$}} | |
3cb1b51e | 31294 | {$1-request+$local_part=$domain@your.dom.example}fail} |
4f578862 PH |
31295 | no_more |
31296 | .endd | |
31297 | Before you start sending out messages with VERPed return paths, you must also | |
31298 | configure Exim to accept the bounce messages that come back to those paths. | |
31299 | Typically this is done by setting a &%local_part_suffix%& option for a | |
31300 | router, and using this to route the messages to wherever you want to handle | |
31301 | them. | |
31302 | ||
31303 | The overhead incurred in using VERP depends very much on the size of the | |
31304 | message, the number of recipient addresses that resolve to the same remote | |
31305 | host, and the speed of the connection over which the message is being sent. If | |
31306 | a lot of addresses resolve to the same host and the connection is slow, sending | |
31307 | a separate copy of the message for each address may take substantially longer | |
31308 | than sending a single copy with many recipients (for which VERP cannot be | |
31309 | used). | |
4f578862 PH |
31310 | |
31311 | ||
31312 | ||
31313 | ||
31314 | ||
31315 | ||
9b371988 PH |
31316 | .section "Virtual domains" "SECTvirtualdomains" |
31317 | .cindex "virtual domains" | |
31318 | .cindex "domain" "virtual" | |
31319 | The phrase &'virtual domain'& is unfortunately used with two rather different | |
168e428f PH |
31320 | meanings: |
31321 | ||
9b371988 PH |
31322 | .ilist |
31323 | A domain for which there are no real mailboxes; all valid local parts are | |
168e428f | 31324 | aliases for other email addresses. Common examples are organizational |
9b371988 PH |
31325 | top-level domains and &"vanity"& domains. |
31326 | .next | |
31327 | One of a number of independent domains that are all handled by the same host, | |
168e428f PH |
31328 | with mailboxes on that host, but where the mailbox owners do not necessarily |
31329 | have login accounts on that host. | |
9b371988 | 31330 | .endlist |
168e428f | 31331 | |
9b371988 PH |
31332 | The first usage is probably more common, and does seem more &"virtual"& than |
31333 | the second. This kind of domain can be handled in Exim with a straightforward | |
168e428f PH |
31334 | aliasing router. One approach is to create a separate alias file for each |
31335 | virtual domain. Exim can test for the existence of the alias file to determine | |
9b371988 | 31336 | whether the domain exists. The &(dsearch)& lookup type is useful here, leading |
168e428f | 31337 | to a router of this form: |
9b371988 PH |
31338 | .code |
31339 | virtual: | |
31340 | driver = redirect | |
31341 | domains = dsearch;/etc/mail/virtual | |
31342 | data = ${lookup{$local_part}lsearch{/etc/mail/virtual/$domain}} | |
31343 | no_more | |
31344 | .endd | |
31345 | The &%domains%& option specifies that the router is to be skipped, unless there | |
31346 | is a file in the &_/etc/mail/virtual_& directory whose name is the same as the | |
168e428f | 31347 | domain that is being processed. When the router runs, it looks up the local |
9b371988 PH |
31348 | part in the file to find a new address (or list of addresses). The &%no_more%& |
31349 | setting ensures that if the lookup fails (leading to &%data%& being an empty | |
168e428f PH |
31350 | string), Exim gives up on the address without trying any subsequent routers. |
31351 | ||
31352 | This one router can handle all the virtual domains because the alias file names | |
31353 | follow a fixed pattern. Permissions can be arranged so that appropriate people | |
31354 | can edit the different alias files. A successful aliasing operation results in | |
31355 | a new envelope recipient address, which is then routed from scratch. | |
31356 | ||
9b371988 | 31357 | The other kind of &"virtual"& domain can also be handled in a straightforward |
168e428f PH |
31358 | way. One approach is to create a file for each domain containing a list of |
31359 | valid local parts, and use it in a router like this: | |
9b371988 PH |
31360 | .code |
31361 | my_domains: | |
31362 | driver = accept | |
31363 | domains = dsearch;/etc/mail/domains | |
31364 | local_parts = lsearch;/etc/mail/domains/$domain | |
31365 | transport = my_mailboxes | |
31366 | .endd | |
168e428f | 31367 | The address is accepted if there is a file for the domain, and the local part |
9b371988 PH |
31368 | can be found in the file. The &%domains%& option is used to check for the |
31369 | file's existence because &%domains%& is tested before the &%local_parts%& | |
31370 | option (see section &<<SECTrouprecon>>&). You cannot use &%require_files%&, | |
31371 | because that option is tested after &%local_parts%&. The transport is as | |
31372 | follows: | |
31373 | .code | |
31374 | my_mailboxes: | |
31375 | driver = appendfile | |
31376 | file = /var/mail/$domain/$local_part | |
31377 | user = mail | |
31378 | .endd | |
31379 | This uses a directory of mailboxes for each domain. The &%user%& setting is | |
168e428f PH |
31380 | required, to specify which uid is to be used for writing to the mailboxes. |
31381 | ||
31382 | The configuration shown here is just one example of how you might support this | |
31383 | requirement. There are many other ways this kind of configuration can be set | |
31384 | up, for example, by using a database instead of separate files to hold all the | |
31385 | information about the domains. | |
31386 | ||
31387 | ||
31388 | ||
9b371988 PH |
31389 | .section "Multiple user mailboxes" "SECTmulbox" |
31390 | .cindex "multiple mailboxes" | |
31391 | .cindex "mailbox" "multiple" | |
31392 | .cindex "local part" "prefix" | |
31393 | .cindex "local part" "suffix" | |
168e428f PH |
31394 | Heavy email users often want to operate with multiple mailboxes, into which |
31395 | incoming mail is automatically sorted. A popular way of handling this is to | |
31396 | allow users to use multiple sender addresses, so that replies can easily be | |
31397 | identified. Users are permitted to add prefixes or suffixes to their local | |
31398 | parts for this purpose. The wildcard facility of the generic router options | |
9b371988 | 31399 | &%local_part_prefix%& and &%local_part_suffix%& can be used for this. For |
168e428f | 31400 | example, consider this router: |
9b371988 PH |
31401 | .code |
31402 | userforward: | |
31403 | driver = redirect | |
31404 | check_local_user | |
31405 | file = $home/.forward | |
31406 | local_part_suffix = -* | |
31407 | local_part_suffix_optional | |
31408 | allow_filter | |
31409 | .endd | |
f89d2485 | 31410 | .vindex "&$local_part_suffix$&" |
9b371988 PH |
31411 | It runs a user's &_.forward_& file for all local parts of the form |
31412 | &'username-*'&. Within the filter file the user can distinguish different | |
31413 | cases by testing the variable &$local_part_suffix$&. For example: | |
31414 | .code | |
31415 | if $local_part_suffix contains -special then | |
31416 | save /home/$local_part/Mail/special | |
31417 | endif | |
31418 | .endd | |
168e428f PH |
31419 | If the filter file does not exist, or does not deal with such addresses, they |
31420 | fall through to subsequent routers, and, assuming no subsequent use of the | |
9b371988 | 31421 | &%local_part_suffix%& option is made, they presumably fail. Thus, users have |
168e428f PH |
31422 | control over which suffixes are valid. |
31423 | ||
31424 | Alternatively, a suffix can be used to trigger the use of a different | |
9b371988 | 31425 | &_.forward_& file &-- which is the way a similar facility is implemented in |
168e428f | 31426 | another MTA: |
9b371988 PH |
31427 | .code |
31428 | userforward: | |
31429 | driver = redirect | |
31430 | check_local_user | |
31431 | file = $home/.forward$local_part_suffix | |
31432 | local_part_suffix = -* | |
31433 | local_part_suffix_optional | |
31434 | allow_filter | |
31435 | .endd | |
31436 | If there is no suffix, &_.forward_& is used; if the suffix is &'-special'&, for | |
31437 | example, &_.forward-special_& is used. Once again, if the appropriate file | |
168e428f PH |
31438 | does not exist, or does not deal with the address, it is passed on to |
31439 | subsequent routers, which could, if required, look for an unqualified | |
9b371988 | 31440 | &_.forward_& file to use as a default. |
168e428f PH |
31441 | |
31442 | ||
31443 | ||
f89d2485 | 31444 | .section "Simplified vacation processing" "SECID244" |
9b371988 PH |
31445 | .cindex "vacation processing" |
31446 | The traditional way of running the &'vacation'& program is for a user to set up | |
31447 | a pipe command in a &_.forward_& file | |
31448 | (see section &<<SECTspecitredli>>& for syntax details). | |
168e428f PH |
31449 | This is prone to error by inexperienced users. There are two features of Exim |
31450 | that can be used to make this process simpler for users: | |
31451 | ||
9b371988 PH |
31452 | .ilist |
31453 | A local part prefix such as &"vacation-"& can be specified on a router which | |
31454 | can cause the message to be delivered directly to the &'vacation'& program, or | |
31455 | alternatively can use Exim's &(autoreply)& transport. The contents of a user's | |
31456 | &_.forward_& file are then much simpler. For example: | |
31457 | .code | |
31458 | spqr, vacation-spqr | |
31459 | .endd | |
31460 | .next | |
31461 | The &%require_files%& generic router option can be used to trigger a | |
168e428f | 31462 | vacation delivery by checking for the existence of a certain file in the |
9b371988 | 31463 | user's home directory. The &%unseen%& generic option should also be used, to |
168e428f | 31464 | ensure that the original delivery also proceeds. In this case, all the user has |
9b371988 | 31465 | to do is to create a file called, say, &_.vacation_&, containing a vacation |
168e428f | 31466 | message. |
9b371988 | 31467 | .endlist |
168e428f PH |
31468 | |
31469 | Another advantage of both these methods is that they both work even when the | |
31470 | use of arbitrary pipes by users is locked out. | |
31471 | ||
31472 | ||
31473 | ||
f89d2485 | 31474 | .section "Taking copies of mail" "SECID245" |
9b371988 | 31475 | .cindex "message" "copying every" |
168e428f PH |
31476 | Some installations have policies that require archive copies of all messages to |
31477 | be made. A single copy of each message can easily be taken by an appropriate | |
31478 | command in a system filter, which could, for example, use a different file for | |
31479 | each day's messages. | |
31480 | ||
31481 | There is also a shadow transport mechanism that can be used to take copies of | |
31482 | messages that are successfully delivered by local transports, one copy per | |
9b371988 | 31483 | delivery. This could be used, &'inter alia'&, to implement automatic |
168e428f PH |
31484 | notification of delivery by sites that insist on doing such things. |
31485 | ||
31486 | ||
31487 | ||
f89d2485 | 31488 | .section "Intermittently connected hosts" "SECID246" |
9b371988 | 31489 | .cindex "intermittently connected hosts" |
168e428f PH |
31490 | It has become quite common (because it is cheaper) for hosts to connect to the |
31491 | Internet periodically rather than remain connected all the time. The normal | |
31492 | arrangement is that mail for such hosts accumulates on a system that is | |
31493 | permanently connected. | |
31494 | ||
31495 | Exim was designed for use on permanently connected hosts, and so it is not | |
31496 | particularly well-suited to use in an intermittently connected environment. | |
31497 | Nevertheless there are some features that can be used. | |
31498 | ||
31499 | ||
f89d2485 | 31500 | .section "Exim on the upstream server host" "SECID247" |
168e428f PH |
31501 | It is tempting to arrange for incoming mail for the intermittently connected |
31502 | host to remain on Exim's queue until the client connects. However, this | |
31503 | approach does not scale very well. Two different kinds of waiting message are | |
9b371988 | 31504 | being mixed up in the same queue &-- those that cannot be delivered because of |
168e428f PH |
31505 | some temporary problem, and those that are waiting for their destination host |
31506 | to connect. This makes it hard to manage the queue, as well as wasting | |
31507 | resources, because each queue runner scans the entire queue. | |
31508 | ||
31509 | A better approach is to separate off those messages that are waiting for an | |
31510 | intermittently connected host. This can be done by delivering these messages | |
9b371988 | 31511 | into local files in batch SMTP, &"mailstore"&, or other envelope-preserving |
168e428f PH |
31512 | format, from where they are transmitted by other software when their |
31513 | destination connects. This makes it easy to collect all the mail for one host | |
31514 | in a single directory, and to apply local timeout rules on a per-message basis | |
31515 | if required. | |
31516 | ||
31517 | On a very small scale, leaving the mail on Exim's queue can be made to work. If | |
31518 | you are doing this, you should configure Exim with a long retry period for the | |
31519 | intermittent host. For example: | |
9b371988 PH |
31520 | .code |
31521 | cheshire.wonderland.fict.example * F,5d,24h | |
31522 | .endd | |
168e428f PH |
31523 | This stops a lot of failed delivery attempts from occurring, but Exim remembers |
31524 | which messages it has queued up for that host. Once the intermittent host comes | |
9b371988 PH |
31525 | online, forcing delivery of one message (either by using the &%-M%& or &%-R%& |
31526 | options, or by using the ETRN SMTP command (see section &<<SECTETRN>>&) | |
168e428f PH |
31527 | causes all the queued up messages to be delivered, often down a single SMTP |
31528 | connection. While the host remains connected, any new messages get delivered | |
31529 | immediately. | |
31530 | ||
31531 | If the connecting hosts do not have fixed IP addresses, that is, if a host is | |
31532 | issued with a different IP address each time it connects, Exim's retry | |
31533 | mechanisms on the holding host get confused, because the IP address is normally | |
31534 | used as part of the key string for holding retry information. This can be | |
9b371988 | 31535 | avoided by unsetting &%retry_include_ip_address%& on the &(smtp)& transport. |
168e428f PH |
31536 | Since this has disadvantages for permanently connected hosts, it is best to |
31537 | arrange a separate transport for the intermittently connected ones. | |
31538 | ||
31539 | ||
31540 | ||
f89d2485 | 31541 | .section "Exim on the intermittently connected client host" "SECID248" |
9b371988 | 31542 | The value of &%smtp_accept_queue_per_connection%& should probably be |
168e428f PH |
31543 | increased, or even set to zero (that is, disabled) on the intermittently |
31544 | connected host, so that all incoming messages down a single connection get | |
31545 | delivered immediately. | |
31546 | ||
9b371988 PH |
31547 | .cindex "SMTP" "passed connection" |
31548 | .cindex "SMTP" "multiple deliveries" | |
31549 | .cindex "multiple SMTP deliveries" | |
168e428f PH |
31550 | Mail waiting to be sent from an intermittently connected host will probably |
31551 | not have been routed, because without a connection DNS lookups are not | |
31552 | possible. This means that if a normal queue run is done at connection time, | |
31553 | each message is likely to be sent in a separate SMTP session. This can be | |
31554 | avoided by starting the queue run with a command line option beginning with | |
9b371988 PH |
31555 | &%-qq%& instead of &%-q%&. In this case, the queue is scanned twice. In the |
31556 | first pass, routing is done but no deliveries take place. The second pass is a | |
31557 | normal queue run; since all the messages have been previously routed, those | |
31558 | destined for the same host are likely to get sent as multiple deliveries in a | |
31559 | single SMTP connection. | |
168e428f PH |
31560 | |
31561 | ||
31562 | ||
9b371988 PH |
31563 | . //////////////////////////////////////////////////////////////////////////// |
31564 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 31565 | |
9b371988 PH |
31566 | .chapter "Using Exim as a non-queueing client" "CHAPnonqueueing" &&& |
31567 | "Exim as a non-queueing client" | |
f89d2485 PH |
31568 | .cindex "client, non-queueing" |
31569 | .cindex "smart host" "suppressing queueing" | |
168e428f | 31570 | On a personal computer, it is a common requirement for all |
9b371988 | 31571 | email to be sent to a &"smart host"&. There are plenty of MUAs that can be |
168e428f PH |
31572 | configured to operate that way, for all the popular operating systems. |
31573 | However, there are some MUAs for Unix-like systems that cannot be so | |
31574 | configured: they submit messages using the command line interface of | |
9b371988 | 31575 | &_/usr/sbin/sendmail_&. Furthermore, utility programs such as &'cron'& submit |
168e428f PH |
31576 | messages this way. |
31577 | ||
31578 | If the personal computer runs continuously, there is no problem, because it can | |
31579 | run a conventional MTA that handles delivery to the smart host, and deal with | |
31580 | any delays via its queueing mechanism. However, if the computer does not run | |
31581 | continuously or runs different operating systems at different times, queueing | |
31582 | email is not desirable. | |
31583 | ||
31584 | There is therefore a requirement for something that can provide the | |
9b371988 | 31585 | &_/usr/sbin/sendmail_& interface but deliver messages to a smart host without |
168e428f PH |
31586 | any queueing or retrying facilities. Furthermore, the delivery to the smart |
31587 | host should be synchronous, so that if it fails, the sending MUA is immediately | |
31588 | informed. In other words, we want something that extends an MUA that submits | |
31589 | to a local MTA via the command line so that it behaves like one that submits | |
31590 | to a remote smart host using TCP/SMTP. | |
31591 | ||
9b371988 | 31592 | There are a number of applications (for example, there is one called &'ssmtp'&) |
168e428f PH |
31593 | that do this job. However, people have found them to be lacking in various |
31594 | ways. For instance, you might want to allow aliasing and forwarding to be done | |
31595 | before sending a message to the smart host. | |
31596 | ||
31597 | Exim already had the necessary infrastructure for doing this job. Just a few | |
31598 | tweaks were needed to make it behave as required, though it is somewhat of an | |
31599 | overkill to use a fully-featured MTA for this purpose. | |
31600 | ||
0a4e3112 | 31601 | .oindex "&%mua_wrapper%&" |
9b371988 PH |
31602 | There is a Boolean global option called &%mua_wrapper%&, defaulting false. |
31603 | Setting &%mua_wrapper%& true causes Exim to run in a special mode where it | |
31604 | assumes that it is being used to &"wrap"& a command-line MUA in the manner | |
31605 | just described. As well as setting &%mua_wrapper%&, you also need to provide a | |
168e428f PH |
31606 | compatible router and transport configuration. Typically there will be just one |
31607 | router and one transport, sending everything to a smart host. | |
31608 | ||
31609 | When run in MUA wrapping mode, the behaviour of Exim changes in the | |
31610 | following ways: | |
31611 | ||
9b371988 PH |
31612 | .ilist |
31613 | A daemon cannot be run, nor will Exim accept incoming messages from &'inetd'&. | |
168e428f | 31614 | In other words, the only way to submit messages is via the command line. |
9b371988 | 31615 | .next |
f89d2485 | 31616 | Each message is synchronously delivered as soon as it is received (&%-odi%& is |
9b371988 PH |
31617 | assumed). All queueing options (&%queue_only%&, &%queue_smtp_domains%&, |
31618 | &%control%& in an ACL, etc.) are quietly ignored. The Exim reception process | |
31619 | does not finish until the delivery attempt is complete. If the delivery is | |
168e428f | 31620 | successful, a zero return code is given. |
9b371988 PH |
31621 | .next |
31622 | Address redirection is permitted, but the final routing for all addresses must | |
168e428f PH |
31623 | be to the same remote transport, and to the same list of hosts. Furthermore, |
31624 | the return address (envelope sender) must be the same for all recipients, as | |
31625 | must any added or deleted header lines. In other words, it must be possible to | |
31626 | deliver the message in a single SMTP transaction, however many recipients there | |
31627 | are. | |
9b371988 PH |
31628 | .next |
31629 | If these conditions are not met, or if routing any address results in a | |
168e428f PH |
31630 | failure or defer status, or if Exim is unable to deliver all the recipients |
31631 | successfully to one of the smart hosts, delivery of the entire message fails. | |
9b371988 PH |
31632 | .next |
31633 | Because no queueing is allowed, all failures are treated as permanent; there | |
31634 | is no distinction between 4&'xx'& and 5&'xx'& SMTP response codes from the | |
168e428f PH |
31635 | smart host. Furthermore, because only a single yes/no response can be given to |
31636 | the caller, it is not possible to deliver to some recipients and not others. If | |
31637 | there is an error (temporary or permanent) for any recipient, all are failed. | |
9b371988 PH |
31638 | .next |
31639 | If more than one smart host is listed, Exim will try another host after a | |
168e428f PH |
31640 | connection failure or a timeout, in the normal way. However, if this kind of |
31641 | failure happens for all the hosts, the delivery fails. | |
9b371988 PH |
31642 | .next |
31643 | When delivery fails, an error message is written to the standard error stream | |
168e428f PH |
31644 | (as well as to Exim's log), and Exim exits to the caller with a return code |
31645 | value 1. The message is expunged from Exim's spool files. No bounce messages | |
31646 | are ever generated. | |
9b371988 PH |
31647 | .next |
31648 | No retry data is maintained, and any retry rules are ignored. | |
31649 | .next | |
31650 | A number of Exim options are overridden: &%deliver_drop_privilege%& is forced | |
595028e4 | 31651 | true, &%max_rcpt%& in the &(smtp)& transport is forced to &"unlimited"&, |
9b371988 PH |
31652 | &%remote_max_parallel%& is forced to one, and fallback hosts are ignored. |
31653 | .endlist | |
168e428f PH |
31654 | |
31655 | The overall effect is that Exim makes a single synchronous attempt to deliver | |
31656 | the message, failing if there is any kind of problem. Because no local | |
31657 | deliveries are done and no daemon can be run, Exim does not need root | |
9b371988 PH |
31658 | privilege. It should be possible to run it setuid to &'exim'& instead of setuid |
31659 | to &'root'&. See section &<<SECTrunexiwitpri>>& for a general discussion about | |
31660 | the advantages and disadvantages of running without root privilege. | |
168e428f PH |
31661 | |
31662 | ||
31663 | ||
31664 | ||
9b371988 PH |
31665 | . //////////////////////////////////////////////////////////////////////////// |
31666 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 31667 | |
9b371988 | 31668 | .chapter "Log files" "CHAPlog" |
4f578862 | 31669 | .scindex IIDloggen "log" "general description" |
9b371988 | 31670 | .cindex "log" "types of" |
168e428f PH |
31671 | Exim writes three different logs, referred to as the main log, the reject log, |
31672 | and the panic log: | |
31673 | ||
9b371988 PH |
31674 | .ilist |
31675 | .cindex "main log" | |
168e428f PH |
31676 | The main log records the arrival of each message and each delivery in a single |
31677 | line in each case. The format is as compact as possible, in an attempt to keep | |
31678 | down the size of log files. Two-character flag sequences make it easy to pick | |
31679 | out these lines. A number of other events are recorded in the main log. Some of | |
9b371988 PH |
31680 | them are optional, in which case the &%log_selector%& option controls whether |
31681 | they are included or not. A Perl script called &'eximstats'&, which does simple | |
168e428f | 31682 | analysis of main log files, is provided in the Exim distribution (see section |
9b371988 PH |
31683 | &<<SECTmailstat>>&). |
31684 | .next | |
31685 | .cindex "reject log" | |
168e428f PH |
31686 | The reject log records information from messages that are rejected as a result |
31687 | of a configuration option (that is, for policy reasons). | |
31688 | The first line of each rejection is a copy of the line that is also written to | |
31689 | the main log. Then, if the message's header has been read at the time the log | |
31690 | is written, its contents are written to this log. Only the original header | |
31691 | lines are available; header lines added by ACLs are not logged. You can use the | |
31692 | reject log to check that your policy controls are working correctly; on a busy | |
31693 | host this may be easier than scanning the main log for rejection messages. You | |
9b371988 PH |
31694 | can suppress the writing of the reject log by setting &%write_rejectlog%& |
31695 | false. | |
31696 | .next | |
31697 | .cindex "panic log" | |
31698 | .cindex "system log" | |
168e428f PH |
31699 | When certain serious errors occur, Exim writes entries to its panic log. If the |
31700 | error is sufficiently disastrous, Exim bombs out afterwards. Panic log entries | |
31701 | are usually written to the main log as well, but can get lost amid the mass of | |
31702 | other entries. The panic log should be empty under normal circumstances. It is | |
9b371988 | 31703 | therefore a good idea to check it (or to have a &'cron'& script check it) |
168e428f PH |
31704 | regularly, in order to become aware of any problems. When Exim cannot open its |
31705 | panic log, it tries as a last resort to write to the system log (syslog). This | |
31706 | is opened with LOG_PID+LOG_CONS and the facility code of LOG_MAIL. The | |
31707 | message itself is written at priority LOG_CRIT. | |
9b371988 PH |
31708 | .endlist |
31709 | ||
31710 | Every log line starts with a timestamp, in the format shown in the following | |
31711 | example. Note that many of the examples shown in this chapter are line-wrapped. | |
31712 | In the log file, this would be all on one line: | |
31713 | .code | |
31714 | 2001-09-16 16:09:47 SMTP connection from [127.0.0.1] closed | |
31715 | by QUIT | |
31716 | .endd | |
168e428f PH |
31717 | By default, the timestamps are in the local timezone. There are two |
31718 | ways of changing this: | |
31719 | ||
9b371988 PH |
31720 | .ilist |
31721 | You can set the &%timezone%& option to a different time zone; in particular, if | |
168e428f | 31722 | you set |
9b371988 PH |
31723 | .code |
31724 | timezone = UTC | |
31725 | .endd | |
168e428f | 31726 | the timestamps will be in UTC (aka GMT). |
9b371988 PH |
31727 | .next |
31728 | If you set &%log_timezone%& true, the time zone is added to the timestamp, for | |
168e428f | 31729 | example: |
9b371988 PH |
31730 | .code |
31731 | 2003-04-25 11:17:07 +0100 Start queue run: pid=12762 | |
31732 | .endd | |
31733 | .endlist | |
168e428f | 31734 | |
f89d2485 PH |
31735 | .cindex "log" "process ids in" |
31736 | .cindex "pid (process id)" "in log lines" | |
31737 | Exim does not include its process id in log lines by default, but you can | |
31738 | request that it does so by specifying the &`pid`& log selector (see section | |
31739 | &<<SECTlogselector>>&). When this is set, the process id is output, in square | |
31740 | brackets, immediately after the time and date. | |
f89d2485 | 31741 | |
168e428f PH |
31742 | |
31743 | ||
31744 | ||
9b371988 PH |
31745 | .section "Where the logs are written" "SECTwhelogwri" |
31746 | .cindex "log" "destination" | |
31747 | .cindex "log" "to file" | |
31748 | .cindex "log" "to syslog" | |
31749 | .cindex "syslog" | |
168e428f PH |
31750 | The logs may be written to local files, or to syslog, or both. However, it |
31751 | should be noted that many syslog implementations use UDP as a transport, and | |
31752 | are therefore unreliable in the sense that messages are not guaranteed to | |
31753 | arrive at the loghost, nor is the ordering of messages necessarily maintained. | |
31754 | It has also been reported that on large log files (tens of megabytes) you may | |
9b371988 PH |
31755 | need to tweak syslog to prevent it syncing the file with each write &-- on |
31756 | Linux this has been seen to make syslog take 90% plus of CPU time. | |
168e428f PH |
31757 | |
31758 | The destination for Exim's logs is configured by setting LOG_FILE_PATH in | |
9b371988 | 31759 | &_Local/Makefile_& or by setting &%log_file_path%& in the run time |
168e428f PH |
31760 | configuration. This latter string is expanded, so it can contain, for example, |
31761 | references to the host name: | |
9b371988 PH |
31762 | .code |
31763 | log_file_path = /var/log/$primary_hostname/exim_%slog | |
31764 | .endd | |
31765 | It is generally advisable, however, to set the string in &_Local/Makefile_& | |
168e428f PH |
31766 | rather than at run time, because then the setting is available right from the |
31767 | start of Exim's execution. Otherwise, if there's something it wants to log | |
31768 | before it has read the configuration file (for example, an error in the | |
31769 | configuration file) it will not use the path you want, and may not be able to | |
31770 | log at all. | |
31771 | ||
9b371988 | 31772 | The value of LOG_FILE_PATH or &%log_file_path%& is a colon-separated |
168e428f PH |
31773 | list, currently limited to at most two items. This is one option where the |
31774 | facility for changing a list separator may not be used. The list must always be | |
9b371988 PH |
31775 | colon-separated. If an item in the list is &"syslog"& then syslog is used; |
31776 | otherwise the item must either be an absolute path, containing &`%s`& at the | |
31777 | point where &"main"&, &"reject"&, or &"panic"& is to be inserted, or be empty, | |
168e428f PH |
31778 | implying the use of a default path. |
31779 | ||
31780 | When Exim encounters an empty item in the list, it searches the list defined by | |
31781 | LOG_FILE_PATH, and uses the first item it finds that is neither empty nor | |
9b371988 PH |
31782 | &"syslog"&. This means that an empty item in &%log_file_path%& can be used to |
31783 | mean &"use the path specified at build time"&. It no such item exists, log | |
31784 | files are written in the &_log_& subdirectory of the spool directory. This is | |
168e428f | 31785 | equivalent to the setting: |
9b371988 PH |
31786 | .code |
31787 | log_file_path = $spool_directory/log/%slog | |
31788 | .endd | |
168e428f PH |
31789 | If you do not specify anything at build time or run time, that is where the |
31790 | logs are written. | |
31791 | ||
9b371988 PH |
31792 | A log file path may also contain &`%D`& if datestamped log file names are in |
31793 | use &-- see section &<<SECTdatlogfil>>& below. | |
168e428f PH |
31794 | |
31795 | Here are some examples of possible settings: | |
9b371988 PH |
31796 | .display |
31797 | &`LOG_FILE_PATH=syslog `& syslog only | |
31798 | &`LOG_FILE_PATH=:syslog `& syslog and default path | |
31799 | &`LOG_FILE_PATH=syslog : /usr/log/exim_%s `& syslog and specified path | |
31800 | &`LOG_FILE_PATH=/usr/log/exim_%s `& specified path only | |
31801 | .endd | |
168e428f PH |
31802 | If there are more than two paths in the list, the first is used and a panic |
31803 | error is logged. | |
31804 | ||
31805 | ||
31806 | ||
f89d2485 | 31807 | .section "Logging to local files that are periodically &""cycled""&" "SECID285" |
9b371988 PH |
31808 | .cindex "log" "cycling local files" |
31809 | .cindex "cycling logs" | |
31810 | .cindex "&'exicyclog'&" | |
31811 | .cindex "log" "local files; writing to" | |
f89d2485 | 31812 | Some operating systems provide centralized and standardized methods for cycling |
9b371988 PH |
31813 | log files. For those that do not, a utility script called &'exicyclog'& is |
31814 | provided (see section &<<SECTcyclogfil>>&). This renames and compresses the | |
31815 | main and reject logs each time it is called. The maximum number of old logs to | |
31816 | keep can be set. It is suggested this script is run as a daily &'cron'& job. | |
168e428f PH |
31817 | |
31818 | An Exim delivery process opens the main log when it first needs to write to it, | |
9b371988 | 31819 | and it keeps the file open in case subsequent entries are required &-- for |
168e428f PH |
31820 | example, if a number of different deliveries are being done for the same |
31821 | message. However, remote SMTP deliveries can take a long time, and this means | |
9b371988 | 31822 | that the file may be kept open long after it is renamed if &'exicyclog'& or |
168e428f PH |
31823 | something similar is being used to rename log files on a regular basis. To |
31824 | ensure that a switch of log files is noticed as soon as possible, Exim calls | |
9b371988 | 31825 | &[stat()]& on the main log's name before reusing an open file, and if the file |
168e428f PH |
31826 | does not exist, or its inode has changed, the old file is closed and Exim |
31827 | tries to open the main log from scratch. Thus, an old log file may remain open | |
31828 | for quite some time, but no Exim processes should write to it once it has been | |
31829 | renamed. | |
31830 | ||
31831 | ||
31832 | ||
9b371988 PH |
31833 | .section "Datestamped log files" "SECTdatlogfil" |
31834 | .cindex "log" "datestamped files" | |
168e428f PH |
31835 | Instead of cycling the main and reject log files by renaming them |
31836 | periodically, some sites like to use files whose names contain a datestamp, | |
9b371988 | 31837 | for example, &_mainlog-20031225_&. The datestamp is in the form &_yyyymmdd_&. |
168e428f | 31838 | Exim has support for this way of working. It is enabled by setting the |
9b371988 | 31839 | &%log_file_path%& option to a path that includes &`%D`& at the point where the |
168e428f | 31840 | datestamp is required. For example: |
9b371988 PH |
31841 | .code |
31842 | log_file_path = /var/spool/exim/log/%slog-%D | |
31843 | log_file_path = /var/log/exim-%s-%D.log | |
31844 | log_file_path = /var/spool/exim/log/%D-%slog | |
31845 | .endd | |
31846 | As before, &`%s`& is replaced by &"main"& or &"reject"&; the following are | |
31847 | examples of names generated by the above examples: | |
31848 | .code | |
31849 | /var/spool/exim/log/mainlog-20021225 | |
31850 | /var/log/exim-reject-20021225.log | |
31851 | /var/spool/exim/log/20021225-mainlog | |
31852 | .endd | |
168e428f PH |
31853 | When this form of log file is specified, Exim automatically switches to new |
31854 | files at midnight. It does not make any attempt to compress old logs; you | |
31855 | will need to write your own script if you require this. You should not | |
9b371988 | 31856 | run &'exicyclog'& with this form of logging. |
168e428f | 31857 | |
9b371988 | 31858 | The location of the panic log is also determined by &%log_file_path%&, but it |
168e428f | 31859 | is not datestamped, because rotation of the panic log does not make sense. |
9b371988 | 31860 | When generating the name of the panic log, &`%D`& is removed from the string. |
168e428f PH |
31861 | In addition, if it immediately follows a slash, a following non-alphanumeric |
31862 | character is removed; otherwise a preceding non-alphanumeric character is | |
31863 | removed. Thus, the three examples above would give these panic log names: | |
9b371988 PH |
31864 | .code |
31865 | /var/spool/exim/log/paniclog | |
31866 | /var/log/exim-panic.log | |
31867 | /var/spool/exim/log/paniclog | |
31868 | .endd | |
168e428f PH |
31869 | |
31870 | ||
f89d2485 | 31871 | .section "Logging to syslog" "SECID249" |
9b371988 | 31872 | .cindex "log" "syslog; writing to" |
168e428f | 31873 | The use of syslog does not change what Exim logs or the format of its messages, |
9b371988 | 31874 | except in one respect. If &%syslog_timestamp%& is set false, the timestamps on |
168e428f PH |
31875 | Exim's log lines are omitted when these lines are sent to syslog. Apart from |
31876 | that, the same strings are written to syslog as to log files. The syslog | |
9b371988 PH |
31877 | &"facility"& is set to LOG_MAIL, and the program name to &"exim"& |
31878 | by default, but you can change these by setting the &%syslog_facility%& and | |
31879 | &%syslog_processname%& options, respectively. If Exim was compiled with | |
31880 | SYSLOG_LOG_PID set in &_Local/Makefile_& (this is the default in | |
31881 | &_src/EDITME_&), then, on systems that permit it (all except ULTRIX), the | |
31882 | LOG_PID flag is set so that the &[syslog()]& call adds the pid as well as | |
168e428f PH |
31883 | the time and host name to each line. |
31884 | The three log streams are mapped onto syslog priorities as follows: | |
31885 | ||
9b371988 PH |
31886 | .ilist |
31887 | &'mainlog'& is mapped to LOG_INFO | |
31888 | .next | |
31889 | &'rejectlog'& is mapped to LOG_NOTICE | |
31890 | .next | |
31891 | &'paniclog'& is mapped to LOG_ALERT | |
31892 | .endlist | |
168e428f | 31893 | |
9b371988 PH |
31894 | Many log lines are written to both &'mainlog'& and &'rejectlog'&, and some are |
31895 | written to both &'mainlog'& and &'paniclog'&, so there will be duplicates if | |
168e428f | 31896 | these are routed by syslog to the same place. You can suppress this duplication |
9b371988 | 31897 | by setting &%syslog_duplication%& false. |
168e428f | 31898 | |
9b371988 | 31899 | Exim's log lines can sometimes be very long, and some of its &'rejectlog'& |
168e428f | 31900 | entries contain multiple lines when headers are included. To cope with both |
9b371988 | 31901 | these cases, entries written to syslog are split into separate &[syslog()]& |
168e428f PH |
31902 | calls at each internal newline, and also after a maximum of |
31903 | 870 data characters. (This allows for a total syslog line length of 1024, when | |
31904 | additions such as timestamps are added.) If you are running a syslog | |
31905 | replacement that can handle lines longer than the 1024 characters allowed by | |
31906 | RFC 3164, you should set | |
9b371988 PH |
31907 | .code |
31908 | SYSLOG_LONG_LINES=yes | |
31909 | .endd | |
31910 | in &_Local/Makefile_& before building Exim. That stops Exim from splitting long | |
31911 | lines, but it still splits at internal newlines in &'reject'& log entries. | |
168e428f PH |
31912 | |
31913 | To make it easy to re-assemble split lines later, each component of a split | |
9b371988 PH |
31914 | entry starts with a string of the form [<&'n'&>/<&'m'&>] or [<&'n'&>\<&'m'&>] |
31915 | where <&'n'&> is the component number and <&'m'&> is the total number of | |
31916 | components in the entry. The / delimiter is used when the line was split | |
31917 | because it was too long; if it was split because of an internal newline, the \ | |
31918 | delimiter is used. For example, supposing the length limit to be 50 instead of | |
31919 | 870, the following would be the result of a typical rejection message to | |
31920 | &'mainlog'& (LOG_INFO), each line in addition being preceded by the time, host | |
31921 | name, and pid as added by syslog: | |
31922 | .code | |
31923 | [1/5] 2002-09-16 16:09:43 16RdAL-0006pc-00 rejected from | |
31924 | [2/5] [127.0.0.1] (ph10): syntax error in 'From' header | |
31925 | [3/5] when scanning for sender: missing or malformed lo | |
31926 | [4/5] cal part in "<>" (envelope sender is <ph10@cam.exa | |
31927 | [5/5] mple>) | |
31928 | .endd | |
31929 | The same error might cause the following lines to be written to &"rejectlog"& | |
168e428f | 31930 | (LOG_NOTICE): |
9b371988 PH |
31931 | .code |
31932 | [1/18] 2002-09-16 16:09:43 16RdAL-0006pc-00 rejected fro | |
31933 | [2/18] m [127.0.0.1] (ph10): syntax error in 'From' head | |
31934 | [3/18] er when scanning for sender: missing or malformed | |
31935 | [4/18] local part in "<>" (envelope sender is <ph10@cam | |
31936 | [5\18] .example>) | |
31937 | [6\18] Recipients: ph10@some.domain.cam.example | |
31938 | [7\18] P Received: from [127.0.0.1] (ident=ph10) | |
31939 | [8\18] by xxxxx.cam.example with smtp (Exim 4.00) | |
31940 | [9\18] id 16RdAL-0006pc-00 | |
31941 | [10/18] for ph10@cam.example; Mon, 16 Sep 2002 16: | |
31942 | [11\18] 09:43 +0100 | |
31943 | [12\18] F From: <> | |
31944 | [13\18] Subject: this is a test header | |
31945 | [18\18] X-something: this is another header | |
31946 | [15/18] I Message-Id: <E16RdAL-0006pc-00@xxxxx.cam.examp | |
31947 | [16\18] le> | |
31948 | [17\18] B Bcc: | |
31949 | [18/18] Date: Mon, 16 Sep 2002 16:09:43 +0100 | |
31950 | .endd | |
168e428f PH |
31951 | Log lines that are neither too long nor contain newlines are written to syslog |
31952 | without modification. | |
31953 | ||
31954 | If only syslog is being used, the Exim monitor is unable to provide a log tail | |
9b371988 | 31955 | display, unless syslog is routing &'mainlog'& to a file on the local host and |
168e428f PH |
31956 | the environment variable EXIMON_LOG_FILE_PATH is set to tell the monitor |
31957 | where it is. | |
31958 | ||
31959 | ||
31960 | ||
f89d2485 | 31961 | .section "Log line flags" "SECID250" |
168e428f PH |
31962 | One line is written to the main log for each message received, and for each |
31963 | successful, unsuccessful, and delayed delivery. These lines can readily be | |
31964 | picked out by the distinctive two-character flags that immediately follow the | |
31965 | timestamp. The flags are: | |
9b371988 PH |
31966 | .display |
31967 | &`<=`& message arrival | |
31968 | &`=>`& normal message delivery | |
31969 | &`->`& additional address in same delivery | |
31970 | &`*>`& delivery suppressed by &%-N%& | |
31971 | &`**`& delivery failed; address bounced | |
31972 | &`==`& delivery deferred; temporary problem | |
31973 | .endd | |
31974 | ||
31975 | ||
f89d2485 | 31976 | .section "Logging message reception" "SECID251" |
9b371988 | 31977 | .cindex "log" "reception line" |
168e428f PH |
31978 | The format of the single-line entry in the main log that is written for every |
31979 | message received is shown in the basic example below, which is split over | |
31980 | several lines in order to fit it on the page: | |
9b371988 PH |
31981 | .code |
31982 | 2002-10-31 08:57:53 16ZCW1-0005MB-00 <= kryten@dwarf.fict.example | |
31983 | H=mailer.fict.example [192.168.123.123] U=exim | |
31984 | P=smtp S=5678 id=<incoming message id> | |
31985 | .endd | |
31986 | The address immediately following &"<="& is the envelope sender address. A | |
31987 | bounce message is shown with the sender address &"<>"&, and if it is locally | |
31988 | generated, this is followed by an item of the form | |
31989 | .code | |
31990 | R=<message id> | |
31991 | .endd | |
168e428f PH |
31992 | which is a reference to the message that caused the bounce to be sent. |
31993 | ||
9b371988 PH |
31994 | .cindex "HELO" |
31995 | .cindex "EHLO" | |
168e428f PH |
31996 | For messages from other hosts, the H and U fields identify the remote host and |
31997 | record the RFC 1413 identity of the user that sent the message, if one was | |
31998 | received. The number given in square brackets is the IP address of the sending | |
31999 | host. If there is a single, unparenthesized host name in the H field, as | |
32000 | above, it has been verified to correspond to the IP address (see the | |
9b371988 | 32001 | &%host_lookup%& option). If the name is in parentheses, it was the name quoted |
168e428f PH |
32002 | by the remote host in the SMTP HELO or EHLO command, and has not been |
32003 | verified. If verification yields a different name to that given for HELO or | |
32004 | EHLO, the verified name appears first, followed by the HELO or EHLO | |
32005 | name in parentheses. | |
32006 | ||
32007 | Misconfigured hosts (and mail forgers) sometimes put an IP address, with or | |
32008 | without brackets, in the HELO or EHLO command, leading to entries in | |
32009 | the log containing text like these examples: | |
9b371988 PH |
32010 | .code |
32011 | H=(10.21.32.43) [192.168.8.34] | |
32012 | H=([10.21.32.43]) [192.168.8.34] | |
32013 | .endd | |
168e428f PH |
32014 | This can be confusing. Only the final address in square brackets can be relied |
32015 | on. | |
32016 | ||
32017 | For locally generated messages (that is, messages not received over TCP/IP), | |
32018 | the H field is omitted, and the U field contains the login name of the caller | |
32019 | of Exim. | |
32020 | ||
9b371988 PH |
32021 | .cindex "authentication" "logging" |
32022 | .cindex "AUTH" "logging" | |
168e428f | 32023 | For all messages, the P field specifies the protocol used to receive the |
9b371988 | 32024 | message. This is the value that is stored in &$received_protocol$&. In the case |
068aaea8 PH |
32025 | of incoming SMTP messages, the value indicates whether or not any SMTP |
32026 | extensions (ESMTP), encryption, or authentication were used. If the SMTP | |
32027 | session was encrypted, there is an additional X field that records the cipher | |
32028 | suite that was used. | |
32029 | ||
3cb1b51e | 32030 | The protocol is set to &"esmtpsa"& or &"esmtpa"& for messages received from |
068aaea8 | 32031 | hosts that have authenticated themselves using the SMTP AUTH command. The first |
9b371988 | 32032 | value is used when the SMTP connection was encrypted (&"secure"&). In this case |
068aaea8 PH |
32033 | there is an additional item A= followed by the name of the authenticator that |
32034 | was used. If an authenticated identification was set up by the authenticator's | |
9b371988 | 32035 | &%server_set_id%& option, this is logged too, separated by a colon from the |
168e428f PH |
32036 | authenticator name. |
32037 | ||
9b371988 | 32038 | .cindex "size" "of message" |
068aaea8 PH |
32039 | The id field records the existing message id, if present. The size of the |
32040 | received message is given by the S field. When the message is delivered, | |
32041 | headers may be removed or added, so that the size of delivered copies of the | |
32042 | message may not correspond with this value (and indeed may be different to each | |
32043 | other). | |
168e428f | 32044 | |
9b371988 PH |
32045 | The &%log_selector%& option can be used to request the logging of additional |
32046 | data when a message is received. See section &<<SECTlogselector>>& below. | |
168e428f PH |
32047 | |
32048 | ||
32049 | ||
f89d2485 | 32050 | .section "Logging deliveries" "SECID252" |
9b371988 | 32051 | .cindex "log" "delivery line" |
168e428f | 32052 | The format of the single-line entry in the main log that is written for every |
9b371988 PH |
32053 | delivery is shown in one of the examples below, for local and remote |
32054 | deliveries, respectively. Each example has been split into two lines in order | |
32055 | to fit it on the page: | |
32056 | .code | |
32057 | 2002-10-31 08:59:13 16ZCW1-0005MB-00 => marv | |
32058 | <marv@hitch.fict.example> R=localuser T=local_delivery | |
32059 | 2002-10-31 09:00:10 16ZCW1-0005MB-00 => | |
32060 | monk@holistic.fict.example R=dnslookup T=remote_smtp | |
32061 | H=holistic.fict.example [192.168.234.234] | |
32062 | .endd | |
168e428f PH |
32063 | For ordinary local deliveries, the original address is given in angle brackets |
32064 | after the final delivery address, which might be a pipe or a file. If | |
32065 | intermediate address(es) exist between the original and the final address, the | |
32066 | last of these is given in parentheses after the final address. The R and T | |
32067 | fields record the router and transport that were used to process the address. | |
32068 | ||
32069 | If a shadow transport was run after a successful local delivery, the log line | |
32070 | for the successful delivery has an item added on the end, of the form | |
9b371988 PH |
32071 | .display |
32072 | &`ST=<`&&'shadow transport name'&&`>`& | |
32073 | .endd | |
168e428f PH |
32074 | If the shadow transport did not succeed, the error message is put in |
32075 | parentheses afterwards. | |
32076 | ||
9b371988 | 32077 | .cindex "asterisk" "after IP address" |
168e428f | 32078 | When more than one address is included in a single delivery (for example, two |
068aaea8 | 32079 | SMTP RCPT commands in one transaction) the second and subsequent addresses are |
9b371988 PH |
32080 | flagged with &`->`& instead of &`=>`&. When two or more messages are delivered |
32081 | down a single SMTP connection, an asterisk follows the IP address in the log | |
32082 | lines for the second and subsequent messages. | |
168e428f | 32083 | |
9b371988 PH |
32084 | The generation of a reply message by a filter file gets logged as a |
32085 | &"delivery"& to the addressee, preceded by &">"&. | |
168e428f | 32086 | |
9b371988 PH |
32087 | The &%log_selector%& option can be used to request the logging of additional |
32088 | data when a message is delivered. See section &<<SECTlogselector>>& below. | |
168e428f PH |
32089 | |
32090 | ||
f89d2485 | 32091 | .section "Discarded deliveries" "SECID253" |
9b371988 PH |
32092 | .cindex "discarded messages" |
32093 | .cindex "message" "discarded" | |
32094 | .cindex "delivery" "discarded; logging" | |
32095 | When a message is discarded as a result of the command &"seen finish"& being | |
168e428f | 32096 | obeyed in a filter file which generates no deliveries, a log entry of the form |
9b371988 PH |
32097 | .code |
32098 | 2002-12-10 00:50:49 16auJc-0001UB-00 => discarded | |
32099 | <low.club@bridge.example> R=userforward | |
32100 | .endd | |
168e428f | 32101 | is written, to record why no deliveries are logged. When a message is discarded |
9b371988 PH |
32102 | because it is aliased to &":blackhole:"& the log line is like this: |
32103 | .code | |
32104 | 1999-03-02 09:44:33 10HmaX-0005vi-00 => :blackhole: | |
32105 | <hole@nowhere.example> R=blackhole_router | |
32106 | .endd | |
168e428f PH |
32107 | |
32108 | ||
f89d2485 | 32109 | .section "Deferred deliveries" "SECID254" |
168e428f | 32110 | When a delivery is deferred, a line of the following form is logged: |
9b371988 PH |
32111 | .code |
32112 | 2002-12-19 16:20:23 16aiQz-0002Q5-00 == marvin@endrest.example | |
32113 | R=dnslookup T=smtp defer (146): Connection refused | |
32114 | .endd | |
168e428f PH |
32115 | In the case of remote deliveries, the error is the one that was given for the |
32116 | last IP address that was tried. Details of individual SMTP failures are also | |
32117 | written to the log, so the above line would be preceded by something like | |
9b371988 PH |
32118 | .code |
32119 | 2002-12-19 16:20:23 16aiQz-0002Q5-00 Failed to connect to | |
32120 | mail1.endrest.example [192.168.239.239]: Connection refused | |
32121 | .endd | |
168e428f PH |
32122 | When a deferred address is skipped because its retry time has not been reached, |
32123 | a message is written to the log, but this can be suppressed by setting an | |
9b371988 | 32124 | appropriate value in &%log_selector%&. |
168e428f PH |
32125 | |
32126 | ||
32127 | ||
f89d2485 | 32128 | .section "Delivery failures" "SECID255" |
9b371988 | 32129 | .cindex "delivery" "failure; logging" |
168e428f PH |
32130 | If a delivery fails because an address cannot be routed, a line of the |
32131 | following form is logged: | |
9b371988 PH |
32132 | .code |
32133 | 1995-12-19 16:20:23 0tRiQz-0002Q5-00 ** jim@trek99.example | |
32134 | <jim@trek99.example>: unknown mail domain | |
32135 | .endd | |
168e428f PH |
32136 | If a delivery fails at transport time, the router and transport are shown, and |
32137 | the response from the remote host is included, as in this example: | |
9b371988 PH |
32138 | .code |
32139 | 2002-07-11 07:14:17 17SXDU-000189-00 ** ace400@pb.example | |
32140 | R=dnslookup T=remote_smtp: SMTP error from remote mailer | |
32141 | after pipelined RCPT TO:<ace400@pb.example>: host | |
32142 | pbmail3.py.example [192.168.63.111]: 553 5.3.0 | |
32143 | <ace400@pb.example>...Addressee unknown | |
32144 | .endd | |
32145 | The word &"pipelined"& indicates that the SMTP PIPELINING extension was being | |
32146 | used. See &%hosts_avoid_esmtp%& in the &(smtp)& transport for a way of | |
32147 | disabling PIPELINING. The log lines for all forms of delivery failure are | |
32148 | flagged with &`**`&. | |
32149 | ||
32150 | ||
32151 | ||
f89d2485 | 32152 | .section "Fake deliveries" "SECID256" |
9b371988 PH |
32153 | .cindex "delivery" "fake; logging" |
32154 | If a delivery does not actually take place because the &%-N%& option has been | |
168e428f | 32155 | used to suppress it, a normal delivery line is written to the log, except that |
9b371988 | 32156 | &"=>"& is replaced by &"*>"&. |
168e428f PH |
32157 | |
32158 | ||
32159 | ||
f89d2485 | 32160 | .section "Completion" "SECID257" |
168e428f | 32161 | A line of the form |
9b371988 PH |
32162 | .code |
32163 | 2002-10-31 09:00:11 16ZCW1-0005MB-00 Completed | |
32164 | .endd | |
168e428f PH |
32165 | is written to the main log when a message is about to be removed from the spool |
32166 | at the end of its processing. | |
32167 | ||
32168 | ||
32169 | ||
32170 | ||
f89d2485 | 32171 | .section "Summary of Fields in Log Lines" "SECID258" |
9b371988 | 32172 | .cindex "log" "summary of fields" |
168e428f PH |
32173 | A summary of the field identifiers that are used in log lines is shown in |
32174 | the following table: | |
9b371988 PH |
32175 | .display |
32176 | &`A `& authenticator name (and optional id) | |
32177 | &`C `& SMTP confirmation on delivery | |
f89d2485 | 32178 | &` `& command list for &"no mail in SMTP session"& |
9b371988 | 32179 | &`CV `& certificate verification status |
f89d2485 | 32180 | &`D `& duration of &"no mail in SMTP session"& |
9b371988 PH |
32181 | &`DN `& distinguished name from peer certificate |
32182 | &`DT `& on &`=>`& lines: time taken for a delivery | |
32183 | &`F `& sender address (on delivery lines) | |
32184 | &`H `& host name and IP address | |
32185 | &`I `& local interface used | |
32186 | &`id `& message id for incoming message | |
32187 | &`P `& on &`<=`& lines: protocol used | |
32188 | &` `& on &`=>`& and &`**`& lines: return path | |
32189 | &`QT `& on &`=>`& lines: time spent on queue so far | |
32190 | &` `& on &"Completed"& lines: time spent on queue | |
32191 | &`R `& on &`<=`& lines: reference for local bounce | |
32192 | &` `& on &`=>`& &`**`& and &`==`& lines: router name | |
32193 | &`S `& size of message | |
32194 | &`ST `& shadow transport name | |
32195 | &`T `& on &`<=`& lines: message subject (topic) | |
32196 | &` `& on &`=>`& &`**`& and &`==`& lines: transport name | |
32197 | &`U `& local user or RFC 1413 identity | |
32198 | &`X `& TLS cipher suite | |
32199 | .endd | |
32200 | ||
32201 | ||
f89d2485 | 32202 | .section "Other log entries" "SECID259" |
168e428f PH |
32203 | Various other types of log entry are written from time to time. Most should be |
32204 | self-explanatory. Among the more common are: | |
32205 | ||
9b371988 PH |
32206 | .ilist |
32207 | .cindex "retry" "time not reached" | |
32208 | &'retry time not reached'&&~&~An address previously suffered a temporary error | |
168e428f PH |
32209 | during routing or local delivery, and the time to retry has not yet arrived. |
32210 | This message is not written to an individual message log file unless it happens | |
32211 | during the first delivery attempt. | |
9b371988 PH |
32212 | .next |
32213 | &'retry time not reached for any host'&&~&~An address previously suffered | |
168e428f PH |
32214 | temporary errors during remote delivery, and the retry time has not yet arrived |
32215 | for any of the hosts to which it is routed. | |
9b371988 PH |
32216 | .next |
32217 | .cindex "spool directory" "file locked" | |
32218 | &'spool file locked'&&~&~An attempt to deliver a message cannot proceed because | |
168e428f PH |
32219 | some other Exim process is already working on the message. This can be quite |
32220 | common if queue running processes are started at frequent intervals. The | |
9b371988 | 32221 | &'exiwhat'& utility script can be used to find out what Exim processes are |
168e428f | 32222 | doing. |
9b371988 PH |
32223 | .next |
32224 | .cindex "error" "ignored" | |
32225 | &'error ignored'&&~&~There are several circumstances that give rise to this | |
168e428f | 32226 | message: |
9b371988 PH |
32227 | .olist |
32228 | Exim failed to deliver a bounce message whose age was greater than | |
32229 | &%ignore_bounce_errors_after%&. The bounce was discarded. | |
32230 | .next | |
32231 | A filter file set up a delivery using the &"noerror"& option, and the delivery | |
168e428f | 32232 | failed. The delivery was discarded. |
9b371988 PH |
32233 | .next |
32234 | A delivery set up by a router configured with | |
32235 | . ==== As this is a nested list, any displays it contains must be indented | |
32236 | . ==== as otherwise they are too far to the left. | |
32237 | .code | |
168e428f | 32238 | errors_to = <> |
9b371988 | 32239 | .endd |
168e428f | 32240 | failed. The delivery was discarded. |
9b371988 PH |
32241 | .endlist olist |
32242 | .endlist ilist | |
168e428f PH |
32243 | |
32244 | ||
32245 | ||
32246 | ||
32247 | ||
9b371988 PH |
32248 | .section "Reducing or increasing what is logged" "SECTlogselector" |
32249 | .cindex "log" "selectors" | |
32250 | By setting the &%log_selector%& global option, you can disable some of Exim's | |
168e428f | 32251 | default logging, or you can request additional logging. The value of |
9b371988 | 32252 | &%log_selector%& is made up of names preceded by plus or minus characters. For |
168e428f | 32253 | example: |
9b371988 PH |
32254 | .code |
32255 | log_selector = +arguments -retry_defer | |
32256 | .endd | |
168e428f PH |
32257 | The list of optional log items is in the following table, with the default |
32258 | selection marked by asterisks: | |
9b371988 PH |
32259 | .display |
32260 | &`*acl_warn_skipped `& skipped &%warn%& statement in ACL | |
32261 | &` address_rewrite `& address rewriting | |
32262 | &` all_parents `& all parents in => lines | |
32263 | &` arguments `& command line arguments | |
32264 | &`*connection_reject `& connection rejections | |
32265 | &`*delay_delivery `& immediate delivery delayed | |
32266 | &` deliver_time `& time taken to perform delivery | |
32267 | &` delivery_size `& add &`S=`&&'nnn'& to => lines | |
32268 | &`*dnslist_defer `& defers of DNS list (aka RBL) lookups | |
32269 | &`*etrn `& ETRN commands | |
32270 | &`*host_lookup_failed `& as it says | |
32271 | &` ident_timeout `& timeout for ident connection | |
32272 | &` incoming_interface `& incoming interface on <= lines | |
32273 | &` incoming_port `& incoming port on <= lines | |
32274 | &`*lost_incoming_connection `& as it says (includes timeouts) | |
32275 | &` outgoing_port `& add remote port to => lines | |
32276 | &`*queue_run `& start and end queue runs | |
32277 | &` queue_time `& time on queue for one recipient | |
32278 | &` queue_time_overall `& time on queue for whole message | |
f89d2485 | 32279 | &` pid `& Exim process id |
9b371988 PH |
32280 | &` received_recipients `& recipients on <= lines |
32281 | &` received_sender `& sender on <= lines | |
32282 | &`*rejected_header `& header contents on reject log | |
32283 | &`*retry_defer `& &"retry time not reached"& | |
db9452a9 | 32284 | &` return_path_on_delivery `& put return path on => and ** lines |
9b371988 | 32285 | &` sender_on_delivery `& add sender to => lines |
4f578862 | 32286 | &`*sender_verify_fail `& sender verification failures |
9b371988 PH |
32287 | &`*size_reject `& rejection because too big |
32288 | &`*skip_delivery `& delivery skipped in a queue run | |
32289 | &` smtp_confirmation `& SMTP confirmation on => lines | |
32290 | &` smtp_connection `& SMTP connections | |
32291 | &` smtp_incomplete_transaction`& incomplete SMTP transactions | |
f89d2485 | 32292 | &` smtp_no_mail `& session with no MAIL commands |
9b371988 PH |
32293 | &` smtp_protocol_error `& SMTP protocol errors |
32294 | &` smtp_syntax_error `& SMTP syntax errors | |
32295 | &` subject `& contents of &'Subject:'& on <= lines | |
32296 | &` tls_certificate_verified `& certificate verification status | |
32297 | &`*tls_cipher `& TLS cipher suite on <= and => lines | |
32298 | &` tls_peerdn `& TLS peer DN on <= and => lines | |
32299 | &` unknown_in_list `& DNS lookup failed in list match | |
32300 | ||
32301 | &` all `& all of the above | |
32302 | .endd | |
168e428f PH |
32303 | More details on each of these items follows: |
32304 | ||
9b371988 | 32305 | .ilist |
f89d2485 | 32306 | .cindex "&%warn%& ACL verb" "log when skipping" |
9b371988 PH |
32307 | &%acl_warn_skipped%&: When an ACL &%warn%& statement is skipped because one of |
32308 | its conditions cannot be evaluated, a log line to this effect is written if | |
32309 | this log selector is set. | |
9b371988 PH |
32310 | .next |
32311 | .cindex "log" "rewriting" | |
32312 | .cindex "rewriting" "logging" | |
32313 | &%address_rewrite%&: This applies both to global rewrites and per-transport | |
d1e83bff PH |
32314 | rewrites, but not to rewrites in filters run as an unprivileged user (because |
32315 | such users cannot access the log). | |
9b371988 PH |
32316 | .next |
32317 | .cindex "log" "full parentage" | |
32318 | &%all_parents%&: Normally only the original and final addresses are logged on | |
168e428f PH |
32319 | delivery lines; with this selector, intermediate parents are given in |
32320 | parentheses between them. | |
9b371988 PH |
32321 | .next |
32322 | .cindex "log" "Exim arguments" | |
f89d2485 | 32323 | .cindex "Exim arguments, logging" |
9b371988 | 32324 | &%arguments%&: This causes Exim to write the arguments with which it was called |
168e428f PH |
32325 | to the main log, preceded by the current working directory. This is a debugging |
32326 | feature, added to make it easier to find out how certain MUAs call | |
9b371988 PH |
32327 | &_/usr/sbin/sendmail_&. The logging does not happen if Exim has given up root |
32328 | privilege because it was called with the &%-C%& or &%-D%& options. Arguments | |
32329 | that are empty or that contain white space are quoted. Non-printing characters | |
32330 | are shown as escape sequences. This facility cannot log unrecognized arguments, | |
168e428f | 32331 | because the arguments are checked before the configuration file is read. The |
9b371988 | 32332 | only way to log such cases is to interpose a script such as &_util/logargs.sh_& |
168e428f | 32333 | between the caller and Exim. |
9b371988 PH |
32334 | .next |
32335 | .cindex "log" "connection rejections" | |
32336 | &%connection_reject%&: A log entry is written whenever an incoming SMTP | |
168e428f | 32337 | connection is rejected, for whatever reason. |
9b371988 PH |
32338 | .next |
32339 | .cindex "log" "delayed delivery" | |
f89d2485 | 32340 | .cindex "delayed delivery, logging" |
9b371988 | 32341 | &%delay_delivery%&: A log entry is written whenever a delivery process is not |
168e428f PH |
32342 | started for an incoming message because the load is too high or too many |
32343 | messages were received on one connection. Logging does not occur if no delivery | |
9b371988 PH |
32344 | process is started because &%queue_only%& is set or &%-odq%& was used. |
32345 | .next | |
32346 | .cindex "log" "delivery duration" | |
32347 | &%deliver_time%&: For each delivery, the amount of real time it has taken to | |
32348 | perform the actual delivery is logged as DT=<&'time'&>, for example, &`DT=1s`&. | |
32349 | .next | |
32350 | .cindex "log" "message size on delivery" | |
32351 | .cindex "size" "of message" | |
32352 | &%delivery_size%&: For each delivery, the size of message delivered is added to | |
32353 | the &"=>"& line, tagged with S=. | |
32354 | .next | |
32355 | .cindex "log" "dnslist defer" | |
32356 | .cindex "DNS list" "logging defer" | |
32357 | .cindex "black list (DNS)" | |
32358 | &%dnslist_defer%&: A log entry is written if an attempt to look up a host in a | |
168e428f | 32359 | DNS black list suffers a temporary error. |
9b371988 PH |
32360 | .next |
32361 | .cindex "log" "ETRN commands" | |
32362 | .cindex "ETRN" "logging" | |
3cb1b51e | 32363 | &%etrn%&: Every valid ETRN command that is received is logged, before the ACL |
9b371988 | 32364 | is run to determine whether or not it is actually accepted. An invalid ETRN |
168e428f | 32365 | command, or one received within a message transaction is not logged by this |
9b371988 PH |
32366 | selector (see &%smtp_syntax_error%& and &%smtp_protocol_error%&). |
32367 | .next | |
32368 | .cindex "log" "host lookup failure" | |
32369 | &%host_lookup_failed%&: When a lookup of a host's IP addresses fails to find | |
168e428f PH |
32370 | any addresses, or when a lookup of an IP address fails to find a host name, a |
32371 | log line is written. This logging does not apply to direct DNS lookups when | |
9b371988 PH |
32372 | routing email addresses, but it does apply to &"byname"& lookups. |
32373 | .next | |
32374 | .cindex "log" "ident timeout" | |
32375 | .cindex "RFC 1413" "logging timeout" | |
32376 | &%ident_timeout%&: A log line is written whenever an attempt to connect to a | |
168e428f | 32377 | client's ident port times out. |
9b371988 PH |
32378 | .next |
32379 | .cindex "log" "incoming interface" | |
32380 | .cindex "interface" "logging" | |
32381 | &%incoming_interface%&: The interface on which a message was received is added | |
32382 | to the &"<="& line as an IP address in square brackets, tagged by I= and | |
32383 | followed by a colon and the port number. The local interface and port are also | |
32384 | added to other SMTP log lines, for example &"SMTP connection from"&, and to | |
32385 | rejection lines. | |
32386 | .next | |
32387 | .cindex "log" "incoming remote port" | |
32388 | .cindex "port" "logging remote" | |
32389 | .cindex "TCP/IP" "logging incoming remote port" | |
f89d2485 PH |
32390 | .vindex "&$sender_fullhost$&" |
32391 | .vindex "&$sender_rcvhost$&" | |
9b371988 PH |
32392 | &%incoming_port%&: The remote port number from which a message was received is |
32393 | added to log entries and &'Received:'& header lines, following the IP address | |
32394 | in square brackets, and separated from it by a colon. This is implemented by | |
32395 | changing the value that is put in the &$sender_fullhost$& and | |
32396 | &$sender_rcvhost$& variables. Recording the remote port number has become more | |
168e428f | 32397 | important with the widening use of NAT (see RFC 2505). |
9b371988 PH |
32398 | .next |
32399 | .cindex "log" "dropped connection" | |
32400 | &%lost_incoming_connection%&: A log line is written when an incoming SMTP | |
168e428f | 32401 | connection is unexpectedly dropped. |
9b371988 PH |
32402 | .next |
32403 | .cindex "log" "outgoing remote port" | |
32404 | .cindex "port" "logging outgoint remote" | |
32405 | .cindex "TCP/IP" "logging ougtoing remote port" | |
32406 | &%outgoing_port%&: The remote port number is added to delivery log lines (those | |
168e428f PH |
32407 | containing => tags) following the IP address. This option is not included in |
32408 | the default setting, because for most ordinary configurations, the remote port | |
32409 | number is always 25 (the SMTP port). | |
9b371988 | 32410 | .next |
f89d2485 PH |
32411 | .cindex "log" "process ids in" |
32412 | .cindex "pid (process id)" "in log lines" | |
32413 | &%pid%&: The current process id is added to every log line, in square brackets, | |
32414 | immediately after the time and date. | |
f89d2485 | 32415 | .next |
9b371988 PH |
32416 | .cindex "log" "queue run" |
32417 | .cindex "queue runner" "logging" | |
32418 | &%queue_run%&: The start and end of every queue run are logged. | |
32419 | .next | |
32420 | .cindex "log" "queue time" | |
32421 | &%queue_time%&: The amount of time the message has been in the queue on the | |
32422 | local host is logged as QT=<&'time'&> on delivery (&`=>`&) lines, for example, | |
32423 | &`QT=3m45s`&. The clock starts when Exim starts to receive the message, so it | |
168e428f PH |
32424 | includes reception time as well as the delivery time for the current address. |
32425 | This means that it may be longer than the difference between the arrival and | |
32426 | delivery log line times, because the arrival log line is not written until the | |
32427 | message has been successfully received. | |
9b371988 PH |
32428 | .next |
32429 | &%queue_time_overall%&: The amount of time the message has been in the queue on | |
32430 | the local host is logged as QT=<&'time'&> on &"Completed"& lines, for | |
32431 | example, &`QT=3m45s`&. The clock starts when Exim starts to receive the | |
168e428f | 32432 | message, so it includes reception time as well as the total delivery time. |
9b371988 PH |
32433 | .next |
32434 | .cindex "log" "recipients" | |
32435 | &%received_recipients%&: The recipients of a message are listed in the main log | |
168e428f | 32436 | as soon as the message is received. The list appears at the end of the log line |
9b371988 | 32437 | that is written when a message is received, preceded by the word &"for"&. The |
168e428f PH |
32438 | addresses are listed after they have been qualified, but before any rewriting |
32439 | has taken place. | |
32440 | Recipients that were discarded by an ACL for MAIL or RCPT do not appear | |
32441 | in the list. | |
9b371988 PH |
32442 | .next |
32443 | .cindex "log" "sender reception" | |
32444 | &%received_sender%&: The unrewritten original sender of a message is added to | |
168e428f | 32445 | the end of the log line that records the message's arrival, after the word |
9b371988 PH |
32446 | &"from"& (before the recipients if &%received_recipients%& is also set). |
32447 | .next | |
32448 | .cindex "log" "header lines for rejection" | |
32449 | &%rejected_header%&: If a message's header has been received at the time a | |
168e428f PH |
32450 | rejection is written to the reject log, the complete header is added to the |
32451 | log. Header logging can be turned off individually for messages that are | |
9b371988 PH |
32452 | rejected by the &[local_scan()]& function (see section &<<SECTapiforloc>>&). |
32453 | .next | |
32454 | .cindex "log" "retry defer" | |
32455 | &%retry_defer%&: A log line is written if a delivery is deferred because a | |
32456 | retry time has not yet been reached. However, this &"retry time not reached"& | |
32457 | message is always omitted from individual message logs after the first delivery | |
168e428f | 32458 | attempt. |
9b371988 PH |
32459 | .next |
32460 | .cindex "log" "return path" | |
32461 | &%return_path_on_delivery%&: The return path that is being transmitted with | |
168e428f PH |
32462 | the message is included in delivery and bounce lines, using the tag P=. |
32463 | This is omitted if no delivery actually happens, for example, if routing fails, | |
9b371988 PH |
32464 | or if delivery is to &_/dev/null_& or to &`:blackhole:`&. |
32465 | .next | |
32466 | .cindex "log" "sender on delivery" | |
32467 | &%sender_on_delivery%&: The message's sender address is added to every delivery | |
32468 | and bounce line, tagged by F= (for &"from"&). | |
168e428f PH |
32469 | This is the original sender that was received with the message; it is not |
32470 | necessarily the same as the outgoing return path. | |
9b371988 | 32471 | .next |
4f578862 | 32472 | .cindex "log" "sender verify failure" |
db9452a9 PH |
32473 | &%sender_verify_fail%&: If this selector is unset, the separate log line that |
32474 | gives details of a sender verification failure is not written. Log lines for | |
32475 | the rejection of SMTP commands contain just &"sender verify failed"&, so some | |
32476 | detail is lost. | |
4f578862 | 32477 | .next |
9b371988 PH |
32478 | .cindex "log" "size rejection" |
32479 | &%size_reject%&: A log line is written whenever a message is rejected because | |
32480 | it is too big. | |
32481 | .next | |
32482 | .cindex "log" "frozen messages; skipped" | |
32483 | .cindex "frozen messages" "logging skipping" | |
32484 | &%skip_delivery%&: A log line is written whenever a message is skipped during a | |
168e428f PH |
32485 | queue run because it is frozen or because another process is already delivering |
32486 | it. | |
9b371988 PH |
32487 | .cindex "&""spool file is locked""&" |
32488 | The message that is written is &"spool file is locked"&. | |
32489 | .next | |
32490 | .cindex "log" "smtp confirmation" | |
32491 | .cindex "SMTP" "logging confirmation" | |
32492 | &%smtp_confirmation%&: The response to the final &"."& in the SMTP dialogue for | |
32493 | outgoing messages is added to delivery log lines in the form &`C=`&<&'text'&>. | |
32494 | A number of MTAs (including Exim) return an identifying string in this | |
32495 | response. | |
32496 | .next | |
32497 | .cindex "log" "SMTP connections" | |
32498 | .cindex "SMTP" "logging connections" | |
32499 | &%smtp_connection%&: A log line is written whenever an SMTP connection is | |
168e428f | 32500 | established or closed, unless the connection is from a host that matches |
9b371988 PH |
32501 | &%hosts_connection_nolog%&. (In contrast, &%lost_incoming_connection%& applies |
32502 | only when the closure is unexpected.) This applies to connections from local | |
32503 | processes that use &%-bs%& as well as to TCP/IP connections. If a connection is | |
168e428f PH |
32504 | dropped in the middle of a message, a log line is always written, whether or |
32505 | not this selector is set, but otherwise nothing is written at the start and end | |
32506 | of connections unless this selector is enabled. | |
9b371988 | 32507 | |
168e428f PH |
32508 | For TCP/IP connections to an Exim daemon, the current number of connections is |
32509 | included in the log message for each new connection, but note that the count is | |
32510 | reset if the daemon is restarted. | |
32511 | Also, because connections are closed (and the closure is logged) in | |
32512 | subprocesses, the count may not include connections that have been closed but | |
32513 | whose termination the daemon has not yet noticed. Thus, while it is possible to | |
32514 | match up the opening and closing of connections in the log, the value of the | |
32515 | logged counts may not be entirely accurate. | |
9b371988 PH |
32516 | .next |
32517 | .cindex "log" "SMTP transaction; incomplete" | |
32518 | .cindex "SMTP" "logging incomplete transactions" | |
32519 | &%smtp_incomplete_transaction%&: When a mail transaction is aborted by | |
168e428f PH |
32520 | RSET, QUIT, loss of connection, or otherwise, the incident is logged, |
32521 | and the message sender plus any accepted recipients are included in the log | |
32522 | line. This can provide evidence of dictionary attacks. | |
9b371988 | 32523 | .next |
f89d2485 PH |
32524 | .cindex "log" "non-MAIL SMTP sessions" |
32525 | .cindex "MAIL" "logging session without" | |
32526 | &%smtp_no_mail%&: A line is written to the main log whenever an accepted SMTP | |
32527 | connection terminates without having issued a MAIL command. This includes both | |
32528 | the case when the connection is dropped, and the case when QUIT is used. It | |
32529 | does not include cases where the connection is rejected right at the start (by | |
32530 | an ACL, or because there are too many connections, or whatever). These cases | |
32531 | already have their own log lines. | |
32532 | ||
32533 | The log line that is written contains the identity of the client in the usual | |
32534 | way, followed by D= and a time, which records the duration of the connection. | |
32535 | If the connection was authenticated, this fact is logged exactly as it is for | |
32536 | an incoming message, with an A= item. If the connection was encrypted, CV=, | |
32537 | DN=, and X= items may appear as they do for an incoming message, controlled by | |
32538 | the same logging options. | |
32539 | ||
32540 | Finally, if any SMTP commands were issued during the connection, a C= item | |
32541 | is added to the line, listing the commands that were used. For example, | |
32542 | .code | |
32543 | C=EHLO,QUIT | |
32544 | .endd | |
32545 | shows that the client issued QUIT straight after EHLO. If there were fewer | |
32546 | than 20 commands, they are all listed. If there were more than 20 commands, | |
32547 | the last 20 are listed, preceded by &"..."&. However, with the default | |
32548 | setting of 10 for &%smtp_accep_max_nonmail%&, the connection will in any case | |
32549 | have been aborted before 20 non-mail commands are processed. | |
f89d2485 | 32550 | .next |
9b371988 PH |
32551 | .cindex "log" "SMTP protocol error" |
32552 | .cindex "SMTP" "logging protocol error" | |
32553 | &%smtp_protocol_error%&: A log line is written for every SMTP protocol error | |
168e428f PH |
32554 | encountered. Exim does not have perfect detection of all protocol errors |
32555 | because of transmission delays and the use of pipelining. If PIPELINING has | |
32556 | been advertised to a client, an Exim server assumes that the client will use | |
9b371988 | 32557 | it, and therefore it does not count &"expected"& errors (for example, RCPT |
168e428f | 32558 | received after rejecting MAIL) as protocol errors. |
9b371988 PH |
32559 | .next |
32560 | .cindex "SMTP" "logging syntax errors" | |
32561 | .cindex "SMTP" "syntax errors; logging" | |
32562 | .cindex "SMTP" "unknown command; logging" | |
32563 | .cindex "log" "unknown SMTP command" | |
32564 | .cindex "log" "SMTP syntax error" | |
32565 | &%smtp_syntax_error%&: A log line is written for every SMTP syntax error | |
168e428f PH |
32566 | encountered. An unrecognized command is treated as a syntax error. For an |
32567 | external connection, the host identity is given; for an internal connection | |
9b371988 PH |
32568 | using &%-bs%& the sender identification (normally the calling user) is given. |
32569 | .next | |
32570 | .cindex "log" "subject" | |
f89d2485 | 32571 | .cindex "subject, logging" |
9b371988 PH |
32572 | &%subject%&: The subject of the message is added to the arrival log line, |
32573 | preceded by &"T="& (T for &"topic"&, since S is already used for &"size"&). | |
32574 | Any MIME &"words"& in the subject are decoded. The &%print_topbitchars%& option | |
168e428f PH |
32575 | specifies whether characters with values greater than 127 should be logged |
32576 | unchanged, or whether they should be rendered as escape sequences. | |
9b371988 PH |
32577 | .next |
32578 | .cindex "log" "certificate verification" | |
32579 | &%tls_certificate_verified%&: An extra item is added to <= and => log lines | |
32580 | when TLS is in use. The item is &`CV=yes`& if the peer's certificate was | |
32581 | verified, and &`CV=no`& if not. | |
32582 | .next | |
32583 | .cindex "log" "TLS cipher" | |
32584 | .cindex "TLS" "logging cipher" | |
32585 | &%tls_cipher%&: When a message is sent or received over an encrypted | |
32586 | connection, the cipher suite used is added to the log line, preceded by X=. | |
32587 | .next | |
32588 | .cindex "log" "TLS peer DN" | |
32589 | .cindex "TLS" "logging peer DN" | |
32590 | &%tls_peerdn%&: When a message is sent or received over an encrypted | |
32591 | connection, and a certificate is supplied by the remote host, the peer DN is | |
32592 | added to the log line, preceded by DN=. | |
32593 | .next | |
9b371988 PH |
32594 | .cindex "log" "DNS failure in list" |
32595 | &%unknown_in_list%&: This setting causes a log entry to be written when the | |
068aaea8 | 32596 | result of a list match is failure because a DNS lookup failed. |
9b371988 | 32597 | .endlist |
168e428f PH |
32598 | |
32599 | ||
f89d2485 | 32600 | .section "Message log" "SECID260" |
9b371988 PH |
32601 | .cindex "message" "log file for" |
32602 | .cindex "log" "message log; description of" | |
32603 | .cindex "&_msglog_& directory" | |
0a4e3112 | 32604 | .oindex "&%preserve_message_logs%&" |
168e428f PH |
32605 | In addition to the general log files, Exim writes a log file for each message |
32606 | that it handles. The names of these per-message logs are the message ids, and | |
9b371988 | 32607 | they are kept in the &_msglog_& sub-directory of the spool directory. Each |
168e428f PH |
32608 | message log contains copies of the log lines that apply to the message. This |
32609 | makes it easier to inspect the status of an individual message without having | |
32610 | to search the main log. A message log is deleted when processing of the message | |
9b371988 PH |
32611 | is complete, unless &%preserve_message_logs%& is set, but this should be used |
32612 | only with great care because they can fill up your disk very quickly. | |
168e428f PH |
32613 | |
32614 | On a heavily loaded system, it may be desirable to disable the use of | |
32615 | per-message logs, in order to reduce disk I/O. This can be done by setting the | |
9b371988 | 32616 | &%message_logs%& option false. |
4f578862 | 32617 | .ecindex IIDloggen |
168e428f PH |
32618 | |
32619 | ||
f89d2485 PH |
32620 | |
32621 | ||
9b371988 PH |
32622 | . //////////////////////////////////////////////////////////////////////////// |
32623 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 32624 | |
9b371988 | 32625 | .chapter "Exim utilities" "CHAPutils" |
4f578862 | 32626 | .scindex IIDutils "utilities" |
168e428f PH |
32627 | A number of utility scripts and programs are supplied with Exim and are |
32628 | described in this chapter. There is also the Exim Monitor, which is covered in | |
32629 | the next chapter. The utilities described here are: | |
32630 | ||
f89d2485 PH |
32631 | .itable none 0 0 3 7* left 15* left 40* left |
32632 | .irow &<<SECTfinoutwha>>& &'exiwhat'& &&& | |
9b371988 | 32633 | "list what Exim processes are doing" |
f89d2485 PH |
32634 | .irow &<<SECTgreptheque>>& &'exiqgrep'& "grep the queue" |
32635 | .irow &<<SECTsumtheque>>& &'exiqsumm'& "summarize the queue" | |
32636 | .irow &<<SECTextspeinf>>& &'exigrep'& "search the main log" | |
32637 | .irow &<<SECTexipick>>& &'exipick'& "select messages on &&& | |
32638 | various criteria" | |
32639 | .irow &<<SECTcyclogfil>>& &'exicyclog'& "cycle (rotate) log files" | |
32640 | .irow &<<SECTmailstat>>& &'eximstats'& &&& | |
9b371988 | 32641 | "extract statistics from the log" |
f89d2485 | 32642 | .irow &<<SECTcheckaccess>>& &'exim_checkaccess'& &&& |
9b371988 | 32643 | "check address acceptance from given IP" |
f89d2485 PH |
32644 | .irow &<<SECTdbmbuild>>& &'exim_dbmbuild'& "build a DBM file" |
32645 | .irow &<<SECTfinindret>>& &'exinext'& "extract retry information" | |
32646 | .irow &<<SECThindatmai>>& &'exim_dumpdb'& "dump a hints database" | |
32647 | .irow &<<SECThindatmai>>& &'exim_tidydb'& "clean up a hints database" | |
32648 | .irow &<<SECThindatmai>>& &'exim_fixdb'& "patch a hints database" | |
32649 | .irow &<<SECTmailboxmaint>>& &'exim_lock'& "lock a mailbox file" | |
9b371988 PH |
32650 | .endtable |
32651 | ||
068aaea8 | 32652 | Another utility that might be of use to sites with many MTAs is Tom Kistner's |
9b371988 PH |
32653 | &'exilog'&. It provides log visualizations across multiple Exim servers. See |
32654 | &url(http://duncanthrax.net/exilog/) for details. | |
068aaea8 PH |
32655 | |
32656 | ||
32657 | ||
32658 | ||
9b371988 PH |
32659 | .section "Finding out what Exim processes are doing (exiwhat)" "SECTfinoutwha" |
32660 | .cindex "&'exiwhat'&" | |
f89d2485 | 32661 | .cindex "process, querying" |
9b371988 | 32662 | .cindex "SIGUSR1" |
168e428f PH |
32663 | On operating systems that can restart a system call after receiving a signal |
32664 | (most modern OS), an Exim process responds to the SIGUSR1 signal by writing | |
9b371988 PH |
32665 | a line describing what it is doing to the file &_exim-process.info_& in the |
32666 | Exim spool directory. The &'exiwhat'& script sends the signal to all Exim | |
168e428f PH |
32667 | processes it can find, having first emptied the file. It then waits for one |
32668 | second to allow the Exim processes to react before displaying the results. In | |
9b371988 | 32669 | order to run &'exiwhat'& successfully you have to have sufficient privilege to |
168e428f PH |
32670 | send the signal to the Exim processes, so it is normally run as root. |
32671 | ||
9b371988 | 32672 | &*Warning*&: This is not an efficient process. It is intended for occasional |
168e428f PH |
32673 | use by system administrators. It is not sensible, for example, to set up a |
32674 | script that sends SIGUSR1 signals to Exim processes at short intervals. | |
32675 | ||
32676 | ||
9b371988 | 32677 | Unfortunately, the &'ps'& command that &'exiwhat'& uses to find Exim processes |
168e428f PH |
32678 | varies in different operating systems. Not only are different options used, |
32679 | but the format of the output is different. For this reason, there are some | |
9b371988 PH |
32680 | system configuration options that configure exactly how &'exiwhat'& works. If |
32681 | it doesn't seem to be working for you, check the following compile-time | |
32682 | options: | |
32683 | .display | |
32684 | &`EXIWHAT_PS_CMD `& the command for running &'ps'& | |
32685 | &`EXIWHAT_PS_ARG `& the argument for &'ps'& | |
32686 | &`EXIWHAT_EGREP_ARG `& the argument for &'egrep'& to select from &'ps'& output | |
32687 | &`EXIWHAT_KILL_ARG `& the argument for the &'kill'& command | |
32688 | .endd | |
32689 | An example of typical output from &'exiwhat'& is | |
32690 | .code | |
32691 | 164 daemon: -q1h, listening on port 25 | |
32692 | 10483 running queue: waiting for 0tAycK-0002ij-00 (10492) | |
32693 | 10492 delivering 0tAycK-0002ij-00 to mail.ref.example | |
32694 | [10.19.42.42] (editor@ref.example) | |
32695 | 10592 handling incoming call from [192.168.243.242] | |
32696 | 10628 accepting a local non-SMTP message | |
32697 | .endd | |
168e428f PH |
32698 | The first number in the output line is the process number. The third line has |
32699 | been split here, in order to fit it on the page. | |
32700 | ||
32701 | ||
32702 | ||
9b371988 PH |
32703 | .section "Selective queue listing (exiqgrep)" "SECTgreptheque" |
32704 | .cindex "&'exiqgrep'&" | |
32705 | .cindex "queue" "grepping" | |
168e428f | 32706 | This utility is a Perl script contributed by Matt Hubbard. It runs |
9b371988 PH |
32707 | .code |
32708 | exim -bpu | |
32709 | .endd | |
168e428f PH |
32710 | to obtain a queue listing with undelivered recipients only, and then greps the |
32711 | output to select messages that match given criteria. The following selection | |
32712 | options are available: | |
32713 | ||
9b371988 PH |
32714 | .vlist |
32715 | .vitem &*-f*&&~<&'regex'&> | |
168e428f PH |
32716 | Match the sender address. The field that is tested is enclosed in angle |
32717 | brackets, so you can test for bounce messages with | |
9b371988 PH |
32718 | .code |
32719 | exiqgrep -f '^<>$' | |
32720 | .endd | |
32721 | .vitem &*-r*&&~<&'regex'&> | |
168e428f PH |
32722 | Match a recipient address. The field that is tested is not enclosed in angle |
32723 | brackets. | |
32724 | ||
9b371988 | 32725 | .vitem &*-s*&&~<&'regex'&> |
168e428f PH |
32726 | Match against the size field. |
32727 | ||
9b371988 | 32728 | .vitem &*-y*&&~<&'seconds'&> |
168e428f PH |
32729 | Match messages that are younger than the given time. |
32730 | ||
9b371988 | 32731 | .vitem &*-o*&&~<&'seconds'&> |
168e428f PH |
32732 | Match messages that are older than the given time. |
32733 | ||
9b371988 | 32734 | .vitem &*-z*& |
168e428f PH |
32735 | Match only frozen messages. |
32736 | ||
9b371988 | 32737 | .vitem &*-x*& |
168e428f | 32738 | Match only non-frozen messages. |
9b371988 | 32739 | .endlist |
168e428f PH |
32740 | |
32741 | The following options control the format of the output: | |
32742 | ||
9b371988 PH |
32743 | .vlist |
32744 | .vitem &*-c*& | |
168e428f PH |
32745 | Display only the count of matching messages. |
32746 | ||
9b371988 PH |
32747 | .vitem &*-l*& |
32748 | Long format &-- display the full message information as output by Exim. This is | |
168e428f PH |
32749 | the default. |
32750 | ||
9b371988 | 32751 | .vitem &*-i*& |
168e428f PH |
32752 | Display message ids only. |
32753 | ||
9b371988 PH |
32754 | .vitem &*-b*& |
32755 | Brief format &-- one line per message. | |
168e428f | 32756 | |
9b371988 | 32757 | .vitem &*-R*& |
168e428f | 32758 | Display messages in reverse order. |
9b371988 | 32759 | .endlist |
168e428f | 32760 | |
9b371988 | 32761 | There is one more option, &%-h%&, which outputs a list of options. |
168e428f | 32762 | |
168e428f PH |
32763 | |
32764 | ||
f89d2485 | 32765 | .section "Summarizing the queue (exiqsumm)" "SECTsumtheque" |
9b371988 PH |
32766 | .cindex "&'exiqsumm'&" |
32767 | .cindex "queue" "summary" | |
32768 | The &'exiqsumm'& utility is a Perl script which reads the output of &`exim | |
32769 | -bp`& and produces a summary of the messages on the queue. Thus, you use it by | |
168e428f | 32770 | running a command such as |
9b371988 PH |
32771 | .code |
32772 | exim -bp | exiqsumm | |
32773 | .endd | |
168e428f PH |
32774 | The output consists of one line for each domain that has messages waiting for |
32775 | it, as in the following example: | |
9b371988 PH |
32776 | .code |
32777 | 3 2322 74m 66m msn.com.example | |
32778 | .endd | |
3cb1b51e PH |
32779 | Each line lists the number of pending deliveries for a domain, their total |
32780 | volume, and the length of time that the oldest and the newest messages have | |
32781 | been waiting. Note that the number of pending deliveries is greater than the | |
32782 | number of messages when messages have more than one recipient. | |
168e428f PH |
32783 | |
32784 | A summary line is output at the end. By default the output is sorted on the | |
9b371988 PH |
32785 | domain name, but &'exiqsumm'& has the options &%-a%& and &%-c%&, which cause |
32786 | the output to be sorted by oldest message and by count of messages, | |
3cb1b51e PH |
32787 | respectively. There are also three options that split the messages for each |
32788 | domain into two or more subcounts: &%-b%& separates bounce messages, &%-f%& | |
32789 | separates frozen messages, and &%-s%& separates messages according to their | |
32790 | sender. | |
168e428f | 32791 | |
9b371988 PH |
32792 | The output of &'exim -bp'& contains the original addresses in the message, so |
32793 | this also applies to the output from &'exiqsumm'&. No domains from addresses | |
32794 | generated by aliasing or forwarding are included (unless the &%one_time%& | |
32795 | option of the &(redirect)& router has been used to convert them into &"top | |
32796 | level"& addresses). | |
168e428f PH |
32797 | |
32798 | ||
32799 | ||
32800 | ||
9b371988 PH |
32801 | .section "Extracting specific information from the log (exigrep)" &&& |
32802 | "SECTextspeinf" | |
32803 | .cindex "&'exigrep'&" | |
32804 | .cindex "log" "extracts; grepping for" | |
9b371988 | 32805 | The &'exigrep'& utility is a Perl script that searches one or more main log |
168e428f PH |
32806 | files for entries that match a given pattern. When it finds a match, it |
32807 | extracts all the log entries for the relevant message, not just those that | |
9b371988 | 32808 | match the pattern. Thus, &'exigrep'& can extract complete log entries for a |
168e428f | 32809 | given message, or all mail for a given user, or for a given host, for example. |
068aaea8 | 32810 | The input files can be in Exim log format or syslog format. |
f89d2485 PH |
32811 | If a matching log line is not associated with a specific message, it is |
32812 | included in &'exigrep'&'s output without any additional lines. The usage is: | |
9b371988 | 32813 | .display |
f89d2485 | 32814 | &`exigrep [-t<`&&'n'&&`>] [-I] [-l] [-v] <`&&'pattern'&&`> [<`&&'log file'&&`>] ...`& |
9b371988 | 32815 | .endd |
f89d2485 PH |
32816 | If no log file names are given on the command line, the standard input is read. |
32817 | ||
9b371988 | 32818 | The &%-t%& argument specifies a number of seconds. It adds an additional |
168e428f | 32819 | condition for message selection. Messages that are complete are shown only if |
9b371988 | 32820 | they spent more than <&'n'&> seconds on the queue. |
168e428f | 32821 | |
f89d2485 PH |
32822 | By default, &'exigrep'& does case-insensitive matching. The &%-I%& option |
32823 | makes it case-sensitive. This may give a performance improvement when searching | |
32824 | large log files. Without &%-I%&, the Perl pattern matches use Perl's &`/i`& | |
32825 | option; with &%-I%& they do not. In both cases it is possible to change the | |
32826 | case sensitivity within the pattern by using &`(?i)`& or &`(?-i)`&. | |
32827 | ||
32828 | The &%-l%& option means &"literal"&, that is, treat all characters in the | |
168e428f | 32829 | pattern as standing for themselves. Otherwise the pattern must be a Perl |
f89d2485 PH |
32830 | regular expression. |
32831 | ||
32832 | The &%-v%& option inverts the matching condition. That is, a line is selected | |
32833 | if it does &'not'& match the pattern. | |
168e428f | 32834 | |
9b371988 PH |
32835 | If the location of a &'zcat'& command is known from the definition of |
32836 | ZCAT_COMMAND in &_Local/Makefile_&, &'exigrep'& automatically passes any file | |
32837 | whose name ends in COMPRESS_SUFFIX through &'zcat'& as it searches it. | |
168e428f PH |
32838 | |
32839 | ||
9b371988 PH |
32840 | .section "Selecting messages by various criteria (exipick)" "SECTexipick" |
32841 | .cindex "&'exipick'&" | |
32842 | John Jetmore's &'exipick'& utility is included in the Exim distribution. It | |
f89d2485 PH |
32843 | lists messages from the queue according to a variety of criteria. For details |
32844 | of &'exipick'&'s facilities, visit the web page at | |
32845 | &url(http://www.exim.org/eximwiki/ToolExipickManPage) or run &'exipick'& with | |
32846 | the &%--help%& option. | |
168e428f PH |
32847 | |
32848 | ||
9b371988 PH |
32849 | .section "Cycling log files (exicyclog)" "SECTcyclogfil" |
32850 | .cindex "log" "cycling local files" | |
32851 | .cindex "cycling logs" | |
32852 | .cindex "&'exicyclog'&" | |
32853 | The &'exicyclog'& script can be used to cycle (rotate) &'mainlog'& and | |
32854 | &'rejectlog'& files. This is not necessary if only syslog is being used, or if | |
168e428f | 32855 | you are using log files with datestamps in their names (see section |
9b371988 PH |
32856 | &<<SECTdatlogfil>>&). Some operating systems have their own standard mechanisms |
32857 | for log cycling, and these can be used instead of &'exicyclog'& if preferred. | |
4f578862 PH |
32858 | There are two command line options for &'exicyclog'&: |
32859 | .ilist | |
32860 | &%-k%& <&'count'&> specifies the number of log files to keep, overriding the | |
32861 | default that is set when Exim is built. The default default is 10. | |
32862 | .next | |
32863 | &%-l%& <&'path'&> specifies the log file path, in the same format as Exim's | |
32864 | &%log_file_path%& option (for example, &`/var/log/exim_%slog`&), again | |
32865 | overriding the script's default, which is to find the setting from Exim's | |
32866 | configuration. | |
32867 | .endlist | |
168e428f | 32868 | |
9b371988 PH |
32869 | Each time &'exicyclog'& is run the file names get &"shuffled down"& by one. If |
32870 | the main log file name is &_mainlog_& (the default) then when &'exicyclog'& is | |
32871 | run &_mainlog_& becomes &_mainlog.01_&, the previous &_mainlog.01_& becomes | |
4f578862 PH |
32872 | &_mainlog.02_& and so on, up to the limit that is set in the script or by the |
32873 | &%-k%& option. Log files whose numbers exceed the limit are discarded. Reject | |
168e428f PH |
32874 | logs are handled similarly. |
32875 | ||
32876 | If the limit is greater than 99, the script uses 3-digit numbers such as | |
9b371988 PH |
32877 | &_mainlog.001_&, &_mainlog.002_&, etc. If you change from a number less than 99 |
32878 | to one that is greater, or &'vice versa'&, you will have to fix the names of | |
168e428f PH |
32879 | any existing log files. |
32880 | ||
9b371988 | 32881 | If no &_mainlog_& file exists, the script does nothing. Files that &"drop off"& |
168e428f PH |
32882 | the end are deleted. All files with numbers greater than 01 are compressed, |
32883 | using a compression command which is configured by the COMPRESS_COMMAND | |
9b371988 PH |
32884 | setting in &_Local/Makefile_&. It is usual to run &'exicyclog'& daily from a |
32885 | root &%crontab%& entry of the form | |
32886 | .code | |
32887 | 1 0 * * * su exim -c /usr/exim/bin/exicyclog | |
32888 | .endd | |
32889 | assuming you have used the name &"exim"& for the Exim user. You can run | |
32890 | &'exicyclog'& as root if you wish, but there is no need. | |
168e428f PH |
32891 | |
32892 | ||
32893 | ||
9b371988 PH |
32894 | .section "Mail statistics (eximstats)" "SECTmailstat" |
32895 | .cindex "statistics" | |
32896 | .cindex "&'eximstats'&" | |
32897 | A Perl script called &'eximstats'& is provided for extracting statistical | |
168e428f | 32898 | information from log files. The output is either plain text, or HTML. |
f89d2485 | 32899 | Exim log files are also supported by the &'Lire'& system produced by the |
9b371988 | 32900 | LogReport Foundation &url(http://www.logreport.org). |
168e428f | 32901 | |
9b371988 | 32902 | The &'eximstats'& script has been hacked about quite a bit over time. The |
168e428f PH |
32903 | latest version is the result of some extensive revision by Steve Campbell. A |
32904 | lot of information is given by default, but there are options for suppressing | |
32905 | various parts of it. Following any options, the arguments to the script are a | |
32906 | list of files, which should be main log files. For example: | |
9b371988 PH |
32907 | .code |
32908 | eximstats -nr /var/spool/exim/log/mainlog.01 | |
32909 | .endd | |
32910 | By default, &'eximstats'& extracts information about the number and volume of | |
168e428f PH |
32911 | messages received from or delivered to various hosts. The information is sorted |
32912 | both by message count and by volume, and the top fifty hosts in each category | |
32913 | are listed on the standard output. Similar information, based on email | |
32914 | addresses or domains instead of hosts can be requested by means of various | |
32915 | options. For messages delivered and received locally, similar statistics are | |
32916 | also produced per user. | |
32917 | ||
32918 | The output also includes total counts and statistics about delivery errors, and | |
32919 | histograms showing the number of messages received and deliveries made in each | |
32920 | hour of the day. A delivery with more than one address in its envelope (for | |
32921 | example, an SMTP transaction with more than one RCPT command) is counted | |
9b371988 | 32922 | as a single delivery by &'eximstats'&. |
168e428f PH |
32923 | |
32924 | Though normally more deliveries than receipts are reported (as messages may | |
9b371988 | 32925 | have multiple recipients), it is possible for &'eximstats'& to report more |
168e428f PH |
32926 | messages received than delivered, even though the queue is empty at the start |
32927 | and end of the period in question. If an incoming message contains no valid | |
32928 | recipients, no deliveries are recorded for it. A bounce message is handled as | |
32929 | an entirely separate message. | |
32930 | ||
9b371988 | 32931 | &'eximstats'& always outputs a grand total summary giving the volume and number |
168e428f PH |
32932 | of messages received and deliveries made, and the number of hosts involved in |
32933 | each case. It also outputs the number of messages that were delayed (that is, | |
32934 | not completely delivered at the first attempt), and the number that had at | |
32935 | least one address that failed. | |
32936 | ||
32937 | The remainder of the output is in sections that can be independently disabled | |
32938 | or modified by various options. It consists of a summary of deliveries by | |
32939 | transport, histograms of messages received and delivered per time interval | |
32940 | (default per hour), information about the time messages spent on the queue, | |
32941 | a list of relayed messages, lists of the top fifty sending hosts, local | |
32942 | senders, destination hosts, and destination local users by count and by volume, | |
32943 | and a list of delivery errors that occurred. | |
32944 | ||
32945 | The relay information lists messages that were actually relayed, that is, they | |
32946 | came from a remote host and were directly delivered to some other remote host, | |
32947 | without being processed (for example, for aliasing or forwarding) locally. | |
32948 | ||
9b371988 | 32949 | There are quite a few options for &'eximstats'& to control exactly what it |
168e428f | 32950 | outputs. These are documented in the Perl script itself, and can be extracted |
9b371988 PH |
32951 | by running the command &(perldoc)& on the script. For example: |
32952 | .code | |
32953 | perldoc /usr/exim/bin/eximstats | |
32954 | .endd | |
32955 | ||
32956 | .section "Checking access policy (exim_checkaccess)" "SECTcheckaccess" | |
32957 | .cindex "&'exim_checkaccess'&" | |
32958 | .cindex "policy control" "checking access" | |
32959 | .cindex "checking access" | |
32960 | The &%-bh%& command line argument allows you to run a fake SMTP session with | |
168e428f PH |
32961 | debugging output, in order to check what Exim is doing when it is applying |
32962 | policy controls to incoming SMTP mail. However, not everybody is sufficiently | |
9b371988 PH |
32963 | familiar with the SMTP protocol to be able to make full use of &%-bh%&, and |
32964 | sometimes you just want to answer the question &"Does this address have | |
32965 | access?"& without bothering with any further details. | |
168e428f | 32966 | |
9b371988 | 32967 | The &'exim_checkaccess'& utility is a &"packaged"& version of &%-bh%&. It takes |
168e428f | 32968 | two arguments, an IP address and an email address: |
9b371988 PH |
32969 | .code |
32970 | exim_checkaccess 10.9.8.7 A.User@a.domain.example | |
32971 | .endd | |
32972 | The utility runs a call to Exim with the &%-bh%& option, to test whether the | |
168e428f PH |
32973 | given email address would be accepted in a RCPT command in a TCP/IP |
32974 | connection from the host with the given IP address. The output of the utility | |
9b371988 PH |
32975 | is either the word &"accepted"&, or the SMTP error response, for example: |
32976 | .code | |
32977 | Rejected: | |
32978 | 550 Relay not permitted | |
32979 | .endd | |
32980 | When running this test, the utility uses &`<>`& as the envelope sender address | |
168e428f PH |
32981 | for the MAIL command, but you can change this by providing additional |
32982 | options. These are passed directly to the Exim command. For example, to specify | |
9b371988 | 32983 | that the test is to be run with the sender address &'himself@there.example'& |
168e428f | 32984 | you can use: |
9b371988 | 32985 | .code |
168e428f PH |
32986 | exim_checkaccess 10.9.8.7 A.User@a.domain.example \ |
32987 | -f himself@there.example | |
9b371988 | 32988 | .endd |
168e428f PH |
32989 | Note that these additional Exim command line items must be given after the two |
32990 | mandatory arguments. | |
32991 | ||
9b371988 PH |
32992 | Because the &%exim_checkaccess%& uses &%-bh%&, it does not perform callouts |
32993 | while running its checks. You can run checks that include callouts by using | |
32994 | &%-bhc%&, but this is not yet available in a &"packaged"& form. | |
168e428f PH |
32995 | |
32996 | ||
32997 | ||
9b371988 PH |
32998 | .section "Making DBM files (exim_dbmbuild)" "SECTdbmbuild" |
32999 | .cindex "DBM" "building dbm files" | |
33000 | .cindex "building DBM files" | |
33001 | .cindex "&'exim_dbmbuild'&" | |
33002 | .cindex "lower casing" | |
33003 | .cindex "binary zero" "in lookup key" | |
33004 | The &'exim_dbmbuild'& program reads an input file containing keys and data in | |
33005 | the format used by the &(lsearch)& lookup (see section | |
33006 | &<<SECTsinglekeylookups>>&). It writes a DBM file using the lower-cased alias | |
33007 | names as keys and the remainder of the information as data. The lower-casing | |
33008 | can be prevented by calling the program with the &%-nolc%& option. | |
168e428f PH |
33009 | |
33010 | A terminating zero is included as part of the key string. This is expected by | |
9b371988 PH |
33011 | the &(dbm)& lookup type. However, if the option &%-nozero%& is given, |
33012 | &'exim_dbmbuild'& creates files without terminating zeroes in either the key | |
33013 | strings or the data strings. The &(dbmnz)& lookup type can be used with such | |
168e428f PH |
33014 | files. |
33015 | ||
33016 | The program requires two arguments: the name of the input file (which can be a | |
33017 | single hyphen to indicate the standard input), and the name of the output file. | |
33018 | It creates the output under a temporary name, and then renames it if all went | |
33019 | well. | |
33020 | ||
9b371988 | 33021 | .cindex "USE_DB" |
168e428f | 33022 | If the native DB interface is in use (USE_DB is set in a compile-time |
9b371988 | 33023 | configuration file &-- this is common in free versions of Unix) the two file |
168e428f PH |
33024 | names must be different, because in this mode the Berkeley DB functions create |
33025 | a single output file using exactly the name given. For example, | |
9b371988 PH |
33026 | .code |
33027 | exim_dbmbuild /etc/aliases /etc/aliases.db | |
33028 | .endd | |
168e428f | 33029 | reads the system alias file and creates a DBM version of it in |
9b371988 | 33030 | &_/etc/aliases.db_&. |
168e428f | 33031 | |
9b371988 PH |
33032 | In systems that use the &'ndbm'& routines (mostly proprietary versions of |
33033 | Unix), two files are used, with the suffixes &_.dir_& and &_.pag_&. In this | |
168e428f | 33034 | environment, the suffixes are added to the second argument of |
9b371988 | 33035 | &'exim_dbmbuild'&, so it can be the same as the first. This is also the case |
168e428f | 33036 | when the Berkeley functions are used in compatibility mode (though this is not |
9b371988 | 33037 | recommended), because in that case it adds a &_.db_& suffix to the file name. |
168e428f PH |
33038 | |
33039 | If a duplicate key is encountered, the program outputs a warning, and when it | |
9b371988 PH |
33040 | finishes, its return code is 1 rather than zero, unless the &%-noduperr%& |
33041 | option is used. By default, only the first of a set of duplicates is used &-- | |
33042 | this makes it compatible with &(lsearch)& lookups. There is an option | |
33043 | &%-lastdup%& which causes it to use the data for the last duplicate instead. | |
33044 | There is also an option &%-nowarn%&, which stops it listing duplicate keys to | |
33045 | &%stderr%&. For other errors, where it doesn't actually make a new file, the | |
33046 | return code is 2. | |
168e428f PH |
33047 | |
33048 | ||
33049 | ||
33050 | ||
9b371988 PH |
33051 | .section "Finding individual retry times (exinext)" "SECTfinindret" |
33052 | .cindex "retry" "times" | |
33053 | .cindex "&'exinext'&" | |
33054 | A utility called &'exinext'& (mostly a Perl script) provides the ability to | |
33055 | fish specific information out of the retry database. Given a mail domain (or a | |
168e428f PH |
33056 | complete address), it looks up the hosts for that domain, and outputs any retry |
33057 | information for the hosts or for the domain. At present, the retry information | |
9b371988 | 33058 | is obtained by running &'exim_dumpdb'& (see below) and post-processing the |
168e428f | 33059 | output. For example: |
9b371988 PH |
33060 | .code |
33061 | $ exinext piglet@milne.fict.example | |
33062 | kanga.milne.example:192.168.8.1 error 146: Connection refused | |
33063 | first failed: 21-Feb-1996 14:57:34 | |
33064 | last tried: 21-Feb-1996 14:57:34 | |
33065 | next try at: 21-Feb-1996 15:02:34 | |
33066 | roo.milne.example:192.168.8.3 error 146: Connection refused | |
33067 | first failed: 20-Jan-1996 13:12:08 | |
33068 | last tried: 21-Feb-1996 11:42:03 | |
33069 | next try at: 21-Feb-1996 19:42:03 | |
33070 | past final cutoff time | |
33071 | .endd | |
33072 | You can also give &'exinext'& a local part, without a domain, and it | |
168e428f PH |
33073 | will give any retry information for that local part in your default domain. |
33074 | A message id can be used to obtain retry information pertaining to a specific | |
33075 | message. This exists only when an attempt to deliver a message to a remote host | |
9b371988 PH |
33076 | suffers a message-specific error (see section &<<SECToutSMTPerr>>&). |
33077 | &'exinext'& is not particularly efficient, but then it is not expected to be | |
33078 | run very often. | |
168e428f | 33079 | |
9b371988 PH |
33080 | The &'exinext'& utility calls Exim to find out information such as the location |
33081 | of the spool directory. The utility has &%-C%& and &%-D%& options, which are | |
33082 | passed on to the &'exim'& commands. The first specifies an alternate Exim | |
168e428f PH |
33083 | configuration file, and the second sets macros for use within the configuration |
33084 | file. These features are mainly to help in testing, but might also be useful in | |
33085 | environments where more than one configuration file is in use. | |
33086 | ||
33087 | ||
33088 | ||
9b371988 PH |
33089 | .section "Hints database maintenance" "SECThindatmai" |
33090 | .cindex "hints database" "maintenance" | |
33091 | .cindex "maintaining Exim's hints database" | |
168e428f PH |
33092 | Three utility programs are provided for maintaining the DBM files that Exim |
33093 | uses to contain its delivery hint information. Each program requires two | |
33094 | arguments. The first specifies the name of Exim's spool directory, and the | |
068aaea8 | 33095 | second is the name of the database it is to operate on. These are as follows: |
168e428f | 33096 | |
9b371988 PH |
33097 | .ilist |
33098 | &'retry'&: the database of retry information | |
33099 | .next | |
33100 | &'wait-'&<&'transport name'&>: databases of information about messages waiting | |
168e428f | 33101 | for remote hosts |
9b371988 PH |
33102 | .next |
33103 | &'callout'&: the callout cache | |
9b371988 PH |
33104 | .next |
33105 | &'ratelimit'&: the data for implementing the ratelimit ACL condition | |
9b371988 PH |
33106 | .next |
33107 | &'misc'&: other hints data | |
33108 | .endlist | |
168e428f | 33109 | |
9b371988 | 33110 | The &'misc'& database is used for |
168e428f | 33111 | |
9b371988 PH |
33112 | .ilist |
33113 | Serializing ETRN runs (when &%smtp_etrn_serialize%& is set) | |
33114 | .next | |
33115 | Serializing delivery to a specific host (when &%serialize_hosts%& is set in an | |
33116 | &(smtp)& transport) | |
33117 | .endlist | |
168e428f | 33118 | |
168e428f PH |
33119 | |
33120 | ||
f89d2485 | 33121 | .section "exim_dumpdb" "SECID261" |
9b371988 | 33122 | .cindex "&'exim_dumpdb'&" |
168e428f | 33123 | The entire contents of a database are written to the standard output by the |
9b371988 | 33124 | &'exim_dumpdb'& program, which has no options or arguments other than the |
168e428f | 33125 | spool and database names. For example, to dump the retry database: |
9b371988 PH |
33126 | .code |
33127 | exim_dumpdb /var/spool/exim retry | |
33128 | .endd | |
168e428f | 33129 | Two lines of output are produced for each entry: |
9b371988 PH |
33130 | .code |
33131 | T:mail.ref.example:192.168.242.242 146 77 Connection refused | |
33132 | 31-Oct-1995 12:00:12 02-Nov-1995 12:21:39 02-Nov-1995 20:21:39 * | |
33133 | .endd | |
168e428f PH |
33134 | The first item on the first line is the key of the record. It starts with one |
33135 | of the letters R, or T, depending on whether it refers to a routing or | |
33136 | transport retry. For a local delivery, the next part is the local address; for | |
33137 | a remote delivery it is the name of the remote host, followed by its failing IP | |
f89d2485 | 33138 | address (unless &%retry_include_ip_address%& is set false on the &(smtp)& |
168e428f PH |
33139 | transport). If the remote port is not the standard one (port 25), it is added |
33140 | to the IP address. Then there follows an error code, an additional error code, | |
33141 | and a textual description of the error. | |
33142 | ||
33143 | The three times on the second line are the time of first failure, the time of | |
33144 | the last delivery attempt, and the computed time for the next attempt. The line | |
33145 | ends with an asterisk if the cutoff time for the last retry rule has been | |
33146 | exceeded. | |
33147 | ||
9b371988 | 33148 | Each output line from &'exim_dumpdb'& for the &'wait-xxx'& databases |
168e428f PH |
33149 | consists of a host name followed by a list of ids for messages that are or were |
33150 | waiting to be delivered to that host. If there are a very large number for any | |
33151 | one host, continuation records, with a sequence number added to the host name, | |
33152 | may be seen. The data in these records is often out of date, because a message | |
33153 | may be routed to several alternative hosts, and Exim makes no effort to keep | |
33154 | cross-references. | |
33155 | ||
33156 | ||
33157 | ||
f89d2485 | 33158 | .section "exim_tidydb" "SECID262" |
9b371988 | 33159 | .cindex "&'exim_tidydb'&" |
9b371988 | 33160 | The &'exim_tidydb'& utility program is used to tidy up the contents of a hints |
068aaea8 PH |
33161 | database. If run with no options, it removes all records that are more than 30 |
33162 | days old. The age is calculated from the date and time that the record was last | |
9b371988 | 33163 | updated. Note that, in the case of the retry database, it is &'not'& the time |
068aaea8 PH |
33164 | since the first delivery failure. Information about a host that has been down |
33165 | for more than 30 days will remain in the database, provided that the record is | |
33166 | updated sufficiently often. | |
33167 | ||
9b371988 | 33168 | The cutoff date can be altered by means of the &%-t%& option, which must be |
068aaea8 PH |
33169 | followed by a time. For example, to remove all records older than a week from |
33170 | the retry database: | |
9b371988 PH |
33171 | .code |
33172 | exim_tidydb -t 7d /var/spool/exim retry | |
33173 | .endd | |
33174 | Both the &'wait-xxx'& and &'retry'& databases contain items that involve | |
33175 | message ids. In the former these appear as data in records keyed by host &-- | |
33176 | they were messages that were waiting for that host &-- and in the latter they | |
168e428f | 33177 | are the keys for retry information for messages that have suffered certain |
9b371988 | 33178 | types of error. When &'exim_tidydb'& is run, a check is made to ensure that |
168e428f PH |
33179 | message ids in database records are those of messages that are still on the |
33180 | queue. Message ids for messages that no longer exist are removed from | |
9b371988 PH |
33181 | &'wait-xxx'& records, and if this leaves any records empty, they are deleted. |
33182 | For the &'retry'& database, records whose keys are non-existent message ids are | |
33183 | removed. The &'exim_tidydb'& utility outputs comments on the standard output | |
33184 | whenever it removes information from the database. | |
168e428f PH |
33185 | |
33186 | Certain records are automatically removed by Exim when they are no longer | |
33187 | needed, but others are not. For example, if all the MX hosts for a domain are | |
33188 | down, a retry record is created for each one. If the primary MX host comes back | |
33189 | first, its record is removed when Exim successfully delivers to it, but the | |
33190 | records for the others remain because Exim has not tried to use those hosts. | |
33191 | ||
9b371988 | 33192 | It is important, therefore, to run &'exim_tidydb'& periodically on all the |
168e428f PH |
33193 | hints databases. You should do this at a quiet time of day, because it requires |
33194 | a database to be locked (and therefore inaccessible to Exim) while it does its | |
33195 | work. Removing records from a DBM file does not normally make the file smaller, | |
33196 | but all the common DBM libraries are able to re-use the space that is released. | |
33197 | After an initial phase of increasing in size, the databases normally reach a | |
33198 | point at which they no longer get any bigger, as long as they are regularly | |
33199 | tidied. | |
33200 | ||
9b371988 | 33201 | &*Warning*&: If you never run &'exim_tidydb'&, the space used by the hints |
168e428f PH |
33202 | databases is likely to keep on increasing. |
33203 | ||
33204 | ||
33205 | ||
33206 | ||
f89d2485 | 33207 | .section "exim_fixdb" "SECID263" |
9b371988 PH |
33208 | .cindex "&'exim_fixdb'&" |
33209 | The &'exim_fixdb'& program is a utility for interactively modifying databases. | |
168e428f PH |
33210 | Its main use is for testing Exim, but it might also be occasionally useful for |
33211 | getting round problems in a live system. It has no options, and its interface | |
33212 | is somewhat crude. On entry, it prompts for input with a right angle-bracket. A | |
33213 | key of a database record can then be entered, and the data for that record is | |
33214 | displayed. | |
33215 | ||
9b371988 PH |
33216 | If &"d"& is typed at the next prompt, the entire record is deleted. For all |
33217 | except the &'retry'& database, that is the only operation that can be carried | |
33218 | out. For the &'retry'& database, each field is output preceded by a number, and | |
168e428f PH |
33219 | data for individual fields can be changed by typing the field number followed |
33220 | by new data, for example: | |
9b371988 PH |
33221 | .code |
33222 | > 4 951102:1000 | |
33223 | .endd | |
168e428f PH |
33224 | resets the time of the next delivery attempt. Time values are given as a |
33225 | sequence of digit pairs for year, month, day, hour, and minute. Colons can be | |
33226 | used as optional separators. | |
33227 | ||
33228 | ||
33229 | ||
33230 | ||
9b371988 PH |
33231 | .section "Mailbox maintenance (exim_lock)" "SECTmailboxmaint" |
33232 | .cindex "mailbox" "maintenance" | |
33233 | .cindex "&'exim_lock'&" | |
33234 | .cindex "locking mailboxes" | |
33235 | The &'exim_lock'& utility locks a mailbox file using the same algorithm as | |
33236 | Exim. For a discussion of locking issues, see section &<<SECTopappend>>&. | |
33237 | &'Exim_lock'& can be used to prevent any modification of a mailbox by Exim or | |
168e428f PH |
33238 | a user agent while investigating a problem. The utility requires the name of |
33239 | the file as its first argument. If the locking is successful, the second | |
9b371988 | 33240 | argument is run as a command (using C's &[system()]& function); if there is no |
168e428f | 33241 | second argument, the value of the SHELL environment variable is used; if this |
9b371988 | 33242 | is unset or empty, &_/bin/sh_& is run. When the command finishes, the mailbox |
168e428f PH |
33243 | is unlocked and the utility ends. The following options are available: |
33244 | ||
9b371988 PH |
33245 | .vlist |
33246 | .vitem &%-fcntl%& | |
33247 | Use &[fcntl()]& locking on the open mailbox. | |
33248 | ||
33249 | .vitem &%-flock%& | |
33250 | Use &[flock()]& locking on the open mailbox, provided the operating system | |
33251 | supports it. | |
33252 | ||
33253 | .vitem &%-interval%& | |
33254 | This must be followed by a number, which is a number of seconds; it sets the | |
33255 | interval to sleep between retries (default 3). | |
33256 | ||
33257 | .vitem &%-lockfile%& | |
33258 | Create a lock file before opening the mailbox. | |
33259 | ||
33260 | .vitem &%-mbx%& | |
33261 | Lock the mailbox using MBX rules. | |
33262 | ||
33263 | .vitem &%-q%& | |
33264 | Suppress verification output. | |
33265 | ||
33266 | .vitem &%-retries%& | |
33267 | This must be followed by a number; it sets the number of times to try to get | |
33268 | the lock (default 10). | |
33269 | ||
33270 | .vitem &%-restore_time%& | |
33271 | This option causes &%exim_lock%& to restore the modified and read times to the | |
33272 | locked file before exiting. This allows you to access a locked mailbox (for | |
33273 | example, to take a backup copy) without disturbing the times that the user | |
33274 | subsequently sees. | |
33275 | ||
33276 | .vitem &%-timeout%& | |
33277 | This must be followed by a number, which is a number of seconds; it sets a | |
33278 | timeout to be used with a blocking &[fcntl()]& lock. If it is not set (the | |
33279 | default), a non-blocking call is used. | |
33280 | ||
33281 | .vitem &%-v%& | |
33282 | Generate verbose output. | |
33283 | .endlist | |
33284 | ||
33285 | If none of &%-fcntl%&, &%-flock%&, &%-lockfile%& or &%-mbx%& are given, the | |
33286 | default is to create a lock file and also to use &[fcntl()]& locking on the | |
33287 | mailbox, which is the same as Exim's default. The use of &%-flock%& or | |
33288 | &%-fcntl%& requires that the file be writeable; the use of &%-lockfile%& | |
33289 | requires that the directory containing the file be writeable. Locking by lock | |
33290 | file does not last for ever; Exim assumes that a lock file is expired if it is | |
33291 | more than 30 minutes old. | |
33292 | ||
33293 | The &%-mbx%& option can be used with either or both of &%-fcntl%& or | |
33294 | &%-flock%&. It assumes &%-fcntl%& by default. MBX locking causes a shared lock | |
33295 | to be taken out on the open mailbox, and an exclusive lock on the file | |
33296 | &_/tmp/.n.m_& where &'n'& and &'m'& are the device number and inode | |
33297 | number of the mailbox file. When the locking is released, if an exclusive lock | |
33298 | can be obtained for the mailbox, the file in &_/tmp_& is deleted. | |
168e428f PH |
33299 | |
33300 | The default output contains verification of the locking that takes place. The | |
9b371988 | 33301 | &%-v%& option causes some additional information to be given. The &%-q%& option |
168e428f PH |
33302 | suppresses all output except error messages. |
33303 | ||
33304 | A command such as | |
9b371988 PH |
33305 | .code |
33306 | exim_lock /var/spool/mail/spqr | |
33307 | .endd | |
168e428f | 33308 | runs an interactive shell while the file is locked, whereas |
9b371988 PH |
33309 | .display |
33310 | &`exim_lock -q /var/spool/mail/spqr <<End`& | |
33311 | <&'some commands'&> | |
33312 | &`End`& | |
33313 | .endd | |
168e428f PH |
33314 | runs a specific non-interactive sequence of commands while the file is locked, |
33315 | suppressing all verification output. A single command can be run by a command | |
33316 | such as | |
9b371988 | 33317 | .code |
168e428f PH |
33318 | exim_lock -q /var/spool/mail/spqr \ |
33319 | "cp /var/spool/mail/spqr /some/where" | |
9b371988 | 33320 | .endd |
168e428f | 33321 | Note that if a command is supplied, it must be entirely contained within the |
9b371988 | 33322 | second argument &-- hence the quotes. |
4f578862 | 33323 | .ecindex IIDutils |
168e428f PH |
33324 | |
33325 | ||
9b371988 PH |
33326 | . //////////////////////////////////////////////////////////////////////////// |
33327 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 33328 | |
9b371988 | 33329 | .chapter "The Exim monitor" "CHAPeximon" |
4f578862 | 33330 | .scindex IIDeximon "Exim monitor" "description" |
9b371988 PH |
33331 | .cindex "X-windows" |
33332 | .cindex "&'eximon'&" | |
33333 | .cindex "Local/eximon.conf" | |
3cb1b51e | 33334 | .cindex "&_exim_monitor/EDITME_&" |
168e428f PH |
33335 | The Exim monitor is an application which displays in an X window information |
33336 | about the state of Exim's queue and what Exim is doing. An admin user can | |
33337 | perform certain operations on messages from this GUI interface; however all | |
33338 | such facilities are also available from the command line, and indeed, the | |
33339 | monitor itself makes use of the command line to perform any actions requested. | |
33340 | ||
33341 | ||
33342 | ||
f89d2485 | 33343 | .section "Running the monitor" "SECID264" |
9b371988 | 33344 | The monitor is started by running the script called &'eximon'&. This is a shell |
168e428f | 33345 | script that sets up a number of environment variables, and then runs the |
9b371988 PH |
33346 | binary called &_eximon.bin_&. The default appearance of the monitor window can |
33347 | be changed by editing the &_Local/eximon.conf_& file created by editing | |
33348 | &_exim_monitor/EDITME_&. Comments in that file describe what the various | |
168e428f PH |
33349 | parameters are for. |
33350 | ||
9b371988 PH |
33351 | The parameters that get built into the &'eximon'& script can be overridden for |
33352 | a particular invocation by setting up environment variables of the same names, | |
33353 | preceded by &`EXIMON_`&. For example, a shell command such as | |
33354 | .code | |
33355 | EXIMON_LOG_DEPTH=400 eximon | |
33356 | .endd | |
33357 | (in a Bourne-compatible shell) runs &'eximon'& with an overriding setting of | |
33358 | the LOG_DEPTH parameter. If EXIMON_LOG_FILE_PATH is set in the environment, it | |
33359 | overrides the Exim log file configuration. This makes it possible to have | |
33360 | &'eximon'& tailing log data that is written to syslog, provided that MAIL.INFO | |
33361 | syslog messages are routed to a file on the local host. | |
168e428f PH |
33362 | |
33363 | X resources can be used to change the appearance of the window in the normal | |
33364 | way. For example, a resource setting of the form | |
9b371988 PH |
33365 | .code |
33366 | Eximon*background: gray94 | |
33367 | .endd | |
168e428f PH |
33368 | changes the colour of the background to light grey rather than white. The |
33369 | stripcharts are drawn with both the data lines and the reference lines in | |
33370 | black. This means that the reference lines are not visible when on top of the | |
33371 | data. However, their colour can be changed by setting a resource called | |
9b371988 | 33372 | &"highlight"& (an odd name, but that's what the Athena stripchart widget uses). |
168e428f PH |
33373 | For example, if your X server is running Unix, you could set up lighter |
33374 | reference lines in the stripcharts by obeying | |
9b371988 PH |
33375 | .code |
33376 | xrdb -merge <<End | |
33377 | Eximon*highlight: gray | |
33378 | End | |
33379 | .endd | |
33380 | .cindex "admin user" | |
168e428f | 33381 | In order to see the contents of messages on the queue, and to operate on them, |
9b371988 | 33382 | &'eximon'& must either be run as root or by an admin user. |
168e428f PH |
33383 | |
33384 | The monitor's window is divided into three parts. The first contains one or | |
9b371988 | 33385 | more stripcharts and two action buttons, the second contains a &"tail"& of the |
168e428f PH |
33386 | main log file, and the third is a display of the queue of messages awaiting |
33387 | delivery, with two more action buttons. The following sections describe these | |
33388 | different parts of the display. | |
33389 | ||
33390 | ||
33391 | ||
33392 | ||
f89d2485 | 33393 | .section "The stripcharts" "SECID265" |
9b371988 | 33394 | .cindex "stripchart" |
168e428f PH |
33395 | The first stripchart is always a count of messages on the queue. Its name can |
33396 | be configured by setting QUEUE_STRIPCHART_NAME in the | |
9b371988 | 33397 | &_Local/eximon.conf_& file. The remaining stripcharts are defined in the |
168e428f PH |
33398 | configuration script by regular expression matches on log file entries, making |
33399 | it possible to display, for example, counts of messages delivered to certain | |
33400 | hosts or using certain transports. The supplied defaults display counts of | |
33401 | received and delivered messages, and of local and SMTP deliveries. The default | |
33402 | period between stripchart updates is one minute; this can be adjusted by a | |
9b371988 | 33403 | parameter in the &_Local/eximon.conf_& file. |
168e428f PH |
33404 | |
33405 | The stripchart displays rescale themselves automatically as the value they are | |
33406 | displaying changes. There are always 10 horizontal lines in each chart; the | |
33407 | title string indicates the value of each division when it is greater than one. | |
9b371988 | 33408 | For example, &"x2"& means that each division represents a value of 2. |
168e428f PH |
33409 | |
33410 | It is also possible to have a stripchart which shows the percentage fullness of | |
33411 | a particular disk partition, which is useful when local deliveries are confined | |
33412 | to a single partition. | |
33413 | ||
9b371988 PH |
33414 | .cindex "&%statvfs%& function" |
33415 | This relies on the availability of the &[statvfs()]& function or equivalent in | |
168e428f PH |
33416 | the operating system. Most, but not all versions of Unix that support Exim have |
33417 | this. For this particular stripchart, the top of the chart always represents | |
9b371988 | 33418 | 100%, and the scale is given as &"x10%"&. This chart is configured by setting |
168e428f | 33419 | SIZE_STRIPCHART and (optionally) SIZE_STRIPCHART_NAME in the |
9b371988 | 33420 | &_Local/eximon.conf_& file. |
168e428f PH |
33421 | |
33422 | ||
33423 | ||
33424 | ||
f89d2485 | 33425 | .section "Main action buttons" "SECID266" |
9b371988 PH |
33426 | .cindex "size" "of monitor window" |
33427 | .cindex "Exim monitor" "window size" | |
33428 | .cindex "window size" | |
168e428f | 33429 | Below the stripcharts there is an action button for quitting the monitor. Next |
9b371988 PH |
33430 | to this is another button marked &"Size"&. They are placed here so that |
33431 | shrinking the window to its default minimum size leaves just the queue count | |
33432 | stripchart and these two buttons visible. Pressing the &"Size"& button causes | |
33433 | the window to expand to its maximum size, unless it is already at the maximum, | |
33434 | in which case it is reduced to its minimum. | |
168e428f PH |
33435 | |
33436 | When expanding to the maximum, if the window cannot be fully seen where it | |
33437 | currently is, it is moved back to where it was the last time it was at full | |
33438 | size. When it is expanding from its minimum size, the old position is | |
33439 | remembered, and next time it is reduced to the minimum it is moved back there. | |
33440 | ||
33441 | The idea is that you can keep a reduced window just showing one or two | |
33442 | stripcharts at a convenient place on your screen, easily expand it to show | |
33443 | the full window when required, and just as easily put it back to what it was. | |
9b371988 PH |
33444 | The idea is copied from what the &'twm'& window manager does for its |
33445 | &'f.fullzoom'& action. The minimum size of the window can be changed by setting | |
33446 | the MIN_HEIGHT and MIN_WIDTH values in &_Local/eximon.conf_&. | |
168e428f PH |
33447 | |
33448 | Normally, the monitor starts up with the window at its full size, but it can be | |
33449 | built so that it starts up with the window at its smallest size, by setting | |
9b371988 | 33450 | START_SMALL=yes in &_Local/eximon.conf_&. |
168e428f PH |
33451 | |
33452 | ||
33453 | ||
f89d2485 | 33454 | .section "The log display" "SECID267" |
9b371988 | 33455 | .cindex "log" "tail of; in monitor" |
168e428f PH |
33456 | The second section of the window is an area in which a display of the tail of |
33457 | the main log is maintained. | |
33458 | To save space on the screen, the timestamp on each log line is shortened by | |
9b371988 | 33459 | removing the date and, if &%log_timezone%& is set, the timezone. |
168e428f PH |
33460 | The log tail is not available when the only destination for logging data is |
33461 | syslog, unless the syslog lines are routed to a local file whose name is passed | |
9b371988 | 33462 | to &'eximon'& via the EXIMON_LOG_FILE_PATH environment variable. |
168e428f PH |
33463 | |
33464 | The log sub-window has a scroll bar at its lefthand side which can be used to | |
33465 | move back to look at earlier text, and the up and down arrow keys also have a | |
33466 | scrolling effect. The amount of log that is kept depends on the setting of | |
9b371988 PH |
33467 | LOG_BUFFER in &_Local/eximon.conf_&, which specifies the amount of memory |
33468 | to use. When this is full, the earlier 50% of data is discarded &-- this is | |
33469 | much more efficient than throwing it away line by line. The sub-window also has | |
33470 | a horizontal scroll bar for accessing the ends of long log lines. This is the | |
168e428f PH |
33471 | only means of horizontal scrolling; the right and left arrow keys are not |
33472 | available. Text can be cut from this part of the window using the mouse in the | |
33473 | normal way. The size of this subwindow is controlled by parameters in the | |
9b371988 | 33474 | configuration file &_Local/eximon.conf_&. |
168e428f PH |
33475 | |
33476 | Searches of the text in the log window can be carried out by means of the ^R | |
33477 | and ^S keystrokes, which default to a reverse and a forward search, | |
33478 | respectively. The search covers only the text that is displayed in the window. | |
33479 | It cannot go further back up the log. | |
33480 | ||
33481 | The point from which the search starts is indicated by a caret marker. This is | |
33482 | normally at the end of the text in the window, but can be positioned explicitly | |
33483 | by pointing and clicking with the left mouse button, and is moved automatically | |
33484 | by a successful search. If new text arrives in the window when it is scrolled | |
33485 | back, the caret remains where it is, but if the window is not scrolled back, | |
33486 | the caret is moved to the end of the new text. | |
33487 | ||
33488 | Pressing ^R or ^S pops up a window into which the search text can be typed. | |
33489 | There are buttons for selecting forward or reverse searching, for carrying out | |
9b371988 | 33490 | the search, and for cancelling. If the &"Search"& button is pressed, the search |
168e428f | 33491 | happens and the window remains so that further searches can be done. If the |
9b371988 | 33492 | &"Return"& key is pressed, a single search is done and the window is closed. If |
168e428f PH |
33493 | ^C is typed the search is cancelled. |
33494 | ||
33495 | The searching facility is implemented using the facilities of the Athena text | |
9b371988 PH |
33496 | widget. By default this pops up a window containing both &"search"& and |
33497 | &"replace"& options. In order to suppress the unwanted &"replace"& portion for | |
33498 | eximon, a modified version of the &%TextPop%& widget is distributed with Exim. | |
33499 | However, the linkers in BSDI and HP-UX seem unable to handle an externally | |
33500 | provided version of &%TextPop%& when the remaining parts of the text widget | |
33501 | come from the standard libraries. The compile-time option EXIMON_TEXTPOP can be | |
33502 | unset to cut out the modified &%TextPop%&, making it possible to build Eximon | |
33503 | on these systems, at the expense of having unwanted items in the search popup | |
33504 | window. | |
168e428f PH |
33505 | |
33506 | ||
33507 | ||
f89d2485 | 33508 | .section "The queue display" "SECID268" |
9b371988 | 33509 | .cindex "queue" "display in monitor" |
168e428f PH |
33510 | The bottom section of the monitor window contains a list of all messages that |
33511 | are on the queue, which includes those currently being received or delivered, | |
33512 | as well as those awaiting delivery. The size of this subwindow is controlled by | |
9b371988 PH |
33513 | parameters in the configuration file &_Local/eximon.conf_&, and the frequency |
33514 | at which it is updated is controlled by another parameter in the same file &-- | |
168e428f | 33515 | the default is 5 minutes, since queue scans can be quite expensive. However, |
9b371988 PH |
33516 | there is an &"Update"& action button just above the display which can be used |
33517 | to force an update of the queue display at any time. | |
168e428f PH |
33518 | |
33519 | When a host is down for some time, a lot of pending mail can build up for it, | |
33520 | and this can make it hard to deal with other messages on the queue. To help | |
9b371988 PH |
33521 | with this situation there is a button next to &"Update"& called &"Hide"&. If |
33522 | pressed, a dialogue box called &"Hide addresses ending with"& is put up. If you | |
33523 | type anything in here and press &"Return"&, the text is added to a chain of | |
33524 | such texts, and if every undelivered address in a message matches at least one | |
168e428f PH |
33525 | of the texts, the message is not displayed. |
33526 | ||
33527 | If there is an address that does not match any of the texts, all the addresses | |
33528 | are displayed as normal. The matching happens on the ends of addresses so, for | |
9b371988 PH |
33529 | example, &'cam.ac.uk'& specifies all addresses in Cambridge, while |
33530 | &'xxx@foo.com.example'& specifies just one specific address. When any hiding | |
33531 | has been set up, a button called &"Unhide"& is displayed. If pressed, it | |
33532 | cancels all hiding. Also, to ensure that hidden messages do not get forgotten, | |
33533 | a hide request is automatically cancelled after one hour. | |
168e428f PH |
33534 | |
33535 | While the dialogue box is displayed, you can't press any buttons or do anything | |
33536 | else to the monitor window. For this reason, if you want to cut text from the | |
33537 | queue display to use in the dialogue box, you have to do the cutting before | |
9b371988 | 33538 | pressing the &"Hide"& button. |
168e428f PH |
33539 | |
33540 | The queue display contains, for each unhidden queued message, the length of | |
33541 | time it has been on the queue, the size of the message, the message id, the | |
33542 | message sender, and the first undelivered recipient, all on one line. If it is | |
9b371988 | 33543 | a bounce message, the sender is shown as &"<>"&. If there is more than one |
168e428f PH |
33544 | recipient to which the message has not yet been delivered, subsequent ones are |
33545 | listed on additional lines, up to a maximum configured number, following which | |
33546 | an ellipsis is displayed. Recipients that have already received the message are | |
33547 | not shown. | |
33548 | ||
9b371988 | 33549 | .cindex "frozen messages" "display" |
168e428f PH |
33550 | If a message is frozen, an asterisk is displayed at the left-hand side. |
33551 | ||
33552 | The queue display has a vertical scroll bar, and can also be scrolled by means | |
33553 | of the arrow keys. Text can be cut from it using the mouse in the normal way. | |
33554 | The text searching facilities, as described above for the log window, are also | |
33555 | available, but the caret is always moved to the end of the text when the queue | |
33556 | display is updated. | |
33557 | ||
33558 | ||
33559 | ||
f89d2485 | 33560 | .section "The queue menu" "SECID269" |
9b371988 PH |
33561 | .cindex "queue" "menu in monitor" |
33562 | If the &%shift%& key is held down and the left button is clicked when the mouse | |
168e428f PH |
33563 | pointer is over the text for any message, an action menu pops up, and the first |
33564 | line of the queue display for the message is highlighted. This does not affect | |
33565 | any selected text. | |
33566 | ||
33567 | If you want to use some other event for popping up the menu, you can set the | |
9b371988 | 33568 | MENU_EVENT parameter in &_Local/eximon.conf_& to change the default, or |
168e428f PH |
33569 | set EXIMON_MENU_EVENT in the environment before starting the monitor. The |
33570 | value set in this parameter is a standard X event description. For example, to | |
9b371988 PH |
33571 | run eximon using &%ctrl%& rather than &%shift%& you could use |
33572 | .code | |
33573 | EXIMON_MENU_EVENT='Ctrl<Btn1Down>' eximon | |
33574 | .endd | |
168e428f PH |
33575 | The title of the menu is the message id, and it contains entries which act as |
33576 | follows: | |
33577 | ||
9b371988 PH |
33578 | .ilist |
33579 | &'message log'&: The contents of the message log for the message are displayed | |
33580 | in a new text window. | |
33581 | .next | |
33582 | &'headers'&: Information from the spool file that contains the envelope | |
168e428f | 33583 | information and headers is displayed in a new text window. See chapter |
9b371988 PH |
33584 | &<<CHAPspool>>& for a description of the format of spool files. |
33585 | .next | |
33586 | &'body'&: The contents of the spool file containing the body of the message are | |
168e428f PH |
33587 | displayed in a new text window. There is a default limit of 20,000 bytes to the |
33588 | amount of data displayed. This can be changed by setting the BODY_MAX | |
33589 | option at compile time, or the EXIMON_BODY_MAX option at run time. | |
9b371988 PH |
33590 | .next |
33591 | &'deliver message'&: A call to Exim is made using the &%-M%& option to request | |
168e428f | 33592 | delivery of the message. This causes an automatic thaw if the message is |
9b371988 | 33593 | frozen. The &%-v%& option is also set, and the output from Exim is displayed in |
168e428f PH |
33594 | a new text window. The delivery is run in a separate process, to avoid holding |
33595 | up the monitor while the delivery proceeds. | |
9b371988 PH |
33596 | .next |
33597 | &'freeze message'&: A call to Exim is made using the &%-Mf%& option to request | |
168e428f | 33598 | that the message be frozen. |
9b371988 PH |
33599 | .next |
33600 | .cindex "thawing messages" | |
33601 | .cindex "unfreezing messages" | |
33602 | .cindex "frozen messages" "thawing" | |
33603 | &'thaw message'&: A call to Exim is made using the &%-Mt%& option to request | |
33604 | that the message be thawed. | |
33605 | .next | |
33606 | .cindex "delivery" "forcing failure" | |
33607 | &'give up on msg'&: A call to Exim is made using the &%-Mg%& option to request | |
168e428f PH |
33608 | that Exim gives up trying to deliver the message. A bounce message is generated |
33609 | for any remaining undelivered addresses. | |
9b371988 PH |
33610 | .next |
33611 | &'remove message'&: A call to Exim is made using the &%-Mrm%& option to request | |
168e428f PH |
33612 | that the message be deleted from the system without generating a bounce |
33613 | message. | |
9b371988 PH |
33614 | .next |
33615 | &'add recipient'&: A dialog box is displayed into which a recipient address can | |
168e428f | 33616 | be typed. If the address is not qualified and the QUALIFY_DOMAIN parameter |
9b371988 | 33617 | is set in &_Local/eximon.conf_&, the address is qualified with that domain. |
168e428f | 33618 | Otherwise it must be entered as a fully qualified address. Pressing RETURN |
9b371988 | 33619 | causes a call to Exim to be made using the &%-Mar%& option to request that an |
168e428f PH |
33620 | additional recipient be added to the message, unless the entry box is empty, in |
33621 | which case no action is taken. | |
9b371988 PH |
33622 | .next |
33623 | &'mark delivered'&: A dialog box is displayed into which a recipient address | |
33624 | can be typed. If the address is not qualified and the QUALIFY_DOMAIN parameter | |
33625 | is set in &_Local/eximon.conf_&, the address is qualified with that domain. | |
168e428f | 33626 | Otherwise it must be entered as a fully qualified address. Pressing RETURN |
9b371988 | 33627 | causes a call to Exim to be made using the &%-Mmd%& option to mark the given |
168e428f PH |
33628 | recipient address as already delivered, unless the entry box is empty, in which |
33629 | case no action is taken. | |
9b371988 PH |
33630 | .next |
33631 | &'mark all delivered'&: A call to Exim is made using the &%-Mmad%& option to | |
33632 | mark all recipient addresses as already delivered. | |
33633 | .next | |
33634 | &'edit sender'&: A dialog box is displayed initialized with the current | |
33635 | sender's address. Pressing RETURN causes a call to Exim to be made using the | |
33636 | &%-Mes%& option to replace the sender address, unless the entry box is empty, | |
33637 | in which case no action is taken. If you want to set an empty sender (as in | |
33638 | bounce messages), you must specify it as &"<>"&. Otherwise, if the address is | |
33639 | not qualified and the QUALIFY_DOMAIN parameter is set in &_Local/eximon.conf_&, | |
33640 | the address is qualified with that domain. | |
33641 | .endlist | |
33642 | ||
33643 | When a delivery is forced, a window showing the &%-v%& output is displayed. In | |
168e428f PH |
33644 | other cases when a call to Exim is made, if there is any output from Exim (in |
33645 | particular, if the command fails) a window containing the command and the | |
33646 | output is displayed. Otherwise, the results of the action are normally apparent | |
33647 | from the log and queue displays. However, if you set ACTION_OUTPUT=yes in | |
9b371988 | 33648 | &_Local/eximon.conf_&, a window showing the Exim command is always opened, even |
168e428f PH |
33649 | if no output is generated. |
33650 | ||
33651 | The queue display is automatically updated for actions such as freezing and | |
33652 | thawing, unless ACTION_QUEUE_UPDATE=no has been set in | |
9b371988 PH |
33653 | &_Local/eximon.conf_&. In this case the &"Update"& button has to be used to |
33654 | force an update of the display after one of these actions. | |
168e428f PH |
33655 | |
33656 | In any text window that is displayed as result of a menu action, the normal | |
33657 | cut-and-paste facility is available, and searching can be carried out using ^R | |
33658 | and ^S, as described above for the log tail window. | |
4f578862 | 33659 | .ecindex IIDeximon |
168e428f PH |
33660 | |
33661 | ||
33662 | ||
33663 | ||
33664 | ||
9b371988 PH |
33665 | . //////////////////////////////////////////////////////////////////////////// |
33666 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 33667 | |
9b371988 | 33668 | .chapter "Security considerations" "CHAPsecurity" |
4f578862 | 33669 | .scindex IIDsecurcon "security" "discussion of" |
168e428f PH |
33670 | This chapter discusses a number of issues concerned with security, some of |
33671 | which are also covered in other parts of this manual. | |
33672 | ||
33673 | For reasons that this author does not understand, some people have promoted | |
9b371988 PH |
33674 | Exim as a &"particularly secure"& mailer. Perhaps it is because of the |
33675 | existence of this chapter in the documentation. However, the intent of the | |
33676 | chapter is simply to describe the way Exim works in relation to certain | |
33677 | security concerns, not to make any specific claims about the effectiveness of | |
33678 | its security as compared with other MTAs. | |
168e428f PH |
33679 | |
33680 | What follows is a description of the way Exim is supposed to be. Best efforts | |
33681 | have been made to try to ensure that the code agrees with the theory, but an | |
33682 | absence of bugs can never be guaranteed. Any that are reported will get fixed | |
33683 | as soon as possible. | |
33684 | ||
33685 | ||
f89d2485 | 33686 | .section "Building a more &""hardened""& Exim" "SECID286" |
9b371988 PH |
33687 | .cindex "security" "build-time features" |
33688 | There are a number of build-time options that can be set in &_Local/Makefile_& | |
33689 | to create Exim binaries that are &"harder"& to attack, in particular by a rogue | |
168e428f PH |
33690 | Exim administrator who does not have the root password, or by someone who has |
33691 | penetrated the Exim (but not the root) account. These options are as follows: | |
33692 | ||
9b371988 PH |
33693 | .ilist |
33694 | ALT_CONFIG_PREFIX can be set to a string that is required to match the | |
33695 | start of any file names used with the &%-C%& option. When it is set, these file | |
33696 | names are also not allowed to contain the sequence &"/../"&. (However, if the | |
33697 | value of the &%-C%& option is identical to the value of CONFIGURE_FILE in | |
33698 | &_Local/Makefile_&, Exim ignores &%-C%& and proceeds as usual.) There is no | |
33699 | default setting for &%ALT_CONFIG_PREFIX%&. | |
33700 | ||
168e428f PH |
33701 | If the permitted configuration files are confined to a directory to |
33702 | which only root has access, this guards against someone who has broken | |
33703 | into the Exim account from running a privileged Exim with an arbitrary | |
33704 | configuration file, and using it to break into other accounts. | |
9b371988 PH |
33705 | .next |
33706 | If ALT_CONFIG_ROOT_ONLY is defined, root privilege is retained for &%-C%& | |
33707 | and &%-D%& only if the caller of Exim is root. Without it, the Exim user may | |
33708 | also use &%-C%& and &%-D%& and retain privilege. Setting this option locks out | |
33709 | the possibility of testing a configuration using &%-C%& right through message | |
168e428f PH |
33710 | reception and delivery, even if the caller is root. The reception works, but by |
33711 | that time, Exim is running as the Exim user, so when it re-execs to regain | |
9b371988 | 33712 | privilege for the delivery, the use of &%-C%& causes privilege to be lost. |
168e428f PH |
33713 | However, root can test reception and delivery using two separate commands. |
33714 | ALT_CONFIG_ROOT_ONLY is not set by default. | |
9b371988 PH |
33715 | .next |
33716 | If DISABLE_D_OPTION is defined, the use of the &%-D%& command line option | |
168e428f | 33717 | is disabled. |
9b371988 PH |
33718 | .next |
33719 | FIXED_NEVER_USERS can be set to a colon-separated list of users that are | |
33720 | never to be used for any deliveries. This is like the &%never_users%& runtime | |
168e428f | 33721 | option, but it cannot be overridden; the runtime option adds additional users |
9b371988 | 33722 | to the list. The default setting is &"root"&; this prevents a non-root user who |
168e428f | 33723 | is permitted to modify the runtime file from using Exim as a way to get root. |
9b371988 | 33724 | .endlist |
168e428f PH |
33725 | |
33726 | ||
33727 | ||
33728 | ||
f89d2485 | 33729 | .section "Root privilege" "SECID270" |
9b371988 PH |
33730 | .cindex "setuid" |
33731 | .cindex "root privilege" | |
168e428f PH |
33732 | The Exim binary is normally setuid to root, which means that it gains root |
33733 | privilege (runs as root) when it starts execution. In some special cases (for | |
33734 | example, when the daemon is not in use and there are no local deliveries), it | |
33735 | may be possible to run Exim setuid to some user other than root. This is | |
33736 | discussed in the next section. However, in most installations, root privilege | |
33737 | is required for two things: | |
33738 | ||
9b371988 PH |
33739 | .ilist |
33740 | To set up a socket connected to the standard SMTP port (25) when initialising | |
33741 | the listening daemon. If Exim is run from &'inetd'&, this privileged action is | |
168e428f | 33742 | not required. |
9b371988 PH |
33743 | .next |
33744 | To be able to change uid and gid in order to read users' &_.forward_& files and | |
168e428f PH |
33745 | perform local deliveries as the receiving user or as specified in the |
33746 | configuration. | |
9b371988 | 33747 | .endlist |
168e428f PH |
33748 | |
33749 | It is not necessary to be root to do any of the other things Exim does, such as | |
33750 | receiving messages and delivering them externally over SMTP, and it is | |
33751 | obviously more secure if Exim does not run as root except when necessary. | |
33752 | For this reason, a user and group for Exim to use must be defined in | |
9b371988 PH |
33753 | &_Local/Makefile_&. These are known as &"the Exim user"& and &"the Exim |
33754 | group"&. Their values can be changed by the run time configuration, though this | |
33755 | is not recommended. Often a user called &'exim'& is used, but some sites use | |
33756 | &'mail'& or another user name altogether. | |
168e428f | 33757 | |
9b371988 | 33758 | Exim uses &[setuid()]& whenever it gives up root privilege. This is a permanent |
168e428f | 33759 | abdication; the process cannot regain root afterwards. Prior to release 4.00, |
9b371988 | 33760 | &[seteuid()]& was used in some circumstances, but this is no longer the case. |
168e428f PH |
33761 | |
33762 | After a new Exim process has interpreted its command line options, it changes | |
33763 | uid and gid in the following cases: | |
33764 | ||
9b371988 | 33765 | .ilist |
f89d2485 PH |
33766 | .oindex "&%-C%&" |
33767 | .oindex "&%-D%&" | |
9b371988 PH |
33768 | If the &%-C%& option is used to specify an alternate configuration file, or if |
33769 | the &%-D%& option is used to define macro values for the configuration, and the | |
168e428f PH |
33770 | calling process is not running as root or the Exim user, the uid and gid are |
33771 | changed to those of the calling process. | |
9b371988 PH |
33772 | However, if ALT_CONFIG_ROOT_ONLY is defined in &_Local/Makefile_&, only |
33773 | root callers may use &%-C%& and &%-D%& without losing privilege, and if | |
33774 | DISABLE_D_OPTION is set, the &%-D%& option may not be used at all. | |
33775 | .next | |
f89d2485 PH |
33776 | .oindex "&%-be%&" |
33777 | .oindex "&%-bf%&" | |
33778 | .oindex "&%-bF%&" | |
9b371988 PH |
33779 | If the expansion test option (&%-be%&) or one of the filter testing options |
33780 | (&%-bf%& or &%-bF%&) are used, the uid and gid are changed to those of the | |
168e428f | 33781 | calling process. |
9b371988 PH |
33782 | .next |
33783 | If the process is not a daemon process or a queue runner process or a delivery | |
33784 | process or a process for testing address routing (started with &%-bt%&), the | |
33785 | uid and gid are changed to the Exim user and group. This means that Exim always | |
168e428f PH |
33786 | runs under its own uid and gid when receiving messages. This also applies when |
33787 | testing address verification | |
f89d2485 PH |
33788 | .oindex "&%-bv%&" |
33789 | .oindex "&%-bh%&" | |
9b371988 | 33790 | (the &%-bv%& option) and testing incoming message policy controls (the &%-bh%& |
168e428f | 33791 | option). |
9b371988 PH |
33792 | .next |
33793 | For a daemon, queue runner, delivery, or address testing process, the uid | |
168e428f | 33794 | remains as root at this stage, but the gid is changed to the Exim group. |
9b371988 | 33795 | .endlist |
168e428f PH |
33796 | |
33797 | The processes that initially retain root privilege behave as follows: | |
33798 | ||
9b371988 PH |
33799 | .ilist |
33800 | A daemon process changes the gid to the Exim group and the uid to the Exim | |
33801 | user after setting up one or more listening sockets. The &[initgroups()]& | |
168e428f PH |
33802 | function is called, so that if the Exim user is in any additional groups, they |
33803 | will be used during message reception. | |
9b371988 PH |
33804 | .next |
33805 | A queue runner process retains root privilege throughout its execution. Its | |
168e428f | 33806 | job is to fork a controlled sequence of delivery processes. |
9b371988 PH |
33807 | .next |
33808 | A delivery process retains root privilege throughout most of its execution, | |
168e428f PH |
33809 | but any actual deliveries (that is, the transports themselves) are run in |
33810 | subprocesses which always change to a non-root uid and gid. For local | |
33811 | deliveries this is typically the uid and gid of the owner of the mailbox; for | |
33812 | remote deliveries, the Exim uid and gid are used. Once all the delivery | |
33813 | subprocesses have been run, a delivery process changes to the Exim uid and gid | |
33814 | while doing post-delivery tidying up such as updating the retry database and | |
33815 | generating bounce and warning messages. | |
9b371988 | 33816 | |
168e428f PH |
33817 | While the recipient addresses in a message are being routed, the delivery |
33818 | process runs as root. However, if a user's filter file has to be processed, | |
33819 | this is done in a subprocess that runs under the individual user's uid and | |
9b371988 PH |
33820 | gid. A system filter is run as root unless &%system_filter_user%& is set. |
33821 | .next | |
33822 | A process that is testing addresses (the &%-bt%& option) runs as root so that | |
168e428f | 33823 | the routing is done in the same environment as a message delivery. |
9b371988 | 33824 | .endlist |
168e428f PH |
33825 | |
33826 | ||
33827 | ||
33828 | ||
9b371988 | 33829 | .section "Running Exim without privilege" "SECTrunexiwitpri" |
f89d2485 | 33830 | .cindex "privilege, running without" |
9b371988 PH |
33831 | .cindex "unprivileged running" |
33832 | .cindex "root privilege" "running without" | |
168e428f PH |
33833 | Some installations like to run Exim in an unprivileged state for more of its |
33834 | operation, for added security. Support for this mode of operation is provided | |
9b371988 | 33835 | by the global option &%deliver_drop_privilege%&. When this is set, the uid and |
168e428f PH |
33836 | gid are changed to the Exim user and group at the start of a delivery process |
33837 | (and also queue runner and address testing processes). This means that address | |
33838 | routing is no longer run as root, and the deliveries themselves cannot change | |
33839 | to any other uid. | |
33840 | ||
3cb1b51e PH |
33841 | .cindex SIGHUP |
33842 | .cindex "daemon" "restarting" | |
9b371988 | 33843 | Leaving the binary setuid to root, but setting &%deliver_drop_privilege%& means |
168e428f PH |
33844 | that the daemon can still be started in the usual way, and it can respond |
33845 | correctly to SIGHUP because the re-invocation regains root privilege. | |
33846 | ||
33847 | An alternative approach is to make Exim setuid to the Exim user and also setgid | |
3cb1b51e PH |
33848 | to the Exim group. If you do this, the daemon must be started from a root |
33849 | process. (Calling Exim from a root process makes it behave in the way it does | |
33850 | when it is setuid root.) However, the daemon cannot restart itself after a | |
33851 | SIGHUP signal because it cannot regain privilege. | |
168e428f | 33852 | |
9b371988 | 33853 | It is still useful to set &%deliver_drop_privilege%& in this case, because it |
168e428f PH |
33854 | stops Exim from trying to re-invoke itself to do a delivery after a message has |
33855 | been received. Such a re-invocation is a waste of resources because it has no | |
33856 | effect. | |
33857 | ||
9b371988 PH |
33858 | If restarting the daemon is not an issue (for example, if &%mua_wrapper%& is |
33859 | set, or &'inetd'& is being used instead of a daemon), having the binary setuid | |
33860 | to the Exim user seems a clean approach, but there is one complication: | |
168e428f PH |
33861 | |
33862 | In this style of operation, Exim is running with the real uid and gid set to | |
33863 | those of the calling process, and the effective uid/gid set to Exim's values. | |
33864 | Ideally, any association with the calling process' uid/gid should be dropped, | |
33865 | that is, the real uid/gid should be reset to the effective values so as to | |
33866 | discard any privileges that the caller may have. While some operating systems | |
33867 | have a function that permits this action for a non-root effective uid, quite a | |
33868 | number of them do not. Because of this lack of standardization, Exim does not | |
33869 | address this problem at this time. | |
33870 | ||
9b371988 PH |
33871 | For this reason, the recommended approach for &"mostly unprivileged"& running |
33872 | is to keep the Exim binary setuid to root, and to set | |
33873 | &%deliver_drop_privilege%&. This also has the advantage of allowing a daemon to | |
33874 | be used in the most straightforward way. | |
168e428f PH |
33875 | |
33876 | If you configure Exim not to run delivery processes as root, there are a | |
33877 | number of restrictions on what you can do: | |
33878 | ||
9b371988 PH |
33879 | .ilist |
33880 | You can deliver only as the Exim user/group. You should explicitly use the | |
33881 | &%user%& and &%group%& options to override routers or local transports that | |
168e428f PH |
33882 | normally deliver as the recipient. This makes sure that configurations that |
33883 | work in this mode function the same way in normal mode. Any implicit or | |
33884 | explicit specification of another user causes an error. | |
9b371988 PH |
33885 | .next |
33886 | Use of &_.forward_& files is severely restricted, such that it is usually | |
168e428f | 33887 | not worthwhile to include them in the configuration. |
9b371988 PH |
33888 | .next |
33889 | Users who wish to use &_.forward_& would have to make their home directory and | |
168e428f PH |
33890 | the file itself accessible to the Exim user. Pipe and append-to-file entries, |
33891 | and their equivalents in Exim filters, cannot be used. While they could be | |
33892 | enabled in the Exim user's name, that would be insecure and not very useful. | |
9b371988 PH |
33893 | .next |
33894 | Unless the local user mailboxes are all owned by the Exim user (possible in | |
168e428f PH |
33895 | some POP3 or IMAP-only environments): |
33896 | ||
9b371988 | 33897 | .olist |
f89d2485 | 33898 | They must be owned by the Exim group and be writeable by that group. This |
9b371988 | 33899 | implies you must set &%mode%& in the appendfile configuration, as well as the |
168e428f | 33900 | mode of the mailbox files themselves. |
9b371988 PH |
33901 | .next |
33902 | You must set &%no_check_owner%&, since most or all of the files will not be | |
168e428f | 33903 | owned by the Exim user. |
9b371988 PH |
33904 | .next |
33905 | You must set &%file_must_exist%&, because Exim cannot set the owner correctly | |
168e428f PH |
33906 | on a newly created mailbox when unprivileged. This also implies that new |
33907 | mailboxes need to be created manually. | |
9b371988 PH |
33908 | .endlist olist |
33909 | .endlist ilist | |
33910 | ||
168e428f PH |
33911 | |
33912 | These restrictions severely restrict what can be done in local deliveries. | |
33913 | However, there are no restrictions on remote deliveries. If you are running a | |
9b371988 | 33914 | gateway host that does no local deliveries, setting &%deliver_drop_privilege%& |
168e428f PH |
33915 | gives more security at essentially no cost. |
33916 | ||
9b371988 PH |
33917 | If you are using the &%mua_wrapper%& facility (see chapter |
33918 | &<<CHAPnonqueueing>>&), &%deliver_drop_privilege%& is forced to be true. | |
168e428f PH |
33919 | |
33920 | ||
33921 | ||
33922 | ||
f89d2485 | 33923 | .section "Delivering to local files" "SECID271" |
9b371988 PH |
33924 | Full details of the checks applied by &(appendfile)& before it writes to a file |
33925 | are given in chapter &<<CHAPappendfile>>&. | |
168e428f PH |
33926 | |
33927 | ||
33928 | ||
f89d2485 | 33929 | .section "IPv4 source routing" "SECID272" |
9b371988 PH |
33930 | .cindex "source routing" "in IP packets" |
33931 | .cindex "IP source routing" | |
168e428f PH |
33932 | Many operating systems suppress IP source-routed packets in the kernel, but |
33933 | some cannot be made to do this, so Exim does its own check. It logs incoming | |
33934 | IPv4 source-routed TCP calls, and then drops them. Things are all different in | |
33935 | IPv6. No special checking is currently done. | |
33936 | ||
33937 | ||
33938 | ||
f89d2485 | 33939 | .section "The VRFY, EXPN, and ETRN commands in SMTP" "SECID273" |
168e428f PH |
33940 | Support for these SMTP commands is disabled by default. If required, they can |
33941 | be enabled by defining suitable ACLs. | |
33942 | ||
33943 | ||
33944 | ||
33945 | ||
f89d2485 PH |
33946 | .section "Privileged users" "SECID274" |
33947 | .cindex "trusted users" | |
9b371988 PH |
33948 | .cindex "admin user" |
33949 | .cindex "privileged user" | |
33950 | .cindex "user" "trusted" | |
33951 | .cindex "user" "admin" | |
f89d2485 | 33952 | Exim recognizes two sets of users with special privileges. Trusted users are |
168e428f PH |
33953 | able to submit new messages to Exim locally, but supply their own sender |
33954 | addresses and information about a sending host. For other users submitting | |
33955 | local messages, Exim sets up the sender address from the uid, and doesn't | |
33956 | permit a remote host to be specified. | |
33957 | ||
f89d2485 | 33958 | .oindex "&%-f%&" |
9b371988 PH |
33959 | However, an untrusted user is permitted to use the &%-f%& command line option |
33960 | in the special form &%-f <>%& to indicate that a delivery failure for the | |
33961 | message should not cause an error report. This affects the message's envelope, | |
33962 | but it does not affect the &'Sender:'& header. Untrusted users may also be | |
33963 | permitted to use specific forms of address with the &%-f%& option by setting | |
33964 | the &%untrusted_set_sender%& option. | |
168e428f PH |
33965 | |
33966 | Trusted users are used to run processes that receive mail messages from some | |
33967 | other mail domain and pass them on to Exim for delivery either locally, or over | |
33968 | the Internet. Exim trusts a caller that is running as root, as the Exim user, | |
9b371988 PH |
33969 | as any user listed in the &%trusted_users%& configuration option, or under any |
33970 | group listed in the &%trusted_groups%& option. | |
168e428f PH |
33971 | |
33972 | Admin users are permitted to do things to the messages on Exim's queue. They | |
33973 | can freeze or thaw messages, cause them to be returned to their senders, remove | |
33974 | them entirely, or modify them in various ways. In addition, admin users can run | |
33975 | the Exim monitor and see all the information it is capable of providing, which | |
33976 | includes the contents of files on the spool. | |
33977 | ||
f89d2485 PH |
33978 | .oindex "&%-M%&" |
33979 | .oindex "&%-q%&" | |
9b371988 | 33980 | By default, the use of the &%-M%& and &%-q%& options to cause Exim to attempt |
168e428f | 33981 | delivery of messages on its queue is restricted to admin users. This |
9b371988 PH |
33982 | restriction can be relaxed by setting the &%no_prod_requires_admin%& option. |
33983 | Similarly, the use of &%-bp%& (and its variants) to list the contents of the | |
168e428f | 33984 | queue is also restricted to admin users. This restriction can be relaxed by |
9b371988 | 33985 | setting &%no_queue_list_requires_admin%&. |
168e428f | 33986 | |
f89d2485 | 33987 | Exim recognizes an admin user if the calling process is running as root or as |
168e428f PH |
33988 | the Exim user or if any of the groups associated with the calling process is |
33989 | the Exim group. It is not necessary actually to be running under the Exim | |
33990 | group. However, if admin users who are not root or the Exim user are to access | |
33991 | the contents of files on the spool via the Exim monitor (which runs | |
33992 | unprivileged), Exim must be built to allow group read access to its spool | |
33993 | files. | |
33994 | ||
33995 | ||
33996 | ||
f89d2485 | 33997 | .section "Spool files" "SECID275" |
9b371988 | 33998 | .cindex "spool directory" "files" |
168e428f PH |
33999 | Exim's spool directory and everything it contains is owned by the Exim user and |
34000 | set to the Exim group. The mode for spool files is defined in the | |
9b371988 | 34001 | &_Local/Makefile_& configuration file, and defaults to 0640. This means that |
168e428f PH |
34002 | any user who is a member of the Exim group can access these files. |
34003 | ||
34004 | ||
34005 | ||
f89d2485 | 34006 | .section "Use of argv[0]" "SECID276" |
9b371988 | 34007 | Exim examines the last component of &%argv[0]%&, and if it matches one of a set |
168e428f | 34008 | of specific strings, Exim assumes certain options. For example, calling Exim |
9b371988 PH |
34009 | with the last component of &%argv[0]%& set to &"rsmtp"& is exactly equivalent |
34010 | to calling it with the option &%-bS%&. There are no security implications in | |
34011 | this. | |
168e428f PH |
34012 | |
34013 | ||
34014 | ||
f89d2485 | 34015 | .section "Use of %f formatting" "SECID277" |
9b371988 | 34016 | The only use made of &"%f"& by Exim is in formatting load average values. These |
168e428f PH |
34017 | are actually stored in integer variables as 1000 times the load average. |
34018 | Consequently, their range is limited and so therefore is the length of the | |
34019 | converted output. | |
34020 | ||
34021 | ||
34022 | ||
f89d2485 | 34023 | .section "Embedded Exim path" "SECID278" |
168e428f PH |
34024 | Exim uses its own path name, which is embedded in the code, only when it needs |
34025 | to re-exec in order to regain root privilege. Therefore, it is not root when it | |
34026 | does so. If some bug allowed the path to get overwritten, it would lead to an | |
34027 | arbitrary program's being run as exim, not as root. | |
34028 | ||
34029 | ||
34030 | ||
f89d2485 | 34031 | .section "Use of sprintf()" "SECID279" |
9b371988 PH |
34032 | .cindex "&[sprintf()]&" |
34033 | A large number of occurrences of &"sprintf"& in the code are actually calls to | |
34034 | &'string_sprintf()'&, a function that returns the result in malloc'd store. | |
168e428f PH |
34035 | The intermediate formatting is done into a large fixed buffer by a function |
34036 | that runs through the format string itself, and checks the length of each | |
34037 | conversion before performing it, thus preventing buffer overruns. | |
34038 | ||
9b371988 | 34039 | The remaining uses of &[sprintf()]& happen in controlled circumstances where |
168e428f PH |
34040 | the output buffer is known to be sufficiently long to contain the converted |
34041 | string. | |
34042 | ||
34043 | ||
34044 | ||
f89d2485 | 34045 | .section "Use of debug_printf() and log_write()" "SECID280" |
168e428f | 34046 | Arbitrary strings are passed to both these functions, but they do their |
9b371988 | 34047 | formatting by calling the function &'string_vformat()'&, which runs through |
168e428f PH |
34048 | the format string itself, and checks the length of each conversion. |
34049 | ||
34050 | ||
34051 | ||
f89d2485 | 34052 | .section "Use of strcat() and strcpy()" "SECID281" |
168e428f PH |
34053 | These are used only in cases where the output buffer is known to be large |
34054 | enough to hold the result. | |
4f578862 | 34055 | .ecindex IIDsecurcon |
168e428f PH |
34056 | |
34057 | ||
34058 | ||
34059 | ||
9b371988 PH |
34060 | . //////////////////////////////////////////////////////////////////////////// |
34061 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 34062 | |
9b371988 | 34063 | .chapter "Format of spool files" "CHAPspool" |
4f578862 PH |
34064 | .scindex IIDforspo1 "format" "spool files" |
34065 | .scindex IIDforspo2 "spool directory" "format of files" | |
34066 | .scindex IIDforspo3 "spool files" "format of" | |
9b371988 | 34067 | .cindex "spool files" "editing" |
168e428f PH |
34068 | A message on Exim's queue consists of two files, whose names are the message id |
34069 | followed by -D and -H, respectively. The data portion of the message is kept in | |
34070 | the -D file on its own. The message's envelope, status, and headers are all | |
34071 | kept in the -H file, whose format is described in this chapter. Each of these | |
34072 | two files contains the final component of its own name as its first line. This | |
34073 | is insurance against disk crashes where the directory is lost but the files | |
34074 | themselves are recoverable. | |
34075 | ||
34076 | Some people are tempted into editing -D files in order to modify messages. You | |
34077 | need to be extremely careful if you do this; it is not recommended and you are | |
34078 | on your own if you do it. Here are some of the pitfalls: | |
34079 | ||
9b371988 | 34080 | .ilist |
9b371988 | 34081 | You must ensure that Exim does not try to deliver the message while you are |
068aaea8 | 34082 | fiddling with it. The safest way is to take out a write lock on the -D file, |
9b371988 | 34083 | which is what Exim itself does, using &[fcntl()]&. If you update the file in |
068aaea8 PH |
34084 | place, the lock will be retained. If you write a new file and rename it, the |
34085 | lock will be lost at the instant of rename. | |
9b371988 | 34086 | .next |
f89d2485 | 34087 | .vindex "&$body_linecount$&" |
068aaea8 | 34088 | If you change the number of lines in the file, the value of |
9b371988 | 34089 | &$body_linecount$&, which is stored in the -H file, will be incorrect. At |
068aaea8 PH |
34090 | present, this value is not used by Exim, but there is no guarantee that this |
34091 | will always be the case. | |
9b371988 PH |
34092 | .next |
34093 | If the message is in MIME format, you must take care not to break it. | |
34094 | .next | |
34095 | If the message is cryptographically signed, any change will invalidate the | |
168e428f | 34096 | signature. |
9b371988 | 34097 | .endlist |
f89d2485 | 34098 | All in all, modifying -D files is fraught with danger. |
168e428f | 34099 | |
9b371988 PH |
34100 | Files whose names end with -J may also be seen in the &_input_& directory (or |
34101 | its subdirectories when &%split_spool_directory%& is set). These are journal | |
168e428f | 34102 | files, used to record addresses to which the message has been delivered during |
f89d2485 PH |
34103 | the course of a delivery attempt. If there are still undelivered recipients at |
34104 | the end, the -H file is updated, and the -J file is deleted. If, however, there | |
34105 | is some kind of crash (for example, a power outage) before this happens, the -J | |
34106 | file remains in existence. When Exim next processes the message, it notices the | |
34107 | -J file and uses it to update the -H file before starting the next delivery | |
34108 | attempt. | |
168e428f | 34109 | |
f89d2485 | 34110 | .section "Format of the -H file" "SECID282" |
9b371988 PH |
34111 | .cindex "uid (user id)" "in spool file" |
34112 | .cindex "gid (group id)" "in spool file" | |
168e428f PH |
34113 | The second line of the -H file contains the login name for the uid of the |
34114 | process that called Exim to read the message, followed by the numerical uid and | |
34115 | gid. For a locally generated message, this is normally the user who sent the | |
595028e4 | 34116 | message. For a message received over TCP/IP via the daemon, it is |
f89d2485 | 34117 | normally the Exim user. |
168e428f PH |
34118 | |
34119 | The third line of the file contains the address of the message's sender as | |
34120 | transmitted in the envelope, contained in angle brackets. The sender address is | |
34121 | empty for bounce messages. For incoming SMTP mail, the sender address is given | |
34122 | in the MAIL command. For locally generated mail, the sender address is | |
34123 | created by Exim from the login name of the current user and the configured | |
9b371988 PH |
34124 | &%qualify_domain%&. However, this can be overridden by the &%-f%& option or a |
34125 | leading &"From&~"& line if the caller is trusted, or if the supplied address is | |
34126 | &"<>"& or an address that matches &%untrusted_set_senders%&. | |
168e428f PH |
34127 | |
34128 | The fourth line contains two numbers. The first is the time that the message | |
9b371988 | 34129 | was received, in the conventional Unix form &-- the number of seconds since the |
168e428f PH |
34130 | start of the epoch. The second number is a count of the number of messages |
34131 | warning of delayed delivery that have been sent to the sender. | |
34132 | ||
34133 | There follow a number of lines starting with a hyphen. These can appear in any | |
34134 | order, and are omitted when not relevant: | |
34135 | ||
9b371988 | 34136 | .vlist |
3cb1b51e | 34137 | .vitem "&%-acl%&&~<&'number'&>&~<&'length'&>" |
4f578862 PH |
34138 | This item is obsolete, and is not generated from Exim release 4.61 onwards; |
34139 | &%-aclc%& and &%-aclm%& are used instead. However, &%-acl%& is still | |
34140 | recognized, to provide backward compatibility. In the old format, a line of | |
34141 | this form is present for every ACL variable that is not empty. The number | |
34142 | identifies the variable; the &%acl_c%&&*x*& variables are numbered 0&--9 and | |
34143 | the &%acl_m%&&*x*& variables are numbered 10&--19. The length is the length of | |
34144 | the data string for the variable. The string itself starts at the beginning of | |
34145 | the next line, and is followed by a newline character. It may contain internal | |
34146 | newlines. | |
34147 | ||
3cb1b51e PH |
34148 | .vitem "&%-aclc%&&~<&'rest-of-name'&>&~<&'length'&>" |
34149 | A line of this form is present for every ACL connection variable that is | |
34150 | defined. Note that there is a space between &%-aclc%& and the rest of the name. | |
34151 | The length is the length of the data string for the variable. The string itself | |
34152 | starts at the beginning of the next line, and is followed by a newline | |
34153 | character. It may contain internal newlines. | |
34154 | ||
34155 | .vitem "&%-aclm%&&~<&'rest-of-name'&>&~<&'length'&>" | |
34156 | A line of this form is present for every ACL message variable that is defined. | |
34157 | Note that there is a space between &%-aclm%& and the rest of the name. The | |
34158 | length is the length of the data string for the variable. The string itself | |
34159 | starts at the beginning of the next line, and is followed by a newline | |
34160 | character. It may contain internal newlines. | |
168e428f | 34161 | |
3cb1b51e | 34162 | .vitem "&%-active_hostname%&&~<&'hostname'&>" |
168e428f | 34163 | This is present if, when the message was received over SMTP, the value of |
9b371988 | 34164 | &$smtp_active_hostname$& was different to the value of &$primary_hostname$&. |
168e428f | 34165 | |
9b371988 | 34166 | .vitem &%-allow_unqualified_recipient%& |
168e428f PH |
34167 | This is present if unqualified recipient addresses are permitted in header |
34168 | lines (to stop such addresses from being qualified if rewriting occurs at | |
9b371988 PH |
34169 | transport time). Local messages that were input using &%-bnq%& and remote |
34170 | messages from hosts that match &%recipient_unqualified_hosts%& set this flag. | |
168e428f | 34171 | |
9b371988 | 34172 | .vitem &%-allow_unqualified_sender%& |
168e428f PH |
34173 | This is present if unqualified sender addresses are permitted in header lines |
34174 | (to stop such addresses from being qualified if rewriting occurs at transport | |
9b371988 PH |
34175 | time). Local messages that were input using &%-bnq%& and remote messages from |
34176 | hosts that match &%sender_unqualified_hosts%& set this flag. | |
168e428f | 34177 | |
3cb1b51e | 34178 | .vitem "&%-auth_id%&&~<&'text'&>" |
168e428f | 34179 | The id information for a message received on an authenticated SMTP connection |
9b371988 | 34180 | &-- the value of the &$authenticated_id$& variable. |
168e428f | 34181 | |
3cb1b51e | 34182 | .vitem "&%-auth_sender%&&~<&'address'&>" |
9b371988 PH |
34183 | The address of an authenticated sender &-- the value of the |
34184 | &$authenticated_sender$& variable. | |
168e428f | 34185 | |
3cb1b51e | 34186 | .vitem "&%-body_linecount%&&~<&'number'&>" |
168e428f PH |
34187 | This records the number of lines in the body of the message, and is always |
34188 | present. | |
34189 | ||
3cb1b51e | 34190 | .vitem "&%-body_zerocount%&&~<&'number'&>" |
168e428f PH |
34191 | This records the number of binary zero bytes in the body of the message, and is |
34192 | present if the number is greater than zero. | |
34193 | ||
9b371988 | 34194 | .vitem &%-deliver_firsttime%& |
168e428f PH |
34195 | This is written when a new message is first added to the spool. When the spool |
34196 | file is updated after a deferral, it is omitted. | |
34197 | ||
3cb1b51e | 34198 | .vitem "&%-frozen%&&~<&'time'&>" |
9b371988 PH |
34199 | .cindex "frozen messages" "spool data" |
34200 | The message is frozen, and the freezing happened at <&'time'&>. | |
168e428f | 34201 | |
3cb1b51e | 34202 | .vitem "&%-helo_name%&&~<&'text'&>" |
168e428f PH |
34203 | This records the host name as specified by a remote host in a HELO or EHLO |
34204 | command. | |
34205 | ||
3cb1b51e | 34206 | .vitem "&%-host_address%&&~<&'address'&>.<&'port'&>" |
168e428f PH |
34207 | This records the IP address of the host from which the message was received and |
34208 | the remote port number that was used. It is omitted for locally generated | |
34209 | messages. | |
34210 | ||
3cb1b51e | 34211 | .vitem "&%-host_auth%&&~<&'text'&>" |
168e428f | 34212 | If the message was received on an authenticated SMTP connection, this records |
9b371988 PH |
34213 | the name of the authenticator &-- the value of the |
34214 | &$sender_host_authenticated$& variable. | |
168e428f | 34215 | |
9b371988 | 34216 | .vitem &%-host_lookup_failed%& |
168e428f | 34217 | This is present if an attempt to look up the sending host's name from its IP |
9b371988 | 34218 | address failed. It corresponds to the &$host_lookup_failed$& variable. |
168e428f | 34219 | |
3cb1b51e | 34220 | .vitem "&%-host_name%&&~<&'text'&>" |
9b371988 PH |
34221 | .cindex "reverse DNS lookup" |
34222 | .cindex "DNS" "reverse lookup" | |
168e428f PH |
34223 | This records the name of the remote host from which the message was received, |
34224 | if the host name was looked up from the IP address when the message was being | |
34225 | received. It is not present if no reverse lookup was done. | |
34226 | ||
3cb1b51e | 34227 | .vitem "&%-ident%&&~<&'text'&>" |
168e428f | 34228 | For locally submitted messages, this records the login of the originating user, |
9b371988 PH |
34229 | unless it was a trusted user and the &%-oMt%& option was used to specify an |
34230 | ident value. For messages received over TCP/IP, this records the ident string | |
168e428f PH |
34231 | supplied by the remote host, if any. |
34232 | ||
3cb1b51e | 34233 | .vitem "&%-interface_address%&&~<&'address'&>.<&'port'&>" |
168e428f PH |
34234 | This records the IP address of the local interface and the port number through |
34235 | which a message was received from a remote host. It is omitted for locally | |
34236 | generated messages. | |
34237 | ||
9b371988 | 34238 | .vitem &%-local%& |
168e428f PH |
34239 | The message is from a local sender. |
34240 | ||
9b371988 | 34241 | .vitem &%-localerror%& |
168e428f PH |
34242 | The message is a locally-generated bounce message. |
34243 | ||
3cb1b51e | 34244 | .vitem "&%-local_scan%&&~<&'string'&>" |
9b371988 PH |
34245 | This records the data string that was returned by the &[local_scan()]& function |
34246 | when the message was received &-- the value of the &$local_scan_data$& | |
34247 | variable. It is omitted if no data was returned. | |
168e428f | 34248 | |
9b371988 | 34249 | .vitem &%-manual_thaw%& |
168e428f PH |
34250 | The message was frozen but has been thawed manually, that is, by an explicit |
34251 | Exim command rather than via the auto-thaw process. | |
34252 | ||
9b371988 PH |
34253 | .vitem &%-N%& |
34254 | A testing delivery process was started using the &%-N%& option to suppress any | |
168e428f | 34255 | actual deliveries, but delivery was deferred. At any further delivery attempts, |
9b371988 | 34256 | &%-N%& is assumed. |
168e428f | 34257 | |
9b371988 PH |
34258 | .vitem &%-received_protocol%& |
34259 | This records the value of the &$received_protocol$& variable, which contains | |
34260 | the name of the protocol by which the message was received. | |
168e428f | 34261 | |
9b371988 | 34262 | .vitem &%-sender_set_untrusted%& |
168e428f PH |
34263 | The envelope sender of this message was set by an untrusted local caller (used |
34264 | to ensure that the caller is displayed in queue listings). | |
34265 | ||
3cb1b51e | 34266 | .vitem "&%-spam_score_int%&&~<&'number'&>" |
168e428f | 34267 | If a message was scanned by SpamAssassin, this is present. It records the value |
9b371988 | 34268 | of &$spam_score_int$&. |
168e428f | 34269 | |
9b371988 | 34270 | .vitem &%-tls_certificate_verified%& |
168e428f PH |
34271 | A TLS certificate was received from the client that sent this message, and the |
34272 | certificate was verified by the server. | |
34273 | ||
3cb1b51e | 34274 | .vitem "&%-tls_cipher%&&~<&'cipher name'&>" |
168e428f PH |
34275 | When the message was received over an encrypted connection, this records the |
34276 | name of the cipher suite that was used. | |
34277 | ||
3cb1b51e | 34278 | .vitem "&%-tls_peerdn%&&~<&'peer DN'&>" |
168e428f PH |
34279 | When the message was received over an encrypted connection, and a certificate |
34280 | was received from the client, this records the Distinguished Name from that | |
34281 | certificate. | |
9b371988 | 34282 | .endlist |
168e428f PH |
34283 | |
34284 | Following the options there is a list of those addresses to which the message | |
34285 | is not to be delivered. This set of addresses is initialized from the command | |
9b371988 | 34286 | line when the &%-t%& option is used and &%extract_addresses_remove_arguments%& |
168e428f PH |
34287 | is set; otherwise it starts out empty. Whenever a successful delivery is made, |
34288 | the address is added to this set. The addresses are kept internally as a | |
34289 | balanced binary tree, and it is a representation of that tree which is written | |
34290 | to the spool file. If an address is expanded via an alias or forward file, the | |
34291 | original address is added to the tree when deliveries to all its child | |
34292 | addresses are complete. | |
34293 | ||
34294 | If the tree is empty, there is a single line in the spool file containing just | |
9b371988 | 34295 | the text &"XX"&. Otherwise, each line consists of two letters, which are either |
168e428f PH |
34296 | Y or N, followed by an address. The address is the value for the node of the |
34297 | tree, and the letters indicate whether the node has a left branch and/or a | |
34298 | right branch attached to it, respectively. If branches exist, they immediately | |
34299 | follow. Here is an example of a three-node tree: | |
9b371988 PH |
34300 | .code |
34301 | YY darcy@austen.fict.example | |
34302 | NN alice@wonderland.fict.example | |
34303 | NN editor@thesaurus.ref.example | |
34304 | .endd | |
168e428f PH |
34305 | After the non-recipients tree, there is a list of the message's recipients. |
34306 | This is a simple list, preceded by a count. It includes all the original | |
34307 | recipients of the message, including those to whom the message has already been | |
34308 | delivered. In the simplest case, the list contains one address per line. For | |
34309 | example: | |
9b371988 PH |
34310 | .code |
34311 | 4 | |
34312 | editor@thesaurus.ref.example | |
34313 | darcy@austen.fict.example | |
34314 | rdo@foundation | |
34315 | alice@wonderland.fict.example | |
34316 | .endd | |
168e428f | 34317 | However, when a child address has been added to the top-level addresses as a |
9b371988 PH |
34318 | result of the use of the &%one_time%& option on a &(redirect)& router, each |
34319 | line is of the following form: | |
34320 | .display | |
34321 | <&'top-level address'&> <&'errors_to address'&> &&& | |
34322 | <&'length'&>,<&'parent number'&>#<&'flag bits'&> | |
34323 | .endd | |
168e428f PH |
34324 | The 01 flag bit indicates the presence of the three other fields that follow |
34325 | the top-level address. Other bits may be used in future to support additional | |
9b371988 PH |
34326 | fields. The <&'parent number'&> is the offset in the recipients list of the |
34327 | original parent of the &"one time"& address. The first two fields are the | |
168e428f PH |
34328 | envelope sender that is associated with this address and its length. If the |
34329 | length is zero, there is no special envelope sender (there are then two space | |
9b371988 PH |
34330 | characters in the line). A non-empty field can arise from a &(redirect)& router |
34331 | that has an &%errors_to%& setting. | |
168e428f PH |
34332 | |
34333 | ||
34334 | A blank line separates the envelope and status information from the headers | |
34335 | which follow. A header may occupy several lines of the file, and to save effort | |
34336 | when reading it in, each header is preceded by a number and an identifying | |
34337 | character. The number is the number of characters in the header, including any | |
34338 | embedded newlines and the terminating newline. The character is one of the | |
34339 | following: | |
34340 | ||
9b371988 PH |
34341 | .table2 50pt |
34342 | .row <&'blank'&> "header in which Exim has no special interest" | |
34343 | .row &`B`& "&'Bcc:'& header" | |
34344 | .row &`C`& "&'Cc:'& header" | |
34345 | .row &`F`& "&'From:'& header" | |
34346 | .row &`I`& "&'Message-id:'& header" | |
34347 | .row &`P`& "&'Received:'& header &-- P for &""postmark""&" | |
34348 | .row &`R`& "&'Reply-To:'& header" | |
34349 | .row &`S`& "&'Sender:'& header" | |
34350 | .row &`T`& "&'To:'& header" | |
34351 | .row &`*`& "replaced or deleted header" | |
34352 | .endtable | |
168e428f PH |
34353 | |
34354 | Deleted or replaced (rewritten) headers remain in the spool file for debugging | |
34355 | purposes. They are not transmitted when the message is delivered. Here is a | |
34356 | typical set of headers: | |
9b371988 PH |
34357 | .code |
34358 | 111P Received: by hobbit.fict.example with local (Exim 4.00) | |
34359 | id 14y9EI-00026G-00; Fri, 11 May 2001 10:28:59 +0100 | |
34360 | 049 Message-Id: <E14y9EI-00026G-00@hobbit.fict.example> | |
34361 | 038* X-rewrote-sender: bb@hobbit.fict.example | |
34362 | 042* From: Bilbo Baggins <bb@hobbit.fict.example> | |
34363 | 049F From: Bilbo Baggins <B.Baggins@hobbit.fict.example> | |
34364 | 099* To: alice@wonderland.fict.example, rdo@foundation, | |
34365 | darcy@austen.fict.example, editor@thesaurus.ref.example | |
34366 | 104T To: alice@wonderland.fict.example, rdo@foundation.example, | |
34367 | darcy@austen.fict.example, editor@thesaurus.ref.example | |
34368 | 038 Date: Fri, 11 May 2001 10:28:59 +0100 | |
34369 | .endd | |
34370 | The asterisked headers indicate that the envelope sender, &'From:'& header, and | |
34371 | &'To:'& header have been rewritten, the last one because routing expanded the | |
34372 | unqualified domain &'foundation'&. | |
4f578862 PH |
34373 | .ecindex IIDforspo1 |
34374 | .ecindex IIDforspo2 | |
34375 | .ecindex IIDforspo3 | |
9b371988 | 34376 | |
0b23848a TK |
34377 | . //////////////////////////////////////////////////////////////////////////// |
34378 | . //////////////////////////////////////////////////////////////////////////// | |
34379 | ||
34380 | .chapter "Support for DKIM (DomainKeys Identified Mail) - RFC4871" "CHID12" &&& | |
34381 | "DKIM Support" | |
34382 | .cindex "DKIM" | |
34383 | ||
34384 | Since version 4.70, DKIM support is compiled into Exim by default. It can be | |
34385 | disabled by setting DISABLE_DKIM=yes in Local/Makefile. | |
34386 | ||
34387 | Exim's DKIM implementation allows to | |
34388 | .olist | |
34389 | Sign outgoing messages: This function is implemented in the SMTP transport. | |
34390 | It can co-exist with all other Exim features, including transport filters. | |
34391 | .next | |
34392 | Verify signatures in incoming messages: This is implemented by an additional | |
34393 | ACL (acl_smtp_dkim), which can be called several times per message, with | |
34394 | different signature context. | |
34395 | .endlist | |
34396 | ||
214bab57 TK |
34397 | In typical Exim style, the verification implementation does not include any |
34398 | default "policy". Instead it enables you to build your own policy using | |
34399 | Exim's standard controls. | |
34400 | ||
34401 | Please note that verification of DKIM signatures in incoming mail is turned | |
34402 | on by default for logging purposes. For each signature in incoming email, | |
34403 | exim will log a line displaying the most important signature details, and the | |
34404 | signature status. Here is an example: | |
34405 | .code | |
34406 | 2009-09-09 10:22:28 1MlIRf-0003LU-U3 DKIM: d=facebookmail.com s=q1-2009b c=relaxed/relaxed a=rsa-sha1 i=@facebookmail.com t=1252484542 [verification succeeded] | |
34407 | .endd | |
34408 | You might want to turn off DKIM verification processing entirely for internal | |
34409 | or relay mail sources. To do that, set the &%dkim_disable_verify%& ACL | |
34410 | control modifier. This should typically be done in the RCPT ACL, at points | |
34411 | where you accept mail from relay sources (internal hosts or authenticated | |
34412 | senders). | |
34413 | ||
34414 | ||
0b23848a TK |
34415 | .section "Signing outgoing messages" "SECID513" |
34416 | .cindex "DKIM" "signing" | |
34417 | ||
34418 | Signing is implemented by setting private options on the SMTP transport. | |
34419 | These options take (expandable) strings as arguments. | |
34420 | ||
7eadfc98 TK |
34421 | .option dkim_domain smtp string&!! unset |
34422 | MANDATORY | |
0b23848a | 34423 | The domain you want to sign with. The result of this expanded |
214bab57 | 34424 | option is put into the &%$dkim_domain%& expansion variable. |
0b23848a | 34425 | |
7eadfc98 TK |
34426 | .option dkim_selector smtp string&!! unset |
34427 | MANDATORY | |
214bab57 | 34428 | This sets the key selector string. You can use the &%$dkim_domain%& expansion |
0b23848a | 34429 | variable to look up a matching selector. The result is put in the expansion |
214bab57 TK |
34430 | variable &%$dkim_selector%& which should be used in the &%dkim_private_key%& |
34431 | option along with &%$dkim_domain%&. | |
0b23848a | 34432 | |
7eadfc98 TK |
34433 | .option dkim_private_key smtp string&!! unset |
34434 | MANDATORY | |
214bab57 TK |
34435 | This sets the private key to use. You can use the &%$dkim_domain%& and |
34436 | &%$dkim_selector%& expansion variables to determine the private key to use. | |
0b23848a | 34437 | The result can either |
c72d2505 | 34438 | .ilist |
0b23848a TK |
34439 | be a valid RSA private key in ASCII armor, including line breaks. |
34440 | .next | |
34441 | start with a slash, in which case it is treated as a file that contains | |
34442 | the private key. | |
34443 | .next | |
34444 | be "0", "false" or the empty string, in which case the message will not | |
214bab57 TK |
34445 | be signed. This case will not result in an error, even if &%dkim_strict%& |
34446 | is set. | |
0b23848a TK |
34447 | .endlist |
34448 | ||
7eadfc98 TK |
34449 | .option dkim_canon smtp string&!! unset |
34450 | OPTIONAL | |
0b23848a TK |
34451 | This option sets the canonicalization method used when signing a message. |
34452 | The DKIM RFC currently supports two methods: "simple" and "relaxed". | |
34453 | The option defaults to "relaxed" when unset. Note: the current implementation | |
214bab57 | 34454 | only supports using the same canonicalization method for both headers and body. |
0b23848a | 34455 | |
7eadfc98 TK |
34456 | .option dkim_strict smtp string&!! unset |
34457 | OPTIONAL | |
0b23848a TK |
34458 | This option defines how Exim behaves when signing a message that |
34459 | should be signed fails for some reason. When the expansion evaluates to | |
34460 | either "1" or "true", Exim will defer. Otherwise Exim will send the message | |
214bab57 | 34461 | unsigned. You can use the &%$dkim_domain%& and &%$dkim_selector%& expansion |
0b23848a TK |
34462 | variables here. |
34463 | ||
7eadfc98 TK |
34464 | .option dkim_sign_headers smtp string&!! unset |
34465 | OPTIONAL | |
0b23848a | 34466 | When set, this option must expand to (or be specified as) a colon-separated |
214bab57 TK |
34467 | list of header names. Headers with these names will be included in the message |
34468 | signature. When unspecified, the header names recommended in RFC4871 will be | |
34469 | used. | |
34470 | ||
34471 | ||
34472 | .section "Verifying DKIM signatures in incoming mail" "SECID514" | |
34473 | .cindex "DKIM" "verification" | |
34474 | ||
34475 | Verification of DKIM signatures in incoming email is implemented via the | |
34476 | &%acl_smtp_dkim%& ACL. By default, this ACL is called once for each | |
34477 | syntactically(!) correct signature in the incoming message. | |
34478 | ||
34479 | To evaluate the signature in the ACL a large number of expansion variables | |
34480 | containing the signature status and its details are set up during the | |
34481 | runtime of the ACL. | |
34482 | ||
34483 | Calling the ACL only for existing signatures is not sufficient to build | |
34484 | more advanced policies. For that reason, the global option | |
34485 | &%dkim_verify_signers%&, and a global expansion variable | |
6afc8383 | 34486 | &%$dkim_signers%& exist. |
9b371988 | 34487 | |
214bab57 TK |
34488 | The global option &%dkim_verify_signers%& can be set to a colon-separated |
34489 | list of DKIM domains or identities for which the ACL &%acl_smtp_dkim%& is | |
34490 | called. It is expanded when the message has been received. At this point, | |
6afc8383 TK |
34491 | the expansion variable &%$dkim_signers%& already contains a colon- |
34492 | separated list of signer domains and identities for the message. When | |
34493 | &%dkim_verify_signers%& is not specified in the main configuration, | |
34494 | it defaults as: | |
214bab57 | 34495 | .code |
6afc8383 | 34496 | dkim_verify_signers = $dkim_signers |
214bab57 TK |
34497 | .endd |
34498 | This leads to the default behaviour of calling &%acl_smtp_dkim%& for each | |
34499 | DKIM signature in the message. Current DKIM verifiers may want to explicitly | |
34500 | call the ACL for known domains or identities. This would be achieved as follows: | |
34501 | .code | |
6afc8383 | 34502 | dkim_verify_signers = paypal.com:ebay.com:$dkim_signers |
214bab57 TK |
34503 | .endd |
34504 | This would result in &%acl_smtp_dkim%& always being called for "paypal.com" | |
6afc8383 TK |
34505 | and "ebay.com", plus all domains and identities that have signatures in the message. |
34506 | You can also be more creative in constructing your policy. Example: | |
214bab57 | 34507 | .code |
6afc8383 | 34508 | dkim_verify_signers = $sender_address_domain:$dkim_signers |
214bab57 TK |
34509 | .endd |
34510 | ||
6afc8383 TK |
34511 | If a domain or identity is listed several times in the (expanded) value of |
34512 | &%dkim_verify_signers%&, the ACL is only called once for that domain or identity. | |
34513 | ||
34514 | ||
214bab57 TK |
34515 | Inside the &%acl_smtp_dkim%&, the following expansion variables are |
34516 | available (from most to least important): | |
34517 | ||
34518 | .vlist | |
6afc8383 TK |
34519 | .vitem &%$dkim_cur_signer%& |
34520 | The signer that is being evaluated in this ACL run. This can be domain or | |
34521 | an identity. This is one of the list items from the expanded main option | |
34522 | &%dkim_verify_signers%& (see above). | |
214bab57 TK |
34523 | .vitem &%$dkim_verify_status%& |
34524 | A string describing the general status of the signature. One of | |
34525 | .ilist | |
34526 | &%none%&: There is no signature in the message for the current domain or | |
6afc8383 | 34527 | identity (as reflected by &%$dkim_cur_signer%&). |
214bab57 TK |
34528 | .next |
34529 | &%invalid%&: The signature could not be verified due to a processing error. | |
34530 | More detail is available in &%$dkim_verify_reason%&. | |
34531 | .next | |
34532 | &%fail%&: Verification of the signature failed. More detail is | |
34533 | available in &%$dkim_verify_reason%&. | |
34534 | .next | |
34535 | &%pass%&: The signature passed verification. It is valid. | |
34536 | .endlist | |
34537 | .vitem &%$dkim_verify_reason%& | |
34538 | A string giving a litte bit more detail when &%$dkim_verify_status%& is either | |
34539 | "fail" or "invalid". One of | |
34540 | .ilist | |
34541 | &%pubkey_unavailable%& (when &%$dkim_verify_status%&="invalid"): The public | |
34542 | key for the domain could not be retrieved. This may be a temporary problem. | |
34543 | .next | |
34544 | &%pubkey_syntax%& (when &%$dkim_verify_status%&="invalid"): The public key | |
34545 | record for the domain is syntactically invalid. | |
34546 | .next | |
34547 | &%bodyhash_mismatch%& (when &%$dkim_verify_status%&="fail"): The calculated | |
34548 | body hash does not match the one specified in the signature header. This | |
34549 | means that the message body was modified in transit. | |
34550 | .next | |
34551 | &%signature_incorrect%& (when &%$dkim_verify_status%&="fail"): The signature | |
34552 | could not be verified. This may mean that headers were modified, | |
34553 | re-written or otherwise changed in a way which is incompatible with | |
34554 | DKIM verification. It may of course also mean that the signature is forged. | |
34555 | .endlist | |
34556 | .vitem &%$dkim_domain%& | |
34557 | The signing domain. IMPORTANT: This variable is only populated if there is | |
6afc8383 TK |
34558 | an actual signature in the message for the current domain or identity (as |
34559 | reflected by &%$dkim_cur_signer%&). | |
214bab57 | 34560 | .vitem &%$dkim_identity%& |
6afc8383 TK |
34561 | The signing identity, if present. IMPORTANT: This variable is only populated |
34562 | if there is an actual signature in the message for the current domain or | |
34563 | identity (as reflected by &%$dkim_cur_signer%&). | |
214bab57 TK |
34564 | .vitem &%$dkim_selector%& |
34565 | The key record selector string | |
34566 | .vitem &%$dkim_algo%& | |
34567 | The algorithm used. One of 'rsa-sha1' or 'rsa-sha256'. | |
34568 | .vitem &%$dkim_canon_body%& | |
34569 | The body canonicalization method. One of 'relaxed' or 'simple'. | |
34570 | .vitem &%dkim_canon_headers%& | |
34571 | The header canonicalization method. One of 'relaxed' or 'simple'. | |
34572 | .vitem &%$dkim_copiedheaders%& | |
34573 | A transcript of headers and their values which are included in the signature | |
34574 | (copied from the 'z=' tag of the signature). | |
34575 | .vitem &%$dkim_bodylength%& | |
34576 | The number of signed body bytes. If zero ("0"), the body is unsigned. If no | |
34577 | limit was set by the signer, "9999999999999" is returned. This makes sure | |
34578 | that this variable always expands to an integer value. | |
34579 | .vitem &%$dkim_created%& | |
34580 | UNIX timestamp reflecting the date and time when the signature was created. | |
34581 | When this was not specified by the signer, "0" is returned. | |
34582 | .vitem &%$dkim_expires%& | |
34583 | UNIX timestamp reflecting the date and time when the signer wants the | |
34584 | signature to be treated as "expired". When this was not specified by the | |
34585 | signer, "9999999999999" is returned. This makes it possible to do useful | |
34586 | integer size comparisons against this value. | |
34587 | .vitem &%$dkim_headernames%& | |
34588 | A colon-separated list of names of headers included in the signature. | |
34589 | .vitem &%$dkim_key_testing%& | |
34590 | "1" if the key record has the "testing" flag set, "0" if not. | |
34591 | .vitem &%$dkim_key_nosubdomaining%& | |
34592 | "1" if the key record forbids subdomaining, "0" otherwise. | |
34593 | .vitem &%$dkim_key_srvtype%& | |
34594 | Service type (tag s=) from the key record. Defaults to "*" if not specified | |
34595 | in the key record. | |
34596 | .vitem &%$dkim_key_granularity%& | |
34597 | Key granularity (tag g=) from the key record. Defaults to "*" if not specified | |
34598 | in the key record. | |
34599 | .vitem &%$dkim_key_notes%& | |
34600 | Notes from the key record (tag n=) | |
34601 | .endlist | |
34602 | ||
34603 | In addition, two ACL conditions are provided: | |
34604 | ||
34605 | .vlist | |
34606 | .vitem &%dkim_signers%& | |
34607 | ACL condition that checks a colon-separated list of domains or identities | |
6afc8383 TK |
34608 | for a match against the domain or identity that the ACL is currently verifying |
34609 | (reflected by &%$dkim_cur_signer%&). This is typically used to restrict an ACL | |
34610 | verb to a group of domains or identities, like: | |
214bab57 TK |
34611 | |
34612 | .code | |
34613 | # Warn when message apparently from GMail has no signature at all | |
34614 | warn log_message = GMail sender without DKIM signature | |
34615 | sender_domains = gmail.com | |
34616 | dkim_signers = gmail.com | |
34617 | dkim_status = none | |
34618 | .endd | |
34619 | ||
34620 | .vitem &%dkim_status%& | |
34621 | ACL condition that checks a colon-separated list of possible DKIM verification | |
34622 | results agains the actual result of verification. This is typically used | |
34623 | to restrict an ACL verb to a list of verification outcomes, like: | |
34624 | ||
34625 | .code | |
34626 | deny message = Message from Paypal with invalid or missing signature | |
34627 | sender_domains = paypal.com:paypal.de | |
34628 | dkim_signers = paypal.com:paypal.de | |
34629 | dkim_status = none:invalid:fail | |
34630 | .endd | |
34631 | ||
34632 | The possible status keywords are: 'none','invalid','fail' and 'pass'. Please | |
34633 | see the documentation of the &%$dkim_verify_status%& expansion variable above | |
34634 | for more information of what they mean. | |
34635 | .endlist | |
9b371988 PH |
34636 | |
34637 | . //////////////////////////////////////////////////////////////////////////// | |
34638 | . //////////////////////////////////////////////////////////////////////////// | |
34639 | ||
0b23848a | 34640 | .chapter "Adding new drivers or lookup types" "CHID13" &&& |
9b371988 PH |
34641 | "Adding drivers or lookups" |
34642 | .cindex "adding drivers" | |
f89d2485 | 34643 | .cindex "new drivers, adding" |
9b371988 | 34644 | .cindex "drivers" "adding new" |
168e428f PH |
34645 | The following actions have to be taken in order to add a new router, transport, |
34646 | authenticator, or lookup type to Exim: | |
34647 | ||
9b371988 PH |
34648 | .olist |
34649 | Choose a name for the driver or lookup type that does not conflict with any | |
34650 | existing name; I will use &"newdriver"& in what follows. | |
34651 | .next | |
34652 | Add to &_src/EDITME_& the line: | |
34653 | .display | |
34654 | <&'type'&>&`_NEWDRIVER=yes`& | |
34655 | .endd | |
34656 | where <&'type'&> is ROUTER, TRANSPORT, AUTH, or LOOKUP. If the | |
168e428f PH |
34657 | code is not to be included in the binary by default, comment this line out. You |
34658 | should also add any relevant comments about the driver or lookup type. | |
9b371988 PH |
34659 | .next |
34660 | Add to &_src/config.h.defaults_& the line: | |
34661 | .code | |
34662 | #define <type>_NEWDRIVER | |
34663 | .endd | |
34664 | .next | |
34665 | Edit &_src/drtables.c_&, adding conditional code to pull in the private header | |
168e428f | 34666 | and create a table entry as is done for all the other drivers and lookup types. |
9b371988 PH |
34667 | .next |
34668 | Edit &_Makefile_& in the appropriate sub-directory (&_src/routers_&, | |
34669 | &_src/transports_&, &_src/auths_&, or &_src/lookups_&); add a line for the new | |
168e428f | 34670 | driver or lookup type and add it to the definition of OBJ. |
9b371988 PH |
34671 | .next |
34672 | Create &_newdriver.h_& and &_newdriver.c_& in the appropriate sub-directory of | |
34673 | &_src_&. | |
34674 | .next | |
34675 | Edit &_scripts/MakeLinks_& and add commands to link the &_.h_& and &_.c_& files | |
168e428f | 34676 | as for other drivers and lookups. |
9b371988 | 34677 | .endlist |
168e428f PH |
34678 | |
34679 | Then all you need to do is write the code! A good way to start is to make a | |
34680 | proforma by copying an existing module of the same type, globally changing all | |
34681 | occurrences of the name, and cutting out most of the code. Note that any | |
34682 | options you create must be listed in alphabetical order, because the tables are | |
34683 | searched using a binary chop procedure. | |
34684 | ||
9b371988 | 34685 | There is a &_README_& file in each of the sub-directories of &_src_& describing |
168e428f PH |
34686 | the interface that is expected. |
34687 | ||
34688 | ||
34689 | ||
34690 | ||
9b371988 PH |
34691 | . //////////////////////////////////////////////////////////////////////////// |
34692 | . //////////////////////////////////////////////////////////////////////////// | |
34693 | ||
f89d2485 PH |
34694 | . ///////////////////////////////////////////////////////////////////////////// |
34695 | . These lines are processing instructions for the Simple DocBook Processor that | |
34696 | . Philip Hazel has developed as a less cumbersome way of making PostScript and | |
34697 | . PDFs than using xmlto and fop. They will be ignored by all other XML | |
34698 | . processors. | |
34699 | . ///////////////////////////////////////////////////////////////////////////// | |
34700 | ||
34701 | .literal xml | |
34702 | <?sdop | |
34703 | format="newpage" | |
34704 | foot_right_recto="&chaptertitle;" | |
34705 | foot_right_verso="&chaptertitle;" | |
34706 | ?> | |
34707 | .literal off | |
168e428f | 34708 | |
f89d2485 PH |
34709 | .makeindex "Options index" "option" |
34710 | .makeindex "Variables index" "variable" | |
34711 | .makeindex "Concept index" "concept" | |
168e428f | 34712 | |
168e428f | 34713 | |
9b371988 PH |
34714 | . ///////////////////////////////////////////////////////////////////////////// |
34715 | . ///////////////////////////////////////////////////////////////////////////// |