| 1 | . $Cambridge: exim/doc/doc-src/spec.src,v 1.3 2005/01/14 16:18:57 tom Exp $ |
| 2 | . |
| 3 | .set version "4.50" |
| 4 | .set previousversion "4.40" |
| 5 | .set versionmonth "January" |
| 6 | .set versionyear "2005" |
| 7 | .set ACL "ACL" |
| 8 | |
| 9 | . The last of those is to make ACL index entries easier to type. It is put |
| 10 | . up here so that it gets picked up by the HTML converter, which otherwise |
| 11 | . skips to the first chapter. A longer version is set below for use in the |
| 12 | . printed index. |
| 13 | |
| 14 | .set sgcal true |
| 15 | .set html false |
| 16 | .set texinfo false |
| 17 | |
| 18 | .if !set style |
| 19 | .library "a4ps" |
| 20 | .linelength ~~sys.linelength + 0.2in |
| 21 | .set newlinelength ~~sys.linelength |
| 22 | .emphasis ~~sys.linelength + 0.1in |
| 23 | .pagedepth ~~sys.pagedepth - 0.2in |
| 24 | .bindfont 51 "atl/Times-Bold" 9 |
| 25 | .bindfont 52 "atl/Times-Roman" 9 |
| 26 | .bindfont 53 "atl/Times-Roman" 7 |
| 27 | .bindfont 54 "atl/Courier" 9 |
| 28 | .bindfont 55 "atl/Courier-Bold" ~~maintypesize |
| 29 | .bindfont 56 "atl/Times-Italic" 7 |
| 30 | .bindfont 57 "atl/Times-Bold" 7 |
| 31 | .bindfont 58 "atl/Symbol" 7 |
| 32 | .set ssspaceb 1.50 |
| 33 | |
| 34 | .if ~~sgcal |
| 35 | . Used for the "small print" incorporated code stuff. Only rm, it, bf, sp are |
| 36 | . actually used at present. |
| 37 | . rm it sl bf bi ss tt sp sc |
| 38 | .fontgroup 9 = 53 56 0 57 0 0 0 58 0 |
| 39 | .fi |
| 40 | .fi |
| 41 | |
| 42 | .if !~~sys.fancy |
| 43 | .fontgroup 9 = 0 0 0 0 0 0 0 0 0 |
| 44 | .fi |
| 45 | |
| 46 | .include "markup.sg" |
| 47 | |
| 48 | .if ~~sys.fancy |
| 49 | .flag $smc{ "$push$g0$f54" |
| 50 | .flag $sm{ "$push$g0$f53" |
| 51 | .flag $smi{ "$push$g0$f56" |
| 52 | .flag $as{ "$push$g0$f52" |
| 53 | .flag $ab{ "$push$g0$f51" |
| 54 | .flag $cb{ "$push$g0$f55" |
| 55 | . |
| 56 | .else |
| 57 | .flag $smc{ "$push" |
| 58 | .flag $sm{ "$push" |
| 59 | .flag $smi{ "$push" |
| 60 | .flag $cb{ "$push" |
| 61 | .fi |
| 62 | |
| 63 | .macro isunderscore "string" |
| 64 | .set string "~~1" |
| 65 | .set length length "~~1" |
| 66 | .undrec 1 |
| 67 | .endm |
| 68 | |
| 69 | .macro undrec "offset" |
| 70 | .if ~~1 > ~~length |
| 71 | .set underscore false |
| 72 | .else |
| 73 | .set sub "~~string"(1,~~1) |
| 74 | .if "~~sub" == "_" |
| 75 | .set underscore true |
| 76 | .else |
| 77 | .set next ~~1 + 1 |
| 78 | .undrec ~~next |
| 79 | .fi |
| 80 | .fi |
| 81 | .endm |
| 82 | |
| 83 | .macro testunderscore "string" |
| 84 | .isunderscore "~~1" |
| 85 | .newline |
| 86 | .endm |
| 87 | |
| 88 | .macro tabs 6 |
| 89 | .if ~~sys.fancy |
| 90 | .tabset ~~1em |
| 91 | .else |
| 92 | .set temp (~~1 * 5)/4 |
| 93 | .tabset ~~temp em |
| 94 | .fi |
| 95 | .endm |
| 96 | |
| 97 | .macro startoptions |
| 98 | .newline |
| 99 | .push |
| 100 | .if ~~sys.fancy |
| 101 | .indent 6em |
| 102 | .else |
| 103 | .indent 7em |
| 104 | .fi |
| 105 | .endm |
| 106 | |
| 107 | .macro endoptions |
| 108 | .newline |
| 109 | .pop |
| 110 | .endm |
| 111 | |
| 112 | .macro option "option" "" |
| 113 | .newpar |
| 114 | .index \-~~1-\ option |
| 115 | .tempindent 0 |
| 116 | \-~~1-\~~2#$i |
| 117 | .nosep |
| 118 | .endm |
| 119 | |
| 120 | .macro startitems |
| 121 | .newline |
| 122 | .push |
| 123 | .indent 3em |
| 124 | .endm |
| 125 | |
| 126 | .macro enditems |
| 127 | .newline |
| 128 | .pop |
| 129 | .endm |
| 130 | |
| 131 | .macro item "item" "6" |
| 132 | .newpar |
| 133 | .if ~~sys.leftonpage < ~~2ld |
| 134 | .newpage |
| 135 | .fi |
| 136 | .tempindent 0 |
| 137 | \**~~1**\ |
| 138 | .blank |
| 139 | .endm |
| 140 | |
| 141 | .macro startconf |
| 142 | .newline |
| 143 | .push |
| 144 | .if ~~sys.fancy |
| 145 | .indent 2em |
| 146 | .tabset 9em |
| 147 | .else |
| 148 | .indent 4em |
| 149 | .tabset 13em |
| 150 | .fi |
| 151 | .endm |
| 152 | |
| 153 | .macro endconf |
| 154 | .newline |
| 155 | .pop |
| 156 | .endm |
| 157 | |
| 158 | .macro conf "option" "type" "default" "6" |
| 159 | .newpar |
| 160 | .if ~~sys.leftonpage < ~~4ld |
| 161 | .newpage |
| 162 | .fi |
| 163 | .testunderscore "~~1" |
| 164 | .if ~~underscore |
| 165 | .index \~~1\ |
| 166 | .else |
| 167 | .index \~~1\ option |
| 168 | .fi |
| 169 | .tempindent 0 |
| 170 | \**~~1**\ $c $rm{Type:} $it{~~2} $e $rm{Default:} $it{~~3} |
| 171 | .blank |
| 172 | .endm |
| 173 | |
| 174 | .set contents true |
| 175 | .set figurenumber -1 |
| 176 | .set displayindent 2em |
| 177 | |
| 178 | .index @$1, @$2, etc. $it{see numerical variables} |
| 179 | .index address||rewriting $it{see rewriting} |
| 180 | .index CR character $it{see carriage return} |
| 181 | .index CRL $it{see certificate revocation list} |
| 182 | .index delivery||failure report $it{see bounce message} |
| 183 | .index dialup $it{see intermittently connected hosts} |
| 184 | .index exiscan $it{see content scanning} |
| 185 | .index failover $it{see fallback} |
| 186 | .index fallover $it{see fallback} |
| 187 | .index filter||Sieve $it{see Sieve filter} |
| 188 | .index ident $it{see RFC 1413} |
| 189 | .index LF character $it{see linefeed} |
| 190 | .index maximum $it{see limit} |
| 191 | .index NUL $it{see binary zero} |
| 192 | .index process id $it{see pid} |
| 193 | .index RBL $it{see DNS list} |
| 194 | .index redirection $it{see address redirection} |
| 195 | .index return path||$it{see also envelope sender} |
| 196 | .index scanning $it{see content scanning} |
| 197 | .index SSL $it{see TLS} |
| 198 | .index string||expansion $it{see expansion} |
| 199 | .index top bit $it{see 8-bit characters} |
| 200 | .index variables $it{see expansion, variables} |
| 201 | .index zero, binary $it{see binary zero} |
| 202 | |
| 203 | . This is used for the printed index. See setting above for |
| 204 | . the HTML index value. |
| 205 | |
| 206 | .set ACL "access control lists (ACLs)" |
| 207 | |
| 208 | . ====================================================== |
| 209 | |
| 210 | .push |
| 211 | .disable filling |
| 212 | .justify centre |
| 213 | .nofoot |
| 214 | .space 8ld |
| 215 | $chead{University of Cambridge Computing Service} |
| 216 | .space 2ld |
| 217 | $chead{Specification of the Exim Mail Transfer Agent} |
| 218 | .space 3ld |
| 219 | by |
| 220 | .space 1ld |
| 221 | Philip Hazel |
| 222 | .space ~~sys.leftonpage - 15*~~sys.linedepth |
| 223 | .justify left |
| 224 | University Computing Service |
| 225 | New Museums Site |
| 226 | Pembroke Street |
| 227 | Cambridge CB2 3QH |
| 228 | United Kingdom |
| 229 | .blank |
| 230 | .tabs 6 |
| 231 | $it{phone:} $t +44 1223 334600 |
| 232 | $it{fax:} $t +44 1223 334679 |
| 233 | $it{email:} $t ph10 $it{at} cus.cam.ac.uk |
| 234 | .blank |
| 235 | Edition for Exim ~~version, ~~versionmonth ~~versionyear |
| 236 | .space 2ld |
| 237 | .if ~~sgcal |
| 238 | .fontgroup 1 |
| 239 | .fi |
| 240 | $c$rm{Copyright (c) University of Cambridge ~~versionyear} |
| 241 | |
| 242 | |
| 243 | .if ~~sgcal |
| 244 | .fontgroup 0 |
| 245 | .font 0 |
| 246 | .fi |
| 247 | |
| 248 | .pop |
| 249 | .newpage |
| 250 | |
| 251 | . Blank verso for title page |
| 252 | .space 1ld |
| 253 | .newpage |
| 254 | |
| 255 | |
| 256 | . Set up for actual text pages |
| 257 | .page 1 |
| 258 | . The first one to prevent a warning from sgfr |
| 259 | . set runningfoot "~~chapter" |
| 260 | .set runningfoot "" |
| 261 | |
| 262 | .if ~~sys.fancy |
| 263 | .footdepth 2ld |
| 264 | .foot |
| 265 | .if "~~runningfoot" == "" |
| 266 | .set rhs "" |
| 267 | .else |
| 268 | .set rhs "~~runningfoot (~~chapter)" |
| 269 | .fi |
| 270 | .set lhs "Exim ~~version" |
| 271 | .linelength ~~newlinelength |
| 272 | $it{~~lhs}$c[~~sys.pagenumber]$e$it{~~rhs} |
| 273 | .endfoot |
| 274 | .fi |
| 275 | |
| 276 | |
| 277 | |
| 278 | |
| 279 | . |
| 280 | . |
| 281 | . |
| 282 | . |
| 283 | . ============================================================================ |
| 284 | .chapter Introduction |
| 285 | .set runningfoot "introduction" |
| 286 | |
| 287 | .if ~~sys.fancy |
| 288 | $c$bi{If I have seen further it is by standing on the shoulders of giants.}##(Isaac Newton) |
| 289 | .elif !~~html |
| 290 | $c"If I have seen further it is by standing on the shoulders of giants." |
| 291 | .newline |
| 292 | $e (Isaac Newton) |
| 293 | .else |
| 294 | \*If I have seen further it is by standing on the shoulders of giants.*\ |
| 295 | (Isaac Newton). |
| 296 | .fi |
| 297 | .blank 4 |
| 298 | |
| 299 | Exim is a mail transfer agent (MTA) for hosts that are running Unix or |
| 300 | Unix-like operating systems. It was designed on the assumption that it would be |
| 301 | run on hosts that are permanently connected to the Internet. However, it can be |
| 302 | used on intermittently connected hosts with suitable configuration adjustments. |
| 303 | |
| 304 | Configuration files currently exist for the following operating systems: AIX, |
| 305 | BSD/OS (aka BSDI), Darwin (Mac OS X), DGUX, FreeBSD, GNU/Hurd, GNU/Linux, |
| 306 | HI-OSF (Hitachi), HP-UX, IRIX, MIPS RISCOS, NetBSD, OpenBSD, QNX, SCO, SCO |
| 307 | SVR4.2 (aka UNIX-SV), Solaris (aka SunOS5), SunOS4, Tru64-Unix (formerly |
| 308 | Digital UNIX, formerly DEC-OSF1), Ultrix, and Unixware. Some of these operating |
| 309 | systems are no longer current and cannot easily be tested, so the configuration |
| 310 | files may no longer work in practice. |
| 311 | |
| 312 | There are also configuration files for compiling Exim in the Cygwin environment |
| 313 | that can be installed on systems running Windows. However, this document does |
| 314 | not contain any information about running Exim in the Cygwin environment. |
| 315 | |
| 316 | The terms and conditions for the use and distribution of Exim are contained in |
| 317 | the file \(NOTICE)\. Exim is distributed under the terms of the GNU General |
| 318 | Public Licence, a copy of which may be found in the file \(LICENCE)\. |
| 319 | |
| 320 | The use, supply or promotion of Exim for the purpose of sending bulk, |
| 321 | unsolicited electronic mail is incompatible with the basic aims of the program, |
| 322 | which revolve around the free provision of a service that enhances the quality |
| 323 | of personal communications. The author of Exim regards indiscriminate |
| 324 | mass-mailing as an antisocial, irresponsible abuse of the Internet. |
| 325 | |
| 326 | Exim owes a great deal to Smail 3 and its author, Ron Karr. Without the |
| 327 | experience of running and working on the Smail 3 code, I could never have |
| 328 | contemplated starting to write a new MTA. Many of the ideas and user interfaces |
| 329 | were originally taken from Smail 3, though the actual code of Exim is entirely |
| 330 | new, and has developed far beyond the initial concept. |
| 331 | |
| 332 | Many people, both in Cambridge and around the world, have contributed to the |
| 333 | development and the testing of Exim, and to porting it to various operating |
| 334 | systems. I am grateful to them all. The distribution now contains a file called |
| 335 | \(ACKNOWLEDGMENTS)\, in which I have started recording the names of |
| 336 | contributors. |
| 337 | |
| 338 | .section Exim documentation |
| 339 | .index documentation |
| 340 | This edition of the Exim specification applies to version ~~version of Exim. |
| 341 | Substantive changes from the ~~previousversion edition are marked by bars in |
| 342 | the right-hand margin in the PostScript, PDF, and plain text versions of the |
| 343 | document, and by green text in the HTML version, as shown by this paragraph. |
| 344 | Changes are not marked in the Texinfo version, because Texinfo doesn't support |
| 345 | change bars. Minor corrections and rewordings are not marked. |
| 346 | |
| 347 | This document is very much a reference manual; it is not a tutorial. The reader |
| 348 | is expected to have some familiarity with the SMTP mail transfer protocol and |
| 349 | with general Unix system administration. Although there are some discussions |
| 350 | and examples in places, the information is mostly organized in a way that makes |
| 351 | it easy to look up, rather than in a natural order for sequential reading. |
| 352 | Furthermore, the manual aims to cover every aspect of Exim in detail, including |
| 353 | a number of rarely-used, special-purpose features that are unlikely to be of |
| 354 | very wide interest. |
| 355 | |
| 356 | .index books about Exim |
| 357 | An `easier' discussion of Exim which provides more in-depth explanatory, |
| 358 | introductory, and tutorial material can be found in a book entitled |
| 359 | .if ~~html |
| 360 | [(A HREF="http://www.uit.co.uk/exim-book/")] |
| 361 | $it{The Exim SMTP Mail Server}, |
| 362 | [(/A)] |
| 363 | published by UIT Cambridge. |
| 364 | .else |
| 365 | $it{The Exim SMTP Mail Server}, published by UIT Cambridge |
| 366 | (\?http://www.uit.co.uk/exim-book/?\). |
| 367 | .fi |
| 368 | |
| 369 | This book also contains a chapter that gives a general introduction to SMTP and |
| 370 | Internet mail. Inevitably, however, the book is unlikely to be fully up-to-date |
| 371 | with the latest release of Exim. (Note that the earlier book about Exim, |
| 372 | published by O'Reilly, covers Exim 3, and many things have changed in Exim 4.) |
| 373 | |
| 374 | .index \(doc/NewStuff)\ |
| 375 | .index \(doc/ChangeLog)\ |
| 376 | .index change log |
| 377 | As the program develops, there may be features in newer versions that have not |
| 378 | yet made it into this document, which is updated only when the most significant |
| 379 | digit of the fractional part of the version number changes. However, |
| 380 | specifications of new features that are not yet in this manual are placed in |
| 381 | the file \(doc/NewStuff)\ in the Exim distribution. All changes to the program |
| 382 | (whether new features, bug fixes, or other kinds of change) are noted briefly |
| 383 | in the file called \(doc/ChangeLog)\. |
| 384 | |
| 385 | .index \(doc/spec.txt)\ |
| 386 | This specification itself is available as an ASCII file in \(doc/spec.txt)\ so |
| 387 | that it can easily be searched with a text editor. Other files in the \(doc)\ |
| 388 | directory are: |
| 389 | .display rm |
| 390 | .tabs 18 |
| 391 | \(OptionLists.txt)\ $t $rm{list of all options in alphabetical order} |
| 392 | \(dbm.discuss.txt)\ $t $rm{discussion about DBM libraries} |
| 393 | \(exim.8)\ $t $rm{a man page of Exim's command line options} |
| 394 | \(filter.txt)\ $t $rm{specification of the filter language} |
| 395 | \(pcrepattern.txt)\ $t $rm{specification of PCRE regular expressions} |
| 396 | \(pcretest.txt)\ $t $rm{specification of the PCRE testing program} |
| 397 | \(Exim3.upgrade)\ $t $rm{upgrade notes from release 2 to release 3} |
| 398 | \(Exim4.upgrade)\ $t $rm{upgrade notes from release 3 to release 4} |
| 399 | .endd |
| 400 | The main specification and the specification of the filtering language are also |
| 401 | available in other formats (HTML, PostScript, PDF, and Texinfo). Section |
| 402 | ~~SECTavail below tells you how to get hold of these. |
| 403 | |
| 404 | |
| 405 | .section FTP and web sites, and mailing list |
| 406 | .index web site |
| 407 | .index FTP site |
| 408 | The primary distribution site for Exim is an FTP site, whose contents are |
| 409 | described in \*Where to find the Exim distribution*\ below. In addition, |
| 410 | there is a web site at \?http://www.exim.org?\ by courtesy of Energis Squared, |
| 411 | formerly Planet Online Ltd, who are situated in the UK. The site is mirrored in |
| 412 | a number of other countries; links to the mirrors are listed on the home page. |
| 413 | The web site contains the Exim distribution, and you can also find the |
| 414 | documentation and the |
| 415 | .index FAQ |
| 416 | .if ~~html |
| 417 | [(A HREF="FAQ.html")] |
| 418 | .fi |
| 419 | FAQ |
| 420 | .if ~~html |
| 421 | [(/A)] |
| 422 | .fi |
| 423 | online there, as well as other relevant material. |
| 424 | |
| 425 | .index mailing lists||for Exim users |
| 426 | Energis Squared also provide resources for the following mailing lists: |
| 427 | .display rm |
| 428 | .tabs 28 |
| 429 | $it{exim-users@@exim.org} $t general discussion list |
| 430 | $it{exim-announce@@exim.org} $t moderated, low volume announcements list |
| 431 | .endd |
| 432 | You can subscribe to these lists, change your existing subscriptions, and view |
| 433 | or search the archives via the |
| 434 | .if ~~html |
| 435 | [(A HREF="http://www.exim.org/maillist.html")] |
| 436 | .fi |
| 437 | mailing lists |
| 438 | .if ~~html |
| 439 | [(/A)] |
| 440 | .fi |
| 441 | link on the Exim home page. The $it{exim-users} mailing list is also forwarded |
| 442 | to \?http://www.egroups.com/list/exim-users?\, an archiving system with |
| 443 | searching capabilities. |
| 444 | |
| 445 | .section Exim training |
| 446 | .index training courses |
| 447 | From time to time (approximately annually at the time of writing), |
| 448 | lecture-based training courses are run by the author of Exim in Cambridge, UK. |
| 449 | Details can be found on the web site |
| 450 | .if ~~html |
| 451 | [(A HREF="http://www-tus.csx.cam.ac.uk/courses/exim/")] |
| 452 | .fi |
| 453 | \?http://www-tus@.csx@.cam@.ac.uk/courses/exim/?\. |
| 454 | .if ~~html |
| 455 | [(/A)] |
| 456 | .fi |
| 457 | |
| 458 | .section Bug reports |
| 459 | .index bug reports |
| 460 | .index reporting bugs |
| 461 | Reports of obvious bugs should be emailed to \*bugs@@exim.org*\. However, if |
| 462 | you are unsure whether some behaviour is a bug or not, the best thing to do is |
| 463 | to post a message to the $it{exim-users} mailing list and have it discussed. |
| 464 | |
| 465 | |
| 466 | .section Where to find the Exim distribution |
| 467 | .rset SECTavail "~~chapter.~~section" |
| 468 | .index FTP site |
| 469 | .index distribution||ftp site |
| 470 | The master ftp site for the Exim distribution is |
| 471 | .display rm |
| 472 | .if ! ~~sys.fancy |
| 473 | .indent 0 |
| 474 | .fi |
| 475 | \?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim?\ |
| 476 | .endd |
| 477 | Within that directory there are subdirectories called \(exim3)\ (for previous |
| 478 | Exim 3 distributions), \(exim4)\ (for the latest Exim 4 distributions), and |
| 479 | \(Testing)\ for occasional testing versions. Those mirror sites that I know |
| 480 | about are listed in the file |
| 481 | .display rm |
| 482 | .if ! ~~sys.fancy |
| 483 | .indent 0 |
| 484 | .fi |
| 485 | \?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/Mirrors?\ |
| 486 | .endd |
| 487 | In the \(exim4)\ subdirectory, the current release can always be found in |
| 488 | files called |
| 489 | .display rm |
| 490 | \(exim-$it{n.nn}.tar.gz)\ |
| 491 | \(exim-$it{n.nn}.tar.bz2)\ |
| 492 | .endd |
| 493 | where $it{n.nn} is the highest such version number in the directory. The two |
| 494 | files contain identical data; the only difference is the type of compression. |
| 495 | The \(.bz2)\ file is usually a lot smaller than the \(.gz)\ file. |
| 496 | .index distribution||signing details |
| 497 | .index distribution||public key |
| 498 | .index public key for signed distribution |
| 499 | The distributions are signed with Philip Hazel's GPG key. |
| 500 | The corresponding public key is available from a number of keyservers, and |
| 501 | there is also a copy in the file: |
| 502 | .display rm |
| 503 | .if ! ~~sys.fancy |
| 504 | .indent 0 |
| 505 | .fi |
| 506 | \?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/Public-Key?\ |
| 507 | .endd |
| 508 | The signatures for the tar bundles are in: |
| 509 | .display rm |
| 510 | \(exim-$it{n.nn}.tar.gz.sig)\ |
| 511 | \(exim-$it{n.nn}.tar.bz2.sig)\ |
| 512 | .endd |
| 513 | |
| 514 | When there is only a small amount of change from one release to the next, a |
| 515 | patch file may be provided, with a final component name of the form |
| 516 | .display rm |
| 517 | \(exim-patch-$it{n.nn}-$it{m.mm}.gz)\ |
| 518 | .endd |
| 519 | For each released version, the log of changes is made separately available in |
| 520 | the directory |
| 521 | .display rm |
| 522 | \?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/ChangeLogs?\ |
| 523 | .endd |
| 524 | so that it is possible to find out what has changed without having to download |
| 525 | the entire distribution. |
| 526 | |
| 527 | .index documentation||available formats |
| 528 | The main distribution contains ASCII versions of this specification and other |
| 529 | documentation; other formats of the documents are available in separate files |
| 530 | inside the \(exim4)\ directory of the FTP site: |
| 531 | .display rm |
| 532 | \(exim-html-$it{n.nn}.tar.gz)\ |
| 533 | \(exim-pdf-$it{n.nn}.tar.gz)\ |
| 534 | \(exim-postscript-$it{n.nn}.tar.gz)\ |
| 535 | \(exim-texinfo-$it{n.nn}.tar.gz)\ |
| 536 | .endd |
| 537 | These tar files contain only the \(doc)\ directory, not the complete |
| 538 | distribution, and are also available in \(.bz2)\ as well as \(.gz)\ forms. |
| 539 | |
| 540 | .index FAQ |
| 541 | The FAQ is available for downloading in two different formats from |
| 542 | .display rm |
| 543 | .if ! ~~sys.fancy |
| 544 | .indent 0 |
| 545 | .fi |
| 546 | \?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/exim4/FAQ.txt.gz?\ |
| 547 | \?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/exim4/FAQ.html.tar.gz?\ |
| 548 | .endd |
| 549 | The first of these is a single ASCII file that can be searched with a text |
| 550 | editor. The second is a directory of HTML files, normally accessed by starting |
| 551 | at \(index.html)\. The HTML version of the FAQ (which is also included in the |
| 552 | HTML documentation tarbundle) includes a keyword-in-context index, which is |
| 553 | often the most convenient way of finding your way around. |
| 554 | |
| 555 | .section Wish list |
| 556 | .index wish list |
| 557 | A wish list is maintained, containing ideas for new features that have been |
| 558 | submitted. From time to time the file is exported to the ftp site: |
| 559 | .display rm |
| 560 | \?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/exim4/WishList?\ |
| 561 | .endd |
| 562 | Items are removed from the list if they get implemented. |
| 563 | |
| 564 | |
| 565 | .section Contributed material |
| 566 | .index contributed material |
| 567 | At the ftp site, there is a directory called |
| 568 | .display rm |
| 569 | .if ! ~~sys.fancy |
| 570 | .indent 0 |
| 571 | .fi |
| 572 | \?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/exim4/Contrib/?\ |
| 573 | .endd |
| 574 | which contains miscellaneous files contributed to the Exim community by Exim |
| 575 | users. There is also a collection of contributed configuration examples in |
| 576 | .display rm |
| 577 | .if ! ~~sys.fancy |
| 578 | .indent 0 |
| 579 | .fi |
| 580 | \?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/exim4/config.samples.tar.gz?\ |
| 581 | .endd |
| 582 | These samples are referenced from the FAQ. |
| 583 | |
| 584 | |
| 585 | .section Limitations |
| 586 | .index limitations of Exim |
| 587 | .numberpars $. |
| 588 | Exim is designed for use as an Internet MTA, and therefore handles addresses |
| 589 | in RFC 2822 domain format only. |
| 590 | .index bang paths||not handled by Exim |
| 591 | It cannot handle UUCP `bang paths', though simple two-component bang paths can |
| 592 | be converted by a straightforward rewriting configuration. This restriction |
| 593 | does not prevent Exim from being interfaced to UUCP as a transport mechanism, |
| 594 | provided that domain addresses are used. |
| 595 | .nextp |
| 596 | .index domainless addresses |
| 597 | .index address||without domain |
| 598 | Exim insists that every address it handles has a domain attached. For incoming |
| 599 | local messages, domainless addresses are automatically qualified with a |
| 600 | configured domain value. Configuration options specify from which remote |
| 601 | systems unqualified addresses are acceptable. These are then qualified on |
| 602 | arrival. |
| 603 | .nextp |
| 604 | .index transport||external |
| 605 | .index external transports |
| 606 | The only external transport currently implemented is an SMTP transport over a |
| 607 | TCP/IP network (using sockets, including support for IPv6). However, a pipe |
| 608 | transport is available, and there are facilities for writing messages to files |
| 609 | and pipes, optionally in \*batched SMTP*\ format; these facilities can be used |
| 610 | to send messages to some other transport mechanism such as UUCP, provided it |
| 611 | can handle domain-style addresses. Batched SMTP input is also catered for. |
| 612 | .nextp |
| 613 | Exim is not designed for storing mail for dial-in hosts. When the volumes of |
| 614 | such mail are large, it is better to get the messages `delivered' into files |
| 615 | (that is, off Exim's queue) and subsequently passed on to the dial-in hosts by |
| 616 | other means. |
| 617 | .nextp |
| 618 | Although Exim does have some facilities for scanning incoming messages, these |
| 619 | are not comprehensive enough to do full virus or spam scanning. Such operations |
| 620 | are best carried out using additional specialized software packages. |
| 621 | .endp |
| 622 | |
| 623 | |
| 624 | |
| 625 | .section Run time configuration |
| 626 | Exim's run time configuration is held in a single text file that is divided |
| 627 | into a number of sections. The entries in this file consist of keywords and |
| 628 | values, in the style of Smail 3 configuration files. A default configuration |
| 629 | file which is suitable for simple online installations is provided in the |
| 630 | distribution, and is described in chapter ~~CHAPdefconfil below. |
| 631 | |
| 632 | |
| 633 | .section Calling interface |
| 634 | .index Sendmail compatibility||command line interface |
| 635 | Like many MTAs, Exim has adopted the Sendmail command line interface so that it |
| 636 | can be a straight replacement for \(/usr/lib/sendmail)\ or |
| 637 | \(/usr/sbin/sendmail)\ when sending mail, but you do not need to know anything |
| 638 | about Sendmail in order to run Exim. For actions other than sending messages, |
| 639 | Sendmail-compatible options also exist, but those that produce output (for |
| 640 | example, \-bp-\, which lists the messages on the queue) do so in Exim's own |
| 641 | format. There are also some additional options that are compatible with Smail |
| 642 | 3, and some further options that are new to Exim. Chapter ~~CHAPcommandline |
| 643 | documents all Exim's command line options. This information is automatically |
| 644 | made into the man page that forms part of the Exim distribution. |
| 645 | |
| 646 | Control of messages on the queue can be done via certain privileged command |
| 647 | line options. There is also an optional monitor program called \*eximon*\, which |
| 648 | displays current information in an X window, and which contains a menu |
| 649 | interface to Exim's command line administration options. |
| 650 | |
| 651 | |
| 652 | .section Terminology |
| 653 | .index terminology definitions |
| 654 | .index body of message||definition of |
| 655 | The \*body*\ of a message is the actual data that the sender wants to transmit. |
| 656 | It is the last part of a message, and is separated from the \*header*\ (see |
| 657 | below) by a blank line. |
| 658 | |
| 659 | .index bounce message||definition of |
| 660 | When a message cannot be delivered, it is normally returned to the sender in a |
| 661 | delivery failure message. The term \*bounce*\ is commonly used for this action, |
| 662 | and the error reports are often called \*bounce messages*\. This is a |
| 663 | convenient shorthand for `delivery failure error report'. Such messages have an |
| 664 | empty sender address in the message's \*envelope*\ (see below) to ensure that |
| 665 | they cannot themselves give rise to further bounce messages. |
| 666 | |
| 667 | The term \*default*\ appears frequently in this manual. It is used to qualify a |
| 668 | value which is used in the absence of any setting in the configuration. It may |
| 669 | also qualify an action which is taken unless a configuration setting specifies |
| 670 | otherwise. |
| 671 | |
| 672 | The term \*defer*\ is used when the delivery of a message to a specific |
| 673 | destination cannot immediately take place for some reason (a remote host may be |
| 674 | down, or a user's local mailbox may be full). Such deliveries are \*deferred*\ |
| 675 | until a later time. |
| 676 | |
| 677 | The word \*domain*\ is sometimes used to mean all but the first component of a |
| 678 | host's name. It is $it{not} used in that sense here, where it normally |
| 679 | refers to the part of an email address following the @@ sign. |
| 680 | |
| 681 | .index envelope, definition of |
| 682 | .index sender||definition of |
| 683 | A message in transit has an associated \*envelope*\, as well as a header and a |
| 684 | body. The envelope contains a sender address (to which bounce messages should |
| 685 | be delivered), and any number of recipient addresses. References to the |
| 686 | sender or the recipients of a message usually mean the addresses in the |
| 687 | envelope. An MTA uses these addresses for delivery, and for returning bounce |
| 688 | messages, not the addresses that appear in the header lines. |
| 689 | |
| 690 | .index message||header, definition of |
| 691 | .index header section||definition of |
| 692 | The \*header*\ of a message is the first part of a message's text, consisting |
| 693 | of a number of lines, each of which has a name such as ::From::, ::To::, |
| 694 | ::Subject::, etc. Long header lines can be split over several text lines by |
| 695 | indenting the continuations. The header is separated from the body by a blank |
| 696 | line. |
| 697 | |
| 698 | .index local part||definition of |
| 699 | .index domain||definition of |
| 700 | The term \*local part*\, which is taken from RFC 2822, is used to refer to that |
| 701 | part of an email address that precedes the @@ sign. The part that follows the |
| 702 | @@ sign is called the \*domain*\ or \*mail domain*\. |
| 703 | |
| 704 | .index local delivery||definition of |
| 705 | .index remote delivery, definition of |
| 706 | The terms \*local delivery*\ and \*remote delivery*\ are used to distinguish |
| 707 | delivery to a file or a pipe on the local host from delivery by SMTP over |
| 708 | TCP/IP to a remote host. |
| 709 | |
| 710 | .index return path||definition of |
| 711 | \*Return path*\ is another name that is used for the sender address in a |
| 712 | message's envelope. |
| 713 | |
| 714 | .index queue||definition of |
| 715 | The term \*queue*\ is used to refer to the set of messages awaiting delivery, |
| 716 | because this term is in widespread use in the context of MTAs. However, in |
| 717 | Exim's case the reality is more like a pool than a queue, because there is |
| 718 | normally no ordering of waiting messages. |
| 719 | |
| 720 | .index queue runner||definition of |
| 721 | The term \*queue runner*\ is used to describe a process that scans the queue |
| 722 | and attempts to deliver those messages whose retry times have come. This term |
| 723 | is used by other MTAs, and also relates to the command \runq\, but in Exim |
| 724 | the waiting messages are normally processed in an unpredictable order. |
| 725 | |
| 726 | .index spool directory||definition of |
| 727 | The term \*spool directory*\ is used for a directory in which Exim keeps the |
| 728 | messages on its queue -- that is, those that it is in the process of |
| 729 | delivering. This should not be confused with the directory in which local |
| 730 | mailboxes are stored, which is called a `spool directory' by some people. In |
| 731 | the Exim documentation, `spool' is always used in the first sense. |
| 732 | |
| 733 | |
| 734 | |
| 735 | . |
| 736 | . |
| 737 | . |
| 738 | . |
| 739 | . ============================================================================ |
| 740 | .chapter Incorporated code |
| 741 | .set runningfoot "incorporated code" |
| 742 | .index incorporated code |
| 743 | .index regular expressions||library |
| 744 | .index PCRE |
| 745 | A number of pieces of external code are included in the Exim distribution. |
| 746 | .numberpars $. |
| 747 | Regular expressions are supported in the main Exim program and in the Exim |
| 748 | monitor using the freely-distributable PCRE library, copyright (c) 2003 |
| 749 | University of Cambridge. The source is distributed in the directory |
| 750 | \(src/pcre)\. However, this is a cut-down version of PCRE. If you want to use |
| 751 | the PCRE library in other programs, you should obtain and install the full |
| 752 | version from \?ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre?\. |
| 753 | |
| 754 | .space 1ld |
| 755 | .nextp |
| 756 | .index cdb||acknowledgement |
| 757 | Support for the cdb (Constant DataBase) lookup method is provided by code |
| 758 | contributed by Nigel Metheringham of Planet Online Ltd. which contains the |
| 759 | following statements: |
| 760 | .rule |
| 761 | .push |
| 762 | .if ~~sgcal |
| 763 | .fontgroup 9 |
| 764 | .font 0 |
| 765 | .fi |
| 766 | Copyright (c) 1998 Nigel Metheringham, Planet Online Ltd |
| 767 | |
| 768 | This program is free software; you can redistribute it and/or modify it under |
| 769 | the terms of the GNU General Public License as published by the Free Software |
| 770 | Foundation; either version 2 of the License, or (at your option) any later |
| 771 | version. |
| 772 | |
| 773 | This code implements Dan Bernstein's Constant DataBase (cdb) spec. Information, |
| 774 | the spec and sample code for cdb can be obtained from |
| 775 | \?http://www.pobox.com/@~djb/cdb.html?\. This implementation borrows some code |
| 776 | from Dan Bernstein's implementation (which has no license restrictions applied |
| 777 | to it). |
| 778 | .newline |
| 779 | .pop |
| 780 | .rule |
| 781 | The implementation is completely contained within the code of Exim. |
| 782 | It does not link against an external cdb library. |
| 783 | .space 1ld |
| 784 | .nextp |
| 785 | .index SPA authentication |
| 786 | .index Samba project |
| 787 | .index Microsoft Secure Password Authentication |
| 788 | Client support for Microsoft's \*Secure Password Authentication*\ is provided |
| 789 | by code contributed by Marc Prud'hommeaux. Server support was contributed by |
| 790 | Tom Kistner. This includes code taken from the Samba project, which is released |
| 791 | under the Gnu GPL. |
| 792 | |
| 793 | .space 1ld |
| 794 | .nextp |
| 795 | .index Cyrus |
| 796 | .index \*pwcheck*\ daemon |
| 797 | .index \*pwauthd*\ daemon |
| 798 | Support for calling the Cyrus \*pwcheck*\ and \*saslauthd*\ daemons is provided |
| 799 | by code taken from the Cyrus-SASL library and adapted by Alexander S. |
| 800 | Sabourenkov. The permission notice appears below, in accordance with the |
| 801 | conditions expressed therein. |
| 802 | |
| 803 | .rule |
| 804 | .push |
| 805 | .if ~~sgcal |
| 806 | .fontgroup 9 |
| 807 | .font 0 |
| 808 | .fi |
| 809 | Copyright (c) 2001 Carnegie Mellon University. All rights reserved. |
| 810 | |
| 811 | Redistribution and use in source and binary forms, with or without |
| 812 | modification, are permitted provided that the following conditions |
| 813 | are met: |
| 814 | |
| 815 | .if ~~sgcal |
| 816 | .cancelflag $npbracket |
| 817 | .flag $npbracket "" "." |
| 818 | .fi |
| 819 | .numberpars |
| 820 | Redistributions of source code must retain the above copyright |
| 821 | notice, this list of conditions and the following disclaimer. |
| 822 | .nextp |
| 823 | Redistributions in binary form must reproduce the above copyright |
| 824 | notice, this list of conditions and the following disclaimer in |
| 825 | the documentation and/or other materials provided with the |
| 826 | distribution. |
| 827 | .nextp |
| 828 | The name `Carnegie Mellon University' must not be used to |
| 829 | endorse or promote products derived from this software without |
| 830 | prior written permission. For permission or any other legal |
| 831 | details, please contact |
| 832 | .display rm |
| 833 | Office of Technology Transfer |
| 834 | Carnegie Mellon University |
| 835 | 5000 Forbes Avenue |
| 836 | Pittsburgh, PA 15213-3890 |
| 837 | (412) 268-4387, fax: (412) 268-7395 |
| 838 | tech-transfer@@andrew.cmu.edu |
| 839 | .endd |
| 840 | .nextp |
| 841 | Redistributions of any form whatsoever must retain the following |
| 842 | acknowledgment: |
| 843 | .newline |
| 844 | .push |
| 845 | .indent ~~sys.indent + 3em |
| 846 | .justify left |
| 847 | $it{This product includes software developed by Computing Services |
| 848 | at Carnegie Mellon University (\?http://www.cmu.edu/computing/?\).} |
| 849 | .newline |
| 850 | .pop |
| 851 | .endp |
| 852 | .if ~~sgcal |
| 853 | .cancelflag $npbracket |
| 854 | .flag $npbracket "(" ")" |
| 855 | .fi |
| 856 | |
| 857 | CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO |
| 858 | THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY |
| 859 | AND FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE |
| 860 | FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES |
| 861 | WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN |
| 862 | AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING |
| 863 | OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. |
| 864 | .newline |
| 865 | .pop |
| 866 | .rule |
| 867 | |
| 868 | .space 1ld |
| 869 | .nextp |
| 870 | .index monitor |
| 871 | .index X-windows |
| 872 | .index Athena |
| 873 | The Exim Monitor program, which is an X-Window application, includes |
| 874 | modified versions of the Athena StripChart and TextPop widgets. |
| 875 | This code is copyright by DEC and MIT, and their permission notice appears |
| 876 | below, in accordance with the conditions expressed therein. |
| 877 | |
| 878 | .rule |
| 879 | .push |
| 880 | .if ~~sgcal |
| 881 | .fontgroup 9 |
| 882 | .font 0 |
| 883 | .fi |
| 884 | Copyright 1987, 1988 by Digital Equipment Corporation, Maynard, Massachusetts, |
| 885 | and the Massachusetts Institute of Technology, Cambridge, Massachusetts. |
| 886 | .blank |
| 887 | $c All Rights Reserved |
| 888 | .blank |
| 889 | Permission to use, copy, modify, and distribute this software and its |
| 890 | documentation for any purpose and without fee is hereby granted, |
| 891 | provided that the above copyright notice appear in all copies and that |
| 892 | both that copyright notice and this permission notice appear in |
| 893 | supporting documentation, and that the names of Digital or MIT not be |
| 894 | used in advertising or publicity pertaining to distribution of the |
| 895 | software without specific, written prior permission. |
| 896 | |
| 897 | DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING |
| 898 | ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL |
| 899 | DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR |
| 900 | ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, |
| 901 | WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, |
| 902 | ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS |
| 903 | SOFTWARE. |
| 904 | .newline |
| 905 | .pop |
| 906 | .rule |
| 907 | .endp |
| 908 | |
| 909 | |
| 910 | |
| 911 | . |
| 912 | . |
| 913 | . |
| 914 | . |
| 915 | . ============================================================================ |
| 916 | .chapter How Exim receives and delivers mail |
| 917 | .set runningfoot "receiving & delivering mail" |
| 918 | |
| 919 | .section Overall philosophy |
| 920 | .index design philosophy |
| 921 | Exim is designed to work efficiently on systems that are permanently connected |
| 922 | to the Internet and are handling a general mix of mail. In such circumstances, |
| 923 | most messages can be delivered immediately. Consequently, Exim does not |
| 924 | maintain independent queues of messages for specific domains or hosts, though |
| 925 | it does try to send several messages in a single SMTP connection after a host |
| 926 | has been down, and it also maintains per-host retry information. |
| 927 | |
| 928 | |
| 929 | .section Policy control |
| 930 | .index policy control||overview |
| 931 | Policy controls are now an important feature of MTAs that are connected to the |
| 932 | Internet. Perhaps their most important job is to stop MTAs being abused as |
| 933 | `open relays' by misguided individuals who send out vast amounts of unsolicited |
| 934 | junk, and want to disguise its source. Exim provides flexible facilities for |
| 935 | specifying policy controls on incoming mail: |
| 936 | .numberpars $. |
| 937 | .index ~~ACL||introduction |
| 938 | Exim 4 (unlike previous versions of Exim) implements policy controls on |
| 939 | incoming SMTP mail by means of \*Access Control Lists*\ (ACLs). Each list is a |
| 940 | series of statements that may either grant or deny access. ACLs can be used at |
| 941 | several places in the SMTP dialogue while receiving a message. However, the |
| 942 | most common places are after each \\RCPT\\ command, and at the very end of the |
| 943 | message. The sysadmin can specify conditions for accepting or rejecting |
| 944 | individual recipients or the entire message, respectively, at these two points |
| 945 | (see chapter ~~CHAPACL). Denial of access results in an SMTP error code. |
| 946 | .nextp |
| 947 | An ACL is also available for locally generated, non-SMTP messages. In this |
| 948 | case, the only available actions are to accept or deny the entire message. |
| 949 | .nextp |
| 950 | When a message has been received, either from a remote host or from the local |
| 951 | host, but before the final acknowledgement has been sent, a locally supplied C |
| 952 | function called \*local@_scan()*\ can be run to inspect the message and decide |
| 953 | whether to accept it or not (see chapter ~~CHAPlocalscan). If the message is |
| 954 | accepted, the list of recipients can be modified by the function. |
| 955 | .nextp |
| 956 | After a message has been accepted, a further checking mechanism is available in |
| 957 | the form of the $it{system filter} (see chapter ~~CHAPsystemfilter). This runs |
| 958 | at the start of every delivery process. |
| 959 | .endp |
| 960 | |
| 961 | .section User filters |
| 962 | .index filter||introduction |
| 963 | .index Sieve filter |
| 964 | In a conventional Exim configuration, users are able to run private filters by |
| 965 | setting up appropriate \(.forward)\ files in their home directories. See |
| 966 | chapter ~~CHAPredirect (about the \%redirect%\ router) for the configuration |
| 967 | needed to support this, and the separate document entitled |
| 968 | .if ~~html |
| 969 | [(A HREF="filter_toc.html")] |
| 970 | .fi |
| 971 | \*Exim's interfaces to mail filtering*\ |
| 972 | .if ~~html |
| 973 | [(/A)] |
| 974 | .fi |
| 975 | for user details. Two different kinds of filtering are available: |
| 976 | .numberpars $. |
| 977 | Sieve filters are written in the standard filtering language that is defined by |
| 978 | RFC 3028. |
| 979 | .nextp |
| 980 | Exim filters are written in a syntax that is unique to Exim, but which is more |
| 981 | powerful than Sieve, which it pre-dates. |
| 982 | .endp |
| 983 | User filters are run as part of the routing process, described below. |
| 984 | |
| 985 | |
| 986 | .section Message identification |
| 987 | .rset SECTmessiden "~~chapter.~~section" |
| 988 | .index message||ids, details of format |
| 989 | .index format||of message id |
| 990 | .index id of message |
| 991 | .index base62 |
| 992 | .index base36 |
| 993 | .index Darwin |
| 994 | .index Cygwin |
| 995 | Every message handled by Exim is given a \*message id*\ which is sixteen |
| 996 | characters long. It is divided into three parts, separated by hyphens, for |
| 997 | example \"16VDhn-0001bo-D3"\. Each part is a sequence of letters and digits, |
| 998 | normally encoding numbers in base 62. However, in the Darwin operating |
| 999 | system (Mac OS X) and when Exim is compiled to run under Cygwin, base 36 |
| 1000 | (avoiding the use of lower case letters) is used instead, because the message |
| 1001 | id is used to construct file names, and the names of files in those systems are |
| 1002 | not case-sensitive. |
| 1003 | |
| 1004 | .index pid (process id)||re-use of |
| 1005 | The detail of the contents of the message id have changed as Exim has evolved. |
| 1006 | Earlier versions relied on the operating system not re-using a process id (pid) |
| 1007 | within one second. On modern operating systems, this assumption can no longer |
| 1008 | be made, so the algorithm had to be changed. To retain backward compatibility, |
| 1009 | the format of the message id was retained, which is why the following rules are |
| 1010 | somewhat eccentric: |
| 1011 | .numberpars $. |
| 1012 | The first six characters of the message id are the time at which the message |
| 1013 | started to be received, to a granularity of one second. That is, this field |
| 1014 | contains the number of seconds since the start of the epoch (the normal Unix |
| 1015 | way of representing the date and time of day). |
| 1016 | .nextp |
| 1017 | After the first hyphen, the next six characters are the id of the process that |
| 1018 | received the message. |
| 1019 | .nextp |
| 1020 | There are two different possibilities for the final two characters: |
| 1021 | .numberpars alpha |
| 1022 | .index \localhost@_number\ |
| 1023 | If \localhost@_number\ is not set, this value is the fractional part of the |
| 1024 | time of reception, normally in units of 1/2000 of a second, but for systems |
| 1025 | that must use base 36 instead of base 62 (because of case-insensitive file |
| 1026 | systems), the units are 1/1000 of a second. |
| 1027 | .nextp |
| 1028 | If \localhost@_number\ is set, it is multiplied by 200 (100) and added to |
| 1029 | the fractional part of the time, which in this case is in units of 1/200 |
| 1030 | (1/100) of a second. |
| 1031 | .endp |
| 1032 | .endp |
| 1033 | After a message has been received, Exim waits for the clock to tick at the |
| 1034 | appropriate resolution before proceeding, so that if another message is |
| 1035 | received by the same process, or by another process with the same (re-used) |
| 1036 | pid, it is guaranteed that the time will be different. In most cases, the clock |
| 1037 | will already have ticked while the message was being received. |
| 1038 | |
| 1039 | .section Receiving mail |
| 1040 | .index receiving mail |
| 1041 | .index message||reception |
| 1042 | The only way Exim can receive mail from a remote host is using SMTP over |
| 1043 | TCP/IP, in which case the sender and recipient addresses are tranferred using |
| 1044 | SMTP commands. However, from a locally running process (such as a user's MUA), |
| 1045 | there are several possibilities: |
| 1046 | .numberpars $. |
| 1047 | If the process runs Exim with the \-bm-\ option, the message is read |
| 1048 | non-interactively (usually via a pipe), with the recipients taken from the |
| 1049 | command line, or from the body of the message if \-t-\ is also used. |
| 1050 | .nextp |
| 1051 | If the process runs Exim with the \-bS-\ option, the message is also read |
| 1052 | non-interactively, but in this case the recipients are listed at the start of |
| 1053 | the message in a series of SMTP \\RCPT\\ commands, terminated by a \\DATA\\ |
| 1054 | command. This is so-called `batch SMTP' format, |
| 1055 | but it isn't really SMTP. The SMTP commands are just another way of passing |
| 1056 | envelope addresses in a non-interactive submission. |
| 1057 | .nextp |
| 1058 | If the process runs Exim with the \-bs-\ option, the message is read |
| 1059 | interactively, using the SMTP protocol. A two-way pipe is normally used for |
| 1060 | passing data between the local process and the Exim process. |
| 1061 | This is `real' SMTP and is handled in the same way as SMTP over TCP/IP. For |
| 1062 | example, the ACLs for SMTP commands are used for this form of submission. |
| 1063 | .nextp |
| 1064 | A local process may also make a TCP/IP call to the host's loopback address |
| 1065 | (127.0.0.1) or any other of its IP addresses. When receiving messages, Exim |
| 1066 | does not treat the loopback address specially. It treats all such connections |
| 1067 | in the same way as connections from other hosts. |
| 1068 | .endp |
| 1069 | |
| 1070 | .index message||sender, constructed by Exim |
| 1071 | .index sender||constructed by Exim |
| 1072 | In the three cases that do not involve TCP/IP, the sender address is |
| 1073 | constructed from the login name of the user that called Exim and a default |
| 1074 | qualification domain (which can be set by the \qualify@_domain\ configuration |
| 1075 | option). For local or batch SMTP, a sender address that is passed using the |
| 1076 | SMTP \\MAIL\\ command is ignored. However, the system administrator may allow |
| 1077 | certain users (`trusted users') to specify a different sender address |
| 1078 | unconditionally, or all users to specify certain forms of different sender |
| 1079 | address. The \-f-\ option or the SMTP \\MAIL\\ command is used to specify these |
| 1080 | different addresses. See section ~~SECTtrustedadmin for details of trusted |
| 1081 | users, and the \untrusted@_set@_sender\ option for a way of allowing untrusted |
| 1082 | users to change sender addresses. |
| 1083 | |
| 1084 | Messages received by either of the non-interactive mechanisms are subject to |
| 1085 | checking by the non-SMTP ACL, if one is defined. Messages received using SMTP |
| 1086 | (either over TCP/IP, or interacting with a local process) can be checked by a |
| 1087 | number of ACLs that operate at different times during the SMTP session. Either |
| 1088 | individual recipients, or the entire message, can be rejected if local policy |
| 1089 | requirements are not met. The \*local@_scan()*\ function (see chapter |
| 1090 | ~~CHAPlocalscan) is run for all incoming messages. |
| 1091 | |
| 1092 | Exim can be configured not to start a delivery process when a message is |
| 1093 | received; this can be unconditional, or depend on the number of incoming SMTP |
| 1094 | connections or the system load. In these situations, new messages wait on the |
| 1095 | queue until a queue runner process picks them up. However, in standard |
| 1096 | configurations under normal conditions, delivery is started as soon as a |
| 1097 | message is received. |
| 1098 | |
| 1099 | |
| 1100 | |
| 1101 | |
| 1102 | .section Handling an incoming message |
| 1103 | .index spool directory||files that hold a message |
| 1104 | .index file||how a message is held |
| 1105 | When Exim accepts a message, it writes two files in its spool directory. The |
| 1106 | first contains the envelope information, the current status of the message, |
| 1107 | and the header lines, and the second contains the body of the message. The |
| 1108 | names of the two spool files consist of the message id, followed by $tt{-H} for |
| 1109 | the file containing the envelope and header, and $tt{-D} for the data file. |
| 1110 | |
| 1111 | .index spool directory||\(input)\ sub-directory |
| 1112 | By default all these message files are held in a single directory called |
| 1113 | \(input)\ inside the general Exim spool directory. Some operating systems do |
| 1114 | not perform very well if the number of files in a directory gets very large; to |
| 1115 | improve performance in such cases, the \split@_spool@_directory\ option can be |
| 1116 | used. This causes Exim to split up the input files into 62 sub-directories |
| 1117 | whose names are single letters or digits. |
| 1118 | |
| 1119 | The envelope information consists of the address of the message's sender and |
| 1120 | the addresses of the recipients. This information is entirely separate from |
| 1121 | any addresses contained in the header lines. The status of the message includes |
| 1122 | a list of recipients who have already received the message. The format of the |
| 1123 | first spool file is described in chapter ~~CHAPspool. |
| 1124 | |
| 1125 | .index rewriting||addresses |
| 1126 | Address rewriting that is specified in the rewrite section of the configuration |
| 1127 | (see chapter ~~CHAPrewrite) is done once and for all on incoming addresses, |
| 1128 | both in the header lines and the envelope, at the time the message is accepted. |
| 1129 | If during the course of delivery additional addresses are generated (for |
| 1130 | example, via aliasing), these new addresses are rewritten as soon as they are |
| 1131 | generated. At the time a message is actually delivered (transported) further |
| 1132 | rewriting can take place; because this is a transport option, it can be |
| 1133 | different for different forms of delivery. It is also possible to specify the |
| 1134 | addition or removal of certain header lines at the time the message is |
| 1135 | delivered (see chapters ~~CHAProutergeneric and ~~CHAPtransportgeneric). |
| 1136 | |
| 1137 | |
| 1138 | .section Life of a message |
| 1139 | .index message||life of |
| 1140 | .index message||frozen |
| 1141 | A message remains in the spool directory until it is completely delivered to |
| 1142 | its recipients or to an error address, or until it is deleted by an |
| 1143 | administrator or by the user who originally created it. In cases when delivery |
| 1144 | cannot proceed -- for example, when a message can neither be delivered to its |
| 1145 | recipients nor returned to its sender, the message is marked `frozen' on the |
| 1146 | spool, and no more deliveries are attempted. |
| 1147 | |
| 1148 | .index frozen messages||thawing |
| 1149 | .index message||thawing frozen |
| 1150 | An administrator can `thaw' such messages when the problem has been corrected, |
| 1151 | and can also freeze individual messages by hand if necessary. In addition, an |
| 1152 | administrator can force a delivery error, causing a bounce message to be sent. |
| 1153 | |
| 1154 | .index \auto@_thaw\ |
| 1155 | There is an option called \auto@_thaw\, which can be used to cause Exim to |
| 1156 | retry frozen messages after a certain time. When this is set, no message will |
| 1157 | remain on the queue for ever, because the delivery timeout will eventually be |
| 1158 | reached. Delivery failure reports (bounce messages) that reach this timeout are |
| 1159 | discarded. |
| 1160 | .index \timeout@_frozen@_after\ |
| 1161 | There is also an option called \timeout@_frozen@_after\, which discards frozen |
| 1162 | messages after a certain time. |
| 1163 | |
| 1164 | .index message||log file for |
| 1165 | .index log||file for each message |
| 1166 | While Exim is working on a message, it writes information about each delivery |
| 1167 | attempt to the main log file. This includes successful, unsuccessful, and |
| 1168 | delayed deliveries for each recipient (see chapter ~~CHAPlog). The log lines |
| 1169 | are also written to a separate $it{message log} file for each message. These |
| 1170 | logs are solely for the benefit of the administrator, and are normally deleted |
| 1171 | along with the spool files when processing of a message is complete. |
| 1172 | The use of individual message logs can be disabled by setting |
| 1173 | \no@_message@_logs\; this might give an improvement in performance on very |
| 1174 | busy systems. |
| 1175 | |
| 1176 | .index journal file |
| 1177 | .index file||journal |
| 1178 | All the information Exim itself needs to set up a delivery is kept in the first |
| 1179 | spool file, along with the header lines. When a successful delivery occurs, the |
| 1180 | address is immediately written at the end of a journal file, whose name is the |
| 1181 | message id followed by $tt{-J}. At the end of a delivery run, if there are some |
| 1182 | addresses left to be tried again later, the first spool file (the $tt{-H} file) |
| 1183 | is updated to indicate which these are, and the journal file is then deleted. |
| 1184 | Updating the spool file is done by writing a new file and renaming it, to |
| 1185 | minimize the possibility of data loss. |
| 1186 | |
| 1187 | Should the system or the program crash after a successful delivery but before |
| 1188 | the spool file has been updated, the journal is left lying around. The next |
| 1189 | time Exim attempts to deliver the message, it reads the journal file and |
| 1190 | updates the spool file before proceeding. This minimizes the chances of double |
| 1191 | deliveries caused by crashes. |
| 1192 | |
| 1193 | |
| 1194 | .section Processing an address for delivery |
| 1195 | .rset SECTprocaddress "~~chapter.~~section" |
| 1196 | .index drivers||definition of |
| 1197 | .index router||definition of |
| 1198 | .index transport||definition of |
| 1199 | The main delivery processing elements of Exim are called $it{routers} and |
| 1200 | $it{transports}, and collectively these are known as $it{drivers}. Code for a |
| 1201 | number of them is provided in the source distribution, and compile-time options |
| 1202 | specify which ones are included in the binary. Run time options specify which |
| 1203 | ones are actually used for delivering messages. |
| 1204 | |
| 1205 | .index drivers||instance definition |
| 1206 | Each driver that is specified in the run time configuration is an \*instance*\ |
| 1207 | of that particular driver type. Multiple instances are allowed; for example, |
| 1208 | you can set up several different \%smtp%\ transports, each with different |
| 1209 | option values that might specify different ports or different timeouts. Each |
| 1210 | instance has its own identifying name. In what follows we will normally use the |
| 1211 | instance name when discussing one particular instance (that is, one specific |
| 1212 | configuration of the driver), and the generic driver name when discussing |
| 1213 | the driver's features in general. |
| 1214 | |
| 1215 | A $it{router} is a driver that operates on an address, either determining how |
| 1216 | its delivery should happen, by routing it to a specific transport, or |
| 1217 | converting the address into one or more new addresses (for example, via an |
| 1218 | alias file). A router may also explicitly choose to fail an address, causing it |
| 1219 | to be bounced. |
| 1220 | |
| 1221 | A $it{transport} is a driver that transmits a copy of the message from Exim's |
| 1222 | spool to some destination. There are two kinds of transport: for a $it{local} |
| 1223 | transport, the destination is a file or a pipe on the local host, whereas for a |
| 1224 | $it{remote} transport the destination is some other host. A message is passed |
| 1225 | to a specific transport as a result of successful routing. If a message has |
| 1226 | several recipients, it may be passed to a number of different transports. |
| 1227 | |
| 1228 | .index preconditions||definition of |
| 1229 | An address is processed by passing it to each configured router instance in |
| 1230 | turn, subject to certain preconditions, until a router accepts the address or |
| 1231 | specifies that it should be bounced. We will describe this process in more |
| 1232 | detail shortly. As a simple example, the diagram below illustrates how each |
| 1233 | recipient address in a message is processed in a small configuration of three |
| 1234 | routers that are configured in various ways. |
| 1235 | |
| 1236 | .if ~~sys.fancy |
| 1237 | .figure "Routing an address" rm |
| 1238 | .indent 0 |
| 1239 | .call aspic -sgcal -nv |
| 1240 | centre ~~sys.linelength; |
| 1241 | magnify 0.8; |
| 1242 | boundingbox 30; |
| 1243 | ibox depth 14 "address"; |
| 1244 | B: arrow down 44; |
| 1245 | textdepth 14; |
| 1246 | A: box width 100 "first router" "conditions ok?"; |
| 1247 | arrow right "yes"; |
| 1248 | C: box width 100 "run" "first router"; |
| 1249 | arrow down "fail"; |
| 1250 | D: ibox depth 20 "address bounces"; |
| 1251 | |
| 1252 | arc clockwise from right of C "accept"; |
| 1253 | arrow down 10; |
| 1254 | ibox "queue for" "transport"; |
| 1255 | |
| 1256 | arrow down from A align bottom of D plus (0,-20) "no"(-6,20)/r; |
| 1257 | E: box width 100 "second router" "conditions ok?"; |
| 1258 | arrow right "yes"; |
| 1259 | F: box width 100 "run" "second router"; |
| 1260 | line right 100 "redirect"; |
| 1261 | line up align middle of B; |
| 1262 | arrow left to middle of B "new addresses"; |
| 1263 | |
| 1264 | line down 20 from bottom left of F plus (30,0); |
| 1265 | arrow left align centre of E "decline"; |
| 1266 | |
| 1267 | line down 20 from bottom right of F plus (-30,0); |
| 1268 | arrow right "fail"; |
| 1269 | ibox width 64 "address" "bounces"; |
| 1270 | |
| 1271 | arrow down 64 from E "no"(-6,20)/r; |
| 1272 | G: box width 100 "third router" "conditions ok?"; |
| 1273 | arrow right "yes"; |
| 1274 | H: box width 100 "run" "third router"; |
| 1275 | arc clockwise from right of H "accept"; |
| 1276 | arrow down 10; |
| 1277 | ibox "queue for" "transport"; |
| 1278 | |
| 1279 | line down 20 from bottom of H; |
| 1280 | arrow left align centre of G "decline"; |
| 1281 | arrow down 64 from G "no"(-6,20)/r; |
| 1282 | |
| 1283 | ibox "no more routers" "address bounces"; |
| 1284 | .endcall |
| 1285 | .endfigure |
| 1286 | .elif !~~html |
| 1287 | .display asis |
| 1288 | |
| 1289 | address |
| 1290 | | |
| 1291 | |<------------- new addresses ----------------------------- |
| 1292 | V | |
| 1293 | ----------------- ----------------- | |
| 1294 | | first router |----- yes ----->| run |--- accept | |
| 1295 | | conditions ok?| | first router | | | |
| 1296 | ----------------- ----------------- | | |
| 1297 | | | V | |
| 1298 | no | fail | queue for | |
| 1299 | | V transport | |
| 1300 | | address bounces | |
| 1301 | | | |
| 1302 | V | |
| 1303 | ----------------- ----------------- | |
| 1304 | | second router |----- yes ----->| run |----redirect ---- |
| 1305 | | conditions ok?| | second router | |
| 1306 | ----------------- ----------------- |
| 1307 | | | | |
| 1308 | no | | | |
| 1309 | |<-------- decline ----------- --- fail ---> address |
| 1310 | | bounces |
| 1311 | V |
| 1312 | ----------------- ----------------- |
| 1313 | | third router |----- yes ----->| run |--- accept |
| 1314 | | conditions ok?| | third router | | |
| 1315 | ----------------- ----------------- | |
| 1316 | | | V |
| 1317 | no | | queue for |
| 1318 | |<-------- decline --------------- transport |
| 1319 | | |
| 1320 | V |
| 1321 | no more routers |
| 1322 | address bounces |
| 1323 | .endd |
| 1324 | .else |
| 1325 | [(img src="routing.gif" alt="Routing an address")][(br)] |
| 1326 | .fi |
| 1327 | To make this a more concrete example, we'll describe it in terms of some actual |
| 1328 | routers, but remember, this is only an example. You can configure Exim's |
| 1329 | routers in many different ways, and there may be any number of routers in a |
| 1330 | configuration. |
| 1331 | |
| 1332 | The first router that is specified in a configuration is often one that handles |
| 1333 | addresses in domains that are not recognized specially by the local host. These |
| 1334 | are typically addresses for arbitrary domains on the Internet. A precondition |
| 1335 | is set up which looks for the special domains known to the host (for example, |
| 1336 | its own domain name), and the router is run for addresses that do $it{not} |
| 1337 | match. Typically, this is a router that looks up domains in the DNS in order to |
| 1338 | find the hosts to which this address routes. If it succeeds, the address is |
| 1339 | queued for a suitable SMTP transport; if it does not succeed, the router is |
| 1340 | configured to fail the address. |
| 1341 | |
| 1342 | The example pictured could be a configuration of this type. The second and |
| 1343 | third routers can only be run for addresses for which the preconditions for |
| 1344 | the first router are not met. If one of these preconditions checks the |
| 1345 | domain, the second and third routers are run only for domains that are somehow |
| 1346 | special to the local host. |
| 1347 | |
| 1348 | The second router does redirection -- also known as aliasing and forwarding. |
| 1349 | When it generates one or more new addresses from the original, each of them is |
| 1350 | routed independently from the start. Otherwise, the router may cause an address |
| 1351 | to fail, or it may simply decline to handle the address, in which case the |
| 1352 | address is passed to the next router. |
| 1353 | |
| 1354 | The final router in many configurations is one that checks to see if the |
| 1355 | address belongs to a local mailbox. The precondition may involve a check to |
| 1356 | see if the local part is the name of a login account, or it may look up the |
| 1357 | local part in a file or a database. If its preconditions are not met, or if |
| 1358 | the router declines, we have reached the end of the routers. When this happens, |
| 1359 | the address is bounced. |
| 1360 | |
| 1361 | |
| 1362 | .section Processing an address for verification |
| 1363 | .index router||for verification |
| 1364 | .index verifying||address, overview |
| 1365 | As well as being used to decide how to deliver to an address, Exim's routers |
| 1366 | are also used for \*address verification*\. Verification can be requested as |
| 1367 | one of the checks to be performed in an ACL for incoming messages, on both |
| 1368 | sender and recipient addresses, and it can be tested using the \-bv-\ and |
| 1369 | \-bvs-\ command line options. |
| 1370 | |
| 1371 | When an address is being verified, the routers are run in `verify mode'. This |
| 1372 | does not affect the way the routers work, but it is a state that can be |
| 1373 | detected. By this means, a router can be skipped or made to behave differently |
| 1374 | when verifying. A common example is a configuration in which the first router |
| 1375 | sends all messages to a message-scanning program, unless they have been |
| 1376 | previously scanned. Thus, the first router accepts all addresses without any |
| 1377 | checking, making it useless for verifying. Normally, the \no@_verify\ option |
| 1378 | would be set for such a router, causing it to be skipped in verify mode. |
| 1379 | |
| 1380 | |
| 1381 | |
| 1382 | .section Running an individual router |
| 1383 | .rset SECTrunindrou "~~chapter.~~section" |
| 1384 | .index router||running details |
| 1385 | .index preconditions||checking |
| 1386 | .index router||result of running |
| 1387 | As explained in the example above, a number of preconditions are checked before |
| 1388 | running a router. If any are not met, the router is skipped, and the address is |
| 1389 | passed to the next router. When all the preconditions on a router $it{are} met, |
| 1390 | the router is run. What happens next depends on the outcome, which is one of |
| 1391 | the following: |
| 1392 | .numberpars $. |
| 1393 | \*accept*\: The router accepts the address, and either queues it for a |
| 1394 | transport, or generates one or more `child' addresses. Processing the original |
| 1395 | address ceases, |
| 1396 | .index \unseen\ option |
| 1397 | unless the \unseen\ option is set on the router. This option |
| 1398 | can be used to set up multiple deliveries with different routing (for example, |
| 1399 | for keeping archive copies of messages). When \unseen\ is set, the address is |
| 1400 | passed to the next router. Normally, however, an \*accept*\ return marks the |
| 1401 | end of routing. |
| 1402 | |
| 1403 | .index case of local parts |
| 1404 | .index address||duplicate, discarding |
| 1405 | If child addresses are generated, Exim checks to see whether they are |
| 1406 | duplicates of any existing recipient addresses. During this check, local parts |
| 1407 | are treated as case-sensitive. Duplicate addresses are discarded. Each of the |
| 1408 | remaining child addresses is then processed independently, starting with the |
| 1409 | first router by default. It is possible to change this by setting the |
| 1410 | \redirect@_router\ option to specify which router to start at for child |
| 1411 | addresses. Unlike \pass@_router\ (see below) the router specified by |
| 1412 | \redirect@_router\ may be anywhere in the router configuration. |
| 1413 | .nextp |
| 1414 | \*pass*\: The router recognizes the address, but cannot handle it itself. It |
| 1415 | requests that the address be passed to another router. By default the address |
| 1416 | is passed to the next router, but this can be changed by setting the |
| 1417 | \pass@_router\ option. However, (unlike \redirect@_router\) the named router |
| 1418 | must be below the current router (to avoid loops). |
| 1419 | .nextp |
| 1420 | \*decline*\: The router declines to accept the address because it does not |
| 1421 | recognize it at all. By default, the address is passed to the next router, but |
| 1422 | this can be prevented by setting the \no@_more\ option. When \no@_more\ is set, |
| 1423 | all the remaining routers are skipped. |
| 1424 | .nextp |
| 1425 | \*fail*\: The router determines that the address should fail, and queues it for |
| 1426 | the generation of a bounce message. There is no further processing of the |
| 1427 | original address unless \unseen\ is set on the router. |
| 1428 | .nextp |
| 1429 | \*defer*\: The router cannot handle the address at the present time. (A database |
| 1430 | may be offline, or a DNS lookup may have timed out.) No further processing of |
| 1431 | the address happens in this delivery attempt. It is tried again next time the |
| 1432 | message is considered for delivery. |
| 1433 | .nextp |
| 1434 | \*error*\: There is some error in the router (for example, a syntax error in |
| 1435 | its configuration). The action is as for defer. |
| 1436 | .endp |
| 1437 | If an address reaches the end of the routers without having been accepted by |
| 1438 | any of them, it is bounced as unrouteable. |
| 1439 | The default error message in this situation is `unrouteable address', but you |
| 1440 | can set your own message by making use of the \cannot@_route@_message\ option. |
| 1441 | This can be set for any router; the value from the last router that `saw' |
| 1442 | the address is used. |
| 1443 | |
| 1444 | Sometimes while routing you want to fail a delivery when some conditions are |
| 1445 | met but others are not, instead of passing the address on for further routing. |
| 1446 | You can do this by having a second router that explicitly fails the delivery |
| 1447 | when the relevant conditions are met. The \%redirect%\ router has a `fail' |
| 1448 | facility for this purpose. |
| 1449 | |
| 1450 | |
| 1451 | |
| 1452 | .section Router preconditions |
| 1453 | .rset SECTrouprecon "~~chapter.~~section" |
| 1454 | .index router||preconditions, order of processing |
| 1455 | .index preconditions||order of processing |
| 1456 | The preconditions that are tested for each router are listed below, in the |
| 1457 | order in which they are tested. The individual configuration options are |
| 1458 | described in more detail in chapter ~~CHAProutergeneric. |
| 1459 | .numberpars $. |
| 1460 | The \local@_part@_prefix\ and \local@_part@_suffix\ options can specify that |
| 1461 | the local parts handled by the router may or must have certain prefixes and/or |
| 1462 | suffixes. If a mandatory affix (prefix or suffix) is not present, the router is |
| 1463 | skipped. These conditions are tested first. When an affix is present, it is |
| 1464 | removed from the local part before further processing, including the evaluation |
| 1465 | of any other conditions. |
| 1466 | .nextp |
| 1467 | Routers can be designated for use only when not verifying an address, that is, |
| 1468 | only when routing it for delivery (or testing its delivery routing). If the |
| 1469 | \verify\ option is set false, the router is skipped when Exim is verifying an |
| 1470 | address. |
| 1471 | Setting the \verify\ option actually sets two options, \verify@_sender\ and |
| 1472 | \verify@_recipient\, which independently control the use of the router for |
| 1473 | sender and recipient verification. You can set these options directly if |
| 1474 | you want a router to be used for only one type of verification. |
| 1475 | .nextp |
| 1476 | If the \address@_test\ option is set false, the router is skipped when Exim is |
| 1477 | run with the \-bt-\ option to test an address routing. This can be helpful when |
| 1478 | the first router sends all new messages to a scanner of some sort; it makes it |
| 1479 | possible to use \-bt-\ to test subsequent delivery routing without having to |
| 1480 | simulate the effect of the scanner. |
| 1481 | .nextp |
| 1482 | Routers can be designated for use only when verifying an address, as |
| 1483 | opposed to routing it for delivery. The \verify@_only\ option controls this. |
| 1484 | .nextp |
| 1485 | Certain routers can be explicitly skipped when running the routers to check an |
| 1486 | address given in the SMTP \\EXPN\\ command (see the \expn\ option). |
| 1487 | .nextp |
| 1488 | If the \domains\ option is set, the domain of the address must be in the set of |
| 1489 | domains that it defines. |
| 1490 | .nextp |
| 1491 | If the \local@_parts\ option is set, the local part of the address must be in |
| 1492 | the set of local parts that it defines. If \local@_part@_prefix\ or |
| 1493 | \local@_part@_suffix\ is in use, the prefix or suffix is removed from the local |
| 1494 | part before this check. If you want to do precondition tests on local parts |
| 1495 | that include affixes, you can do so by using a \condition\ option (see below) |
| 1496 | that uses the variables \$local@_part$\, \$local@_part@_prefix$\, and |
| 1497 | \$local@_part@_suffix$\ as necessary. |
| 1498 | .nextp |
| 1499 | If the \check@_local@_user\ option is set, the local part must be the name of |
| 1500 | an account on the local host. |
| 1501 | If this check succeeds, the uid and gid of the local user are placed in |
| 1502 | \$local@_user@_uid$\ and \$local@_user@_gid$\; these values can be used in the |
| 1503 | remaining preconditions. |
| 1504 | .nextp |
| 1505 | If the \router@_home@_directory\ option is set, it is expanded at this point, |
| 1506 | because it overrides the value of \$home$\. If this expansion were left till |
| 1507 | later, the value of \$home$\ as set by \check@_local@_user\ would be used in |
| 1508 | subsequent tests. Having two different values of \$home$\ in the same router |
| 1509 | could lead to confusion. |
| 1510 | .nextp |
| 1511 | If the \senders\ option is set, the envelope sender address must be in the set |
| 1512 | of addresses that it defines. |
| 1513 | .nextp |
| 1514 | If the \require@_files\ option is set, the existence or non-existence of |
| 1515 | specified files is tested. |
| 1516 | .nextp |
| 1517 | .index customizing||precondition |
| 1518 | If the \condition\ option is set, it is evaluated and tested. This option uses |
| 1519 | an expanded string to allow you to set up your own custom preconditions. |
| 1520 | Expanded strings are described in chapter ~~CHAPexpand. |
| 1521 | .endp |
| 1522 | |
| 1523 | Note that \require@_files\ comes near the end of the list, so you cannot use it |
| 1524 | to check for the existence of a file in which to lookup up a domain, local |
| 1525 | part, or sender. However, as these options are all expanded, you can use the |
| 1526 | \exists\ expansion condition to make such tests within each condition. The |
| 1527 | \require@_files\ option is intended for checking files that the router may be |
| 1528 | going to use internally, or which are needed by a specific transport (for |
| 1529 | example, \(.procmailrc)\). |
| 1530 | |
| 1531 | |
| 1532 | .section Delivery in detail |
| 1533 | .index delivery||in detail |
| 1534 | When a message is to be delivered, the sequence of events is as follows: |
| 1535 | .numberpars $. |
| 1536 | If a system-wide filter file is specified, the message is passed to it. The |
| 1537 | filter may add recipients to the message, replace the recipients, discard the |
| 1538 | message, cause a new message to be generated, or cause the message delivery to |
| 1539 | fail. The format of the system filter file is the same as for Exim user filter |
| 1540 | files, described in the separate document entitled |
| 1541 | .if ~~html |
| 1542 | [(A HREF="filter.html")] |
| 1543 | .fi |
| 1544 | \*Exim's interfaces to mail filtering*\. |
| 1545 | .if ~~html |
| 1546 | [(/A)] |
| 1547 | .fi |
| 1548 | .index Sieve filter||not available for system filter |
| 1549 | (\**Note**\: Sieve cannot be used for system filter files.) |
| 1550 | Some additional features are available in system filters -- see chapter |
| 1551 | ~~CHAPsystemfilter for details. Note that a message is passed to the system |
| 1552 | filter only once per delivery attempt, however many recipients it has. However, |
| 1553 | if there are several delivery attempts because one or more addresses could not |
| 1554 | be immediately delivered, the system filter is run each time. The filter |
| 1555 | condition \first@_delivery\ can be used to detect the first run of the system |
| 1556 | filter. |
| 1557 | .nextp |
| 1558 | Each recipient address is offered to each configured router in turn, subject to |
| 1559 | its preconditions, until one is able to handle it. If no router can handle |
| 1560 | the address, that is, if they all decline, the address is failed. Because |
| 1561 | routers can be targeted at particular domains, several locally handled domains |
| 1562 | can be processed entirely independently of each other. |
| 1563 | .nextp |
| 1564 | .index routing||loops in |
| 1565 | .index loop||while routing |
| 1566 | A router that accepts an address may set up a local or a remote transport for |
| 1567 | it. However, the transport is not run at this time. Instead, the address is |
| 1568 | placed on a list for the particular transport, to be run later. Alternatively, |
| 1569 | the router may generate one or more new addresses (typically from alias, |
| 1570 | forward, or filter files). New addresses are fed back into this process from |
| 1571 | the top, but in order to avoid loops, a router ignores any address which has an |
| 1572 | identically-named ancestor that was processed by itself. |
| 1573 | .nextp |
| 1574 | When all the routing has been done, addresses that have been successfully |
| 1575 | handled are passed to their assigned transports. When local transports are |
| 1576 | doing real local deliveries, they handle only one address at a time, but if a |
| 1577 | local transport is being used as a pseudo-remote transport (for example, to |
| 1578 | collect batched SMTP messages for transmission by some other means) multiple |
| 1579 | addresses can be handled. Remote transports can always handle more than one |
| 1580 | address at a time, but can be configured not to do so, or to restrict multiple |
| 1581 | addresses to the same domain. |
| 1582 | .nextp |
| 1583 | Each local delivery to a file or a pipe runs in a separate process under a |
| 1584 | non-privileged uid, and these deliveries are run one at a time. Remote |
| 1585 | deliveries also run in separate processes, normally under a uid that is private |
| 1586 | to Exim (`the Exim user'), but in this case, several remote deliveries can be |
| 1587 | run in parallel. The maximum number of simultaneous remote deliveries for any |
| 1588 | one message is set by the \remote@_max@_parallel\ option. |
| 1589 | The order in which deliveries are done is not defined, except that all local |
| 1590 | deliveries happen before any remote deliveries. |
| 1591 | .nextp |
| 1592 | .index queue runner |
| 1593 | When it encounters a local delivery during a queue run, Exim checks its retry |
| 1594 | database to see if there has been a previous temporary delivery failure for the |
| 1595 | address before running the local transport. If there was a previous failure, |
| 1596 | Exim does not attempt a new delivery until the retry time for the address is |
| 1597 | reached. However, this happens only for delivery attempts that are part of a |
| 1598 | queue run. Local deliveries are always attempted when delivery immediately |
| 1599 | follows message reception, even if retry times are set for them. This makes for |
| 1600 | better behaviour if one particular message is causing problems (for example, |
| 1601 | causing quota overflow, or provoking an error in a filter file). |
| 1602 | .nextp |
| 1603 | .index delivery||retry in remote transports |
| 1604 | Remote transports do their own retry handling, since an address may be |
| 1605 | deliverable to one of a number of hosts, each of which may have a different |
| 1606 | retry time. If there have been previous temporary failures and no host has |
| 1607 | reached its retry time, no delivery is attempted, whether in a queue run or |
| 1608 | not. See chapter ~~CHAPretry for details of retry strategies. |
| 1609 | .nextp |
| 1610 | If there were any permanent errors, a bounce message is returned to an |
| 1611 | appropriate address (the sender in the common case), with details of the error |
| 1612 | for each failing address. Exim can be configured to send copies of bounce |
| 1613 | messages to other addresses. |
| 1614 | .nextp |
| 1615 | .index delivery||deferral |
| 1616 | If one or more addresses suffered a temporary failure, the message is left on |
| 1617 | the queue, to be tried again later. Delivery of these addresses is said to be |
| 1618 | \*deferred*\. |
| 1619 | .nextp |
| 1620 | When all the recipient addresses have either been delivered or bounced, |
| 1621 | handling of the message is complete. The spool files and message log are |
| 1622 | deleted, though the message log can optionally be preserved if required. |
| 1623 | .endp |
| 1624 | |
| 1625 | |
| 1626 | .section Retry mechanism |
| 1627 | .index delivery||retry mechanism |
| 1628 | .index retry||description of mechanism |
| 1629 | .index queue runner |
| 1630 | Exim's mechanism for retrying messages that fail to get delivered at the first |
| 1631 | attempt is the queue runner process. You must either run an Exim daemon that |
| 1632 | uses the \-q-\ option with a time interval to start queue runners at regular |
| 1633 | intervals, or use some other means (such as \*cron*\) to start them. If you do |
| 1634 | not arrange for queue runners to be run, messages that fail temporarily at the |
| 1635 | first attempt will remain on your queue for ever. A queue runner process works |
| 1636 | it way through the queue, one message at a time, trying each delivery that has |
| 1637 | passed its retry time. |
| 1638 | You can run several queue runners at once. |
| 1639 | |
| 1640 | Exim uses a set of configured rules to determine when next to retry the failing |
| 1641 | address (see chapter ~~CHAPretry). These rules also specify when Exim should |
| 1642 | give up trying to deliver to the address, at which point it generates a bounce |
| 1643 | message. If no retry rules are set for a particular host, address, and error |
| 1644 | combination, no retries are attempted, and temporary errors are treated as |
| 1645 | permanent. |
| 1646 | |
| 1647 | |
| 1648 | .section Temporary delivery failure |
| 1649 | .index delivery||temporary failure |
| 1650 | There are many reasons why a message may not be immediately deliverable to a |
| 1651 | particular address. Failure to connect to a remote machine (because it, or the |
| 1652 | connection to it, is down) is one of the most common. Temporary failures may be |
| 1653 | detected during routing as well as during the transport stage of delivery. |
| 1654 | Local deliveries may be delayed if NFS files are unavailable, or if a mailbox |
| 1655 | is on a file system where the user is over quota. Exim can be configured to |
| 1656 | impose its own quotas on local mailboxes; where system quotas are set they will |
| 1657 | also apply. |
| 1658 | |
| 1659 | If a host is unreachable for a period of time, a number of messages may be |
| 1660 | waiting for it by the time it recovers, and sending them in a single SMTP |
| 1661 | connection is clearly beneficial. Whenever a delivery to a remote host is |
| 1662 | deferred, |
| 1663 | .index hints database |
| 1664 | Exim makes a note in its hints database, and whenever a successful |
| 1665 | SMTP delivery has happened, it looks to see if any other messages are waiting |
| 1666 | for the same host. If any are found, they are sent over the same SMTP |
| 1667 | connection, subject to a configuration limit as to the maximum number in any |
| 1668 | one connection. |
| 1669 | |
| 1670 | |
| 1671 | |
| 1672 | .section Permanent delivery failure |
| 1673 | .index delivery||permanent failure |
| 1674 | .index bounce message||when generated |
| 1675 | When a message cannot be delivered to some or all of its intended recipients, a |
| 1676 | bounce message is generated. Temporary delivery failures turn into permanent |
| 1677 | errors when their timeout expires. All the addresses that fail in a given |
| 1678 | delivery attempt are listed in a single message. If the original message has |
| 1679 | many recipients, it is possible for some addresses to fail in one delivery |
| 1680 | attempt and others to fail subsequently, giving rise to more than one bounce |
| 1681 | message. The wording of bounce messages can be customized by the administrator. |
| 1682 | See chapter ~~CHAPemsgcust for details. |
| 1683 | |
| 1684 | .index ::X-Failed-Recipients:: header line |
| 1685 | Bounce messages contain an ::X-Failed-Recipients:: header line that lists the |
| 1686 | failed addresses, for the benefit of programs that try to analyse such messages |
| 1687 | automatically. |
| 1688 | |
| 1689 | .index bounce message||recipient of |
| 1690 | A bounce message is normally sent to the sender of the original message, as |
| 1691 | obtained from the message's envelope. For incoming SMTP messages, this is the |
| 1692 | address given in the \\MAIL\\ command. However, when an address is |
| 1693 | expanded via a forward or alias file, an alternative address can be specified |
| 1694 | for delivery failures of the generated addresses. For a mailing list expansion |
| 1695 | (see section ~~SECTmailinglists) it is common to direct bounce messages to the |
| 1696 | manager of the list. |
| 1697 | |
| 1698 | |
| 1699 | |
| 1700 | .section Failures to deliver bounce messages |
| 1701 | .index bounce message||failure to deliver |
| 1702 | If a bounce message (either locally generated or received from a remote host) |
| 1703 | itself suffers a permanent delivery failure, the message is left on the queue, |
| 1704 | but it is frozen, awaiting the attention of an administrator. There are options |
| 1705 | which can be used to make Exim discard such failed messages, or to keep them |
| 1706 | for only a short time (see \timeout@_frozen@_after\ and |
| 1707 | \ignore@_bounce@_errors@_after\). |
| 1708 | |
| 1709 | |
| 1710 | |
| 1711 | . |
| 1712 | . |
| 1713 | . |
| 1714 | . |
| 1715 | . ============================================================================ |
| 1716 | .chapter Building and installing Exim |
| 1717 | .set runningfoot "building/installing" |
| 1718 | |
| 1719 | .index building Exim |
| 1720 | .section Unpacking |
| 1721 | Exim is distributed as a gzipped or bzipped tar file which, when upacked, |
| 1722 | creates a directory with the name of the current release (for example, |
| 1723 | \(exim-~~version)\) into which the following files are placed: |
| 1724 | .display rm |
| 1725 | .if !~~sys.fancy && ~~sgcal |
| 1726 | .tabs 16 |
| 1727 | .else |
| 1728 | .tabs 22 |
| 1729 | .fi |
| 1730 | \(ACKNOWLEDGMENTS)\ $t contains some acknowledgments |
| 1731 | .newline |
| 1732 | \(CHANGES)\ $t contains a reference to where changes are documented |
| 1733 | \(LICENCE)\ $t the GNU General Public Licence |
| 1734 | \(Makefile)\ $t top-level make file |
| 1735 | \(NOTICE)\ $t conditions for the use of Exim |
| 1736 | \(README)\ $t list of files, directories and simple build instructions |
| 1737 | .endd |
| 1738 | Other files whose names begin with \(README)\ may also be present. The |
| 1739 | following subdirectories are created: |
| 1740 | .display rm |
| 1741 | .if !~~sys.fancy && ~~sgcal |
| 1742 | .tabs 16 |
| 1743 | .else |
| 1744 | .tabs 22 |
| 1745 | .fi |
| 1746 | \(Local)\ $t an empty directory for local configuration files |
| 1747 | \(OS)\ $t OS-specific files |
| 1748 | \(doc)\ $t documentation files |
| 1749 | \(exim@_monitor)\$t source files for the Exim monitor |
| 1750 | \(scripts)\ $t scripts used in the build process |
| 1751 | \(src)\ $t remaining source files |
| 1752 | \(util)\ $t independent utilities |
| 1753 | .endd |
| 1754 | The main utility programs are contained in the \(src)\ directory, and are built |
| 1755 | with the Exim binary. The \(util)\ directory contains a few optional scripts |
| 1756 | that may be useful to some sites. |
| 1757 | |
| 1758 | .section Multiple machine architectures and operating systems |
| 1759 | .index building Exim||multiple OS/architectures |
| 1760 | The building process for Exim is arranged to make it easy to build binaries for |
| 1761 | a number of different architectures and operating systems from the same set of |
| 1762 | source files. Compilation does not take place in the \(src)\ directory. Instead, |
| 1763 | a \*build directory*\ is created for each architecture and operating system. |
| 1764 | .index symbolic link||to build directory |
| 1765 | Symbolic links to the sources are installed in this directory, which is where |
| 1766 | the actual building takes place. |
| 1767 | |
| 1768 | In most cases, Exim can discover the machine architecture and operating system |
| 1769 | for itself, but the defaults can be overridden if necessary. |
| 1770 | |
| 1771 | .section DBM libraries |
| 1772 | .rset SECTdb "~~chapter.~~section" |
| 1773 | .index DBM||libraries, discussion of |
| 1774 | .index hints database||DBM files used for |
| 1775 | Even if you do not use any DBM files in your configuration, Exim still needs a |
| 1776 | DBM library in order to operate, because it uses indexed files for its hints |
| 1777 | databases. Unfortunately, there are a number of DBM libraries in existence, and |
| 1778 | different operating systems often have different ones installed. |
| 1779 | |
| 1780 | .index Solaris||DBM library for |
| 1781 | .index IRIX, DBM library for |
| 1782 | .index BSD, DBM library for |
| 1783 | .index Linux, DBM library for |
| 1784 | If you are using Solaris, IRIX, one of the modern BSD systems, or a modern |
| 1785 | Linux distribution, the DBM configuration should happen automatically, and you |
| 1786 | may be able to ignore this section. Otherwise, you may have to learn more than |
| 1787 | you would like about DBM libraries from what follows. |
| 1788 | |
| 1789 | .index \*ndbm*\ DBM library |
| 1790 | Licensed versions of Unix normally contain a library of DBM functions operating |
| 1791 | via the \*ndbm*\ interface, and this is what Exim expects by default. Free |
| 1792 | versions of Unix seem to vary in what they contain as standard. In particular, |
| 1793 | some early versions of Linux have no default DBM library, and different |
| 1794 | distributors have chosen to bundle different libraries with their packaged |
| 1795 | versions. However, the more recent releases seem to have standardised on the |
| 1796 | Berkeley DB library. |
| 1797 | |
| 1798 | Different DBM libraries have different conventions for naming the files they |
| 1799 | use. When a program opens a file called \(dbmfile)\, there are four |
| 1800 | possibilities: |
| 1801 | .numberpars |
| 1802 | A traditional \*ndbm*\ implementation, such as that supplied as part of |
| 1803 | Solaris, operates on two files called \(dbmfile.dir)\ and \(dbmfile.pag)\. |
| 1804 | .nextp |
| 1805 | .index \*gdbm*\ DBM library |
| 1806 | The GNU library, \*gdbm*\, operates on a single file. If used via its \*ndbm*\ |
| 1807 | compatibility interface it makes two different hard links to it with names |
| 1808 | \(dbmfile.dir)\ and \(dbmfile.pag)\, but if used via its native interface, the |
| 1809 | file name is used unmodified. |
| 1810 | .nextp |
| 1811 | .index Berkeley DB library |
| 1812 | The Berkeley DB package, if called via its \*ndbm*\ compatibility interface, |
| 1813 | operates on a single file called \(dbmfile.db)\, but otherwise looks to the |
| 1814 | programmer exactly the same as the traditional \*ndbm*\ implementation. |
| 1815 | .nextp |
| 1816 | If the Berkeley package is used in its native mode, it operates on a single |
| 1817 | file called \(dbmfile)\; the programmer's interface is somewhat different to |
| 1818 | the traditional \*ndbm*\ interface. |
| 1819 | .nextp |
| 1820 | To complicate things further, there are several very different versions of the |
| 1821 | Berkeley DB package. Version 1.85 was stable for a very long time, releases |
| 1822 | 2.$it{x} and 3.$it{x} were current for a while, but the latest versions are now |
| 1823 | numbered 4.$it{x}. Maintenance of some of the earlier releases has ceased. All |
| 1824 | versions of Berkeley DB can be obtained from |
| 1825 | .display rm |
| 1826 | \?http://www.sleepycat.com/?\ |
| 1827 | .endd |
| 1828 | .nextp |
| 1829 | .index \*tdb*\ DBM library |
| 1830 | Yet another DBM library, called \*tdb*\, has become available from |
| 1831 | .display rm |
| 1832 | \?http://download.sourceforge.net/tdb?\ |
| 1833 | .endd |
| 1834 | It has its own interface, and also operates on a single file. |
| 1835 | .endp |
| 1836 | .index \\USE@_DB\\ |
| 1837 | .index DBM||libraries, configuration for building |
| 1838 | Exim and its utilities can be compiled to use any of these interfaces. In order |
| 1839 | to use any version of the Berkeley DB package in native mode, you must set |
| 1840 | \\USE@_DB\\ in an appropriate configuration file (typically |
| 1841 | \(Local/Makefile)\). For example: |
| 1842 | .display asis |
| 1843 | USE_DB=yes |
| 1844 | .endd |
| 1845 | Similarly, for gdbm you set \\USE@_GDBM\\, and for tdb you set \\USE@_TDB\\. An |
| 1846 | error is diagnosed if you set more than one of these. |
| 1847 | |
| 1848 | At the lowest level, the build-time configuration sets none of these options, |
| 1849 | thereby assuming an interface of type (1). However, some operating system |
| 1850 | configuration files (for example, those for the BSD operating systems and |
| 1851 | Linux) assume type (4) by setting \\USE@_DB\\ as their default, and the |
| 1852 | configuration files for Cygwin set \\USE@_GDBM\\. Anything you set in |
| 1853 | \(Local/Makefile)\, however, overrides these system defaults. |
| 1854 | |
| 1855 | As well as setting \\USE@_DB\\, \\USE@_GDBM\\, or \\USE@_TDB\\, it may also be |
| 1856 | necessary to set \\DBMLIB\\, to cause inclusion of the appropriate library, as |
| 1857 | in one of these lines: |
| 1858 | .display asis |
| 1859 | DBMLIB = -ldb |
| 1860 | DBMLIB = -ltdb |
| 1861 | .endd |
| 1862 | Settings like that will work if the DBM library is installed in the standard |
| 1863 | place. Sometimes it is not, and the library's header file may also not be in |
| 1864 | the default path. You may need to set \\INCLUDE\\ to specify where the header |
| 1865 | file is, and to specify the path to the library more fully in \\DBMLIB\\, as in |
| 1866 | this example: |
| 1867 | .display asis |
| 1868 | INCLUDE=-I/usr/local/include/db-4.1 |
| 1869 | DBMLIB=/usr/local/lib/db-4.1/libdb.a |
| 1870 | .endd |
| 1871 | |
| 1872 | There is further detailed discussion about the various DBM libraries in the |
| 1873 | file \(doc/dbm.discuss.txt)\ in the Exim distribution. |
| 1874 | |
| 1875 | |
| 1876 | .section Pre-building configuration |
| 1877 | .index building Exim||pre-building configuration |
| 1878 | .index configuration for building Exim |
| 1879 | .index \(Local/Makefile)\ |
| 1880 | .index \(src/EDITME)\ |
| 1881 | Before building Exim, a local configuration file that specifies options |
| 1882 | independent of any operating system has to be created with the name |
| 1883 | \(Local/Makefile)\. A template for this file is supplied as the file |
| 1884 | \(src/EDITME)\, and it contains full descriptions of all the option settings |
| 1885 | therein. These descriptions are therefore not repeated here. If you are |
| 1886 | building Exim for the first time, the simplest thing to do is to copy |
| 1887 | \(src/EDITME)\ to \(Local/Makefile)\, then read it and edit it appropriately. |
| 1888 | |
| 1889 | There are three settings that you must supply, because Exim will not build |
| 1890 | without them. They are the location of the run time configuration file |
| 1891 | (\\CONFIGURE@_FILE\\), the directory in which Exim binaries will be installed |
| 1892 | (\\BIN@_DIRECTORY\\), and the identity of the Exim user (\\EXIM@_USER\\ and |
| 1893 | maybe \\EXIM@_GROUP\\ as well). The value of \\CONFIGURE@_FILE\\ can in fact be |
| 1894 | a colon-separated list of file names; Exim uses the first of them that exists. |
| 1895 | |
| 1896 | There are a few other parameters that can be specified either at build time or |
| 1897 | at run time, to enable the same binary to be used on a number of different |
| 1898 | machines. However, if the locations of Exim's spool directory and log file |
| 1899 | directory (if not within the spool directory) are fixed, it is recommended that |
| 1900 | you specify them in \(Local/Makefile)\ instead of at run time, so that errors |
| 1901 | detected early in Exim's execution (such as a malformed configuration file) can |
| 1902 | be logged. |
| 1903 | |
| 1904 | .index \(Local/eximon.conf)\ |
| 1905 | .index \(exim@_monitor/EDITME)\ |
| 1906 | If you are going to build the Exim monitor, a similar configuration process is |
| 1907 | required. The file \(exim@_monitor/EDITME)\ must be edited appropriately for |
| 1908 | your installation and saved under the name \(Local/eximon.conf)\. If you are |
| 1909 | happy with the default settings described in \(exim@_monitor/EDITME)\, |
| 1910 | \(Local/eximon.conf)\ can be empty, but it must exist. |
| 1911 | |
| 1912 | This is all the configuration that is needed in straightforward cases for known |
| 1913 | operating systems. However, the building process is set up so that it is easy |
| 1914 | to override options that are set by default or by operating-system-specific |
| 1915 | configuration files, for example to change the name of the C compiler, which |
| 1916 | defaults to \gcc\. See section ~~SECToverride below for details of how to do |
| 1917 | this. |
| 1918 | |
| 1919 | |
| 1920 | .section Support for iconv() |
| 1921 | .index \*iconv()*\ support |
| 1922 | The contents of header lines in messages may be encoded according to the rules |
| 1923 | described RFC 2047. This makes it possible to transmit characters that are not |
| 1924 | in the ASCII character set, and to label them as being in a particular |
| 1925 | character set. When Exim is inspecting header lines by means of the \@$h@_\ |
| 1926 | mechanism, it decodes them, and translates them into a specified character set |
| 1927 | (default ISO-8859-1). The translation is possible only if the operating system |
| 1928 | supports the \*iconv()*\ function. |
| 1929 | |
| 1930 | However, some of the operating systems that supply \*iconv()*\ do not support |
| 1931 | very many conversions. The GNU \libiconv\ library (available from |
| 1932 | \?http:/@/www.gnu.org/software/libiconv/?\) can be installed on such systems to |
| 1933 | remedy this deficiency, as well as on systems that do not supply \*iconv()*\ at |
| 1934 | all. After installing \libiconv\, you should add |
| 1935 | .display asis |
| 1936 | HAVE_ICONV=yes |
| 1937 | .endd |
| 1938 | to your \(Local/Makefile)\ and rebuild Exim. |
| 1939 | |
| 1940 | |
| 1941 | .section Including TLS/SSL encryption support |
| 1942 | .rset SECTinctlsssl "~~chapter.~~section" |
| 1943 | .index TLS||including support for TLS |
| 1944 | .index encryption||including support for |
| 1945 | .index \\SUPPORT@_TLS\\ |
| 1946 | .index OpenSSL||building Exim with |
| 1947 | .index GnuTLS||building Exim with |
| 1948 | Exim can be built to support encrypted SMTP connections, using the \\STARTTLS\\ |
| 1949 | command as per RFC 2487. It can also support legacy clients that expect to |
| 1950 | start a TLS session immediately on connection to a non-standard port (see the |
| 1951 | \-tls-on-connect-\ command line option). |
| 1952 | |
| 1953 | If you want to build Exim with TLS support, you must first install either the |
| 1954 | OpenSSL or GnuTLS library. There is no cryptographic code in Exim itself for |
| 1955 | implementing SSL. |
| 1956 | |
| 1957 | If OpenSSL is installed, you should set |
| 1958 | .display asis |
| 1959 | SUPPORT_TLS=yes |
| 1960 | TLS_LIBS=-lssl -lcrypto |
| 1961 | .endd |
| 1962 | in \(Local/Makefile)\. You may also need to specify the locations of the |
| 1963 | OpenSSL library and include files. For example: |
| 1964 | .display asis |
| 1965 | SUPPORT_TLS=yes |
| 1966 | TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto |
| 1967 | TLS_INCLUDE=-I/usr/local/openssl/include/ |
| 1968 | .endd |
| 1969 | |
| 1970 | If GnuTLS is installed, you should set |
| 1971 | .index \\USE@_GNUTLS\\ |
| 1972 | .display asis |
| 1973 | SUPPORT_TLS=yes |
| 1974 | USE_GNUTLS=yes |
| 1975 | TLS_LIBS=-lgnutls -ltasn1 -lgcrypt |
| 1976 | .endd |
| 1977 | in \(Local/Makefile)\, and again you may need to specify the locations of the |
| 1978 | library and include files. For example: |
| 1979 | .display asis |
| 1980 | SUPPORT_TLS=yes |
| 1981 | USE_GNUTLS=yes |
| 1982 | TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt |
| 1983 | TLS_INCLUDE=-I/usr/gnu/include |
| 1984 | .endd |
| 1985 | You do not need to set \\TLS@_INCLUDE\\ if the relevant directory is already |
| 1986 | specified in \\INCLUDE\\. Details of how to configure Exim to make use of TLS |
| 1987 | are given in chapter ~~CHAPTLS. |
| 1988 | |
| 1989 | |
| 1990 | |
| 1991 | .section Use of tcpwrappers |
| 1992 | .index tcpwrappers, building Exim to support |
| 1993 | .index \\USE@_TCP@_WRAPPERS\\ |
| 1994 | Exim can be linked with the \*tcpwrappers*\ library in order to check incoming |
| 1995 | SMTP calls using the \*tcpwrappers*\ control files. This may be a convenient |
| 1996 | alternative to Exim's own checking facilities for installations that are |
| 1997 | already making use of \*tcpwrappers*\ for other purposes. To do this, you should |
| 1998 | set \\USE@_TCP@_WRAPPERS\\ in \(Local/Makefile)\, arrange for the file |
| 1999 | \(tcpd.h)\ to be available at compile time, and also ensure that the library |
| 2000 | \(libwrap.a)\ is available at link time, typically by including \-lwrap-\ in |
| 2001 | \\EXTRALIBS@_EXIM\\. For example, if \*tcpwrappers*\ is installed in |
| 2002 | \(/usr/local)\, you might have |
| 2003 | .display |
| 2004 | USE@_TCP@_WRAPPERS=yes |
| 2005 | CFLAGS=-O -I/usr/local/include |
| 2006 | .newline |
| 2007 | EXTRALIBS@_EXIM=-L/usr/local/lib -lwrap |
| 2008 | .endd |
| 2009 | in \(Local/Makefile)\. The name to use in the \*tcpwrappers*\ control files is |
| 2010 | `exim'. For example, the line |
| 2011 | .display |
| 2012 | exim : LOCAL 192.168.1. .friendly.domain.example |
| 2013 | .endd |
| 2014 | in your \(/etc/hosts.allow)\ file allows connections from the local host, from |
| 2015 | the subnet 192.168.1.0/24, and from all hosts in \*friendly.domain.example*\. |
| 2016 | All other connections are denied. Consult the \*tcpwrappers*\ documentation for |
| 2017 | further details. |
| 2018 | |
| 2019 | |
| 2020 | .section Including support for IPv6 |
| 2021 | .index IPv6||including support for |
| 2022 | Exim contains code for use on systems that have IPv6 support. Setting |
| 2023 | \\HAVE@_IPV6=YES\\ in \(Local/Makefile)\ causes the IPv6 code to be included; |
| 2024 | it may also be necessary to set \\IPV6@_INCLUDE\\ and \\IPV6@_LIBS\\ on systems |
| 2025 | where the IPv6 support is not fully integrated into the normal include and |
| 2026 | library files. |
| 2027 | |
| 2028 | IPv6 is still changing rapidly. Two different types of DNS record for handling |
| 2029 | IPv6 addresses have been defined. AAAA records are already in use, and are |
| 2030 | currently seen as the `mainstream', but another record type called A6 is being |
| 2031 | argued about. Its status is currently `experimental'. Exim has support for A6 |
| 2032 | records, but this is included only if you set \\SUPPORT@_A6=YES\\ in |
| 2033 | \(Local/Makefile)\. |
| 2034 | |
| 2035 | |
| 2036 | .section The building process |
| 2037 | .index build directory |
| 2038 | Once \(Local/Makefile)\ (and \(Local/eximon.conf)\, if required) have been |
| 2039 | created, run \*make*\ at the top level. It determines the architecture and |
| 2040 | operating system types, and creates a build directory if one does not exist. |
| 2041 | For example, on a Sun system running Solaris 8, the directory |
| 2042 | \(build-SunOS5-5.8-sparc)\ is created. |
| 2043 | .index symbolic link||to source files |
| 2044 | Symbolic links to relevant source files are installed in the build directory. |
| 2045 | |
| 2046 | \**Warning**\: The \-j-\ (parallel) flag must not be used with \*make*\; the |
| 2047 | building process fails if it is set. |
| 2048 | |
| 2049 | If this is the first time \*make*\ has been run, it calls a script that builds |
| 2050 | a make file inside the build directory, using the configuration files from the |
| 2051 | \(Local)\ directory. The new make file is then passed to another instance of |
| 2052 | \*make*\. This does the real work, building a number of utility scripts, and |
| 2053 | then compiling and linking the binaries for the Exim monitor (if configured), a |
| 2054 | number of utility programs, and finally Exim itself. The command \*make |
| 2055 | makefile*\ can be used to force a rebuild of the make file in the build |
| 2056 | directory, should this ever be necessary. |
| 2057 | |
| 2058 | If you have problems building Exim, check for any comments there may be in the |
| 2059 | \(README)\ file concerning your operating system, and also take a look at the |
| 2060 | .if ~~html |
| 2061 | [(A HREF="FAQ.html")] |
| 2062 | .fi |
| 2063 | FAQ, |
| 2064 | .if ~~html |
| 2065 | [(/A)] |
| 2066 | .fi |
| 2067 | where some common problems are covered. |
| 2068 | |
| 2069 | |
| 2070 | |
| 2071 | .section Overriding build-time options for Exim |
| 2072 | .index build-time options, overriding |
| 2073 | .rset SECToverride "~~chapter.~~section" |
| 2074 | The main make file that is created at the beginning of the building process |
| 2075 | consists of the concatenation of a number of files which set configuration |
| 2076 | values, followed by a fixed set of \*make*\ instructions. If a value is set |
| 2077 | more than once, the last setting overrides any previous ones. This provides a |
| 2078 | convenient way of overriding defaults. The files that are concatenated are, in |
| 2079 | order: |
| 2080 | .display rm |
| 2081 | \(OS/Makefile-Default)\ |
| 2082 | \(OS/Makefile-)\<<ostype>> |
| 2083 | \(Local/Makefile)\ |
| 2084 | \(Local/Makefile-)\<<ostype>> |
| 2085 | \(Local/Makefile-)\<<archtype>> |
| 2086 | \(Local/Makefile-)\<<ostype>>-<<archtype>> |
| 2087 | \(OS/Makefile-Base)\ |
| 2088 | .endd |
| 2089 | .index \(Local/Makefile)\ |
| 2090 | where <<ostype>> is the operating system type and <<archtype>> is the |
| 2091 | .index building Exim||operating system type |
| 2092 | .index building Exim||architecture type |
| 2093 | architecture type. \(Local/Makefile)\ is required to exist, and the building |
| 2094 | process fails if it is absent. The other three \(Local)\ files are optional, |
| 2095 | and are often not needed. |
| 2096 | |
| 2097 | The values used for <<ostype>> and <<archtype>> are obtained from scripts |
| 2098 | called \(scripts/os-type)\ and \(scripts/arch-type)\ respectively. If either of |
| 2099 | the environment variables \\EXIM@_OSTYPE\\ or \\EXIM@_ARCHTYPE\\ is set, their |
| 2100 | values are used, thereby providing a means of forcing particular settings. |
| 2101 | Otherwise, the scripts try to get values from the \uname\ command. If this |
| 2102 | fails, the shell variables \\OSTYPE\\ and \\ARCHTYPE\\ are inspected. A number |
| 2103 | of $it{ad hoc} transformations are then applied, to produce the standard names |
| 2104 | that Exim expects. You can run these scripts directly from the shell in order |
| 2105 | to find out what values are being used on your system. |
| 2106 | |
| 2107 | |
| 2108 | \(OS/Makefile-Default)\ contains comments about the variables that are set |
| 2109 | therein. Some (but not all) are mentioned below. If there is something that |
| 2110 | needs changing, review the contents of this file and the contents of the make |
| 2111 | file for your operating system (\(OS/Makefile-<<ostype>>)\) to see what the |
| 2112 | default values are. |
| 2113 | |
| 2114 | |
| 2115 | .index building Exim||overriding default settings |
| 2116 | If you need to change any of the values that are set in \(OS/Makefile-Default)\ |
| 2117 | or in \(OS/Makefile-<<ostype>>)\, or to add any new definitions, you do not |
| 2118 | need to change the original files. Instead, you should make the changes by |
| 2119 | putting the new values in an appropriate \(Local)\ file. For example, |
| 2120 | .index Tru64-Unix build-time settings |
| 2121 | when building Exim in many releases of the Tru64-Unix (formerly Digital UNIX, |
| 2122 | formerly DEC-OSF1) operating system, it is necessary to specify that the C |
| 2123 | compiler is called \*cc*\ rather than \*gcc*\. Also, the compiler must be |
| 2124 | called with the option \-std1-\, to make it recognize some of the features of |
| 2125 | Standard C that Exim uses. (Most other compilers recognize Standard C by |
| 2126 | default.) To do this, you should create a file called \(Local/Makefile-OSF1)\ |
| 2127 | containing the lines |
| 2128 | .display |
| 2129 | CC=cc |
| 2130 | CFLAGS=-std1 |
| 2131 | .endd |
| 2132 | If you are compiling for just one operating system, it may be easier to put |
| 2133 | these lines directly into \(Local/Makefile)\. |
| 2134 | |
| 2135 | Keeping all your local configuration settings separate from the distributed |
| 2136 | files makes it easy to transfer them to new versions of Exim simply by copying |
| 2137 | the contents of the \(Local)\ directory. |
| 2138 | |
| 2139 | |
| 2140 | .index NIS lookup type||including support for |
| 2141 | .index NIS@+ lookup type||including support for |
| 2142 | .index LDAP||including support for |
| 2143 | .index lookup||inclusion in binary |
| 2144 | Exim contains support for doing LDAP, NIS, NIS+, and other kinds of file |
| 2145 | lookup, but not all systems have these components installed, so the default is |
| 2146 | not to include the relevant code in the binary. All the different kinds of file |
| 2147 | and database lookup that Exim supports are implemented as separate code modules |
| 2148 | which are included only if the relevant compile-time options are set. In the |
| 2149 | case of LDAP, NIS, and NIS+, the settings for \(Local/Makefile)\ are: |
| 2150 | .display asis |
| 2151 | LOOKUP_LDAP=yes |
| 2152 | LOOKUP_NIS=yes |
| 2153 | LOOKUP_NISPLUS=yes |
| 2154 | .endd |
| 2155 | and similar settings apply to the other lookup types. They are all listed in |
| 2156 | \(src/EDITME)\. In most cases the relevant include files and interface |
| 2157 | libraries need to be installed before compiling Exim. |
| 2158 | .index cdb||including support for |
| 2159 | However, in the case of cdb, which is included in the binary only if |
| 2160 | .display asis |
| 2161 | LOOKUP_CDB=yes |
| 2162 | .endd |
| 2163 | is set, the code is entirely contained within Exim, and no external include |
| 2164 | files or libraries are required. When a lookup type is not included in the |
| 2165 | binary, attempts to configure Exim to use it cause run time configuration |
| 2166 | errors. |
| 2167 | |
| 2168 | .index Perl||including support for |
| 2169 | Exim can be linked with an embedded Perl interpreter, allowing Perl |
| 2170 | subroutines to be called during string expansion. To enable this facility, |
| 2171 | .display asis |
| 2172 | EXIM_PERL=perl.o |
| 2173 | .endd |
| 2174 | must be defined in \(Local/Makefile)\. Details of this facility are given in |
| 2175 | chapter ~~CHAPperl. |
| 2176 | |
| 2177 | .index X11 libraries, location of |
| 2178 | The location of the X11 libraries is something that varies a lot between |
| 2179 | operating systems, and of course there are different versions of X11 to cope |
| 2180 | with. Exim itself makes no use of X11, but if you are compiling the Exim |
| 2181 | monitor, the X11 libraries must be available. |
| 2182 | The following three variables are set in \(OS/Makefile-Default)\: |
| 2183 | .display asis |
| 2184 | X11=/usr/X11R6 |
| 2185 | XINCLUDE=-I$(X11)/include |
| 2186 | XLFLAGS=-L$(X11)/lib |
| 2187 | .endd |
| 2188 | These are overridden in some of the operating-system configuration files. For |
| 2189 | example, in \(OS/Makefile-SunOS5)\ there is |
| 2190 | .display asis |
| 2191 | X11=/usr/openwin |
| 2192 | XINCLUDE=-I$(X11)/include |
| 2193 | XLFLAGS=-L$(X11)/lib -R$(X11)/lib |
| 2194 | .endd |
| 2195 | If you need to override the default setting for your operating system, place a |
| 2196 | definition of all three of these variables into your |
| 2197 | \(Local/Makefile-<<ostype>>)\ file. |
| 2198 | |
| 2199 | .index \\EXTRALIBS\\ |
| 2200 | If you need to add any extra libraries to the link steps, these can be put in a |
| 2201 | variable called \\EXTRALIBS\\, which appears in all the link commands, but by |
| 2202 | default is not defined. In contrast, \\EXTRALIBS@_EXIM\\ is used only on the |
| 2203 | command for linking the main Exim binary, and not for any associated utilities. |
| 2204 | .index DBM||libraries, configuration for building |
| 2205 | There is also \\DBMLIB\\, which appears in the link commands for binaries that |
| 2206 | use DBM functions (see also section ~~SECTdb). Finally, there is |
| 2207 | \\EXTRALIBS@_EXIMON\\, which appears only in the link step for the Exim monitor |
| 2208 | binary, and which can be used, for example, to include additional X11 |
| 2209 | libraries. |
| 2210 | |
| 2211 | .index configuration file||editing |
| 2212 | The make file copes with rebuilding Exim correctly if any of the configuration |
| 2213 | files are edited. However, if an optional configuration file is deleted, it is |
| 2214 | necessary to touch the associated non-optional file (that is, \(Local/Makefile)\ |
| 2215 | or \(Local/eximon.conf)\) before rebuilding. |
| 2216 | |
| 2217 | .section OS-specific header files |
| 2218 | .index \(os.h)\ |
| 2219 | .index building Exim||OS-specific C header files |
| 2220 | The \(OS)\ directory contains a number of files with names of the form |
| 2221 | \(os.h-<<ostype>>)\. These are system-specific C header files that should not |
| 2222 | normally need to be changed. There is a list of macro settings that are |
| 2223 | recognized in the file \(OS/os.configuring)\, which should be consulted if you |
| 2224 | are porting Exim to a new operating system. |
| 2225 | |
| 2226 | |
| 2227 | .section Overriding build-time options for the monitor |
| 2228 | .index building Eximon||overriding default options |
| 2229 | A similar process is used for overriding things when building the Exim monitor, |
| 2230 | where the files that are involved are |
| 2231 | .display rm |
| 2232 | \(OS/eximon.conf-Default)\ |
| 2233 | \(OS/eximon.conf-)\<<ostype>> |
| 2234 | \(Local/eximon.conf)\ |
| 2235 | \(Local/eximon.conf-)\<<ostype>> |
| 2236 | \(Local/eximon.conf-)\<<archtype>> |
| 2237 | \(Local/eximon.conf-)\<<ostype>>-<<archtype>> |
| 2238 | .endd |
| 2239 | .index \(Local/eximon.conf)\ |
| 2240 | As with Exim itself, the final three files need not exist, and in this case the |
| 2241 | \(OS/eximon.conf-<<ostype>>)\ file is also optional. The default values in |
| 2242 | \(OS/eximon.conf-Default)\ can be overridden dynamically by setting environment |
| 2243 | variables of the same name, preceded by \\EXIMON@_\\. For example, setting |
| 2244 | \\EXIMON@_LOG@_DEPTH\\ in the environment overrides the value of |
| 2245 | \\LOG@_DEPTH\\ at run time. |
| 2246 | |
| 2247 | |
| 2248 | |
| 2249 | .section Installing Exim binaries and scripts |
| 2250 | .index installing Exim |
| 2251 | .index \\BIN@_DIRECTORY\\ |
| 2252 | The command \*make install*\ runs the \*exim@_install*\ script with no |
| 2253 | arguments. The script copies binaries and utility scripts into the directory |
| 2254 | whose name is specified by the \\BIN@_DIRECTORY\\ setting in |
| 2255 | \(Local/Makefile)\. |
| 2256 | |
| 2257 | Exim's run time configuration file is named by the \\CONFIGURE@_FILE\\ setting |
| 2258 | .index \\CONFIGURE@_FILE\\ |
| 2259 | in \(Local/Makefile)\. If this names a single file, and the file does not |
| 2260 | exist, the default configuration file \(src/configure.default)\ is copied there |
| 2261 | by the installation script. If a run time configuration file already exists, it |
| 2262 | is left alone. If \\CONFIGURE@_FILE\\ is a colon-separated list, naming several |
| 2263 | alternative files, no default is installed. |
| 2264 | |
| 2265 | .index system aliases file |
| 2266 | .index \(/etc/aliases)\ |
| 2267 | One change is made to the default configuration file when it is installed: the |
| 2268 | default configuration contains a router that references a system aliases file. |
| 2269 | The path to this file is set to the value specified by |
| 2270 | \\SYSTEM@_ALIASES@_FILE\\ in \(Local/Makefile)\ (\(/etc/aliases)\ by default). |
| 2271 | If the system aliases file does not exist, the installation script creates it, |
| 2272 | and outputs a comment to the user. |
| 2273 | |
| 2274 | The created file contains no aliases, but it does contain comments about the |
| 2275 | aliases a site should normally have. Mail aliases have traditionally been |
| 2276 | kept in \(/etc/aliases)\. However, some operating systems are now using |
| 2277 | \(/etc/mail/aliases)\. You should check if yours is one of these, and change |
| 2278 | Exim's configuration if necessary. |
| 2279 | |
| 2280 | The default configuration uses the local host's name as the only local domain, |
| 2281 | and is set up to do local deliveries into the shared directory \(/var/mail)\, |
| 2282 | running as the local user. System aliases and \(.forward)\ files in users' home |
| 2283 | directories are supported, but no NIS or NIS+ support is configured. Domains |
| 2284 | other than the name of the local host are routed using the DNS, with delivery |
| 2285 | over SMTP. |
| 2286 | |
| 2287 | The install script copies files only if they are newer than the files they are |
| 2288 | going to replace. The Exim binary is required to be owned by root and have the |
| 2289 | \*setuid*\ bit set, |
| 2290 | .index setuid||installing Exim with |
| 2291 | for normal configurations. Therefore, you must run \*make install*\ as root so |
| 2292 | that it can set up the Exim binary in this way. However, in some special |
| 2293 | situations (for example, if a host is doing no local deliveries) it may be |
| 2294 | possible to run Exim without making the binary setuid root (see chapter |
| 2295 | ~~CHAPsecurity for details). |
| 2296 | |
| 2297 | It is possible to install Exim for special purposes (such as building a binary |
| 2298 | distribution) in a private part of the file system. You can do this by a |
| 2299 | command such as |
| 2300 | .display asis |
| 2301 | make DESTDIR=/some/directory/ install |
| 2302 | .endd |
| 2303 | This has the effect of pre-pending the specified directory to all the file |
| 2304 | paths, except the name of the system aliases file that appears in the default |
| 2305 | configuration. (If a default alias file is created, its name \*is*\ modified.) |
| 2306 | For backwards compatibility, \\ROOT\\ is used if \\DESTDIR\\ is not set, |
| 2307 | but this usage is deprecated. |
| 2308 | |
| 2309 | .index installing Exim||what is not installed |
| 2310 | Running \*make install*\ does not copy the Exim 4 conversion script |
| 2311 | \*convert4r4*\, or the \*pcretest*\ test program. You will probably run the |
| 2312 | first of these only once (if you are upgrading from Exim 3), and the second |
| 2313 | isn't really part of Exim. None of the documentation files in the \(doc)\ |
| 2314 | directory are copied, except for the info files when you have set |
| 2315 | \\INFO@_DIRECTORY\\, as described in section ~~SECTinsinfdoc below. |
| 2316 | |
| 2317 | For the utility programs, old versions are renamed by adding the suffix \(.O)\ |
| 2318 | to their names. The Exim binary itself, however, is handled differently. It is |
| 2319 | installed under a name that includes the version number and the compile number, |
| 2320 | for example \(exim-~~version-1)\. The script then arranges for a symbolic link |
| 2321 | called \(exim)\ to point to the binary. If you are updating a previous version |
| 2322 | of Exim, the script takes care to ensure that the name \(exim)\ is never absent |
| 2323 | from the directory (as seen by other processes). |
| 2324 | |
| 2325 | .index installing Exim||testing the script |
| 2326 | If you want to see what the \*make install*\ will do before running it for |
| 2327 | real, you can pass the \-n-\ option to the installation script by this command: |
| 2328 | .display asis |
| 2329 | make INSTALL_ARG=-n install |
| 2330 | .endd |
| 2331 | The contents of the variable \\INSTALL@_ARG\\ are passed to the installation |
| 2332 | script. You do not need to be root to run this test. Alternatively, you can run |
| 2333 | the installation script directly, but this must be from within the build |
| 2334 | directory. For example, from the top-level Exim directory you could use this |
| 2335 | command: |
| 2336 | .display |
| 2337 | (cd build-SunOS5-5.5.1-sparc; ../scripts/exim@_install -n) |
| 2338 | .endd |
| 2339 | |
| 2340 | .index installing Exim||install script options |
| 2341 | There are two other options that can be supplied to the installation script. |
| 2342 | .numberpars $. |
| 2343 | \-no@_chown-\ bypasses the call to change the owner of the installed binary |
| 2344 | to root, and the call to make it a setuid binary. |
| 2345 | .nextp |
| 2346 | \-no@_symlink-\ bypasses the setting up of the symbolic link \(exim)\ to the |
| 2347 | installed binary. |
| 2348 | .endp |
| 2349 | \\INSTALL@_ARG\\ can be used to pass these options to the script. For example: |
| 2350 | .display asis |
| 2351 | make INSTALL_ARG=-no_symlink install |
| 2352 | .endd |
| 2353 | |
| 2354 | The installation script can also be given arguments specifying which files are |
| 2355 | to be copied. For example, to install just the Exim binary, and nothing else, |
| 2356 | without creating the symbolic link, you could use: |
| 2357 | .display asis |
| 2358 | make INSTALL_ARG='-no_symlink exim' install |
| 2359 | .endd |
| 2360 | |
| 2361 | |
| 2362 | .section Installing info documentation |
| 2363 | .rset SECTinsinfdoc "~~chapter.~~section" |
| 2364 | .index installing Exim||\*info*\ documentation |
| 2365 | Not all systems use the GNU \*info*\ system for documentation, and for this |
| 2366 | reason, the Texinfo source of Exim's documentation is not included in the main |
| 2367 | distribution. Instead it is available separately from the ftp site (see section |
| 2368 | ~~SECTavail). |
| 2369 | |
| 2370 | If you have defined \\INFO@_DIRECTORY\\ in \(Local/Makefile)\ and the Texinfo |
| 2371 | source of the documentation is found in the source tree, running \*make |
| 2372 | install*\ automatically builds the info files and installs them. |
| 2373 | |
| 2374 | |
| 2375 | .section Setting up the spool directory |
| 2376 | .index spool directory||creating |
| 2377 | When it starts up, Exim tries to create its spool directory if it does not |
| 2378 | exist. The Exim uid and gid are used for the owner and group of the spool |
| 2379 | directory. Sub-directories are automatically created in the spool directory as |
| 2380 | necessary. |
| 2381 | |
| 2382 | |
| 2383 | |
| 2384 | .section Testing |
| 2385 | .index testing||installation |
| 2386 | Having installed Exim, you can check that the run time configuration file is |
| 2387 | syntactically valid by running the following command, which assumes that the |
| 2388 | Exim binary directory is within your \\PATH\\ environment variable: |
| 2389 | .display |
| 2390 | exim -bV |
| 2391 | .endd |
| 2392 | If there are any errors in the configuration file, Exim outputs error messages. |
| 2393 | Otherwise it outputs the version number and build date, |
| 2394 | the DBM library that is being used, and information about which drivers and |
| 2395 | other optional code modules are included in the binary. |
| 2396 | Some simple routing tests can be done by using the address testing option. For |
| 2397 | example, |
| 2398 | .display |
| 2399 | exim -bt <<local username>> |
| 2400 | .endd |
| 2401 | should verify that it recognizes a local mailbox, and |
| 2402 | .display |
| 2403 | exim -bt <<remote address>> |
| 2404 | .endd |
| 2405 | a remote one. Then try getting it to deliver mail, both locally and remotely. |
| 2406 | This can be done by passing messages directly to Exim, without going through a |
| 2407 | user agent. For example: |
| 2408 | .display |
| 2409 | exim -v postmaster@@your.domain.example |
| 2410 | From: user@@your.domain.example |
| 2411 | To: postmaster@@your.domain.example |
| 2412 | Subject: Testing Exim |
| 2413 | |
| 2414 | This is a test message. |
| 2415 | ^D |
| 2416 | .endd |
| 2417 | The \-v-\ option causes Exim to output some verification of what it is doing. |
| 2418 | In this case you should see copies of three log lines, one for the message's |
| 2419 | arrival, one for its delivery, and one containing `Completed'. |
| 2420 | |
| 2421 | .index delivery||problems with |
| 2422 | If you encounter problems, look at Exim's log files (\*mainlog*\ and |
| 2423 | \*paniclog*\) to see if there is any relevant information there. Another source |
| 2424 | of information is running Exim with debugging turned on, by specifying the |
| 2425 | \-d-\ option. If a message is stuck on Exim's spool, you can force a delivery |
| 2426 | with debugging turned on by a command of the form |
| 2427 | .display |
| 2428 | exim -d -M <<message-id>> |
| 2429 | .endd |
| 2430 | You must be root or an `admin user' in order to do this. The \-d-\ option |
| 2431 | produces rather a lot of output, but you can cut this down to specific areas. |
| 2432 | For example, if you use \-d-all+route-\ only the debugging information relevant |
| 2433 | to routing is included. (See the \-d-\ option in chapter ~~CHAPcommandline for |
| 2434 | more details.) |
| 2435 | |
| 2436 | .index `sticky' bit |
| 2437 | .index lock files |
| 2438 | One specific problem that has shown up on some sites is the inability to do |
| 2439 | local deliveries into a shared mailbox directory, because it does not have the |
| 2440 | `sticky bit' set on it. By default, Exim tries to create a lock file before |
| 2441 | writing to a mailbox file, and if it cannot create the lock file, the delivery |
| 2442 | is deferred. You can get round this either by setting the `sticky bit' on the |
| 2443 | directory, or by setting a specific group for local deliveries and allowing |
| 2444 | that group to create files in the directory (see the comments above the |
| 2445 | \%local@_delivery%\ transport in the default configuration file). Another |
| 2446 | approach is to configure Exim not to use lock files, but just to rely on |
| 2447 | \*fcntl()*\ locking instead. However, you should do this only if all user |
| 2448 | agents also use \*fcntl()*\ locking. For further discussion of locking issues, |
| 2449 | see chapter ~~CHAPappendfile. |
| 2450 | |
| 2451 | One thing that cannot be tested on a system that is already running an MTA is |
| 2452 | the receipt of incoming SMTP mail on the standard SMTP port. However, the |
| 2453 | \-oX-\ option can be used to run an Exim daemon that listens on some other |
| 2454 | port, or \*inetd*\ can be used to do this. The \-bh-\ option and the |
| 2455 | \*exim@_checkaccess*\ utility can be used to check out policy controls on |
| 2456 | incoming SMTP mail. |
| 2457 | |
| 2458 | Testing a new version on a system that is already running Exim can most easily |
| 2459 | be done by building a binary with a different \\CONFIGURE@_FILE\\ setting. From |
| 2460 | within the run time configuration, all other file and directory names |
| 2461 | that Exim uses can be altered, in order to keep it entirely clear of the |
| 2462 | production version. |
| 2463 | |
| 2464 | .section Replacing another MTA with Exim |
| 2465 | .index replacing another MTA |
| 2466 | Building and installing Exim for the first time does not of itself put it in |
| 2467 | general use. The name by which the system's MTA is called by mail user agents |
| 2468 | is either \(/usr/sbin/sendmail)\, or \(/usr/lib/sendmail)\ (depending on the |
| 2469 | operating system), and it is necessary to make this name point to the \*exim*\ |
| 2470 | binary in order to get the user agents to pass messages to Exim. This is |
| 2471 | normally done by renaming any existing file and making \(/usr/sbin/sendmail)\ |
| 2472 | or \(/usr/lib/sendmail)\ |
| 2473 | .index symbolic link||to \*exim*\ binary |
| 2474 | a symbolic link to the \*exim*\ binary. It is a good idea to remove any setuid |
| 2475 | privilege and executable status from the old MTA. It is then necessary to stop |
| 2476 | and restart the mailer daemon, if one is running. |
| 2477 | |
| 2478 | .index FreeBSD, MTA indirection |
| 2479 | .index \(/etc/mail/mailer.conf)\ |
| 2480 | Some operating systems have introduced alternative ways of switching MTAs. For |
| 2481 | example, if you are running FreeBSD, you need to edit the file |
| 2482 | \(/etc/mail/mailer.conf)\ instead of setting up a symbolic link as just |
| 2483 | described. A typical example of the contents of this file for running Exim is |
| 2484 | as follows: |
| 2485 | .display asis |
| 2486 | sendmail /usr/exim/bin/exim |
| 2487 | send-mail /usr/exim/bin/exim |
| 2488 | mailq /usr/exim/bin/exim -bp |
| 2489 | newaliases /usr/bin/true |
| 2490 | .endd |
| 2491 | |
| 2492 | Once you have set up the symbolic link, or edited \(/etc/mail/mailer.conf)\, |
| 2493 | your Exim installation is `live'. Check it by sending a message from your |
| 2494 | favourite user agent. |
| 2495 | |
| 2496 | You should consider what to tell your users about the change of MTA. Exim may |
| 2497 | have different capabilities to what was previously running, and there are |
| 2498 | various operational differences such as the text of messages produced by |
| 2499 | command line options and in bounce messages. If you allow your users to make |
| 2500 | use of Exim's filtering capabilities, you should make the document entitled |
| 2501 | .if ~~html |
| 2502 | [(A HREF="filter.html")] |
| 2503 | .fi |
| 2504 | \*Exim's interface to mail filtering*\ |
| 2505 | .if ~~html |
| 2506 | [(/A)] |
| 2507 | .fi |
| 2508 | available to them. |
| 2509 | |
| 2510 | |
| 2511 | .section Upgrading Exim |
| 2512 | .index upgrading Exim |
| 2513 | If you are already running Exim on your host, building and installing a new |
| 2514 | version automatically makes it available to MUAs, or any other programs that |
| 2515 | call the MTA directly. However, if you are running an Exim daemon, you do need |
| 2516 | to send it a HUP signal, to make it re-exec itself, and thereby pick up the new |
| 2517 | binary. You do not need to stop processing mail in order to install a new |
| 2518 | version of Exim. |
| 2519 | |
| 2520 | |
| 2521 | .section Stopping the Exim daemon on Solaris |
| 2522 | .index Solaris||stopping Exim on |
| 2523 | The standard command for stopping the mailer daemon on Solaris is |
| 2524 | .display |
| 2525 | /etc/init.d/sendmail stop |
| 2526 | .endd |
| 2527 | If \(/usr/lib/sendmail)\ has been turned into a symbolic link, this script |
| 2528 | fails to stop Exim because it uses the command \*ps -e*\ and greps the output |
| 2529 | for the text `sendmail'; this is not present because the actual program name |
| 2530 | (that is, `exim') is given by the \*ps*\ command with these options. A solution |
| 2531 | is to replace the line that finds the process id with something like |
| 2532 | .display asis |
| 2533 | pid=`cat /var/spool/exim/exim-daemon.pid` |
| 2534 | .endd |
| 2535 | to obtain the daemon's pid directly from the file that Exim saves it in. |
| 2536 | |
| 2537 | Note, however, that stopping the daemon does not `stop Exim'. Messages can |
| 2538 | still be received from local processes, and if automatic delivery is configured |
| 2539 | (the normal case), deliveries will still occur. |
| 2540 | |
| 2541 | |
| 2542 | . |
| 2543 | . |
| 2544 | . |
| 2545 | . |
| 2546 | . ============================================================================ |
| 2547 | .chapter The Exim command line |
| 2548 | .set runningfoot "command line" |
| 2549 | .rset CHAPcommandline ~~chapter |
| 2550 | .index command line||options |
| 2551 | .index options||command line |
| 2552 | |
| 2553 | Exim's command line takes the standard Unix form of a sequence of options, |
| 2554 | each starting with a hyphen character, followed by a number of arguments. The |
| 2555 | options are compatible with the main options of Sendmail, and there are also |
| 2556 | some additional options, some of which are compatible with Smail 3. Certain |
| 2557 | combinations of options do not make sense, and provoke an error if used. |
| 2558 | The form of the arguments depends on which options are set. |
| 2559 | |
| 2560 | .section Setting options by program name |
| 2561 | .index \*mailq*\ |
| 2562 | If Exim is called under the name \*mailq*\, it behaves as if the option \-bp-\ |
| 2563 | were present before any other options. |
| 2564 | The \-bp-\ option requests a listing of the contents of the mail queue on the |
| 2565 | standard output. |
| 2566 | This feature is for compatibility with some systems that contain a command of |
| 2567 | that name in one of the standard libraries, symbolically linked to |
| 2568 | \(/usr/sbin/sendmail)\ or \(/usr/lib/sendmail)\. |
| 2569 | |
| 2570 | .index \*rsmtp*\ |
| 2571 | If Exim is called under the name \*rsmtp*\ it behaves as if the option \-bS-\ |
| 2572 | were present before any other options, for compatibility with Smail. The \-bS-\ |
| 2573 | option is used for reading in a number of messages in batched SMTP format. |
| 2574 | |
| 2575 | .index \*rmail*\ |
| 2576 | If Exim is called under the name \*rmail*\ it behaves as if the \-i-\ and |
| 2577 | \-oee-\ options were present before any other options, for compatibility with |
| 2578 | Smail. The name \*rmail*\ is used as an interface by some UUCP systems. |
| 2579 | |
| 2580 | .index \*runq*\ |
| 2581 | .index queue runner |
| 2582 | If Exim is called under the name \*runq*\ it behaves as if the option \-q-\ were |
| 2583 | present before any other options, for compatibility with Smail. The \-q-\ |
| 2584 | option causes a single queue runner process to be started. |
| 2585 | |
| 2586 | .index \*newaliases*\ |
| 2587 | .index alias file||building |
| 2588 | .index Sendmail compatibility||calling Exim as \*newaliases*\ |
| 2589 | If Exim is called under the name \*newaliases*\ it behaves as if the option |
| 2590 | \-bi-\ were present before any other options, for compatibility with Sendmail. |
| 2591 | This option is used for rebuilding Sendmail's alias file. Exim does not have |
| 2592 | the concept of a single alias file, but can be configured to run a given |
| 2593 | command if called with the \-bi-\ option. |
| 2594 | |
| 2595 | .section Trusted and admin users |
| 2596 | .rset SECTtrustedadmin "~~chapter.~~section" |
| 2597 | Some Exim options are available only to \*trusted users*\ and others are |
| 2598 | available only to \*admin users*\. In the description below, the phrases `Exim |
| 2599 | user' and `Exim group' mean the user and group defined by \\EXIM@_USER\\ and |
| 2600 | \\EXIM@_GROUP\\ in \(Local/Makefile)\ or set by the \exim@_user\ and |
| 2601 | \exim@_group\ options. These do not necessarily have to use the name `exim'. |
| 2602 | |
| 2603 | .numberpars $. |
| 2604 | .index trusted user||definition of |
| 2605 | .index user||trusted, definition of |
| 2606 | The trusted users are root, the Exim user, any user listed in the |
| 2607 | \trusted@_users\ configuration option, and any user whose current group or any |
| 2608 | supplementary group is one of those listed in the \trusted@_groups\ |
| 2609 | configuration option. Note that the Exim group is not automatically trusted. |
| 2610 | |
| 2611 | .index `From' line |
| 2612 | .index envelope sender |
| 2613 | Trusted users are always permitted to use the \-f-\ option or a leading `From ' |
| 2614 | line to specify the envelope sender of a message that is passed to Exim through |
| 2615 | the local interface (see the \-bm-\ and \-f-\ options below). See the |
| 2616 | \untrusted@_set@_sender\ option for a way of permitting non-trusted users to |
| 2617 | set envelope senders. |
| 2618 | .index ::From:: header line |
| 2619 | .index ::Sender:: header line |
| 2620 | For a trusted user, there is never any check on the contents of the ::From:: |
| 2621 | header line, and a ::Sender:: line is never added. Furthermore, any existing |
| 2622 | ::Sender:: line in incoming local (non-TCP/IP) messages is not removed. |
| 2623 | |
| 2624 | Trusted users may also specify a host name, host address, interface address, |
| 2625 | protocol name, ident value, and authentication data when submitting a message |
| 2626 | locally. Thus, they are able to insert messages into Exim's queue locally that |
| 2627 | have the characteristics of messages received from a remote host. Untrusted |
| 2628 | users may in some circumstances use \-f-\, but can never set the other values |
| 2629 | that are available to trusted users. |
| 2630 | .nextp |
| 2631 | .index user||admin, definition of |
| 2632 | .index admin user||definition of |
| 2633 | The admin users are root, the Exim user, and any user that is a member of the |
| 2634 | Exim group or of any group listed in the \admin@_groups\ configuration option. |
| 2635 | The current group does not have to be one of these groups. |
| 2636 | |
| 2637 | Admin users are permitted to list the queue, and to carry out certain |
| 2638 | operations on messages, for example, to force delivery failures. It is also |
| 2639 | necessary to be an admin user in order to see the full information provided by |
| 2640 | the Exim monitor, and full debugging output. |
| 2641 | |
| 2642 | By default, the use of the \-M-\, \-q-\, \-R-\, and \-S-\ options to cause Exim |
| 2643 | to attempt delivery of messages on its queue is restricted to admin users. |
| 2644 | However, this restriction can be relaxed by setting the \prod@_requires@_admin\ |
| 2645 | option false (that is, specifying \no@_prod@_requires@_admin\). |
| 2646 | |
| 2647 | Similarly, the use of the \-bp-\ option to list all the messages in the queue |
| 2648 | is restricted to admin users unless \queue@_list@_requires@_admin\ is set |
| 2649 | false. |
| 2650 | .endp |
| 2651 | |
| 2652 | \**Warning**\: If you configure your system so that admin users are able to |
| 2653 | edit Exim's configuration file, you are giving those users an easy way of |
| 2654 | getting root. There is further discussion of this issue at the start of chapter |
| 2655 | ~~CHAPconf. |
| 2656 | |
| 2657 | |
| 2658 | |
| 2659 | .section Command line options |
| 2660 | The command options are described in alphabetical order below. |
| 2661 | |
| 2662 | .startoptions |
| 2663 | |
| 2664 | .option @- |
| 2665 | .index options||command line, terminating |
| 2666 | This is a pseudo-option whose only purpose is to terminate the options and |
| 2667 | therefore to cause subsequent command line items to be treated as arguments |
| 2668 | rather than options, even if they begin with hyphens. |
| 2669 | |
| 2670 | .option -help |
| 2671 | This option causes Exim to output a few sentences stating what it is. |
| 2672 | The same output is generated if the Exim binary is called with no options and |
| 2673 | no arguments. |
| 2674 | |
| 2675 | .option B <<type>> |
| 2676 | .index 8-bit characters |
| 2677 | .index Sendmail compatibility||8-bit characters |
| 2678 | This is a Sendmail option for selecting 7 or 8 bit processing. Exim is 8-bit |
| 2679 | clean; it ignores this option. |
| 2680 | |
| 2681 | .option bd |
| 2682 | .index daemon |
| 2683 | .index SMTP listener |
| 2684 | .index queue runner |
| 2685 | This option runs Exim as a daemon, awaiting incoming SMTP connections. Usually |
| 2686 | the \-bd-\ option is combined with the \-q-\<<time>> option, to specify that |
| 2687 | the daemon should also initiate periodic queue runs. |
| 2688 | |
| 2689 | The \-bd-\ option can be used only by an admin user. If either of the \-d-\ |
| 2690 | (debugging) or \-v-\ (verifying) options are set, the daemon does not |
| 2691 | disconnect from the controlling terminal. When running this way, it can be |
| 2692 | stopped by pressing ctrl-C. |
| 2693 | |
| 2694 | By default, Exim listens for incoming connections to the standard SMTP port on |
| 2695 | all the host's running interfaces. However, it is possible to listen on other |
| 2696 | ports, on multiple ports, and only on specific interfaces. Chapter |
| 2697 | ~~CHAPinterfaces contains a description of the options that control this. |
| 2698 | |
| 2699 | .index daemon||process id (pid) |
| 2700 | .index pid (process id)||of daemon |
| 2701 | When a listening daemon is started without the use of \-oX-\ (that is, without |
| 2702 | overriding the normal configuration), it writes its process id to a file called |
| 2703 | \(exim-daemon.pid)\ in Exim's spool directory. This location can be overridden |
| 2704 | by setting \\PID@_FILE@_PATH\\ in \(Local/Makefile)\. The file is written while |
| 2705 | Exim is still running as root. |
| 2706 | |
| 2707 | When \-oX-\ is used on the command line to start a listening daemon, the |
| 2708 | process id is not written to the normal pid file path. However, \-oP-\ can be |
| 2709 | used to specify a path on the command line if a pid file is required. |
| 2710 | |
| 2711 | .index \\SIGHUP\\ |
| 2712 | The \\SIGHUP\\ signal can be used to cause the daemon to re-exec itself. This |
| 2713 | should be done whenever Exim's configuration file, or any file that is |
| 2714 | incorporated into it by means of the \.include\ facility, is changed, and also |
| 2715 | whenever a new version of Exim is installed. It is not necessary to do this |
| 2716 | when other files that are referenced from the configuration (for example, alias |
| 2717 | files) are changed, because these are reread each time they are used. |
| 2718 | |
| 2719 | .option bdf |
| 2720 | This option has the same effect as \-bd-\ except that it never disconnects from |
| 2721 | the controlling terminal, even when no debugging is specified. |
| 2722 | |
| 2723 | .option be |
| 2724 | .index testing||string expansion |
| 2725 | .index expansion||testing |
| 2726 | Run Exim in expansion testing mode. Exim discards its root privilege, to |
| 2727 | prevent ordinary users from using this mode to read otherwise inaccessible |
| 2728 | files. If no arguments are given, Exim runs interactively, prompting for lines |
| 2729 | of data. Long expressions can be split over several lines by using backslash |
| 2730 | continuations. |
| 2731 | As in Exim's run time configuration, whitespace at the start of continuation |
| 2732 | lines is ignored. |
| 2733 | |
| 2734 | Each argument or data line is passed through the string expansion mechanism, |
| 2735 | and the result is output. Variable values from the configuration file (for |
| 2736 | example, \$qualify@_domain$\) are available, but no message-specific values |
| 2737 | (such as \$domain$\) are set, because no message is being processed. |
| 2738 | |
| 2739 | .option bF #<<filename>> |
| 2740 | .index system filter||testing |
| 2741 | .index testing||system filter |
| 2742 | This option is the same as \-bf-\ except that it assumes that the filter being |
| 2743 | tested is a system filter. The additional commands that are available only in |
| 2744 | system filters are recognized. |
| 2745 | |
| 2746 | .option bf #<<filename>> |
| 2747 | .index filter||testing |
| 2748 | .index testing||filter file |
| 2749 | .index forward file||testing |
| 2750 | .index testing||forward file |
| 2751 | .index Sieve filter||testing |
| 2752 | This option runs Exim in filter testing mode; the file is the filter file to be |
| 2753 | tested, and a test message must be supplied on the standard input. If there are |
| 2754 | no message-dependent tests in the filter, an empty file can be supplied. If a |
| 2755 | system filter file is being tested, \-bF-\ should be used instead of \-bf-\. If |
| 2756 | the test file does not begin with |
| 2757 | one of the special lines |
| 2758 | .display asis |
| 2759 | # Exim filter |
| 2760 | # Sieve filter |
| 2761 | .endd |
| 2762 | it is taken to be a normal \(.forward)\ file, and is tested for validity under |
| 2763 | that interpretation. See sections ~~SECTitenonfilred to ~~SECTspecitredli for a |
| 2764 | description of the possible contents of non-filter redirection lists. |
| 2765 | |
| 2766 | The result of an Exim command that uses \-bf-\, provided no errors are |
| 2767 | detected, is a list of the actions that Exim would try to take if presented |
| 2768 | with the message for real. More details of filter testing are given in the |
| 2769 | separate document entitled \*Exim's interfaces to mail filtering*\. |
| 2770 | |
| 2771 | .index `From' line |
| 2772 | .index envelope sender |
| 2773 | .index \-f-\ option||for filter testing |
| 2774 | When testing a filter file, the envelope sender can be set by the \-f-\ option, |
| 2775 | or by a `From ' line at the start of the test message. Various parameters that |
| 2776 | would normally be taken from the envelope recipient address of the message can |
| 2777 | be set by means of additional command line options. These are: |
| 2778 | .display rm |
| 2779 | .if ~~sys.fancy |
| 2780 | .tabset 12em 16em |
| 2781 | .else |
| 2782 | .tabset 15em 20em |
| 2783 | .fi |
| 2784 | . The odd alignment here gets it lined up in the man page. |
| 2785 | \-bfd-\ $t <<domain>> $t $rm{default is the qualify domain} |
| 2786 | \-bfl-\ $t <<local@_part>> $t $rm{default is the logged in user} |
| 2787 | \-bfp-\ $t <<local@_part@_prefix>> $t $rm{default is null} |
| 2788 | \-bfs-\ $t <<local@_part@_suffix>> $t $rm{default is null} |
| 2789 | .endd |
| 2790 | The local part should always be set to the incoming address with any prefix or |
| 2791 | suffix stripped, because that is how it appears to the filter when a message is |
| 2792 | actually being delivered. |
| 2793 | |
| 2794 | .option bh #<<IP address>> |
| 2795 | .index testing||incoming SMTP |
| 2796 | .index SMTP||testing incoming |
| 2797 | .index testing||relay control |
| 2798 | .index relaying||testing configuration |
| 2799 | .index policy control||testing |
| 2800 | .index debugging||\-bh-\ option |
| 2801 | This option runs a fake SMTP session as if from the given IP address, using the |
| 2802 | standard input and output. The IP address may include a port number at the end, |
| 2803 | after a full stop. For example: |
| 2804 | .display asis |
| 2805 | exim -bh 10.9.8.7.1234 |
| 2806 | exim -bh fe80::a00:20ff:fe86:a061.5678 |
| 2807 | .endd |
| 2808 | Comments as to what is going on are written to the standard error file. These |
| 2809 | include lines beginning with `LOG' for anything that would have been logged. |
| 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 |
| 2812 | test your relay controls using \-bh-\. |
| 2813 | |
| 2814 | .index RFC 1413 |
| 2815 | \**Warning 1**\: You cannot test features of the configuration that rely on |
| 2816 | ident (RFC 1413) callouts. These cannot be done when testing using |
| 2817 | \-bh-\ because there is no incoming SMTP connection. |
| 2818 | |
| 2819 | \**Warning 2**\: Address verification callouts (see section ~~SECTcallver) are |
| 2820 | also skipped when testing using \-bh-\. If you want these callouts to occur, |
| 2821 | use \-bhc-\ instead. |
| 2822 | |
| 2823 | Messages supplied during the testing session are discarded, and nothing is |
| 2824 | written to any of the real log files. There may be pauses when DNS (and other) |
| 2825 | lookups are taking place, and of course these may time out. The \-oMi-\ option |
| 2826 | can be used to specify a specific IP interface and port if this is important. |
| 2827 | |
| 2828 | The \*exim@_checkaccess*\ utility is a `packaged' version of \-bh-\ whose |
| 2829 | output just states whether a given recipient address from a given host is |
| 2830 | acceptable or not. See section ~~SECTcheckaccess. |
| 2831 | |
| 2832 | .option bhc #<<IP address>> |
| 2833 | This option operates in the same way as \-bh-\, except that address |
| 2834 | verification callouts are performed if required. This includes consulting and |
| 2835 | updating the callout cache database. |
| 2836 | |
| 2837 | .option bi |
| 2838 | .index alias file||building |
| 2839 | .index building alias file |
| 2840 | .index Sendmail compatibility||\-bi-\ option |
| 2841 | Sendmail interprets the \-bi-\ option as a request to rebuild its alias file. |
| 2842 | Exim does not have the concept of a single alias file, and so it cannot mimic |
| 2843 | this behaviour. However, calls to \(/usr/lib/sendmail)\ with the \-bi-\ option |
| 2844 | tend to appear in various scripts such as NIS make files, so the option must be |
| 2845 | recognized. |
| 2846 | |
| 2847 | If \-bi-\ is encountered, the command specified by the \bi@_command\ |
| 2848 | configuration option is run, under the uid and gid of the caller of Exim. If |
| 2849 | the \-oA-\ option is used, its value is passed to the command as an argument. |
| 2850 | The command set by \bi@_command\ may not contain arguments. The command can use |
| 2851 | the \*exim@_dbmbuild*\ utility, or some other means, to rebuild alias files if |
| 2852 | this is required. If the \bi@_command\ option is not set, calling Exim with |
| 2853 | \-bi-\ is a no-op. |
| 2854 | |
| 2855 | .option bm |
| 2856 | .index local message reception |
| 2857 | This option runs an Exim receiving process that accepts an incoming, |
| 2858 | locally-generated message on the current input. The recipients are given as the |
| 2859 | command arguments (except when \-t-\ is also present -- see below). Each |
| 2860 | argument can be a comma-separated list of RFC 2822 addresses. This is the |
| 2861 | default option for selecting the overall action of an Exim call; it is assumed |
| 2862 | if no other conflicting option is present. |
| 2863 | |
| 2864 | If any addresses in the message are unqualified (have no domain), they are |
| 2865 | qualified by the values of the \qualify@_domain\ or \qualify@_recipient\ |
| 2866 | options, as appropriate. The \-bnq-\ option (see below) provides a way of |
| 2867 | suppressing this for special cases. |
| 2868 | |
| 2869 | Policy checks on the contents of local messages can be enforced by means of the |
| 2870 | non-SMTP ACL. See chapter ~~CHAPACL for details. |
| 2871 | .index return code||for \-bm-\ |
| 2872 | The return code is zero if the message is successfully accepted. Otherwise, the |
| 2873 | action is controlled by the \-oe$it{x}-\ option setting -- see below. |
| 2874 | |
| 2875 | .index message||format |
| 2876 | .index format||message |
| 2877 | .index `From' line |
| 2878 | .index UUCP||`From' line |
| 2879 | .index Sendmail compatibility||`From' line |
| 2880 | The format of the message must be as defined in RFC 2822, except that, for |
| 2881 | compatibility with Sendmail and Smail, a line in one of the forms |
| 2882 | .display |
| 2883 | From sender Fri Jan 5 12:55 GMT 1997 |
| 2884 | From sender Fri, 5 Jan 97 12:55:01 |
| 2885 | .endd |
| 2886 | (with the weekday optional, and possibly with additional text after the date) |
| 2887 | is permitted to appear at the start of the message. There appears to be no |
| 2888 | authoritative specification of the format of this line. Exim recognizes it by |
| 2889 | matching against the regular expression defined by the \uucp@_from@_pattern\ |
| 2890 | option, which can be changed if necessary. |
| 2891 | .index \-f-\ option||overriding `From' line |
| 2892 | The specified sender is treated as if it were given as the argument to the |
| 2893 | \-f-\ option, but if a \-f-\ option is also present, its argument is used in |
| 2894 | preference to the address taken from the message. The caller of Exim must be a |
| 2895 | trusted user for the sender of a message to be set in this way. |
| 2896 | |
| 2897 | .option bnq |
| 2898 | .index address||qualification, suppressing |
| 2899 | By default, Exim automatically qualifies unqualified addresses (those |
| 2900 | without domains) that appear in messages that are submitted locally (that |
| 2901 | is, not over TCP/IP). This qualification applies both to addresses in |
| 2902 | envelopes, and addresses in header lines. Sender addresses are qualified using |
| 2903 | \qualify@_domain\, and recipient addresses using \qualify@_recipient\ (which |
| 2904 | defaults to the value of \qualify@_domain\). |
| 2905 | |
| 2906 | Sometimes, qualification is not wanted. For example, if \-bS-\ (batch SMTP) is |
| 2907 | being used to re-submit messages that originally came from remote hosts after |
| 2908 | content scanning, you probably do not want to qualify unqualified addresses in |
| 2909 | header lines. (Such lines will be present only if you have not enabled a header |
| 2910 | syntax check in the appropriate ACL.) |
| 2911 | |
| 2912 | The \-bnq-\ option suppresses all qualification of unqualified addresses in |
| 2913 | messages that originate on the local host. When this is used, unqualified |
| 2914 | addresses in the envelope provoke errors (causing message rejection) and |
| 2915 | unqualified addresses in header lines are left alone. |
| 2916 | |
| 2917 | |
| 2918 | .option bP |
| 2919 | .index configuration options, extracting |
| 2920 | .index options||configuration, extracting |
| 2921 | If this option is given with no arguments, it causes the values of all Exim's |
| 2922 | main configuration options to be written to the standard output. The values |
| 2923 | of one or more specific options can be requested by giving their names as |
| 2924 | arguments, for example: |
| 2925 | .display |
| 2926 | exim -bP qualify@_domain hold@_domains |
| 2927 | .endd |
| 2928 | However, any option setting that is preceded by the word `hide' in the |
| 2929 | configuration file is not shown in full, except to an admin user. For other |
| 2930 | users, the output is as in this example: |
| 2931 | .display asis |
| 2932 | mysql_servers = <value not displayable> |
| 2933 | .endd |
| 2934 | If \configure@_file\ is given as an argument, the name of the run time |
| 2935 | configuration file is output. |
| 2936 | If a list of configuration files was supplied, the value that is output here |
| 2937 | is the name of the file that was actually used. |
| 2938 | |
| 2939 | .index daemon||process id (pid) |
| 2940 | .index pid (process id)||of daemon |
| 2941 | If \log__file__path\ or \pid@_file@_path\ are given, the names of the |
| 2942 | directories where log files and daemon pid files are written are output, |
| 2943 | respectively. If these values are unset, log files are written in a |
| 2944 | sub-directory of the spool directory called \log\, and the pid file is written |
| 2945 | directly into the spool directory. |
| 2946 | |
| 2947 | If \-bP-\ is followed by a name preceded by \"+"\, for example, |
| 2948 | .display asis |
| 2949 | exim -bP +local_domains |
| 2950 | .endd |
| 2951 | it searches for a matching named list of any type (domain, host, address, or |
| 2952 | local part) and outputs what it finds. |
| 2953 | |
| 2954 | .index options||router, extracting |
| 2955 | .index options||transport, extracting |
| 2956 | If one of the words \router\, \transport\, or \authenticator\ is given, |
| 2957 | followed by the name of an appropriate driver instance, the option settings for |
| 2958 | that driver are output. For example: |
| 2959 | .display |
| 2960 | exim -bP transport local@_delivery |
| 2961 | .endd |
| 2962 | The generic driver options are output first, followed by the driver's private |
| 2963 | options. A list of the names of drivers of a particular type can be obtained by |
| 2964 | using one of the words \router@_list\, \transport@_list\, or |
| 2965 | \authenticator@_list\, and a complete list of all drivers with their option |
| 2966 | settings can be obtained by using \routers\, \transports\, or \authenticators\. |
| 2967 | |
| 2968 | |
| 2969 | .option bp |
| 2970 | .index queue||listing messages on |
| 2971 | .index listing||messages on the queue |
| 2972 | This option requests a listing of the contents of the mail queue on the |
| 2973 | standard output. If the \-bp-\ option is followed by a list of message ids, |
| 2974 | just those messages are listed. By default, this option can be used only by an |
| 2975 | admin user. However, the \queue__list__requires__admin\ option can be set false |
| 2976 | to allow any user to see the queue. |
| 2977 | |
| 2978 | Each message on the queue is displayed as in the following example: |
| 2979 | .display |
| 2980 | 25m 2.9K 0t5C6f-0000c8-00 <alice@@wonderland.fict.example> |
| 2981 | red.king@@looking-glass.fict.example |
| 2982 | <<other addresses>> |
| 2983 | .endd |
| 2984 | .index message||size in queue listing |
| 2985 | .index size||of message |
| 2986 | The first line contains the length of time the message has been on the queue |
| 2987 | (in this case 25 minutes), the size of the message (2.9K), the unique local |
| 2988 | identifier for the message, and the message sender, as contained in the |
| 2989 | envelope. For bounce messages, the sender address is empty, and appears as |
| 2990 | `<>'. If the message was submitted locally by an untrusted user who overrode |
| 2991 | the default sender address, the user's login name is shown in parentheses |
| 2992 | before the sender address. |
| 2993 | .index frozen messages||in queue listing |
| 2994 | If the message is frozen (attempts to deliver it are suspended) then the text |
| 2995 | `$*$$*$$*$ frozen $*$$*$$*$' is displayed at the end of this line. |
| 2996 | |
| 2997 | The recipients of the message (taken from the envelope, not the headers) are |
| 2998 | displayed on subsequent lines. Those addresses to which the message has already |
| 2999 | been delivered are marked with the letter D. If an original address gets |
| 3000 | expanded into several addresses via an alias or forward file, the original is |
| 3001 | displayed with a D only when deliveries for all of its child addresses are |
| 3002 | complete. |
| 3003 | |
| 3004 | |
| 3005 | .option bpa |
| 3006 | This option operates like \-bp-\, but in addition it shows delivered addresses |
| 3007 | that were generated from the original top level address(es) in each message by |
| 3008 | alias or forwarding operations. These addresses are flagged with `+D' instead |
| 3009 | of just `D'. |
| 3010 | |
| 3011 | |
| 3012 | .option bpc |
| 3013 | .index queue||count of messages on |
| 3014 | This option counts the number of messages on the queue, and writes the total |
| 3015 | to the standard output. It is restricted to admin users, unless |
| 3016 | \queue__list__requires__admin\ is set false. |
| 3017 | |
| 3018 | |
| 3019 | .option bpr |
| 3020 | This option operates like \-bp-\, but the output is not sorted into |
| 3021 | chronological order of message arrival. This can speed it up when there are |
| 3022 | lots of messages on the queue, and is particularly useful if the output is |
| 3023 | going to be post-processed in a way that doesn't need the sorting. |
| 3024 | |
| 3025 | .option bpra |
| 3026 | This option is a combination of \-bpr-\ and \-bpa-\. |
| 3027 | |
| 3028 | .option bpru |
| 3029 | This option is a combination of \-bpr-\ and \-bpu-\. |
| 3030 | |
| 3031 | |
| 3032 | .option bpu |
| 3033 | This option operates like \-bp-\ but shows only undelivered top-level addresses |
| 3034 | for each message displayed. Addresses generated by aliasing or forwarding are |
| 3035 | not shown, unless the message was deferred after processing by a router with |
| 3036 | the \one@_time\ option set. |
| 3037 | |
| 3038 | |
| 3039 | .option brt |
| 3040 | .index testing||retry configuration |
| 3041 | .index retry||configuration testing |
| 3042 | This option is for testing retry rules, and it must be followed by up to three |
| 3043 | arguments. It causes Exim to look for a retry rule that matches the values |
| 3044 | and to write it to the standard output. For example: |
| 3045 | .display asis |
| 3046 | exim -brt bach.comp.mus.example |
| 3047 | Retry rule: *.comp.mus.example F,2h,15m; F,4d,30m; |
| 3048 | .endd |
| 3049 | See chapter ~~CHAPretry for a description of Exim's retry rules. The first |
| 3050 | argument, which is required, can be a complete address in the form |
| 3051 | \*local@_part@@domain*\, or it can be just a domain name. The second argument is |
| 3052 | an optional second domain name; if no retry rule is found for the first |
| 3053 | argument, the second is tried. This ties in with Exim's behaviour when looking |
| 3054 | for retry rules for remote hosts -- if no rule is found that matches the host, |
| 3055 | one that matches the mail domain is sought. The final argument is the name of a |
| 3056 | specific delivery error, as used in setting up retry rules, for example |
| 3057 | `quota@_3d'. |
| 3058 | |
| 3059 | .option brw |
| 3060 | .index testing||rewriting |
| 3061 | .index rewriting||testing |
| 3062 | This option is for testing address rewriting rules, and it must be followed by |
| 3063 | a single argument, consisting of either a local part without a domain, or a |
| 3064 | complete address with a fully qualified domain. Exim outputs how this address |
| 3065 | would be rewritten for each possible place it might appear. See chapter |
| 3066 | ~~CHAPrewrite for further details. |
| 3067 | |
| 3068 | .option bS |
| 3069 | .index SMTP||batched incoming |
| 3070 | .index batched SMTP input |
| 3071 | This option is used for batched SMTP input, which is an alternative interface |
| 3072 | for non-interactive local message submission. A number of messages can be |
| 3073 | submitted in a single run. However, despite its name, this is not really SMTP |
| 3074 | input. Exim reads each message's envelope from SMTP commands on the standard |
| 3075 | input, but generates no responses. If the caller is trusted, or |
| 3076 | \untrusted@_set@_sender\ is set, the senders in the SMTP \\MAIL\\ commands are |
| 3077 | believed; otherwise the sender is always the caller of Exim. |
| 3078 | |
| 3079 | The message itself is read from the standard input, in SMTP format (leading |
| 3080 | dots doubled), terminated by a line containing just a single dot. An error is |
| 3081 | provoked if the terminating dot is missing. A further message may then follow. |
| 3082 | |
| 3083 | As for other local message submissions, the contents of incoming batch SMTP |
| 3084 | messages can be checked using the non-SMTP ACL (see chapter ~~CHAPACL). |
| 3085 | Unqualified addresses are automatically qualified using \qualify@_domain\ and |
| 3086 | \qualify@_recipient\, as appropriate, unless the \-bnq-\ option is used. |
| 3087 | |
| 3088 | Some other SMTP commands are recognized in the input. \\HELO\\ and \\EHLO\\ act |
| 3089 | as \\RSET\\; \\VRFY\\, \\EXPN\\, \\ETRN\\, and \\HELP\\ act as \\NOOP\\; |
| 3090 | \\QUIT\\ quits, ignoring the rest of the standard input. |
| 3091 | |
| 3092 | If any error is encountered, reports are written to the standard output and |
| 3093 | error streams, and Exim gives up immediately. |
| 3094 | .index return code||for \-bS-\ |
| 3095 | The return code is 0 if no error was detected; it is 1 if one or more messages |
| 3096 | were accepted before the error was detected; otherwise it is 2. |
| 3097 | |
| 3098 | More details of input using batched SMTP are given in section |
| 3099 | ~~SECTincomingbatchedSMTP. |
| 3100 | |
| 3101 | .option bs |
| 3102 | .index SMTP||local input |
| 3103 | .index local SMTP input |
| 3104 | This option causes Exim to accept one or more messages by reading SMTP commands |
| 3105 | on the standard input, and producing SMTP replies on the standard output. SMTP |
| 3106 | policy controls, as defined in ACLs (see chapter ~~CHAPACL) are applied. |
| 3107 | |
| 3108 | Some user agents use this interface as a way of passing locally-generated |
| 3109 | messages to the MTA. |
| 3110 | .index sender||source of |
| 3111 | In this usage, if the caller of Exim is trusted, or \untrusted@_set@_sender\ is |
| 3112 | set, the senders of messages are taken from the SMTP \\MAIL\\ commands. |
| 3113 | Otherwise the content of these commands is ignored and the sender is set up as |
| 3114 | the calling user. Unqualified addresses are automatically qualified using |
| 3115 | \qualify@_domain\ and \qualify@_recipient\, as appropriate, unless the \-bnq-\ |
| 3116 | option is used. |
| 3117 | |
| 3118 | .index inetd |
| 3119 | The \-bs-\ option is also used to run Exim from \*inetd*\, as an alternative to |
| 3120 | using a listening daemon. Exim can distinguish the two cases by checking |
| 3121 | whether the standard input is a TCP/IP socket. When Exim is called from |
| 3122 | \*inetd*\, the source of the mail is assumed to be remote, and the comments |
| 3123 | above concerning senders and qualification do not apply. In this situation, |
| 3124 | Exim behaves in exactly the same way as it does when receiving a message via |
| 3125 | the listening daemon. |
| 3126 | |
| 3127 | .option bt |
| 3128 | .index testing||addresses |
| 3129 | .index address||testing |
| 3130 | This option runs Exim in address testing mode, in which each argument is taken |
| 3131 | as an address to be tested for deliverability. The results are written to the |
| 3132 | standard output. |
| 3133 | If a test fails, and the caller is not an admin user, no details of the |
| 3134 | failure are output, because these might contain sensitive information such as |
| 3135 | usernames and passwords for database lookups. |
| 3136 | |
| 3137 | If no arguments are given, Exim runs in an interactive manner, prompting with a |
| 3138 | right angle bracket for addresses to be tested. Each address is handled as if |
| 3139 | it were the recipient address of a message (compare the \-bv-\ option). It is |
| 3140 | passed to the routers and the result is written to the standard output. |
| 3141 | However, any router that has \no@_address@_test\ set is bypassed. This can |
| 3142 | make \-bt-\ easier to use for genuine routing tests if your first router passes |
| 3143 | everything to a scanner program. |
| 3144 | |
| 3145 | .index return code||for \-bt-\ |
| 3146 | The return code is 2 if any address failed outright; it is 1 if no address |
| 3147 | failed outright but at least one could not be resolved for some reason. Return |
| 3148 | code 0 is given only when all addresses succeed. |
| 3149 | |
| 3150 | \**Warning**\: \-bt-\ can only do relatively simple testing. If any of the |
| 3151 | routers in the configuration makes any tests on the sender address of a |
| 3152 | message, |
| 3153 | .index \-f-\ option||for address testing |
| 3154 | you can use the \-f-\ option to set an appropriate sender when running |
| 3155 | \-bt-\ tests. Without it, the sender is assumed to be the calling user at the |
| 3156 | default qualifying domain. However, if you have set up (for example) routers |
| 3157 | whose behaviour depends on the contents of an incoming message, you cannot test |
| 3158 | those conditions using \-bt-\. The \-N-\ option provides a possible way of |
| 3159 | doing such tests. |
| 3160 | |
| 3161 | .option bV |
| 3162 | .index version number of Exim, verifying |
| 3163 | This option causes Exim to write the current version number, compilation |
| 3164 | number, and compilation date of the \*exim*\ binary to the standard output. |
| 3165 | It also lists the DBM library this is being used, the optional modules (such as |
| 3166 | specific lookup types), the drivers that are included in the binary, and the |
| 3167 | name of the run time configuration file that is in use. |
| 3168 | |
| 3169 | .option bv |
| 3170 | .index verifying||address, using \-bv-\ |
| 3171 | .index address||verification |
| 3172 | This option runs Exim in address verification mode, in which each argument is |
| 3173 | taken as an address to be verified. During normal operation, verification |
| 3174 | happens mostly as a consequence processing a \verify\ condition in an ACL (see |
| 3175 | chapter ~~CHAPACL). If you want to test an entire ACL, see the \-bh-\ option. |
| 3176 | |
| 3177 | If verification fails, and the caller is not an admin user, no details of the |
| 3178 | failure are output, because these might contain sensitive information such as |
| 3179 | usernames and passwords for database lookups. |
| 3180 | |
| 3181 | If no arguments are given, Exim runs in an interactive manner, prompting with a |
| 3182 | right angle bracket for addresses to be verified. Verification differs from |
| 3183 | address testing (the \-bt-\ option) in that routers that have \no@_verify\ set |
| 3184 | are skipped, and if the address is accepted by a router that has \fail@_verify\ |
| 3185 | set, verification fails. The address is verified as a recipient if \-bv-\ is |
| 3186 | used; to test verification for a sender address, \-bvs-\ should be used. |
| 3187 | |
| 3188 | If the \-v-\ option is not set, the output consists of a single line for each |
| 3189 | address, stating whether it was verified or not, and giving a reason in the |
| 3190 | latter case. Otherwise, more details are given of how the address has been |
| 3191 | handled, and in the case of address redirection, all the generated addresses |
| 3192 | are also considered. Without \-v-\, generating more than one address by |
| 3193 | redirection causes verification to end sucessfully. |
| 3194 | |
| 3195 | .index return code||for \-bv-\ |
| 3196 | The return code is 2 if any address failed outright; it is 1 if no address |
| 3197 | failed outright but at least one could not be resolved for some reason. Return |
| 3198 | code 0 is given only when all addresses succeed. |
| 3199 | |
| 3200 | If any of the routers in the configuration makes any tests on the sender |
| 3201 | address of a message, you should use the \-f-\ option to set an appropriate |
| 3202 | sender when running \-bv-\ tests. Without it, the sender is assumed to be the |
| 3203 | calling user at the default qualifying domain. |
| 3204 | |
| 3205 | .option bvs |
| 3206 | This option acts like \-bv-\, but verifies the address as a sender rather |
| 3207 | than a recipient address. This affects any rewriting and qualification that |
| 3208 | might happen. |
| 3209 | |
| 3210 | .option C #<<filelist>> |
| 3211 | .index configuration file||alternate |
| 3212 | .index \\CONFIGURE@_FILE\\ |
| 3213 | .index alternate configuration file |
| 3214 | This option causes Exim to find the run time configuration file from the given |
| 3215 | list instead of from the list specified by the \\CONFIGURE@_FILE\\ |
| 3216 | compile-time setting. Usually, the list will consist of just a single file |
| 3217 | name, but it can be a colon-separated list of names. In this case, the first |
| 3218 | file that exists is used. Failure to open an existing file stops Exim from |
| 3219 | proceeding any further along the list, and an error is generated. |
| 3220 | |
| 3221 | When this option is used by a caller other than root or the Exim user, |
| 3222 | and the list is different from the compiled-in list, Exim gives up |
| 3223 | its root privilege immediately, and runs with the real and effective uid and |
| 3224 | gid set to those of the caller. |
| 3225 | However, if \\ALT@_CONFIG@_ROOT@_ONLY\\ is defined in \(Local/Makefile)\, root |
| 3226 | privilege is retained for \-C-\ only if the caller of Exim is root. |
| 3227 | This option is not set by default. |
| 3228 | |
| 3229 | Setting \\ALT@_CONFIG@_ROOT@_ONLY\\ locks out the possibility of testing a |
| 3230 | configuration using \-C-\ right through message reception and delivery, even if |
| 3231 | the caller is root. The reception works, but by that time, Exim is running as |
| 3232 | the Exim user, so when it re-execs to regain privilege for the delivery, the |
| 3233 | use of \-C-\ causes privilege to be lost. However, root can test reception and |
| 3234 | delivery using two separate commands (one to put a message on the queue, using |
| 3235 | \-odq-\, and another to do the delivery, using \-M-\). |
| 3236 | |
| 3237 | If \\ALT@_CONFIG@_PREFIX\\ is defined \(in Local/Makefile)\, it specifies a |
| 3238 | prefix string with which any file named in a \-C-\ command line option |
| 3239 | must start. In addition, the file name must not contain the sequence \"/../"\. |
| 3240 | However, if the value of the \-C-\ option is identical to the value of |
| 3241 | \\CONFIGURE@_FILE\\ in \(Local/Makefile)\, Exim ignores \-C-\ and proceeds as |
| 3242 | usual. There is no default setting for \\ALT@_CONFIG@_PREFIX\\; when it is |
| 3243 | unset, any file name can be used with \-C-\. |
| 3244 | |
| 3245 | \\ALT@_CONFIG@_PREFIX\\ can be used to confine alternative configuration files |
| 3246 | to a directory to which only root has access. This prevents someone who has |
| 3247 | broken into the Exim account from running a privileged Exim with an arbitrary |
| 3248 | configuration file. |
| 3249 | |
| 3250 | The \-C-\ facility is useful for ensuring that configuration files are |
| 3251 | syntactically correct, but cannot be used for test deliveries, unless the |
| 3252 | caller is privileged, or unless it is an exotic configuration that does not |
| 3253 | require privilege. No check is made on the owner or group of the files |
| 3254 | specified by this option. |
| 3255 | |
| 3256 | .option D <<macro>>=<<value>> |
| 3257 | .index macro||setting on command line |
| 3258 | This option can be used to override macro definitions in the configuration file |
| 3259 | (see section ~~SECTmacrodefs). However, like \-C-\, if it is used by an |
| 3260 | unprivileged caller, it causes Exim to give up its root privilege. |
| 3261 | If \\DISABLE@_D@_OPTION\\ is defined in \(Local/Makefile)\, the use of \-D-\ is |
| 3262 | completely disabled, and its use causes an immediate error exit. |
| 3263 | |
| 3264 | The entire option (including equals sign if present) must all be within one |
| 3265 | command line item. \-D-\ can be used to set the value of a macro to the empty |
| 3266 | string, in which case the equals sign is optional. These two commands are |
| 3267 | synonymous: |
| 3268 | .display asis |
| 3269 | exim -DABC ... |
| 3270 | exim -DABC= ... |
| 3271 | .endd |
| 3272 | To include spaces in a macro definition item, quotes must be used. If you use |
| 3273 | quotes, spaces are permitted around the macro name and the equals sign. For |
| 3274 | example: |
| 3275 | .display asis |
| 3276 | exim '-D ABC = something' ... |
| 3277 | .endd |
| 3278 | \-D-\ may be repeated up to 10 times on a command line. |
| 3279 | |
| 3280 | .option d <<debug options>> |
| 3281 | .index debugging||list of selectors |
| 3282 | .index debugging||\-d-\ option |
| 3283 | This option causes debugging information to be written to the standard |
| 3284 | error stream. It is restricted to admin users because debugging output may show |
| 3285 | database queries that contain password information. Also, the details of users' |
| 3286 | filter files should be protected. When \-d-\ is used, \-v-\ is assumed. If |
| 3287 | \-d-\ is given on its own, a lot of standard debugging data is output. This can |
| 3288 | be reduced, or increased to include some more rarely needed information, by |
| 3289 | following \-d-\ with a string made up of names preceded by plus or minus |
| 3290 | characters. These add or remove sets of debugging data, respectively. For |
| 3291 | example, \-d+filter-\ adds filter debugging, whereas \-d-all+filter-\ selects |
| 3292 | only filter debugging. The available debugging categories are: |
| 3293 | .display flow |
| 3294 | .tabs 21 |
| 3295 | . |
| 3296 | . The odd formatting of the lines below is deliberate. It does not affect the |
| 3297 | . SGCAL output, but by putting in the space it keeps things aligned in the man |
| 3298 | . page that is automatically generated from this text. |
| 3299 | . |
| 3300 | acl $t $rm{ACL interpretation} |
| 3301 | auth $t $rm{authenticators} |
| 3302 | deliver $t $rm{general delivery logic} |
| 3303 | dns $t $rm{DNS lookups (see also resolver)} |
| 3304 | dnsbl $t $rm{DNS black list (aka RBL) code} |
| 3305 | exec $t $rm{arguments for \execv@(@)\ calls} |
| 3306 | expand $t $rm{detailed debugging for string expansions} |
| 3307 | filter $t $rm{filter handling} |
| 3308 | hints@_lookup $t $rm{hints data lookups} |
| 3309 | host@_lookup $t $rm{all types of name-to-IP address handling} |
| 3310 | ident $t $rm{ident lookup} |
| 3311 | interface $t $rm{lists of local interfaces} |
| 3312 | lists $t $rm{matching things in lists} |
| 3313 | load $t $rm{system load checks} |
| 3314 | local@_scan $t $rm{can be used by \*local@_scan()*\ (see chapter ~~CHAPlocalscan)} |
| 3315 | lookup $t $rm{general lookup code and all lookups} |
| 3316 | memory $t $rm{memory handling} |
| 3317 | pid $t $rm{add pid to debug output lines} |
| 3318 | process@_info $t $rm{setting info for the process log} |
| 3319 | queue@_run $t $rm{queue runs} |
| 3320 | receive $t $rm{general message reception logic} |
| 3321 | resolver $t $rm{turn on the DNS resolver's debugging output} |
| 3322 | retry $t $rm{retry handling} |
| 3323 | rewrite $t $rm{address rewriting} |
| 3324 | route $t $rm{address routing} |
| 3325 | timestamp $t $rm{add timestamp to debug output lines} |
| 3326 | tls $t $rm{TLS logic} |
| 3327 | transport $t $rm{transports} |
| 3328 | uid $t $rm{changes of uid/gid and looking up uid/gid} |
| 3329 | verify $t $rm{address verification logic} |
| 3330 | |
| 3331 | all $t $rm{all of the above, and also \-v-\} |
| 3332 | .endd |
| 3333 | .index resolver, debugging output |
| 3334 | .index DNS||resolver, debugging output |
| 3335 | The \"resolver"\ option produces output only if the DNS resolver was compiled |
| 3336 | with \\DEBUG\\ enabled. This is not the case in some operating systems. Also, |
| 3337 | unfortunately, debugging output from the DNS resolver is written to stdout |
| 3338 | rather than stderr. |
| 3339 | |
| 3340 | The default (\-d-\ with no argument) omits \"expand"\, \"filter"\, |
| 3341 | \"interface"\, \"load"\, \"memory"\, \"pid"\, \"resolver"\, and \"timestamp"\. |
| 3342 | However, the \"pid"\ selector is forced when debugging is turned on for a |
| 3343 | daemon, which then passes it on to any re-executed Exims. Exim also |
| 3344 | automatically adds the pid to debug lines when several remote deliveries are |
| 3345 | run in parallel. |
| 3346 | |
| 3347 | The \"timestamp"\ selector causes the current time to be inserted at the start |
| 3348 | of all debug output lines. This can be useful when trying to track down delays |
| 3349 | in processing. |
| 3350 | |
| 3351 | If the \debug@_print\ option is set in any driver, it produces output whenever |
| 3352 | any debugging is selected, or if \-v-\ is used. |
| 3353 | |
| 3354 | .option dropcr |
| 3355 | This is an obsolete option that is now a no-op. It used to affect the way Exim |
| 3356 | handled CR and LF characters in incoming messages. What happens now is |
| 3357 | described in section ~~SECTlineendings. |
| 3358 | |
| 3359 | |
| 3360 | .option E |
| 3361 | .index bounce message||generating |
| 3362 | This option specifies that an incoming message is a locally-generated delivery |
| 3363 | failure report. It is used internally by Exim when handling delivery failures |
| 3364 | and is not intended for external use. Its only effect is to stop Exim |
| 3365 | generating certain messages to the postmaster, as otherwise message cascades |
| 3366 | could occur in some situations. As part of the same option, a message id may |
| 3367 | follow the characters \-E-\. If it does, the log entry for the receipt of the |
| 3368 | new message contains the id, following `R=', as a cross-reference. |
| 3369 | |
| 3370 | .option e$it{x} |
| 3371 | There are a number of Sendmail options starting with \-oe-\ which seem to be |
| 3372 | called by various programs without the leading \o\ in the option. For example, |
| 3373 | the \vacation\ program uses \-eq-\. Exim treats all options of the form |
| 3374 | \-e$it{x}-\ as synonymous with the corresponding \-oe$it{x}-\ options. |
| 3375 | |
| 3376 | .option F #<<string>> |
| 3377 | .index sender||name |
| 3378 | .index name||of sender |
| 3379 | This option sets the sender's full name for use when a locally-generated |
| 3380 | message is being accepted. In the absence of this option, the user's \*gecos*\ |
| 3381 | entry from the password data is used. As users are generally permitted to alter |
| 3382 | their \*gecos*\ entries, no security considerations are involved. White space |
| 3383 | between \-F-\ and the <<string>> is optional. |
| 3384 | |
| 3385 | .option f #<<address>> |
| 3386 | .index sender||address |
| 3387 | .index address||sender |
| 3388 | .index trusted user |
| 3389 | .index envelope sender |
| 3390 | .index user||trusted |
| 3391 | This option sets the address of the envelope sender of a locally-generated |
| 3392 | message (also known as the return path). The option can normally be used only |
| 3393 | by a trusted user, but \untrusted@_set@_sender\ can be set to allow untrusted |
| 3394 | users to use it. In the absence of \-f-\, or if the caller is not allowed to |
| 3395 | use it, the sender of a local message is set to the caller's login name at the |
| 3396 | default qualify domain. |
| 3397 | |
| 3398 | There is one exception to the restriction on the use of \-f-\: an empty sender |
| 3399 | can be specified by any user, to create a message that can never provoke a |
| 3400 | bounce. An empty sender can be specified either as an empty string, or as a |
| 3401 | pair of angle brackets with nothing between them, as in these examples of shell |
| 3402 | commands: |
| 3403 | .display asis |
| 3404 | exim -f '<>' user@domain |
| 3405 | exim -f "" user@domain |
| 3406 | .endd |
| 3407 | In addition, the use of \-f-\ is not restricted when testing a filter file with |
| 3408 | \-bf-\ or when testing or verifying addresses using the \-bt-\ or \-bv-\ |
| 3409 | options. |
| 3410 | |
| 3411 | Allowing untrusted users to change the sender address does not of itself make |
| 3412 | it possible to send anonymous mail. Exim still checks that the ::From:: header |
| 3413 | refers to the local user, and if it does not, it adds a ::Sender:: header, |
| 3414 | though this can be overridden by setting \no@_local@_from@_check\. |
| 3415 | |
| 3416 | .index `From' line |
| 3417 | White space between \-f-\ and the <<address>> is optional |
| 3418 | (that is, they can be given as two arguments or one combined argument). |
| 3419 | The sender of a locally-generated message can also be set (when permitted) by |
| 3420 | an initial `From ' line in the message -- see the description of \-bm-\ above |
| 3421 | -- but if \-f-\ is also present, it overrides `From'. |
| 3422 | |
| 3423 | .option G |
| 3424 | .index Sendmail compatibility||\-G-\ option ignored |
| 3425 | This is a Sendmail option which is ignored by Exim. |
| 3426 | |
| 3427 | .option h #<<number>> |
| 3428 | .index Sendmail compatibility||\-h-\ option ignored |
| 3429 | This option is accepted for compatibility with Sendmail, but has no effect. (In |
| 3430 | Sendmail it overrides the `hop count' obtained by counting ::Received:: |
| 3431 | headers.) |
| 3432 | |
| 3433 | .option i |
| 3434 | .index Solaris||\*mail*\ command |
| 3435 | .index dot||in incoming, non-SMTP message |
| 3436 | This option, which has the same effect as \-oi-\, specifies that a dot on a |
| 3437 | line by itself should not terminate an incoming, non-SMTP message. I can find |
| 3438 | no documentation for this option in Solaris 2.4 Sendmail, but the \*mailx*\ |
| 3439 | command in Solaris 2.4 uses it. See also \-ti-\. |
| 3440 | |
| 3441 | .option M #<<message id>>#<<message id>> ... |
| 3442 | .index forcing delivery |
| 3443 | .index delivery||forcing attempt |
| 3444 | .index frozen messages||forcing delivery |
| 3445 | This option requests Exim to run a delivery attempt on each message in turn. If |
| 3446 | any of the messages are frozen, they are automatically thawed before the |
| 3447 | delivery attempt. The settings of \queue@_domains\, \queue@_smtp@_domains\, and |
| 3448 | \hold@_domains\ are ignored. |
| 3449 | .index hints database||overriding retry hints |
| 3450 | Retry hints for any of the addresses are |
| 3451 | overridden -- Exim tries to deliver even if the normal retry time has not yet |
| 3452 | been reached. This option requires the caller to be an admin user. However, |
| 3453 | there is an option called \prod@_requires@_admin\ which can be set false to |
| 3454 | relax this restriction (and also the same requirement for the \-q-\, \-R-\, and |
| 3455 | \-S-\ options). |
| 3456 | |
| 3457 | |
| 3458 | .option Mar #<<message id>>#<<address>>#<<address>> ... |
| 3459 | .index message||adding recipients |
| 3460 | .index recipient||adding |
| 3461 | This option requests Exim to add the addresses to the list of recipients of the |
| 3462 | message (`ar' for `add recipients'). The first argument must be a message id, |
| 3463 | and the remaining ones must be email addresses. However, if the message is |
| 3464 | active (in the middle of a delivery attempt), it is not altered. This option |
| 3465 | can be used only by an admin user. |
| 3466 | |
| 3467 | .index SMTP||passed connection |
| 3468 | .index SMTP||multiple deliveries |
| 3469 | .index multiple SMTP deliveries |
| 3470 | .option MC #<<transport>>#<<hostname>>#<<sequence number>>#<<message id>> |
| 3471 | This option is not intended for use by external callers. It is used internally |
| 3472 | by Exim to invoke another instance of itself to deliver a waiting message using |
| 3473 | an existing SMTP connection, which is passed as the standard input. Details are |
| 3474 | given in chapter ~~CHAPSMTP. This must be the final option, and the caller must |
| 3475 | be root or the Exim user in order to use it. |
| 3476 | |
| 3477 | .option MCA |
| 3478 | This option is not intended for use by external callers. It is used internally |
| 3479 | by Exim in conjunction with the \-MC-\ option. It signifies that the connection |
| 3480 | to the remote host has been authenticated. |
| 3481 | |
| 3482 | .option MCP |
| 3483 | This option is not intended for use by external callers. It is used internally |
| 3484 | by Exim in conjunction with the \-MC-\ option. It signifies that the server to |
| 3485 | which Exim is connected supports pipelining. |
| 3486 | |
| 3487 | .option MCQ #<<process id>> <<pipe fd>> |
| 3488 | This option is not intended for use by external callers. It is used internally |
| 3489 | by Exim in conjunction with the \-MC-\ option when the original delivery was |
| 3490 | started by a queue runner. It passes on the process id of the queue runner, |
| 3491 | together with the file descriptor number of an open pipe. Closure of the pipe |
| 3492 | signals the final completion of the sequence of processes that are passing |
| 3493 | messages through the same SMTP connection. |
| 3494 | |
| 3495 | .option MCS |
| 3496 | This option is not intended for use by external callers. It is used internally |
| 3497 | by Exim in conjunction with the \-MC-\ option, and passes on the fact that the |
| 3498 | SMTP \\SIZE\\ option should be used on messages delivered down the existing |
| 3499 | connection. |
| 3500 | |
| 3501 | .option MCT |
| 3502 | This option is not intended for use by external callers. It is used internally |
| 3503 | by Exim in conjunction with the \-MC-\ option, and passes on the fact that the |
| 3504 | host to which Exim is connected supports TLS encryption. |
| 3505 | |
| 3506 | .option Mc #<<message id>>#<<message id>> ... |
| 3507 | .index hints database||not overridden by \-Mc-\ |
| 3508 | .index delivery||manually started, not forced |
| 3509 | This option requests Exim to run a delivery attempt on each message in turn, |
| 3510 | but unlike the \-M-\ option, it does check for retry hints, and respects any |
| 3511 | that are found. This option is not very useful to external callers. It is |
| 3512 | provided mainly for internal use by Exim when it needs to re-invoke itself in |
| 3513 | order to regain root privilege for a delivery (see chapter ~~CHAPsecurity). |
| 3514 | However, \-Mc-\ can be useful when testing, in order to run a delivery that |
| 3515 | respects retry times and other options such as \hold@_domains\ that are |
| 3516 | overridden when \-M-\ is used. Such a delivery does not count as a queue run. |
| 3517 | If you want to run a specific delivery as if in a queue run, you should use |
| 3518 | \-q-\ with a message id argument. A distinction between queue run deliveries |
| 3519 | and other deliveries is made in one or two places. |
| 3520 | |
| 3521 | .option Mes #<<message id>>#<<address>> |
| 3522 | .index message||changing sender |
| 3523 | .index sender||changing |
| 3524 | This option requests Exim to change the sender address in the message to the |
| 3525 | given address, which must be a fully qualified address or `<>' (`es' for `edit |
| 3526 | sender'). There must be exactly two arguments. The first argument must be a |
| 3527 | message id, and the second one an email address. However, if the message is |
| 3528 | active (in the middle of a delivery attempt), its status is not altered. This |
| 3529 | option can be used only by an admin user. |
| 3530 | |
| 3531 | .option Mf #<<message id>>#<<message id>> ... |
| 3532 | .index freezing messages |
| 3533 | .index message||manually freezing |
| 3534 | This option requests Exim to mark each listed message as `frozen'. This |
| 3535 | prevents any delivery attempts taking place until the message is `thawed', |
| 3536 | either manually or as a result of the \auto@_thaw\ configuration option. |
| 3537 | However, if any of the messages are active (in the middle of a delivery |
| 3538 | attempt), their status is not altered. This option can be used only by an admin |
| 3539 | user. |
| 3540 | |
| 3541 | .option Mg #<<message id>>#<<message id>> ... |
| 3542 | .index giving up on messages |
| 3543 | .index message||abandoning delivery attempts |
| 3544 | .index delivery||abandoning further attempts |
| 3545 | This option requests Exim to give up trying to deliver the listed messages, |
| 3546 | including any that are frozen. However, if any of the messages are active, |
| 3547 | their status is not altered. |
| 3548 | For non-bounce messages, a delivery error message is sent to the sender, |
| 3549 | containing the text `cancelled by administrator'. Bounce messages are just |
| 3550 | discarded. |
| 3551 | This option can be used only by an admin user. |
| 3552 | |
| 3553 | .option Mmad #<<message id>>#<<message id>> ... |
| 3554 | .index delivery||cancelling all |
| 3555 | This option requests Exim to mark all the recipient addresses in the messages |
| 3556 | as already delivered (`mad' for `mark all delivered'). However, if any message |
| 3557 | is active (in the middle of a delivery attempt), its status is not altered. |
| 3558 | This option can be used only by an admin user. |
| 3559 | |
| 3560 | .option Mmd #<<message id>>#<<address>>#<<address>> ... |
| 3561 | .index delivery||cancelling by address |
| 3562 | .index recipient||removing |
| 3563 | .index removing recipients |
| 3564 | This option requests Exim to mark the given addresses as already delivered |
| 3565 | (`md' for `mark delivered'). The first argument must be a message id, and the |
| 3566 | remaining ones must be email addresses. These are matched to recipient |
| 3567 | addresses in the message in a case-sensitive manner. If the message is active |
| 3568 | (in the middle of a delivery attempt), its status is not altered. This option |
| 3569 | can be used only by an admin user. |
| 3570 | |
| 3571 | .option Mrm #<<message id>>#<<message id>> ... |
| 3572 | .index removing messages |
| 3573 | .index abandoning mail |
| 3574 | .index message||manually discarding |
| 3575 | This option requests Exim to remove the given messages from the queue. No |
| 3576 | bounce messages are sent; each message is simply forgotten. However, if any of |
| 3577 | the messages are active, their status is not altered. This option can be used |
| 3578 | only by an admin user or by the user who originally caused the message to be |
| 3579 | placed on the queue. |
| 3580 | |
| 3581 | .option Mt #<<message id>>#<<message id>> ... |
| 3582 | .index thawing messages |
| 3583 | .index unfreezing messages |
| 3584 | .index frozen messages||thawing |
| 3585 | .index message||thawing frozen |
| 3586 | This option requests Exim to `thaw' any of the listed messages that are |
| 3587 | `frozen', so that delivery attempts can resume. However, if any of the messages |
| 3588 | are active, their status is not altered. This option can be used only by an |
| 3589 | admin user. |
| 3590 | |
| 3591 | .option Mvb #<<message id>> |
| 3592 | .index listing||message body |
| 3593 | .index message||listing body of |
| 3594 | This option causes the contents of the message body (-D) spool file to be |
| 3595 | written to the standard output. This option can be used only by an admin user. |
| 3596 | |
| 3597 | .option Mvh #<<message id>> |
| 3598 | .index listing||message headers |
| 3599 | .index header lines||listing |
| 3600 | .index message||listing header lines |
| 3601 | This option causes the contents of the message headers (-H) spool file to be |
| 3602 | written to the standard output. This option can be used only by an admin user. |
| 3603 | |
| 3604 | .option Mvl #<<message id>> |
| 3605 | .index listing||message log |
| 3606 | .index message||listing message log |
| 3607 | This option causes the contents of the message log spool file to be written to |
| 3608 | the standard output. This option can be used only by an admin user. |
| 3609 | |
| 3610 | .option m |
| 3611 | This is apparently a synonym for \-om-\ that is accepted by Sendmail, so Exim |
| 3612 | treats it that way too. |
| 3613 | |
| 3614 | .option N |
| 3615 | .index debugging||\-N-\ option |
| 3616 | .index debugging||suppressing delivery |
| 3617 | This is a debugging option that inhibits delivery of a message at the transport |
| 3618 | level. It implies \-v-\. Exim goes through many of the motions of delivery -- |
| 3619 | it just doesn't actually transport the message, but instead behaves as if it |
| 3620 | had successfully done so. However, it does not make any updates to the retry |
| 3621 | database, and the log entries for deliveries are flagged with `$*$>' rather |
| 3622 | than `=>'. |
| 3623 | |
| 3624 | Because \-N-\ discards any message to which it applies, only root or the Exim |
| 3625 | user are allowed to use it with \-bd-\, \-q-\, \-R-\ or \-M-\. In other words, |
| 3626 | an ordinary user can use it only when supplying an incoming message to which it |
| 3627 | will apply. Although transportation never fails when \-N-\ is set, an address |
| 3628 | may be deferred because of a configuration problem on a transport, or a routing |
| 3629 | problem. Once \-N-\ has been used for a delivery attempt, it sticks to the |
| 3630 | message, and applies to any subsequent delivery attempts that may happen for |
| 3631 | that message. |
| 3632 | |
| 3633 | .option n |
| 3634 | .index Sendmail compatibility||\-n-\ option ignored |
| 3635 | This option is interpreted by Sendmail to mean `no aliasing'. It is ignored by |
| 3636 | Exim. |
| 3637 | |
| 3638 | .option O #<<data>> |
| 3639 | This option is interpreted by Sendmail to mean `set option`. It is ignored by |
| 3640 | Exim. |
| 3641 | |
| 3642 | .option oA #<<file name>> |
| 3643 | .index Sendmail compatibility||\-oA-\ option |
| 3644 | This option is used by Sendmail in conjunction with \-bi-\ to specify an |
| 3645 | alternative alias file name. Exim handles \-bi-\ differently; see the |
| 3646 | description above. |
| 3647 | |
| 3648 | .index SMTP||passed connection |
| 3649 | .option oB #<<n>> |
| 3650 | .index SMTP||multiple deliveries |
| 3651 | .index multiple SMTP deliveries |
| 3652 | This is a debugging option which limits the maximum number of messages that can |
| 3653 | be delivered down one SMTP connection, overriding the value set in any \%smtp%\ |
| 3654 | transport. If <<n>> is omitted, the limit is set to 1. |
| 3655 | |
| 3656 | .option odb |
| 3657 | .index background delivery |
| 3658 | .index delivery||in the background |
| 3659 | This option applies to all modes in which Exim accepts incoming messages, |
| 3660 | including the listening daemon. It requests `background' delivery of such |
| 3661 | messages, which means that the accepting process automatically starts delivery |
| 3662 | process for each message received, but does not wait for the delivery process |
| 3663 | to complete. This is the default action if none of the \-od-\ options are |
| 3664 | present. |
| 3665 | |
| 3666 | If one of the queueing options in the configuration file |
| 3667 | (\queue@_only\ or \queue@_only@_file\, for example) is in effect, \-odb-\ |
| 3668 | overrides it if \queue@_only@_override\ is set true, which is the default |
| 3669 | setting. If \queue@_only@_override\ is set false, \-odb-\ has no effect. |
| 3670 | |
| 3671 | .option odf |
| 3672 | .index foreground delivery |
| 3673 | .index delivery||in the foreground |
| 3674 | This option requests `foreground' (synchronous) delivery when Exim has accepted |
| 3675 | a locally-generated message. (For the daemon it is exactly the same as |
| 3676 | \-odb-\.) A delivery process is automatically started to deliver the |
| 3677 | message, and Exim waits for it to complete before proceeding. |
| 3678 | However, like \-odb-\, this option has no effect if \queue@_only@_override\ is |
| 3679 | false and one of the queueing options in the configuration file is in effect. |
| 3680 | |
| 3681 | .option odi |
| 3682 | This option is synonymous with \-odf-\. It is provided for compatibility with |
| 3683 | Sendmail. |
| 3684 | |
| 3685 | .option odq |
| 3686 | .index non-immediate delivery |
| 3687 | .index delivery||suppressing immediate |
| 3688 | .index queueing incoming messages |
| 3689 | This option applies to all modes in which Exim accepts incoming messages, |
| 3690 | including the listening daemon. It specifies that the accepting process should |
| 3691 | not automatically start a delivery process for each message received. Messages |
| 3692 | are placed on the queue, and remain there until a subsequent queue runner |
| 3693 | process encounters them. |
| 3694 | There are several configuration options (such as \queue@_only\) that can be |
| 3695 | used to queue incoming messages under certain conditions. This option overrides |
| 3696 | all of them and also \-odqs-\. It always forces queueing. |
| 3697 | |
| 3698 | .option odqs |
| 3699 | .index SMTP||delaying delivery |
| 3700 | This option is a hybrid between \-odb-\/\-odi-\ and \-odq-\. |
| 3701 | However, like \-odb-\ and \-odi-\, this option has no effect if |
| 3702 | \queue@_only@_override\ is false and one of the queueing options in the |
| 3703 | configuration file is in effect. |
| 3704 | |
| 3705 | When \-odqs-\ does operate, a delivery process is started for each incoming |
| 3706 | message, in the background by default, but in the foreground if \-odi-\ is also |
| 3707 | present. |
| 3708 | The recipient addresses are routed, and local deliveries are done in the normal |
| 3709 | way. However, if any SMTP deliveries are required, they are not done at this |
| 3710 | time, so the message remains on the queue until a subsequent queue runner |
| 3711 | process encounters it. Because routing was done, Exim knows which messages are |
| 3712 | waiting for which hosts, and so a number of messages for the same host can be |
| 3713 | sent in a single SMTP connection. The \queue@_smtp@_domains\ configuration |
| 3714 | option has the same effect for specific domains. See also the \-qq-\ option. |
| 3715 | |
| 3716 | .option oee |
| 3717 | .index error||reporting |
| 3718 | If an error is detected while a non-SMTP message is being received (for |
| 3719 | example, a malformed address), the error is reported to the sender in a mail |
| 3720 | message. |
| 3721 | .index return code||for \-oee-\ |
| 3722 | Provided this error message is successfully sent, the Exim receiving process |
| 3723 | exits with a return code of zero. If not, the return code is 2 if the problem |
| 3724 | is that the original message has no recipients, or 1 any other error. This is |
| 3725 | the default \-oe$it{x}-\ option if Exim is called as \*rmail*\. |
| 3726 | |
| 3727 | .option oem |
| 3728 | .index error||reporting |
| 3729 | .index return code||for \-oem-\ |
| 3730 | This is the same as \-oee-\, except that Exim always exits with a non-zero |
| 3731 | return code, whether or not the error message was successfully sent. |
| 3732 | This is the default \-oe$it{x}-\ option, unless Exim is called as \*rmail*\. |
| 3733 | |
| 3734 | .option oep |
| 3735 | .index error||reporting |
| 3736 | If an error is detected while a non-SMTP message is being received, the |
| 3737 | error is reported by writing a message to the standard error file (stderr). |
| 3738 | .index return code||for \-oep-\ |
| 3739 | The return code is 1 for all errors. |
| 3740 | |
| 3741 | .option oeq |
| 3742 | .index error||reporting |
| 3743 | This option is supported for compatibility with Sendmail, but has the same |
| 3744 | effect as \-oep-\. |
| 3745 | |
| 3746 | .option oew |
| 3747 | .index error||reporting |
| 3748 | This option is supported for compatibility with Sendmail, but has the same |
| 3749 | effect as \-oem-\. |
| 3750 | |
| 3751 | .option oi |
| 3752 | .index dot||in incoming, non-SMTP message |
| 3753 | This option, which has the same effect as \-i-\, specifies that a dot on a line |
| 3754 | by itself should not terminate an incoming, non-SMTP message. |
| 3755 | Otherwise, a single dot does terminate, though Exim does no special processing |
| 3756 | for other lines that start with a dot. |
| 3757 | This option is set by default if Exim is called as \*rmail*\. See also \-ti-\. |
| 3758 | |
| 3759 | .option oitrue |
| 3760 | This option is treated as synonymous with \-oi-\. |
| 3761 | |
| 3762 | .option oMa #<<host address>> |
| 3763 | .index sender||host address, specifying for local message |
| 3764 | A number of options starting with \-oM-\ can be used to set values associated |
| 3765 | with remote hosts on locally-submitted messages (that is, messages not received |
| 3766 | over TCP/IP). These options can be used by any caller in conjunction with the |
| 3767 | \-bh-\, |
| 3768 | \-be-\, |
| 3769 | \-bf-\, \-bF-\, \-bt-\, or \-bv-\ testing options. In other circumstances, they |
| 3770 | are ignored unless the caller is trusted. |
| 3771 | |
| 3772 | The \-oMa-\ option sets the sender host address. This may include a port number |
| 3773 | at the end, after a full stop (period). For example: |
| 3774 | .display asis |
| 3775 | exim -bs -oMa 10.9.8.7.1234 |
| 3776 | .endd |
| 3777 | An alternative syntax is to enclose the IP address in square brackets, followed |
| 3778 | by a colon and the port number: |
| 3779 | .display asis |
| 3780 | exim -bs -oMa [10.9.8.7]:1234 |
| 3781 | .endd |
| 3782 | The IP address is placed in the \$sender@_host@_address$\ variable, and the |
| 3783 | port, if present, in \$sender@_host@_port$\. |
| 3784 | |
| 3785 | .option oMaa #<<name>> |
| 3786 | .index authentication||name, specifying for local message |
| 3787 | See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMaa-\ |
| 3788 | option sets the value of \$sender@_host@_authenticated$\ (the authenticator |
| 3789 | name). See chapter ~~CHAPSMTPAUTH for a discussion of SMTP authentication. |
| 3790 | |
| 3791 | .option oMai #<<string>> |
| 3792 | .index authentication||id, specifying for local message |
| 3793 | See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMai-\ |
| 3794 | option sets the |
| 3795 | value of \$authenticated@_id$\ (the id that was authenticated). |
| 3796 | This overrides the default value (the caller's login id) for messages from |
| 3797 | local sources. See chapter ~~CHAPSMTPAUTH for a discussion of authenticated |
| 3798 | ids. |
| 3799 | |
| 3800 | .option oMas #<<address>> |
| 3801 | .index authentication||sender, specifying for local message |
| 3802 | See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMas-\ |
| 3803 | option sets the authenticated sender value |
| 3804 | in \$authenticated@_sender$\. |
| 3805 | It overrides the sender address that is created from the caller's login id for |
| 3806 | messages from local sources. See chapter ~~CHAPSMTPAUTH for a discussion of |
| 3807 | authenticated senders. |
| 3808 | |
| 3809 | .option oMi #<<interface address>> |
| 3810 | .index interface||address, specifying for local message |
| 3811 | See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMi-\ |
| 3812 | option sets the IP interface address value. A port number may be included, |
| 3813 | using the same syntax as for \-oMa-\. |
| 3814 | The interface address is placed in \$interface@_address$\ and the port number, |
| 3815 | if present, in \$interface@_port$\. |
| 3816 | |
| 3817 | .option oMr #<<protocol name>> |
| 3818 | .index protocol||incoming, specifying for local message |
| 3819 | See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMr-\ |
| 3820 | option sets the received protocol value |
| 3821 | in \$received@_protocol$\. |
| 3822 | However, this applies only when \-bs-\ is not used. For interactive SMTP input, |
| 3823 | the protocol is determined by whether \\EHLO\\ or \\HELO\\ is used, and is |
| 3824 | always either `local-esmtp' or `local-smtp'. For \-bS-\ (batch SMTP) however, |
| 3825 | the protocol can be set by \-oMr-\. |
| 3826 | |
| 3827 | .option oMs #<<host name>> |
| 3828 | .index sender||host name, specifying for local message |
| 3829 | See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMs-\ |
| 3830 | option sets the sender host name |
| 3831 | in \$sender@_host@_name$\. When this option is present, Exim does not attempt |
| 3832 | to look up a host name from an IP address; it uses the name it is given. |
| 3833 | |
| 3834 | .option oMt #<<ident string>> |
| 3835 | .index sender||ident string, specifying for local message |
| 3836 | See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMt-\ |
| 3837 | option sets the sender ident value |
| 3838 | in \$sender@_ident$\. |
| 3839 | The default setting for local callers is the login id of the calling process. |
| 3840 | |
| 3841 | .option om |
| 3842 | .index Sendmail compatibility||\-om-\ option ignored |
| 3843 | In Sendmail, this option means `me too', indicating that the sender of a |
| 3844 | message should receive a copy of the message if the sender appears in an alias |
| 3845 | expansion. Exim always does this, so the option does nothing. |
| 3846 | |
| 3847 | .option oo |
| 3848 | .index Sendmail compatibility||\-oo-\ option ignored |
| 3849 | This option is ignored. In Sendmail it specifies `old style headers', whatever |
| 3850 | that means. |
| 3851 | |
| 3852 | .option oP #<<path>> |
| 3853 | .index pid (process id)||of daemon |
| 3854 | .index daemon||process id (pid) |
| 3855 | This option is useful only in conjunction with \-bd-\ or \-q-\ with a time |
| 3856 | value. The option specifies the file to which the process id of the daemon is |
| 3857 | written. When \-oX-\ is used with \-bd-\, or when \-q-\ with a time is used |
| 3858 | without \-bd-\, this is the only way of causing Exim to write a pid file, |
| 3859 | because in those cases, the normal pid file is not used. |
| 3860 | |
| 3861 | .option or #<<time>> |
| 3862 | .index timeout||for non-SMTP input |
| 3863 | This option sets a timeout value for incoming non-SMTP messages. If it is not |
| 3864 | set, Exim will wait forever for the standard input. The value can also be set |
| 3865 | by the \receive@_timeout\ option. The format used for specifying times is |
| 3866 | described in section ~~SECTtimeformat. |
| 3867 | |
| 3868 | .option os #<<time>> |
| 3869 | .index timeout||for SMTP input |
| 3870 | .index SMTP||timeout, input |
| 3871 | This option sets a timeout value for incoming SMTP messages. The timeout |
| 3872 | applies to each SMTP command and block of data. The value can also be set by |
| 3873 | the \smtp@_receive@_timeout\ option; it defaults to 5 minutes. The format used |
| 3874 | for specifying times is described in section ~~SECTtimeformat. |
| 3875 | |
| 3876 | .option ov |
| 3877 | This option has exactly the same effect as \-v-\. |
| 3878 | |
| 3879 | .option oX #<<number or string>> |
| 3880 | .index TCP/IP||setting listening ports |
| 3881 | .index TCP/IP||setting listening interfaces |
| 3882 | .index port||receiving TCP/IP |
| 3883 | This option is relevant only when the \-bd-\ (start listening daemon) option is |
| 3884 | also given. It controls which ports and interfaces the daemon uses. Details of |
| 3885 | the syntax, and how it interacts with configuration file options, are given in |
| 3886 | chapter ~~CHAPinterfaces. When \-oX-\ is used to start a daemon, no pid file is |
| 3887 | written unless \-oP-\ is also present to specify a pid file name. |
| 3888 | |
| 3889 | .option pd |
| 3890 | .index Perl||starting the interpreter |
| 3891 | This option applies when an embedded Perl interpreter is linked with Exim (see |
| 3892 | chapter ~~CHAPperl). It overrides the setting of the \perl@_at@_start\ option, |
| 3893 | forcing the starting of the interpreter to be delayed until it is needed. |
| 3894 | |
| 3895 | .option ps |
| 3896 | .index Perl||starting the interpreter |
| 3897 | This option applies when an embedded Perl interpreter is linked with Exim (see |
| 3898 | chapter ~~CHAPperl). It overrides the setting of the \perl@_at@_start\ option, |
| 3899 | forcing the starting of the interpreter to occur as soon as Exim is started. |
| 3900 | |
| 3901 | .option p<<rval>>:<<sval>> |
| 3902 | For compatibility with Sendmail, this option |
| 3903 | is equivalent to |
| 3904 | .display |
| 3905 | -oMr <<rval>> -oMs <<sval>> |
| 3906 | .endd |
| 3907 | It sets the incoming protocol and host name (for trusted callers). The |
| 3908 | host name and its colon can be omitted when only the protocol is to be set. |
| 3909 | Note the Exim already has two private options, \-pd-\ and \-ps-\, that refer to |
| 3910 | embedded Perl. It is therefore impossible to set a protocol value of \"p"\ or |
| 3911 | \"s"\ using this option (but that does not seem a real limitation). |
| 3912 | |
| 3913 | .option q |
| 3914 | .index queue runner||starting manually |
| 3915 | This option is normally restricted to admin users. However, there is a |
| 3916 | configuration option called \prod@_requires@_admin\ which can be set false to |
| 3917 | relax this restriction (and also the same requirement for the \-M-\, \-R-\, and |
| 3918 | \-S-\ options). |
| 3919 | |
| 3920 | .index queue runner||description of operation |
| 3921 | The \-q-\ option starts one queue runner process. This scans the queue of |
| 3922 | waiting messages, and runs a delivery process for each one in turn. It waits |
| 3923 | for each delivery process to finish before starting the next one. A delivery |
| 3924 | process may not actually do any deliveries if the retry times for the addresses |
| 3925 | have not been reached. Use \-qf-\ (see below) if you want to override this. |
| 3926 | .index SMTP||passed connection |
| 3927 | .index SMTP||multiple deliveries |
| 3928 | .index multiple SMTP deliveries |
| 3929 | If the delivery process spawns other processes to deliver other messages down |
| 3930 | passed SMTP connections, the queue runner waits for these to finish before |
| 3931 | proceeding. |
| 3932 | |
| 3933 | When all the queued messages have been considered, the original queue runner |
| 3934 | process terminates. In other words, a single pass is made over the waiting |
| 3935 | mail, one message at a time. Use \-q-\ with a time (see below) if you want this |
| 3936 | to be repeated periodically. |
| 3937 | |
| 3938 | Exim processes the waiting messages in an unpredictable order. It isn't very |
| 3939 | random, but it is likely to be different each time, which is all that matters. |
| 3940 | If one particular message screws up a remote MTA, other messages to the same |
| 3941 | MTA have a chance of getting through if they get tried first. |
| 3942 | |
| 3943 | It is possible to cause the messages to be processed in lexical message id |
| 3944 | order, which is essentially the order in which they arrived, by setting the |
| 3945 | \queue@_run@_in@_order\ option, but this is not recommended for normal use. |
| 3946 | |
| 3947 | .option q <<qflags>> |
| 3948 | The \-q-\ option may be followed by one or more flag letters that change its |
| 3949 | behaviour. They are all optional, but if more than one is present, they must |
| 3950 | appear in the correct order. Each flag is described in a separate item below. |
| 3951 | |
| 3952 | .option qq... |
| 3953 | .index queue||double scanning |
| 3954 | .index queue||routing |
| 3955 | .index routing||whole queue before delivery |
| 3956 | An option starting with \-qq-\ requests a two-stage queue run. In the first |
| 3957 | stage, the queue is scanned as if the \queue@_smtp@_domains\ option matched |
| 3958 | every domain. Addresses are routed, local deliveries happen, but no remote |
| 3959 | transports are run. |
| 3960 | .index hints database||remembering routing |
| 3961 | The hints database that remembers which messages are |
| 3962 | waiting for specific hosts is updated, as if delivery to those hosts had been |
| 3963 | deferred. After this is complete, a second, normal queue scan happens, with |
| 3964 | routing and delivery taking place as normal. Messages that are routed to the |
| 3965 | same host should mostly be delivered down a single SMTP |
| 3966 | .index SMTP||passed connection |
| 3967 | .index SMTP||multiple deliveries |
| 3968 | .index multiple SMTP deliveries |
| 3969 | connection because of the hints that were set up during the first queue scan. |
| 3970 | This option may be useful for hosts that are connected to the Internet |
| 3971 | intermittently. |
| 3972 | |
| 3973 | .option q[q]i... |
| 3974 | .index queue||initial delivery |
| 3975 | If the \*i*\ flag is present, the queue runner runs delivery processes only for |
| 3976 | those messages that haven't previously been tried. (\*i*\ stands for `initial |
| 3977 | delivery'.) This can be helpful if you are putting messages on the queue using |
| 3978 | \-odq-\ and want a queue runner just to process the new messages. |
| 3979 | |
| 3980 | .option q[q][i]f... |
| 3981 | .index queue||forcing delivery |
| 3982 | .index delivery||forcing in queue run |
| 3983 | If one \*f*\ flag is present, a delivery attempt is forced for each non-frozen |
| 3984 | message, whereas without \f\ only those non-frozen addresses that have passed |
| 3985 | their retry times are tried. |
| 3986 | |
| 3987 | .option q[q][i]ff... |
| 3988 | .index frozen messages||forcing delivery |
| 3989 | If \*ff*\ is present, a delivery attempt is forced for every message, whether |
| 3990 | frozen or not. |
| 3991 | |
| 3992 | .option q[q][i][f[f]]l |
| 3993 | .index queue||local deliveries only |
| 3994 | The \*l*\ (the letter `ell') flag specifies that only local deliveries are to be |
| 3995 | done. If a message requires any remote deliveries, it remains on the queue for |
| 3996 | later delivery. |
| 3997 | |
| 3998 | .option q <<qflags>>#<<start id>>#<<end id>> |
| 3999 | .index queue||delivering specific messages |
| 4000 | When scanning the queue, Exim can be made to skip over messages whose ids are |
| 4001 | lexically less than a given value by following the \-q-\ option with a starting |
| 4002 | message id. For example: |
| 4003 | .display |
| 4004 | exim -q 0t5C6f-0000c8-00 |
| 4005 | .endd |
| 4006 | Messages that arrived earlier than \"0t5C6f-0000c8-00"\ are not inspected. If a |
| 4007 | second message id is given, messages whose ids are lexically greater than it |
| 4008 | are also skipped. If the same id is given twice, for example, |
| 4009 | .display |
| 4010 | exim -q 0t5C6f-0000c8-00 0t5C6f-0000c8-00 |
| 4011 | .endd |
| 4012 | just one delivery process is started, for that message. This differs from \-M-\ |
| 4013 | in that retry data is respected, and it also differs from \-Mc-\ in that it |
| 4014 | counts as a delivery from a queue run. Note that the selection mechanism does |
| 4015 | not affect the order in which the messages are scanned. There are also other |
| 4016 | ways of selecting specific sets of messages for delivery in a queue run -- see |
| 4017 | \-R-\ and \-S-\. |
| 4018 | |
| 4019 | .option q <<qflags>><<time>> |
| 4020 | .index queue runner||starting periodically |
| 4021 | .index periodic queue running |
| 4022 | When a time value is present, the \-q-\ option causes Exim to run as a daemon, |
| 4023 | starting a queue runner process at intervals specified by the given time value |
| 4024 | (whose format is described in section ~~SECTtimeformat). This form of the \-q-\ |
| 4025 | option is commonly combined with the \-bd-\ option, in which case a single |
| 4026 | daemon process handles both functions. A common way of starting up a combined |
| 4027 | daemon at system boot time is to use a command such as |
| 4028 | .display |
| 4029 | /usr/exim/bin/exim -bd -q30m |
| 4030 | .endd |
| 4031 | Such a daemon listens for incoming SMTP calls, and also starts a queue runner |
| 4032 | process every 30 minutes. |
| 4033 | |
| 4034 | When a daemon is started by \-q-\ with a time value, but without \-bd-\, no pid |
| 4035 | file is written unless one is explicitly requested by the \-oP-\ option. |
| 4036 | |
| 4037 | .option qR <<rsflags>>#<<string>> |
| 4038 | This option is synonymous with \-R-\. It is provided for Sendmail |
| 4039 | compatibility. |
| 4040 | |
| 4041 | .option qS <<rsflags>>#<<string>> |
| 4042 | This option is synonymous with \-S-\. |
| 4043 | |
| 4044 | .option R <<rsflags>>#<<string>> |
| 4045 | .index queue runner||for specific recipients |
| 4046 | .index delivery||to given domain |
| 4047 | .index domain||delivery to |
| 4048 | The <<rsflags>> may be empty, in which case the white space before the string |
| 4049 | is optional, unless the string is \*f*\, \*ff*\, \*r*\, \*rf*\, or \*rff*\, |
| 4050 | which are the possible values for <<rsflags>>. White space is required if |
| 4051 | <<rsflags>> is not empty. |
| 4052 | |
| 4053 | This option is similar to \-q-\ with no time value, that is, it causes Exim to |
| 4054 | perform a single queue run, except that, when scanning the messages on the |
| 4055 | queue, Exim processes only those that have at least one undelivered recipient |
| 4056 | address containing the given string, which is checked in a case-independent |
| 4057 | way. If the <<rsflags>> start with \*r*\, <<string>> is interpreted as a regular |
| 4058 | expression; otherwise it is a literal string. |
| 4059 | |
| 4060 | Once a message is selected, all its addresses are processed. For the first |
| 4061 | selected message, Exim overrides any retry information and forces a delivery |
| 4062 | attempt for each undelivered address. This means that if delivery of any |
| 4063 | address in the first message is successful, any existing retry information is |
| 4064 | deleted, and so delivery attempts for that address in subsequently selected |
| 4065 | messages (which are processed without forcing) will run. However, if delivery |
| 4066 | of any address does not succeed, the retry information is updated, and in |
| 4067 | subsequently selected messages, the failing address will be skipped. |
| 4068 | |
| 4069 | If the <<rsflags>> contain \*f*\ or \*ff*\, the delivery forcing applies to all |
| 4070 | selected messages, not just the first; |
| 4071 | .index frozen messages||forcing delivery |
| 4072 | frozen messages are included when \*ff*\ is present. |
| 4073 | |
| 4074 | The \-R-\ option makes it straightforward to initiate delivery of all messages |
| 4075 | to a given domain after a host has been down for some time. When the SMTP |
| 4076 | command \\ETRN\\ is accepted by its ACL (see chapter ~~CHAPACL), its default |
| 4077 | effect is to run Exim with the \-R-\ option, but it can be configured to run an |
| 4078 | arbitrary command instead. |
| 4079 | |
| 4080 | .option r |
| 4081 | This is a documented (for Sendmail) obsolete alternative name for \-f-\. |
| 4082 | |
| 4083 | .index delivery||from given sender |
| 4084 | .option S <<rsflags>>#<<string>> |
| 4085 | .index queue runner||for specific senders |
| 4086 | This option acts like \-R-\ except that it checks the string against each |
| 4087 | message's sender instead of against the recipients. If \-R-\ is also set, both |
| 4088 | conditions must be met for a message to be selected. If either of the options |
| 4089 | has \*f*\ or \*ff*\ in its flags, the associated action is taken. |
| 4090 | |
| 4091 | .option Tqt#<<times>> |
| 4092 | This an option that is exclusively for use by the Exim testing suite. |
| 4093 | It is not recognized when Exim is run normally. It allows for the setting up |
| 4094 | of explicit `queue times' so that various warning/retry features can be |
| 4095 | tested. |
| 4096 | |
| 4097 | .option t |
| 4098 | .index recipient||extracting from header lines |
| 4099 | .index ::Bcc:: header line |
| 4100 | .index ::Cc:: header line |
| 4101 | .index ::To:: header line |
| 4102 | When Exim is receiving a locally-generated, non-SMTP message on its standard |
| 4103 | input, the \-t-\ option causes the recipients of the message to be obtained |
| 4104 | from the ::To::, ::Cc::, and ::Bcc:: header lines in the message instead of from |
| 4105 | the command arguments. The addresses are extracted before any rewriting takes |
| 4106 | place. |
| 4107 | |
| 4108 | .index Sendmail compatibility||\-t-\ option |
| 4109 | If the command has any arguments, they specify addresses to which the message |
| 4110 | is $it{not} to be delivered. That is, the argument addresses are removed from |
| 4111 | the recipients list obtained from the headers. This is compatible with Smail 3 |
| 4112 | and in accordance with the documented behaviour of several versions of |
| 4113 | Sendmail, as described in man pages on a number of operating systems (e.g. |
| 4114 | Solaris 8, IRIX 6.5, HP-UX 11). However, some versions of Sendmail $it{add} |
| 4115 | argument addresses to those obtained from the headers, and the O'Reilly |
| 4116 | Sendmail book documents it that way. Exim can be made to add argument addresses |
| 4117 | instead of subtracting them by setting the option |
| 4118 | \extract__addresses__remove__arguments\ false. |
| 4119 | |
| 4120 | If a ::Bcc:: header line is present, it is removed from the message unless |
| 4121 | there is no ::To:: or ::Cc::, in which case a ::Bcc:: line with no data is |
| 4122 | created. This is necessary for conformity with the original RFC 822 standard; |
| 4123 | the requirement has been removed in RFC 2822, but that is still very new. |
| 4124 | |
| 4125 | .index \Resent@-\ header lines||with \-t-\ |
| 4126 | If there are any \Resent@-\ header lines in the message, Exim extracts |
| 4127 | recipients from all ::Resent-To::, ::Resent-Cc::, and ::Resent-Bcc:: header |
| 4128 | lines instead of from ::To::, ::Cc::, and ::Bcc::. This is for compatibility |
| 4129 | with Sendmail and other MTAs. (Prior to release 4.20, Exim gave an error if |
| 4130 | \-t-\ was used in conjunction with \Resent@-\ header lines.) |
| 4131 | |
| 4132 | RFC 2822 talks about different sets of \Resent@-\ header lines (for when a |
| 4133 | message is resent several times). The RFC also specifies that they should be |
| 4134 | added at the front of the message, and separated by ::Received:: lines. It is |
| 4135 | not at all clear how \-t-\ should operate in the present of multiple sets, |
| 4136 | nor indeed exactly what constitutes a `set'. |
| 4137 | In practice, it seems that MUAs do not follow the RFC. The \Resent@-\ lines are |
| 4138 | often added at the end of the header, and if a message is resent more than |
| 4139 | once, it is common for the original set of \Resent@-\ headers to be renamed as |
| 4140 | \X-Resent@-\ when a new set is added. This removes any possible ambiguity. |
| 4141 | |
| 4142 | .option ti |
| 4143 | This option is exactly equivalent to \-t-\ \-i-\. It is provided for |
| 4144 | compatibility with Sendmail. |
| 4145 | |
| 4146 | .option tls-on-connect |
| 4147 | .index TLS||use without STARTTLS |
| 4148 | .index TLS||automatic start |
| 4149 | This option is available when Exim is compiled with TLS support. It makes it |
| 4150 | possible to support legacy clients that do not support the \\STARTTLS\\ |
| 4151 | command, but instead expect to start up a TLS session as soon as a connection |
| 4152 | to the server is established. These clients use a special port (usually called |
| 4153 | the `ssmtp' port) instead of the normal SMTP port 25. The \-tls-on-connect-\ |
| 4154 | option can be used to run Exim in this way from \*inetd*\, and it can also be |
| 4155 | used to run a special daemon that operates in this manner (use \-oX-\ to |
| 4156 | specify the port). However, although it is possible to run one daemon that |
| 4157 | listens on several ports, it is not possible to have some of them operate one |
| 4158 | way and some the other. With only a few clients that need the legacy support, a |
| 4159 | convenient approach is to use a daemon for normal SMTP (with or without |
| 4160 | \\STARTTLS\\) and \*inetd*\ with \-tls-on-connect-\ for the legacy clients. |
| 4161 | |
| 4162 | .option U |
| 4163 | .index Sendmail compatibility||\-U-\ option ignored |
| 4164 | Sendmail uses this option for `initial message submission', and its |
| 4165 | documentation states that in future releases, it may complain about |
| 4166 | syntactically invalid messages rather than fixing them when this flag is not |
| 4167 | set. Exim ignores this option. |
| 4168 | |
| 4169 | .option v |
| 4170 | This option causes Exim to write information to the standard error stream, |
| 4171 | describing what it is doing. In particular, it shows the log lines for |
| 4172 | receiving and delivering a message, and if an SMTP connection is made, the SMTP |
| 4173 | dialogue is shown. Some of the log lines shown may not actually be written to |
| 4174 | the log if the setting of \log@_selector\ discards them. Any relevant selectors |
| 4175 | are shown with each log line. If none are shown, the logging is unconditional. |
| 4176 | |
| 4177 | .option x |
| 4178 | AIX uses \-x-\ for a private purpose (`mail from a local mail program has |
| 4179 | National Language Support extended characters in the body of the mail item'). |
| 4180 | It sets \-x-\ when calling the MTA from its \mail\ command. Exim ignores this |
| 4181 | option. |
| 4182 | |
| 4183 | .endoptions |
| 4184 | |
| 4185 | |
| 4186 | |
| 4187 | . |
| 4188 | . |
| 4189 | . |
| 4190 | . |
| 4191 | . ============================================================================ |
| 4192 | .chapter The Exim run time configuration file |
| 4193 | .set runningfoot "configuration file" |
| 4194 | .rset CHAPconf ~~chapter |
| 4195 | |
| 4196 | .index run time configuration |
| 4197 | .index configuration file||general description |
| 4198 | .index \\CONFIGURE@_FILE\\ |
| 4199 | Exim uses a single run time configuration file that is read whenever an Exim |
| 4200 | binary is executed. Note that in normal operation, this happens frequently, |
| 4201 | because Exim is designed to operate in a distributed manner, without central |
| 4202 | control. |
| 4203 | |
| 4204 | The name of the configuration file is compiled into the binary for security |
| 4205 | reasons, and is specified by the \\CONFIGURE@_FILE\\ compilation option. In |
| 4206 | most configurations, this specifies a single file. However, it is permitted to |
| 4207 | give a colon-separated list of file names, in which case Exim uses the first |
| 4208 | existing file in the list. |
| 4209 | |
| 4210 | .index \\EXIM@_USER\\ |
| 4211 | .index \\EXIM@_GROUP\\ |
| 4212 | .index configuration file||ownership |
| 4213 | .index ownership||configuration file |
| 4214 | The run time configuration file must be owned by root or by the user that |
| 4215 | is specified at compile time by the \\EXIM@_USER\\ option, |
| 4216 | or by the user that is specified at compile time by the \\CONFIGURE@_OWNER\\ |
| 4217 | option (if set). |
| 4218 | The configuration file must not be world-writeable or group-writeable, unless |
| 4219 | its group is the one specified at compile time by the \\EXIM@_GROUP\\ option. |
| 4220 | |
| 4221 | \**Warning**\: In a conventional configuration, where the Exim binary is setuid |
| 4222 | to root, anybody who is able to edit the run time configuration file has an |
| 4223 | easy way to run commands as root. If you make your mail administrators members |
| 4224 | of the Exim group, but do not trust them with root, make sure that the run time |
| 4225 | configuration is not group writeable. |
| 4226 | |
| 4227 | |
| 4228 | A default configuration file, which will work correctly in simple situations, |
| 4229 | is provided in the file \(src/configure.default)\. |
| 4230 | If \\CONFIGURE@_FILE\\ defines just one file name, the installation process |
| 4231 | copies the default configuration to a new file of that name if it did not |
| 4232 | previously exist. If \\CONFIGURE@_FILE\\ is a list, no default is automatically |
| 4233 | installed. Chapter ~~CHAPdefconfil is a `walk-through' discussion of the |
| 4234 | default configuration. |
| 4235 | |
| 4236 | .index configuration file||errors in |
| 4237 | .index error||in configuration file |
| 4238 | .index return code||for bad configuration |
| 4239 | If a syntax error is detected while reading the configuration file, Exim |
| 4240 | writes a message on the standard error, and exits with a non-zero return code. |
| 4241 | The message is also written to the panic log. |
| 4242 | |
| 4243 | |
| 4244 | .section Using a different configuration file |
| 4245 | .index configuration file||alternate |
| 4246 | A one-off alternate configuration can be specified by the \-C-\ command line |
| 4247 | option, which may specify a single file or a list of files. However, when \-C-\ |
| 4248 | is used, Exim gives up its root privilege, unless called by root or the Exim |
| 4249 | user (or unless the argument for \-C-\ is identical to the built-in value from |
| 4250 | \\CONFIGURE@_FILE\\). \-C-\ is useful mainly for checking the syntax of |
| 4251 | configuration files before installing them. No owner or group checks are done |
| 4252 | on a configuration file specified by \-C-\. |
| 4253 | |
| 4254 | The privileged use of \-C-\ by the Exim user can be locked out by setting |
| 4255 | \\ALT@_CONFIG@_ROOT@_ONLY\\ in \(Local/Makefile)\ when building Exim. However, |
| 4256 | if you do this, you also lock out the possibility of testing a |
| 4257 | configuration using \-C-\ right through message reception and delivery, even if |
| 4258 | the caller is root. The reception works, but by that time, Exim is running as |
| 4259 | the Exim user, so when it re-execs to regain privilege for the delivery, the |
| 4260 | use of \-C-\ causes privilege to be lost. However, root can test reception and |
| 4261 | delivery using two separate commands (one to put a message on the queue, using |
| 4262 | \-odq-\, and another to do the delivery, using \-M-\). |
| 4263 | |
| 4264 | If \\ALT@_CONFIG@_PREFIX\\ is defined \(in Local/Makefile)\, it specifies a |
| 4265 | prefix string with which any file named in a \-C-\ command line option must |
| 4266 | start. In addition, the file name must not contain the sequence \"/../"\. There |
| 4267 | is no default setting for \\ALT@_CONFIG@_PREFIX\\; when it is unset, any file |
| 4268 | name can be used with \-C-\. |
| 4269 | |
| 4270 | One-off changes to a configuration can be specified by the \-D-\ command line |
| 4271 | option, which defines and overrides values for macros used inside the |
| 4272 | configuration file. However, like \-C-\, the use of this option by a |
| 4273 | non-privileged user causes Exim to discard its root privilege. |
| 4274 | If \\DISABLE@_D@_OPTION\\ is defined in \(Local/Makefile)\, the use of \-D-\ is |
| 4275 | completely disabled, and its use causes an immediate error exit. |
| 4276 | |
| 4277 | Some sites may wish to use the same Exim binary on different machines that |
| 4278 | share a file system, but to use different configuration files on each machine. |
| 4279 | If \\CONFIGURE@_FILE@_USE@_NODE\\ is defined in \(Local/Makefile)\, Exim first |
| 4280 | looks for a file whose name is the configuration file name followed by a dot |
| 4281 | and the machine's node name, as obtained from the \*uname()*\ function. If this |
| 4282 | file does not exist, the standard name is tried. This processing occurs for |
| 4283 | each file name in the list given by \\CONFIGURE@_FILE\\ or \-C-\. |
| 4284 | |
| 4285 | In some esoteric situations different versions of Exim may be run under |
| 4286 | different effective uids and the \\CONFIGURE@_FILE@_USE@_EUID\\ is defined to |
| 4287 | help with this. See the comments in \(src/EDITME)\ for details. |
| 4288 | |
| 4289 | |
| 4290 | .section Configuration file format |
| 4291 | .rset SECTconffilfor "~~chapter.~~section" |
| 4292 | .index configuration file||format of |
| 4293 | .index format||configuration file |
| 4294 | Exim's configuration file is divided into a number of different parts. General |
| 4295 | option settings must always appear at the start of the file. The other parts |
| 4296 | are all optional, and may appear in any order. Each part other than the first |
| 4297 | is introduced by the word `begin' followed by the name of the part. The |
| 4298 | optional parts are: |
| 4299 | |
| 4300 | .numberpars $. |
| 4301 | \*ACL*\: Access control lists for controlling incoming SMTP mail. |
| 4302 | .nextp |
| 4303 | .index \\AUTH\\||configuration |
| 4304 | \*authenticators*\: Configuration settings for the authenticator drivers. These |
| 4305 | are concerned with the SMTP \\AUTH\\ command (see chapter ~~CHAPSMTPAUTH). |
| 4306 | .nextp |
| 4307 | \*routers*\: Configuration settings for the router drivers. Routers process |
| 4308 | addresses and determine how the message is to be delivered. |
| 4309 | .nextp |
| 4310 | \*transports*\: Configuration settings for the transport drivers. Transports |
| 4311 | define mechanisms for copying messages to destinations. |
| 4312 | .nextp |
| 4313 | \*retry*\: Retry rules, for use when a message cannot be immediately delivered. |
| 4314 | .nextp |
| 4315 | \*rewrite*\: Global address rewriting rules, for use when a message arrives and |
| 4316 | when new addresses are generated during delivery. |
| 4317 | .nextp |
| 4318 | \*local@_scan*\: Private options for the \*local@_scan()*\ function. If you |
| 4319 | want to use this feature, you must set |
| 4320 | .display asis |
| 4321 | LOCAL_SCAN_HAS_OPTIONS=yes |
| 4322 | .endd |
| 4323 | in \(Local/Makefile)\ before building Exim. Full details of the |
| 4324 | \*local@_scan()*\ facility are given in chapter ~~CHAPlocalscan. |
| 4325 | .endp |
| 4326 | Blank lines in the file, and lines starting with a @# character (ignoring |
| 4327 | leading white space) are treated as comments and are ignored. \**Note**\: a |
| 4328 | @# character other than at the beginning of a line is not treated specially, |
| 4329 | and does not introduce a comment. |
| 4330 | |
| 4331 | Any non-comment line can be continued by ending it with a backslash. Trailing |
| 4332 | white space after the backslash is ignored, and leading white space at the |
| 4333 | start of continuation lines is also ignored. |
| 4334 | Comment lines beginning with @# (but not empty lines) may appear in the middle |
| 4335 | of a sequence of continuation lines. |
| 4336 | |
| 4337 | A convenient way to create a configuration file is to start from the |
| 4338 | default, which is supplied in \(src/configure.default)\, and add, delete, or |
| 4339 | change settings as required. |
| 4340 | |
| 4341 | The ACLs, retry rules, and rewriting rules have their own syntax which is |
| 4342 | described in chapters ~~CHAPACL, ~~CHAPretry, and ~~CHAPrewrite, respectively. |
| 4343 | The other parts of the configuration file have some syntactic items in common, |
| 4344 | and these are described below, from section ~~SECTcos onwards. Before that, the |
| 4345 | inclusion, macro, and conditional facilities are described. |
| 4346 | |
| 4347 | |
| 4348 | .section File inclusions in the configuration file |
| 4349 | .index inclusions in configuration file |
| 4350 | .index configuration file||including other files |
| 4351 | .index .include in configuration file |
| 4352 | .index .include@_if@_exists in configuration file |
| 4353 | You can include other files inside Exim's run time configuration file by |
| 4354 | using this syntax: |
| 4355 | .display |
| 4356 | @.include <<file name>> |
| 4357 | .endd |
| 4358 | or |
| 4359 | .display |
| 4360 | @.include@_if@_exists <<file name>> |
| 4361 | .endd |
| 4362 | on a line by itself. Double quotes round the file name are optional. If you use |
| 4363 | the first form, a configuration error occurs if the file does not exist; the |
| 4364 | second form does nothing for non-existent files. |
| 4365 | |
| 4366 | Includes may be nested to any depth, but remember that Exim reads its |
| 4367 | configuration file often, so it is a good idea to keep them to a minimum. |
| 4368 | If you change the contents of an included file, you must HUP the daemon, |
| 4369 | because an included file is read only when the configuration itself is read. |
| 4370 | |
| 4371 | The processing of inclusions happens early, at a physical line level, so, like |
| 4372 | comment lines, an inclusion can be used in the middle of an option setting, |
| 4373 | for example: |
| 4374 | .display asis |
| 4375 | hosts_lookup = a.b.c \ |
| 4376 | .include /some/file |
| 4377 | .endd |
| 4378 | Include processing happens |
| 4379 | after |
| 4380 | macro processing (see below). Its effect is to process the lines of the file as |
| 4381 | if they occurred inline where the inclusion appears. |
| 4382 | |
| 4383 | |
| 4384 | .section Macros in the configuration file |
| 4385 | .rset SECTmacrodefs "~~chapter.~~section" |
| 4386 | .index macro||description of |
| 4387 | .index configuration file||macros |
| 4388 | If a line in the main part of the configuration (that is, before the first |
| 4389 | `begin' line) begins with an upper case letter, it is taken as a macro |
| 4390 | definition, and must be of the form |
| 4391 | .display |
| 4392 | <<name>> = <<rest of line>> |
| 4393 | .endd |
| 4394 | The name must consist of letters, digits, and underscores, and need not all be |
| 4395 | in upper case, though that is recommended. The rest of the line, including any |
| 4396 | continuations, is the replacement text, and has leading and trailing white |
| 4397 | space removed. Quotes are not removed. The replacement text can never end with |
| 4398 | a backslash character, but this doesn't seem to be a serious limitation. |
| 4399 | |
| 4400 | Once a macro is defined, all subsequent lines in the file (and any included |
| 4401 | files) are scanned for the macro name; if there are several macros, the line is |
| 4402 | scanned for each in turn, in the order in which they are defined. The |
| 4403 | replacement text is not re-scanned for the current macro, though it is scanned |
| 4404 | for subsequently defined macros. For this reason, a macro name may not contain |
| 4405 | the name of a previously defined macro as a substring. You could, for example, |
| 4406 | define |
| 4407 | .display asis |
| 4408 | ABCD_XYZ = <<something>> |
| 4409 | ABCD = <<something else>> |
| 4410 | .endd |
| 4411 | but putting the definitions in the opposite order would provoke a configuration |
| 4412 | error. |
| 4413 | |
| 4414 | Macro expansion is applied to individual lines from the file, before checking |
| 4415 | for line continuation or file inclusion (see below). If a line consists solely |
| 4416 | of a macro name, and the expansion of the macro is empty, the line is ignored. |
| 4417 | A macro at the start of a line may turn the line into a comment line or a |
| 4418 | \".include"\ line. |
| 4419 | |
| 4420 | As an example of macro usage, consider a configuration where aliases are looked |
| 4421 | up in a MySQL database. It helps to keep the file less cluttered if long |
| 4422 | strings such as SQL statements are defined separately as macros, for example: |
| 4423 | .display asis |
| 4424 | ALIAS_QUERY = select mailbox from user where \ |
| 4425 | login=${quote_mysql:$local_part}; |
| 4426 | .endd |
| 4427 | This can then be used in a \%redirect%\ router setting like this: |
| 4428 | .display asis |
| 4429 | data = ${lookup mysql{ALIAS_QUERY}} |
| 4430 | .endd |
| 4431 | In earlier versions of Exim macros were sometimes used for domain, host, or |
| 4432 | address lists. In Exim 4 these are handled better by named lists -- see section |
| 4433 | ~~SECTnamedlists. |
| 4434 | |
| 4435 | Macros in the configuration file can be overridden by the \-D-\ command line |
| 4436 | option, but Exim gives up its root privilege when \-D-\ is used, unless called |
| 4437 | by root or the Exim user. |
| 4438 | |
| 4439 | |
| 4440 | .section Conditional skips in the configuration file |
| 4441 | .index configuration file||conditional skips |
| 4442 | .index .ifdef |
| 4443 | You can use the directives \".ifdef"\, \".ifndef"\, \".elifdef"\, |
| 4444 | \".elifndef"\, \".else"\, and \".endif"\ to dynamically include or exclude |
| 4445 | portions of the configuration file. The processing happens whenever the file is |
| 4446 | read (that is, when an Exim binary starts to run). |
| 4447 | |
| 4448 | The implementation is very simple. Instances of the first four directives must |
| 4449 | be followed by text that includes the names of one or macros. The condition |
| 4450 | that is tested is whether or not any macro substitution has taken place in the |
| 4451 | line. Thus: |
| 4452 | .display |
| 4453 | @.ifdef AAA |
| 4454 | message@_size@_limit = 50M |
| 4455 | @.else |
| 4456 | message@_size@_limit = 100M |
| 4457 | @.endif |
| 4458 | .endd |
| 4459 | sets a message size limit of 50M if the macro \"AAA"\ is defined, and 100M |
| 4460 | otherwise. If there is more than one macro named on the line, the condition |
| 4461 | is true if any of them are defined. That is, it is an `or' condition. To |
| 4462 | obtain an `and' condition, you need to use nested \".ifdef"\s. |
| 4463 | |
| 4464 | Although you can use a macro expansion to generate one of these directives, |
| 4465 | it is not very useful, because the condition `there was a macro substitution |
| 4466 | in this line' will always be true. |
| 4467 | |
| 4468 | Text following \".else"\ and \".endif"\ is ignored, and can be used as comment |
| 4469 | to clarify complicated nestings. |
| 4470 | |
| 4471 | |
| 4472 | .section Common option syntax |
| 4473 | .rset SECTcos "~~chapter.~~section" |
| 4474 | .index common option syntax |
| 4475 | .index syntax of common options |
| 4476 | .index configuration file||common option syntax |
| 4477 | For the main set of options, driver options, and \*local@_scan()*\ options, |
| 4478 | each setting is on a line by itself, and starts with a name consisting of |
| 4479 | lower-case letters and underscores. Many options require a data value, and in |
| 4480 | these cases the name must be followed by an equals sign (with optional white |
| 4481 | space) and then the value. For example: |
| 4482 | .display asis |
| 4483 | qualify_domain = mydomain.example.com |
| 4484 | .endd |
| 4485 | Some option settings may contain sensitive data, for example, passwords for |
| 4486 | accessing databases. To stop non-admin users from using the \-bP-\ command line |
| 4487 | option to read these values, you can precede the option settings with the word |
| 4488 | `hide'. For example: |
| 4489 | .display asis |
| 4490 | hide mysql_servers = localhost/users/admin/secret-password |
| 4491 | .endd |
| 4492 | For non-admin users, such options are displayed like this: |
| 4493 | .display asis |
| 4494 | mysql_servers = <value not displayable> |
| 4495 | .endd |
| 4496 | If `hide' is used on a driver option, it hides the value of that option on all |
| 4497 | instances of the same driver. |
| 4498 | |
| 4499 | The following sections describe the syntax used for the different data types |
| 4500 | that are found in option settings. |
| 4501 | |
| 4502 | .section Boolean options |
| 4503 | .index format||boolean |
| 4504 | .index boolean configuration values |
| 4505 | Options whose type is given as boolean are on/off switches. There are two |
| 4506 | different ways of specifying such options: with and without a data value. If |
| 4507 | the option name is specified on its own without data, the switch is turned on; |
| 4508 | if it is preceded by `no@_' or `not@_' the switch is turned off. However, |
| 4509 | boolean options may optionally be followed by an equals sign and one of the |
| 4510 | words `true', `false', `yes', or `no', as an alternative syntax. For example, |
| 4511 | the following two settings have exactly the same effect: |
| 4512 | .display asis |
| 4513 | queue_only |
| 4514 | queue_only = true |
| 4515 | .endd |
| 4516 | The following two lines also have the same (opposite) effect: |
| 4517 | .display asis |
| 4518 | no_queue_only |
| 4519 | queue_only = false |
| 4520 | .endd |
| 4521 | You can use whichever syntax you prefer. |
| 4522 | |
| 4523 | |
| 4524 | |
| 4525 | .section Integer values |
| 4526 | .index integer configuration values |
| 4527 | .index format||integer |
| 4528 | If an integer data item starts with the characters `0x', the remainder of it |
| 4529 | is interpreted as a hexadecimal number. Otherwise, it is treated as octal if it |
| 4530 | starts with the digit 0, and decimal if not. If an integer value is followed by |
| 4531 | the letter K, it is multiplied by 1024; if it is followed by the letter M, it |
| 4532 | is multiplied by 1024x1024. |
| 4533 | |
| 4534 | When the values of integer option settings are output, values which are an |
| 4535 | exact multiple of 1024 or 1024x1024 are |
| 4536 | sometimes, but not always, |
| 4537 | printed using the letters K and M. The printing style is independent of the |
| 4538 | actual input format that was used. |
| 4539 | |
| 4540 | .section Octal integer values |
| 4541 | .index integer format |
| 4542 | .index format||octal integer |
| 4543 | The value of an option specified as an octal integer is always interpreted in |
| 4544 | octal, whether or not it starts with the digit zero. Such options are always |
| 4545 | output in octal. |
| 4546 | |
| 4547 | |
| 4548 | .section Fixed point number values |
| 4549 | .index fixed point configuration values |
| 4550 | .index format||fixed point |
| 4551 | A fixed point number consists of a decimal integer, optionally followed by a |
| 4552 | decimal point and up to three further digits. |
| 4553 | |
| 4554 | |
| 4555 | .section Time interval values |
| 4556 | .index time interval||specifying in configuration |
| 4557 | .index format||time interval |
| 4558 | .rset SECTtimeformat "~~chapter.~~section" |
| 4559 | A time interval is specified as a sequence of numbers, each followed by one of |
| 4560 | the following letters, with no intervening white space: |
| 4561 | .display rm |
| 4562 | .tabs 5 |
| 4563 | \s\ $t seconds |
| 4564 | \m\ $t minutes |
| 4565 | \h\ $t hours |
| 4566 | \d\ $t days |
| 4567 | \w\ $t weeks |
| 4568 | .endd |
| 4569 | For example, `3h50m' specifies 3 hours and 50 minutes. The values of time |
| 4570 | intervals are output in the same format. |
| 4571 | Exim does not restrict the values; it is perfectly acceptable, for example, to |
| 4572 | specify `90m' instead of `1h30m'. |
| 4573 | |
| 4574 | |
| 4575 | .section String values |
| 4576 | .index string||format of configuration values |
| 4577 | .index format||string |
| 4578 | .rset SECTstrings "~~chapter.~~section" |
| 4579 | If a string data item does not start with a double-quote character, it is taken |
| 4580 | as consisting of the remainder of the line plus any continuation lines, |
| 4581 | starting at the first character after any leading white space, with trailing |
| 4582 | white space characters removed, and with no interpretation of the characters in |
| 4583 | the string. Because Exim removes comment lines (those beginning with @#) at an |
| 4584 | early stage, they can appear in the middle of a multi-line string. The |
| 4585 | following settings are therefore equivalent: |
| 4586 | .display asis |
| 4587 | trusted_users = uucp:mail |
| 4588 | |
| 4589 | trusted_users = uucp:\ |
| 4590 | # This comment line is ignored |
| 4591 | mail |
| 4592 | .endd |
| 4593 | .index string||quoted |
| 4594 | .index escape characters in quoted strings |
| 4595 | If a string does start with a double-quote, it must end with a closing |
| 4596 | double-quote, and any backslash characters other than those used for line |
| 4597 | continuation are interpreted as escape characters, as follows: |
| 4598 | .display |
| 4599 | .tabs 15 |
| 4600 | @\@\ $t $rm{single backslash} |
| 4601 | @\n $t $rm{newline} |
| 4602 | @\r $t $rm{carriage return} |
| 4603 | @\t $t $rm{tab} |
| 4604 | @\<<octal digits>> $t $rm{up to 3 octal digits specify one character} |
| 4605 | @\x<<hex digits>> $t $rm{up to 2 hexadecimal digits specify one character} |
| 4606 | .endd |
| 4607 | If a backslash is followed by some other character, including a double-quote |
| 4608 | character, that character replaces the pair. |
| 4609 | |
| 4610 | Quoting is necessary only if you want to make use of the backslash escapes to |
| 4611 | insert special characters, or if you need to specify a value with leading or |
| 4612 | trailing spaces. These cases are rare, so quoting is almost never needed in |
| 4613 | current versions of Exim. In versions of Exim before 3.14, quoting was required |
| 4614 | in order to continue lines, so you may come across older configuration files |
| 4615 | and examples that apparently quote unnecessarily. |
| 4616 | |
| 4617 | .section Expanded strings |
| 4618 | .index string||expansion, definition of |
| 4619 | .index expansion||definition of |
| 4620 | Some strings in the configuration file are subjected to \*string expansion*\, |
| 4621 | by which means various parts of the string may be changed according to the |
| 4622 | circumstances (see chapter ~~CHAPexpand). The input syntax for such strings is |
| 4623 | as just described; in particular, the handling of backslashes in quoted strings |
| 4624 | is done as part of the input process, before expansion takes place. However, |
| 4625 | backslash is also an escape character for the expander, so any backslashes that |
| 4626 | are required for that reason must be doubled if they are within a quoted |
| 4627 | configuration string. |
| 4628 | |
| 4629 | .section User and group names |
| 4630 | .index user name||format of |
| 4631 | .index format||user name |
| 4632 | .index group||name format |
| 4633 | .index format||group name |
| 4634 | User and group names are specified as strings, using the syntax described |
| 4635 | above, but the strings are interpreted specially. A user or group name must |
| 4636 | either consist entirely of digits, or be a name that can be looked up using the |
| 4637 | \*getpwnam()*\ or \*getgrnam()*\ function, as appropriate. |
| 4638 | |
| 4639 | .section List construction |
| 4640 | .index list||syntax of in configuration |
| 4641 | .index format||list item in configuration |
| 4642 | .index string list, definition |
| 4643 | .rset SECTlistconstruct "~~chapter.~~section" |
| 4644 | The data for some configuration options is a colon-separated list of items. |
| 4645 | Many of these options are shown with type `string list' in the descriptions |
| 4646 | later in this document. Others are listed as `domain list', `host list', |
| 4647 | `address list', or `local part list'. Syntactically, they are all the same; |
| 4648 | however, those other than `string list' are subject to particular kinds of |
| 4649 | interpretation, as described in chapter ~~CHAPdomhosaddlists. |
| 4650 | |
| 4651 | In all these cases, the entire list is treated as a single string as far as the |
| 4652 | input syntax is concerned. The \trusted@_users\ setting in section |
| 4653 | ~~SECTstrings above is an example. If a colon is actually needed in an item in |
| 4654 | a list, it must be entered as two colons. Leading and trailing white space on |
| 4655 | each item in a list is ignored. This makes it possible to include items that |
| 4656 | start with a colon, and in particular, certain forms of IPv6 address. For |
| 4657 | example, the list |
| 4658 | .display asis |
| 4659 | local_interfaces = 127.0.0.1 : ::::1 |
| 4660 | .endd |
| 4661 | contains two IP addresses, the IPv4 address 127.0.0.1 and the IPv6 address |
| 4662 | @:@:1. IPv6 addresses are going to become more and more common as the new |
| 4663 | protocol gets more widely deployed. |
| 4664 | .index list||separator, changing |
| 4665 | .index IPv6||addresses in lists |
| 4666 | Doubling their colons is an unwelcome chore, so a mechanism was introduced to |
| 4667 | allow the separator character to be changed. If a list begins with a left angle |
| 4668 | bracket, followed by any punctuation character, that character is used instead |
| 4669 | of colon as the list separator. For example, the list above can be rewritten to |
| 4670 | use a semicolon separator like this: |
| 4671 | .display asis |
| 4672 | local_interfaces = <; 127.0.0.1 ; ::1 |
| 4673 | .endd |
| 4674 | This facility applies to all lists, with the exception of the list in |
| 4675 | \log@_file@_path\. It is recommended that the use of non-colon separators be |
| 4676 | confined to circumstances where they really are needed. |
| 4677 | |
| 4678 | |
| 4679 | .section Format of driver configurations |
| 4680 | .rset SECTfordricon "~~chapter.~~section" |
| 4681 | .index drivers||configuration format |
| 4682 | There are separate parts in the configuration for defining routers, transports, |
| 4683 | and authenticators. In each part, you are defining a number of driver |
| 4684 | instances, each with its own set of options. Each driver instance is defined by |
| 4685 | a sequence of lines like this: |
| 4686 | .display |
| 4687 | <<instance name>>: |
| 4688 | <<option>> |
| 4689 | ... |
| 4690 | <<option>> |
| 4691 | .endd |
| 4692 | In the following example, the instance name is \%localuser%\, and it is |
| 4693 | followed by three options settings: |
| 4694 | .display asis |
| 4695 | localuser: |
| 4696 | driver = accept |
| 4697 | check_local_user |
| 4698 | transport = local_delivery |
| 4699 | .endd |
| 4700 | For each driver instance, you specify which Exim code module it uses -- by the |
| 4701 | setting of the \driver\ option -- and (optionally) some configuration settings. |
| 4702 | For example, in the case of transports, if you want a transport to deliver with |
| 4703 | SMTP you would use the \%smtp%\ driver; if you want to deliver to a local file |
| 4704 | you would use the \%appendfile%\ driver. Each of the drivers is described in |
| 4705 | detail in its own separate chapter later in this manual. |
| 4706 | |
| 4707 | You can have several routers, transports, or authenticators that are based on |
| 4708 | the same underlying driver (each must have a different name). |
| 4709 | |
| 4710 | The order in which routers are defined is important, because addresses are |
| 4711 | passed to individual routers one by one, in order. The order in which |
| 4712 | transports are defined does not matter at all. The order in which |
| 4713 | authenticators are defined is used only when Exim, as a client, is searching |
| 4714 | them to find one that matches an authentication mechanism offered by the |
| 4715 | server. |
| 4716 | |
| 4717 | .index generic options |
| 4718 | .index options||generic, definition of |
| 4719 | Within a driver instance definition, there are two kinds of option: |
| 4720 | $it{generic} and $it{private}. The generic options are those that apply to all |
| 4721 | drivers of the same type (that is, all routers, all transports or all |
| 4722 | authenticators). |
| 4723 | The \driver\ option is a generic option that must appear in every definition. |
| 4724 | .index private options |
| 4725 | The private options are special for each driver, and none need appear, because |
| 4726 | they all have default values. |
| 4727 | |
| 4728 | The options may appear in any order, except that the \driver\ option must |
| 4729 | precede any private options, since these depend on the particular driver. For |
| 4730 | this reason, it is recommended that \driver\ always be the first option. |
| 4731 | |
| 4732 | Driver instance names, which are used for reference in log entries and |
| 4733 | elsewhere, can be any sequence of letters, digits, and underscores (starting |
| 4734 | with a letter) and must be unique among drivers of the same type. A router and |
| 4735 | a transport (for example) can each have the same name, but no two router |
| 4736 | instances can have the same name. The name of a driver instance should not be |
| 4737 | confused with the name of the underlying driver module. For example, the |
| 4738 | configuration lines: |
| 4739 | .display asis |
| 4740 | remote_smtp: |
| 4741 | driver = smtp |
| 4742 | .endd |
| 4743 | create an instance of the \%smtp%\ transport driver whose name is |
| 4744 | \%remote@_smtp%\. The same driver code can be used more than once, with |
| 4745 | different instance names and different option settings each time. A second |
| 4746 | instance of the \%smtp%\ transport, with different options, might be defined |
| 4747 | thus: |
| 4748 | .display asis |
| 4749 | special_smtp: |
| 4750 | driver = smtp |
| 4751 | port = 1234 |
| 4752 | command_timeout = 10s |
| 4753 | .endd |
| 4754 | The names \%remote@_smtp%\ and \%special@_smtp%\ would be used to reference |
| 4755 | these transport instances from routers, and these names would appear in log |
| 4756 | lines. |
| 4757 | |
| 4758 | Comment lines may be present in the middle of driver specifications. The full |
| 4759 | list of option settings for any particular driver instance, including all the |
| 4760 | defaulted values, can be extracted by making use of the \-bP-\ command line |
| 4761 | option. |
| 4762 | |
| 4763 | |
| 4764 | |
| 4765 | |
| 4766 | |
| 4767 | |
| 4768 | . |
| 4769 | . |
| 4770 | . |
| 4771 | . |
| 4772 | . ============================================================================ |
| 4773 | .chapter The default configuration file |
| 4774 | .set runningfoot "default configuration" |
| 4775 | .rset CHAPdefconfil "~~chapter" |
| 4776 | .index configuration file||default, `walk through' |
| 4777 | .index default||configuration file `walk through' |
| 4778 | The default configuration file supplied with Exim as \(src/configure.default)\ |
| 4779 | is sufficient for a host with simple mail requirements. As an introduction to |
| 4780 | the way Exim is configured, this chapter `walks through' the default |
| 4781 | configuration, giving brief explanations of the settings. Detailed descriptions |
| 4782 | of the options are given in subsequent chapters. The default configuration file |
| 4783 | itself contains extensive comments about ways you might want to modify the |
| 4784 | initial settings. However, note that there are many options that are not |
| 4785 | mentioned at all in the default configuration. |
| 4786 | |
| 4787 | |
| 4788 | .section Main configuration settings |
| 4789 | The main (global) configuration option settings must always come first in the |
| 4790 | file. The first thing you'll see in the file, after some initial comments, is |
| 4791 | the line |
| 4792 | .display asis |
| 4793 | # primary_hostname = |
| 4794 | .endd |
| 4795 | This is a commented-out setting of the \primary@_hostname\ option. Exim needs |
| 4796 | to know the official, fully qualified name of your host, and this is where you |
| 4797 | can specify it. However, in most cases you do not need to set this option. When |
| 4798 | it is unset, Exim uses the \*uname()*\ system function to obtain the host name. |
| 4799 | |
| 4800 | The first three non-comment configuration lines are as follows: |
| 4801 | .display asis |
| 4802 | domainlist local_domains = @ |
| 4803 | domainlist relay_to_domains = |
| 4804 | hostlist relay_from_hosts = 127.0.0.1 |
| 4805 | .endd |
| 4806 | These are not, in fact, option settings. They are definitions of two named |
| 4807 | domain lists and one named host list. Exim allows you to give names to lists of |
| 4808 | domains, hosts, and email addresses, in order to make it easier to manage the |
| 4809 | configuration file (see section ~~SECTnamedlists). |
| 4810 | |
| 4811 | The first line defines a domain list called \*local@_domains*\; this is used |
| 4812 | later in the configuration to identify domains that are to be delivered |
| 4813 | on the local host. |
| 4814 | .index @@ in a domain list |
| 4815 | There is just one item in this list, the string `@@'. This is a special form of |
| 4816 | entry which means `the name of the local host'. Thus, if the local host is |
| 4817 | called \*a.host.example*\, mail to \*any.user@@a.host.example*\ is expected to |
| 4818 | be delivered locally. Because the local host's name is referenced indirectly, |
| 4819 | the same configuration file can be used on different hosts. |
| 4820 | |
| 4821 | The second line defines a domain list called \*relay@_to@_domains*\, but the |
| 4822 | list itself is empty. Later in the configuration we will come to the part that |
| 4823 | controls mail relaying through the local host; it allows relaying to any |
| 4824 | domains in this list. By default, therefore, no relaying on the basis of a mail |
| 4825 | domain is permitted. |
| 4826 | |
| 4827 | The third line defines a host list called \*relay@_from@_hosts*\. This list is |
| 4828 | used later in the configuration to permit relaying from any host or IP address |
| 4829 | that matches the list. The default contains just the IP address of the IPv4 |
| 4830 | loopback interface, which means that processes on the local host are able to |
| 4831 | submit mail for relaying by sending it over TCP/IP to that interface. No other |
| 4832 | hosts are permitted to submit messages for relaying. |
| 4833 | |
| 4834 | Just to be sure there's no misunderstanding: at this point in the configuration |
| 4835 | we aren't actually setting up any controls. We are just defining some domains |
| 4836 | and hosts that will be used in the controls that are specified later. |
| 4837 | |
| 4838 | The next configuration line is a genuine option setting: |
| 4839 | .display asis |
| 4840 | acl_smtp_rcpt = acl_check_rcpt |
| 4841 | .endd |
| 4842 | This option specifies an \*Access Control List*\ (ACL) which is to be used |
| 4843 | during an incoming SMTP session for every recipient of a message (every |
| 4844 | \\RCPT\\ command). The name of the list is \*acl@_check@_rcpt*\, and we will |
| 4845 | come to its definition below, in the ACL section of the configuration. ACLs |
| 4846 | control which recipients are accepted for an incoming message -- if a |
| 4847 | configuration does not provide an ACL to check recipients, no SMTP mail can be |
| 4848 | accepted. |
| 4849 | |
| 4850 | Two commented-out options settings are next: |
| 4851 | .display asis |
| 4852 | # qualify_domain = |
| 4853 | # qualify_recipient = |
| 4854 | .endd |
| 4855 | The first of these specifies a domain that Exim uses when it constructs a |
| 4856 | complete email address from a local login name. This is often needed when Exim |
| 4857 | receives a message from a local process. If you do not set \qualify@_domain\, |
| 4858 | the value of \primary@_hostname\ is used. If you set both of these options, you |
| 4859 | can have different qualification domains for sender and recipient addresses. If |
| 4860 | you set only the first one, its value is used in both cases. |
| 4861 | |
| 4862 | .index domain literal||recognizing format |
| 4863 | The following line must be uncommented if you want Exim to recognize |
| 4864 | addresses of the form \*user@@[10.11.12.13]*\ that is, with a `domain literal' |
| 4865 | (an IP address) instead of a named domain. |
| 4866 | .display asis |
| 4867 | # allow_domain_literals |
| 4868 | .endd |
| 4869 | The RFCs still require this form, but many people think that in the modern |
| 4870 | Internet it makes little sense to permit mail to be sent to specific hosts by |
| 4871 | quoting their IP addresses. This ancient format has been used by people who |
| 4872 | try to abuse hosts by using them for unwanted relaying. However, some |
| 4873 | people believe there are circumstances (for example, messages addressed to |
| 4874 | \*postmaster*\) where domain literals are still useful. |
| 4875 | |
| 4876 | The next configuration line is a kind of trigger guard: |
| 4877 | .display asis |
| 4878 | never_users = root |
| 4879 | .endd |
| 4880 | It specifies that no delivery must ever be run as the root user. The normal |
| 4881 | convention is to set up \*root*\ as an alias for the system administrator. This |
| 4882 | setting is a guard against slips in the configuration. |
| 4883 | The list of users specified by \never@_users\ is not, however, the complete |
| 4884 | list; the build-time configuration in \(Local/Makefile)\ has an option called |
| 4885 | \\FIXED@_NEVER@_USERS\\ specifying a list that cannot be overridden. The |
| 4886 | contents of \never@_users\ are added to this list. By default |
| 4887 | \\FIXED@_NEVER@_USERS\\ also specifies root. |
| 4888 | |
| 4889 | When a remote host connects to Exim in order to send mail, the only information |
| 4890 | Exim has about the host's identity is its IP address. The next configuration |
| 4891 | line, |
| 4892 | .display asis |
| 4893 | host_lookup = * |
| 4894 | .endd |
| 4895 | specifies that Exim should do a reverse DNS lookup on all incoming connections, |
| 4896 | in order to get a host name. This improves the quality of the logging |
| 4897 | information, but if you feel it is too expensive, you can remove it entirely, |
| 4898 | or restrict the lookup to hosts on `nearby' networks. |
| 4899 | Note that it is not always possible to find a host name from an IP address, |
| 4900 | because not all DNS reverse zones are maintained, and sometimes DNS servers are |
| 4901 | unreachable. |
| 4902 | |
| 4903 | The next two lines are concerned with \*ident*\ callbacks, as defined by RFC |
| 4904 | 1413 (hence their names): |
| 4905 | .display asis |
| 4906 | rfc1413_hosts = * |
| 4907 | rfc1413_query_timeout = 30s |
| 4908 | .endd |
| 4909 | These settings cause Exim to make ident callbacks for all incoming SMTP calls. |
| 4910 | You can limit the hosts to which these calls are made, or change the timeout |
| 4911 | that is used. If you set the timeout to zero, all ident calls are disabled. |
| 4912 | Although they are cheap and can provide useful information for tracing problem |
| 4913 | messages, some hosts and firewalls have problems with ident calls. This can |
| 4914 | result in a timeout instead of an immediate refused connection, leading to |
| 4915 | delays on starting up an incoming SMTP session. |
| 4916 | |
| 4917 | When Exim receives messages over SMTP connections, it expects all addresses to |
| 4918 | be fully qualified with a domain, as required by the SMTP definition. However, |
| 4919 | if you are running a server to which simple clients submit messages, you may |
| 4920 | find that they send unqualified addresses. The two commented-out options: |
| 4921 | .display asis |
| 4922 | # sender_unqualified_hosts = |
| 4923 | # recipient_unqualified_hosts = |
| 4924 | .endd |
| 4925 | show how you can specify hosts that are permitted to send unqualified sender |
| 4926 | and recipient addresses, respectively. |
| 4927 | |
| 4928 | The \percent@_hack@_domains\ option is also commented out: |
| 4929 | .display asis |
| 4930 | # percent_hack_domains = |
| 4931 | .endd |
| 4932 | It provides a list of domains for which the `percent hack' is to operate. This |
| 4933 | is an almost obsolete form of explicit email routing. If you do not know |
| 4934 | anything about it, you can safely ignore this topic. |
| 4935 | |
| 4936 | The last two settings in the main part of the default configuration are |
| 4937 | concerned with messages that have been `frozen' on Exim's queue. When a message |
| 4938 | is frozen, Exim no longer continues to try to deliver it. Freezing occurs when |
| 4939 | a bounce message encounters a permanent failure because the sender address of |
| 4940 | the original message that caused the bounce is invalid, so the bounce cannot be |
| 4941 | delivered. This is probably the most common case, but there are also other |
| 4942 | conditions that cause freezing, and frozen messages are not always bounce |
| 4943 | messages. |
| 4944 | .display asis |
| 4945 | ignore_bounce_errors_after = 2d |
| 4946 | timeout_frozen_after = 7d |
| 4947 | .endd |
| 4948 | The first of these options specifies that failing bounce messages are to be |
| 4949 | discarded after 2 days on the queue. The second specifies that any frozen |
| 4950 | message (whether a bounce message or not) is to be timed out (and discarded) |
| 4951 | after a week. In this configuration, the first setting ensures that no failing |
| 4952 | bounce message ever lasts a week. |
| 4953 | |
| 4954 | |
| 4955 | .section ACL configuration |
| 4956 | .index default||ACLs |
| 4957 | .index ~~ACL||default configuration |
| 4958 | In the default configuration, the ACL section follows the main configuration. |
| 4959 | It starts with the line |
| 4960 | .display asis |
| 4961 | begin acl |
| 4962 | .endd |
| 4963 | and it contains the definition of one ACL called \*acl@_check@_rcpt*\ that was |
| 4964 | referenced in the setting of \acl@_smtp@_rcpt\ above. |
| 4965 | .index \\RCPT\\||ACL for |
| 4966 | This ACL is used for every \\RCPT\\ command in an incoming SMTP message. Each |
| 4967 | \\RCPT\\ command specifies one of the message's recipients. The ACL statements |
| 4968 | are considered in order, until the recipient address is either accepted or |
| 4969 | rejected. The \\RCPT\\ command is then accepted or rejected, according to the |
| 4970 | result of the ACL processing. |
| 4971 | .display asis |
| 4972 | acl_check_rcpt: |
| 4973 | .endd |
| 4974 | This line, consisting of a name terminated by a colon, marks the start of the |
| 4975 | ACL, and names it. |
| 4976 | .display asis |
| 4977 | accept hosts = : |
| 4978 | .endd |
| 4979 | This ACL statement accepts the recipient if the sending host matches the list. |
| 4980 | But what does that strange list mean? It doesn't actually contain any host |
| 4981 | names or IP addresses. The presence of the colon puts an empty item in the |
| 4982 | list; Exim matches this only if the incoming message didn't come from a remote |
| 4983 | host. The colon is important. Without it, the list itself is empty, and can |
| 4984 | never match anything. |
| 4985 | |
| 4986 | What this statement is doing is to accept unconditionally all recipients in |
| 4987 | messages that are submitted by SMTP from local processes using the standard |
| 4988 | input and output (that is, not using TCP/IP). A number of MUAs operate in this |
| 4989 | manner. |
| 4990 | .display asis |
| 4991 | deny domains = +local_domains |
| 4992 | local_parts = ^[.] : ^.*[@%!/|] |
| 4993 | |
| 4994 | deny domains = !+local_domains |
| 4995 | local_parts = ^[./|] : ^.*[@%!] : ^.*/\\.\\./ |
| 4996 | .endd |
| 4997 | These statements are concerned with local parts that contain any of the |
| 4998 | characters `@@', `%', `!', `/', `|', or dots in unusual places. Although these |
| 4999 | characters are entirely legal in local parts (in the case of `@@' and leading |
| 5000 | dots, only if correctly quoted), they do not commonly occur in Internet mail |
| 5001 | addresses. |
| 5002 | |
| 5003 | The first three have in the past been associated with explicitly routed |
| 5004 | addresses (percent is still sometimes used -- see the \percent@_hack@_domains\ |
| 5005 | option). Addresses containing these characters are regularly tried by spammers |
| 5006 | in an attempt to bypass relaying restrictions, and also by open relay testing |
| 5007 | programs. Unless you really need them it is safest to reject these characters |
| 5008 | at this early stage. This configuration is heavy-handed in rejecting these |
| 5009 | characters for all messages it accepts from remote hosts. This is a deliberate |
| 5010 | policy of being as safe as possible. |
| 5011 | |
| 5012 | The first rule above is stricter, and is applied to messages that are addressed |
| 5013 | to one of the local domains handled by this host. This is implemented by the |
| 5014 | first condition, which restricts it to domains that are listed in the |
| 5015 | \*local@_domains*\ domain list. The `+' character is used to indicate a |
| 5016 | reference to a named list. In this configuration, there is just one domain in |
| 5017 | \*local@_domains*\, but in general there may be many. |
| 5018 | |
| 5019 | The second condition on the first statement uses two regular expressions to |
| 5020 | block local parts that begin with a dot or contain `@@', `%', `!', `/', or `|'. |
| 5021 | If you have local accounts that include these characters, you will have to |
| 5022 | modify this rule. |
| 5023 | |
| 5024 | Empty components (two dots in a row) are not valid in RFC 2822, but Exim |
| 5025 | allows them because they have been encountered in practice. (Consider local |
| 5026 | parts constructed as `first-initial.second-initial.family-name' when applied to |
| 5027 | someone like the author of Exim, who has no second initial.) However, a local |
| 5028 | part starting with a dot or containing `/../' can cause trouble if it is used |
| 5029 | as part of a file name (for example, for a mailing list). This is also true for |
| 5030 | local parts that contain slashes. A pipe symbol can also be troublesome if the |
| 5031 | local part is incorporated unthinkingly into a shell command line. |
| 5032 | |
| 5033 | The second rule above applies to all other domains, and is less strict. This |
| 5034 | allows your own users to send outgoing messages to sites that use slashes |
| 5035 | and vertical bars in their local parts. It blocks local parts that begin |
| 5036 | with a dot, slash, or vertical bar, but allows these characters within the |
| 5037 | local part. However, the sequence `/../' is barred. The use of `@@', `%', and |
| 5038 | `!' is blocked, as before. The motivation here is to prevent your users (or |
| 5039 | your users' viruses) from mounting certain kinds of attack on remote sites. |
| 5040 | |
| 5041 | .display asis |
| 5042 | accept local_parts = postmaster |
| 5043 | domains = +local_domains |
| 5044 | .endd |
| 5045 | This statement, which has two conditions, accepts an incoming address if the |
| 5046 | local part is \*postmaster*\ and the domain is one of those listed in the |
| 5047 | \*local@_domains*\ domain list. The `+' character is used to indicate a |
| 5048 | reference to a named list. In this configuration, there is just one domain in |
| 5049 | \*local@_domains*\, but in general there may be many. |
| 5050 | |
| 5051 | The presence of this statement means that mail to postmaster is never blocked |
| 5052 | by any of the subsequent tests. This can be helpful while sorting out problems |
| 5053 | in cases where the subsequent tests are incorrectly denying access. |
| 5054 | .display asis |
| 5055 | require verify = sender |
| 5056 | .endd |
| 5057 | This statement requires the sender address to be verified before any subsequent |
| 5058 | ACL statement can be used. If verification fails, the incoming recipient |
| 5059 | address is refused. Verification consists of trying to route the address, to |
| 5060 | see if a |
| 5061 | bounce |
| 5062 | message could be delivered to it. In the case of remote addresses, basic |
| 5063 | verification checks only the domain, but \*callouts*\ can be used for more |
| 5064 | verification if required. Section ~~SECTaddressverification discusses the |
| 5065 | details of address verification. |
| 5066 | |
| 5067 | .display asis |
| 5068 | # deny message = rejected because $sender_host_address is \ |
| 5069 | # in a black list at $dnslist_domain\n\ |
| 5070 | # $dnslist_text |
| 5071 | # dnslists = black.list.example |
| 5072 | # |
| 5073 | # warn message = X-Warning: $sender_host_address is \ |
| 5074 | # in a black list at $dnslist_domain |
| 5075 | # log_message = found in $dnslist_domain |
| 5076 | # dnslists = black.list.example |
| 5077 | .endd |
| 5078 | These commented-out lines are examples of how you could configure Exim to check |
| 5079 | sending hosts against a DNS black list. The first statement rejects messages |
| 5080 | from blacklisted hosts, whereas the second merely inserts a warning header |
| 5081 | line. |
| 5082 | |
| 5083 | .display asis |
| 5084 | accept domains = +local_domains |
| 5085 | endpass |
| 5086 | message = unknown user |
| 5087 | verify = recipient |
| 5088 | .endd |
| 5089 | This statement accepts the incoming recipient address if its domain is one of |
| 5090 | the local domains, but only if the address can be verified. Verification of |
| 5091 | local addresses normally checks both the local part and the domain. The |
| 5092 | \endpass\ line needs some explanation: if the condition above \endpass\ fails, |
| 5093 | that is, if the address is not in a local domain, control is passed to the next |
| 5094 | ACL statement. However, if the condition below \endpass\ fails, that is, if a |
| 5095 | recipient in a local domain cannot be verified, access is denied and the |
| 5096 | recipient is rejected. |
| 5097 | .index customizing||ACL failure message |
| 5098 | The \message\ modifier provides a customized error message for the failure. |
| 5099 | .display asis |
| 5100 | accept domains = +relay_to_domains |
| 5101 | endpass |
| 5102 | message = unrouteable address |
| 5103 | verify = recipient |
| 5104 | .endd |
| 5105 | This statement accepts the incoming recipient address if its domain is one of |
| 5106 | the domains for which this host is a relay, but again, only if the address can |
| 5107 | be verified. |
| 5108 | .display asis |
| 5109 | accept hosts = +relay_from_hosts |
| 5110 | .endd |
| 5111 | Control reaches this statement only if the recipient's domain is neither a |
| 5112 | local domain, nor a relay domain. The statement accepts the address if the |
| 5113 | message is coming from one of the hosts that are defined as being allowed to |
| 5114 | relay through this host. Recipient verification is omitted here, because in |
| 5115 | many cases the clients are dumb MUAs that do not cope well with SMTP error |
| 5116 | responses. If you are actually relaying out from MTAs, you should probably add |
| 5117 | recipient verification here. |
| 5118 | .display asis |
| 5119 | accept authenticated = * |
| 5120 | .endd |
| 5121 | Control reaches here for attempts to relay to arbitrary domains from arbitrary |
| 5122 | hosts. The statement accepts the address only if the client host has |
| 5123 | authenticated itself. The default configuration does not define any |
| 5124 | authenticators, which means that no client can in fact authenticate. You will |
| 5125 | need to add authenticator definitions if you want to make use of this ACL |
| 5126 | statement. |
| 5127 | .display asis |
| 5128 | deny message = relay not permitted |
| 5129 | .endd |
| 5130 | The final statement denies access, giving a specific error message. Reaching |
| 5131 | the end of the ACL also causes access to be denied, but with the generic |
| 5132 | message `administrative prohibition'. |
| 5133 | |
| 5134 | |
| 5135 | .section Router configuration |
| 5136 | .index default||routers |
| 5137 | .index routers||default |
| 5138 | The router configuration comes next in the default configuration, introduced |
| 5139 | by the line |
| 5140 | .display asis |
| 5141 | begin routers |
| 5142 | .endd |
| 5143 | Routers are the modules in Exim that make decisions about where to send |
| 5144 | messages. An address is passed to each router in turn, until it is either |
| 5145 | accepted, or failed. This means that the order in which you define the routers |
| 5146 | matters. Each router is fully described in its own chapter later in this |
| 5147 | manual. Here we give only brief overviews. |
| 5148 | |
| 5149 | .index domain literal||default router |
| 5150 | .display asis |
| 5151 | # domain_literal: |
| 5152 | # driver = ipliteral |
| 5153 | # domains = !+local_domains |
| 5154 | # transport = remote_smtp |
| 5155 | .endd |
| 5156 | This router is commented out because the majority of sites do not want to |
| 5157 | support domain literal addresses (those of the form \*user@@[10.9.8.7]*\). If |
| 5158 | you uncomment this router, you also need to uncomment the setting of |
| 5159 | \allow@_domain@_literals\ in the main part of the configuration. |
| 5160 | |
| 5161 | .display asis |
| 5162 | dnslookup: |
| 5163 | driver = dnslookup |
| 5164 | domains = ! +local_domains |
| 5165 | transport = remote_smtp |
| 5166 | .newline |
| 5167 | ignore_target_hosts = 0.0.0.0 : 127.0.0.0/8 |
| 5168 | .newline |
| 5169 | no_more |
| 5170 | .endd |
| 5171 | The first uncommented router handles addresses that do not involve any local |
| 5172 | domains. This is specified by the line |
| 5173 | .display asis |
| 5174 | domains = ! +local_domains |
| 5175 | .endd |
| 5176 | The \domains\ option lists the domains to which this router applies, but the |
| 5177 | exclamation mark is a negation sign, so the router is used only for domains |
| 5178 | that are not in the domain list called \*local@_domains*\ (which was defined at |
| 5179 | the start of the configuration). The plus sign before \*local@_domains*\ |
| 5180 | indicates that it is referring to a named list. Addresses in other domains are |
| 5181 | passed on to the following routers. |
| 5182 | |
| 5183 | The name of the router driver is \%dnslookup%\, |
| 5184 | and is specified by the \driver\ option. Do not be confused by the fact that |
| 5185 | the name of this router instance is the same as the name of the driver. The |
| 5186 | instance name is arbitrary, but the name set in the \driver\ option must be one |
| 5187 | of the driver modules that is in the Exim binary. |
| 5188 | |
| 5189 | The \%dnslookup%\ router routes addresses by looking up their domains in the |
| 5190 | DNS in order to obtain a list of hosts to which the address is routed. If the |
| 5191 | router succeeds, the address is queued for the \%remote@_smtp%\ transport, as |
| 5192 | specified by the \transport\ option. If the router does not find the domain in |
| 5193 | the DNS, no further routers are tried because of the \no@_more\ setting, so the |
| 5194 | address fails and is bounced. |
| 5195 | |
| 5196 | The \ignore@_target@_hosts\ option specifies a list of IP addresses that are to |
| 5197 | be entirely ignored. This option is present because a number of cases have been |
| 5198 | encountered where MX records in the DNS point to host names |
| 5199 | whose IP addresses are 0.0.0.0 or are in the 127 subnet (typically 127.0.0.1). |
| 5200 | Completely ignoring these IP addresses causes Exim to fail to route the |
| 5201 | email address, so it bounces. Otherwise, Exim would log a routing problem, and |
| 5202 | continue to try to deliver the message periodically until the address timed |
| 5203 | out. |
| 5204 | .display asis |
| 5205 | system_aliases: |
| 5206 | driver = redirect |
| 5207 | allow_fail |
| 5208 | allow_defer |
| 5209 | data = ${lookup{$local_part}lsearch{/etc/aliases}} |
| 5210 | # user = exim |
| 5211 | file_transport = address_file |
| 5212 | pipe_transport = address_pipe |
| 5213 | .endd |
| 5214 | Control reaches this and subsequent routers only for addresses in the local |
| 5215 | domains. This router checks to see whether the local part is defined as an |
| 5216 | alias in the \(/etc/aliases)\ file, and if so, redirects it according to the |
| 5217 | data that it looks up from that file. If no data is found for the local part, |
| 5218 | the value of the \data\ option is empty, causing the address to be passed to |
| 5219 | the next router. |
| 5220 | |
| 5221 | \(/etc/aliases)\ is a conventional name for the system aliases file that is |
| 5222 | often used. That is why it is referenced by from the default configuration |
| 5223 | file. However, you can change this by setting \\SYSTEM@_ALIASES@_FILE\\ in |
| 5224 | \(Local/Makefile)\ before building Exim. |
| 5225 | |
| 5226 | .display asis |
| 5227 | userforward: |
| 5228 | driver = redirect |
| 5229 | check_local_user |
| 5230 | file = $home/.forward |
| 5231 | no_verify |
| 5232 | no_expn |
| 5233 | check_ancestor |
| 5234 | # allow_filter |
| 5235 | file_transport = address_file |
| 5236 | pipe_transport = address_pipe |
| 5237 | reply_transport = address_reply |
| 5238 | .endd |
| 5239 | This is the most complicated router in the default configuration. It is another |
| 5240 | redirection router, but this time it is looking for forwarding data set up by |
| 5241 | individual users. The \check@_local@_user\ setting means that the first thing it |
| 5242 | does is to check that the local part of the address is the login name of a |
| 5243 | local user. If it is not, the router is skipped. When a local user is found, |
| 5244 | the file called \(.forward)\ in the user's home directory is consulted. If it |
| 5245 | does not exist, or is empty, the router declines. Otherwise, the contents of |
| 5246 | \(.forward)\ are interpreted as redirection data (see chapter ~~CHAPredirect |
| 5247 | for more details). |
| 5248 | |
| 5249 | .index Sieve filter||enabling in default router |
| 5250 | Traditional \(.forward)\ files contain just a list of addresses, pipes, or |
| 5251 | files. Exim supports this by default. However, if \allow@_filter\ is set (it is |
| 5252 | commented out by default), the contents of the file are interpreted as a set of |
| 5253 | Exim or Sieve filtering instructions, provided the file begins with `@#Exim |
| 5254 | filter' or `@#Sieve filter', respectively. User filtering is discussed in the |
| 5255 | separate document entitled \*Exim's interfaces to mail filtering*\. |
| 5256 | |
| 5257 | The \no@_verify\ and \no@_expn\ options mean that this router is skipped when |
| 5258 | verifying addresses, or when running as a consequence of an SMTP \\EXPN\\ |
| 5259 | command. |
| 5260 | There are two reasons for doing this: |
| 5261 | .numberpars |
| 5262 | Whether or not a local user has a \(.forward)\ file is not really relevant when |
| 5263 | checking an address for validity; it makes sense not to waste resources doing |
| 5264 | unnecessary work. |
| 5265 | .nextp |
| 5266 | More importantly, when Exim is verifying addresses or handling an \\EXPN\\ |
| 5267 | command during an SMTP session, it is running as the Exim user, not as root. |
| 5268 | The group is the Exim group, and no additional groups are set up. |
| 5269 | It may therefore not be possible for Exim to read users' \(.forward)\ files at |
| 5270 | this time. |
| 5271 | .endp |
| 5272 | |
| 5273 | The setting of \check@_ancestor\ prevents the router from generating a new |
| 5274 | address that is the same as any previous address that was redirected. (This |
| 5275 | works round a problem concerning a bad interaction between aliasing and |
| 5276 | forwarding -- see section ~~SECTredlocmai). |
| 5277 | |
| 5278 | The final three option settings specify the transports that are to be used when |
| 5279 | forwarding generates a direct delivery to a file, or to a pipe, or sets up an |
| 5280 | auto-reply, respectively. For example, if a \(.forward)\ file contains |
| 5281 | .display asis |
| 5282 | a.nother@elsewhere.example, /home/spqr/archive |
| 5283 | .endd |
| 5284 | the delivery to \(/home/spqr/archive)\ is done by running the \address@_file\ |
| 5285 | transport. |
| 5286 | .display asis |
| 5287 | localuser: |
| 5288 | driver = accept |
| 5289 | check_local_user |
| 5290 | transport = local_delivery |
| 5291 | .endd |
| 5292 | The final router sets up delivery into local mailboxes, provided that the local |
| 5293 | part is the name of a local login, by accepting the address and queuing it for |
| 5294 | the \%local@_delivery%\ transport. Otherwise, we have reached the end of the |
| 5295 | routers, so the address is bounced. |
| 5296 | |
| 5297 | |
| 5298 | .section Transport configuration |
| 5299 | .index default||transports |
| 5300 | .index transports||default |
| 5301 | Transports define mechanisms for actually delivering messages. They operate |
| 5302 | only when referenced from routers, so the order in which they are defined does |
| 5303 | not matter. The transports section of the configuration starts with |
| 5304 | .display asis |
| 5305 | begin transports |
| 5306 | .endd |
| 5307 | One remote transport and four local transports are defined. |
| 5308 | .display asis |
| 5309 | remote_smtp: |
| 5310 | driver = smtp |
| 5311 | .endd |
| 5312 | This transport is used for delivering messages over SMTP connections. All its |
| 5313 | options are defaulted. The list of remote hosts comes from the router. |
| 5314 | .display asis |
| 5315 | local_delivery: |
| 5316 | driver = appendfile |
| 5317 | file = /var/mail/$local_part |
| 5318 | delivery_date_add |
| 5319 | envelope_to_add |
| 5320 | return_path_add |
| 5321 | # group = mail |
| 5322 | # mode = 0660 |
| 5323 | .endd |
| 5324 | This \%appendfile%\ transport is used for local delivery to user mailboxes in |
| 5325 | traditional BSD mailbox format. By default it runs under the uid and gid of the |
| 5326 | local user, which requires the sticky bit to be set on the \(/var/mail)\ |
| 5327 | directory. Some systems use the alternative approach of running mail deliveries |
| 5328 | under a particular group instead of using the sticky bit. The commented options |
| 5329 | show how this can be done. |
| 5330 | |
| 5331 | Exim adds three headers to the message as it delivers it: ::Delivery-date::, |
| 5332 | ::Envelope-to:: and ::Return-path::. This action is requested by the three |
| 5333 | similarly-named options above. |
| 5334 | .display asis |
| 5335 | address_pipe: |
| 5336 | driver = pipe |
| 5337 | return_output |
| 5338 | .endd |
| 5339 | This transport is used for handling deliveries to pipes that are generated by |
| 5340 | redirection (aliasing or users' \(.forward)\ files). The \return@_output\ |
| 5341 | option specifies that any output generated by the pipe is to be returned to the |
| 5342 | sender. |
| 5343 | .display asis |
| 5344 | address_file: |
| 5345 | driver = appendfile |
| 5346 | delivery_date_add |
| 5347 | envelope_to_add |
| 5348 | return_path_add |
| 5349 | .endd |
| 5350 | This transport is used for handling deliveries to files that are generated by |
| 5351 | redirection. The name of the file is not specified in this instance of |
| 5352 | \%appendfile%\, because it comes from the \%redirect%\ router. |
| 5353 | .display asis |
| 5354 | address_reply: |
| 5355 | driver = autoreply |
| 5356 | .endd |
| 5357 | This transport is used for handling automatic replies generated by users' |
| 5358 | filter files. |
| 5359 | |
| 5360 | |
| 5361 | .section Default retry rule |
| 5362 | .index retry||default rule |
| 5363 | .index default||retry rule |
| 5364 | The retry section of the configuration file contains rules which affect the way |
| 5365 | Exim retries deliveries that cannot be completed at the first attempt. It is |
| 5366 | introduced by the line |
| 5367 | .display asis |
| 5368 | begin retry |
| 5369 | .endd |
| 5370 | In the default configuration, there is just one rule, which applies to all |
| 5371 | errors: |
| 5372 | .display asis |
| 5373 | * * F,2h,15m; G,16h,1h,1.5; F,4d,6h |
| 5374 | .endd |
| 5375 | This causes any temporarily failing address to be retried every 15 minutes for |
| 5376 | 2 hours, then at intervals starting at one hour and increasing by a factor of |
| 5377 | 1.5 until 16 hours have passed, then every 6 hours up to 4 days. If an address |
| 5378 | is not delivered after 4 days of failure, it is bounced. |
| 5379 | |
| 5380 | |
| 5381 | .section Rewriting configuration |
| 5382 | The rewriting section of the configuration, introduced by |
| 5383 | .display asis |
| 5384 | begin rewrite |
| 5385 | .endd |
| 5386 | contains rules for rewriting addresses in messages as they arrive. There are no |
| 5387 | rewriting rules in the default configuration file. |
| 5388 | |
| 5389 | |
| 5390 | .section Authenticators configuration |
| 5391 | .index \\AUTH\\||configuration |
| 5392 | The authenticators section of the configuration, introduced by |
| 5393 | .display asis |
| 5394 | begin authenticators |
| 5395 | .endd |
| 5396 | defines mechanisms for the use of the SMTP \\AUTH\\ command. No authenticators |
| 5397 | are specified in the default configuration file. |
| 5398 | |
| 5399 | |
| 5400 | |
| 5401 | . |
| 5402 | . |
| 5403 | . |
| 5404 | . |
| 5405 | . ============================================================================ |
| 5406 | .chapter Regular expressions |
| 5407 | .set runningfoot "regular expressions" |
| 5408 | .rset CHAPregexp ~~chapter |
| 5409 | |
| 5410 | .index regular expressions||library |
| 5411 | .index PCRE |
| 5412 | Exim supports the use of regular expressions in many of its options. It |
| 5413 | uses the PCRE regular expression library; this provides regular expression |
| 5414 | matching that is compatible with Perl 5. The syntax and semantics of |
| 5415 | regular expressions is discussed in many Perl reference books, and also in |
| 5416 | Jeffrey Friedl's |
| 5417 | .if ~~html |
| 5418 | [(A HREF="http://www.oreilly.com/catalog/regex/")] |
| 5419 | .fi |
| 5420 | $it{Mastering Regular Expressions} |
| 5421 | .if ~~html |
| 5422 | [(/A)] |
| 5423 | .fi |
| 5424 | (O'Reilly, ISBN 0-596-00289-0). |
| 5425 | |
| 5426 | The documentation for the syntax and semantics of the regular expressions that |
| 5427 | are supported by PCRE is included in plain text in the file |
| 5428 | \(doc/pcrepattern.txt)\ in the Exim distribution, and also in the HTML |
| 5429 | tarbundle of Exim documentation, and as an appendix to the |
| 5430 | .if ~~html |
| 5431 | [(A HREF="http://www.uit.co.uk/exim-book/")] |
| 5432 | .fi |
| 5433 | Exim book. |
| 5434 | .if ~~html |
| 5435 | [(/A)] |
| 5436 | .fi |
| 5437 | It describes in detail the features of the regular expressions that PCRE |
| 5438 | supports, so no further description is included here. The PCRE functions are |
| 5439 | called from Exim using the default option settings (that is, with no PCRE |
| 5440 | options set), except that the \\PCRE@_CASELESS\\ option is set when the |
| 5441 | matching is required to be case-insensitive. |
| 5442 | |
| 5443 | In most cases, when a regular expression is required in an Exim configuration, |
| 5444 | it has to start with a circumflex, in order to distinguish it from plain text |
| 5445 | or an `ends with' wildcard. In this example of a configuration setting, the |
| 5446 | second item in the colon-separated list is a regular expression. |
| 5447 | .display asis |
| 5448 | domains = a.b.c : ^\\d{3} : *.y.z : ... |
| 5449 | .endd |
| 5450 | The doubling of the backslash is required because of string expansion that |
| 5451 | precedes interpretation -- see section ~~SECTlittext for more discussion of |
| 5452 | this issue, and a way of avoiding the need for doubling backslashes. The |
| 5453 | regular expression that is eventually used in this example contains just one |
| 5454 | backslash. The circumflex is included in the regular expression, and has the |
| 5455 | normal effect of `anchoring' it to the start of the string that is being |
| 5456 | matched. |
| 5457 | |
| 5458 | There are, however, two cases where a circumflex is not required for the |
| 5459 | recognition of a regular expression: these are the \match\ condition in a |
| 5460 | string expansion, and the \matches\ condition in an Exim filter file. In these |
| 5461 | cases, the relevant string is always treated as a regular expression; if it |
| 5462 | does not start with a circumflex, the expression is not anchored, and can match |
| 5463 | anywhere in the subject string. |
| 5464 | |
| 5465 | In all cases, if you want a regular expression to match at the end of a string, |
| 5466 | you must code the @$ metacharacter to indicate this. For example: |
| 5467 | .display asis |
| 5468 | domains = ^\\d{3}\\.example |
| 5469 | .endd |
| 5470 | matches the domain \*123.example*\, but it also matches \*123.example.com*\. |
| 5471 | You need to use: |
| 5472 | .display asis |
| 5473 | domains = ^\\d{3}\\.example\$ |
| 5474 | .endd |
| 5475 | if you want \*example*\ to be the top-level domain. (The backslash before the |
| 5476 | @$ is another artefact of string expansion.) |
| 5477 | |
| 5478 | |
| 5479 | .section Testing regular expressions |
| 5480 | .index testing||regular expressions |
| 5481 | .index regular expressions||testing |
| 5482 | .index \*pcretest*\ |
| 5483 | A program called \*pcretest*\ forms part of the PCRE distribution and is built |
| 5484 | with PCRE during the process of building Exim. It is primarily intended for |
| 5485 | testing PCRE itself, but it can also be used for experimenting with regular |
| 5486 | expressions. After building Exim, the binary can be found in the build |
| 5487 | directory (it is not installed anywhere automatically). There is documentation |
| 5488 | of various options in \(doc/pcretest.txt)\, but for simple testing, none are |
| 5489 | needed. This is the output of a sample run of \*pcretest*\: |
| 5490 | .display |
| 5491 | re> $cb{/^([^@@]+)@@.+@\.(ac|edu)@\.(?!kr)[a-z]@{2@}@$/} |
| 5492 | data> $cb{x@@y.ac.uk} |
| 5493 | 0: x@@y.ac.uk |
| 5494 | 1: x |
| 5495 | 2: ac |
| 5496 | data> $cb{x@@y.ac.kr} |
| 5497 | No match |
| 5498 | data> $cb{x@@y.edu.com} |
| 5499 | No match |
| 5500 | data> $cb{x@@y.edu.co} |
| 5501 | 0: x@@y.edu.co |
| 5502 | 1: x |
| 5503 | 2: edu |
| 5504 | .endd |
| 5505 | .if ~~sys.fancy |
| 5506 | Input typed by the user is shown in bold face. |
| 5507 | .fi |
| 5508 | After the `re>' prompt, a regular expression enclosed in delimiters is |
| 5509 | expected. If this compiles without error, `data>' prompts are given for strings |
| 5510 | against which the expression is matched. An empty data line causes a new |
| 5511 | regular expression to be read. If the match is successful, the captured |
| 5512 | substring values (that is, what would be in the variables \$0$\, \$1$\, \$2$\, |
| 5513 | etc.) are shown. The above example tests for an email address whose domain ends |
| 5514 | with either `ac' or `edu' followed by a two-character top-level domain that is |
| 5515 | not `kr'. The local part is captured in \$1$\ and the `ac' or `edu' in \$2$\. |
| 5516 | |
| 5517 | |
| 5518 | |
| 5519 | |
| 5520 | |
| 5521 | |
| 5522 | . |
| 5523 | . |
| 5524 | . |
| 5525 | . |
| 5526 | . ============================================================================ |
| 5527 | .chapter File and database lookups |
| 5528 | .set runningfoot "file/database lookups" |
| 5529 | .rset CHAPfdlookup "~~chapter" |
| 5530 | .index file||lookup |
| 5531 | .index database lookups |
| 5532 | .index lookup||description of |
| 5533 | Exim can be configured to look up data in files or databases as it processes |
| 5534 | messages. Two different kinds of syntax are used: |
| 5535 | .numberpars |
| 5536 | A string that is to be expanded may contain explicit lookup requests. These |
| 5537 | cause parts of the string to be replaced by data that is obtained from the |
| 5538 | lookup. |
| 5539 | .nextp |
| 5540 | Lists of domains, hosts, and email addresses can contain lookup requests as a |
| 5541 | way of avoiding excessively long linear lists. In this case, the data that is |
| 5542 | returned by the lookup is often (but not always) discarded; whether the lookup |
| 5543 | succeeds or fails is what really counts. These kinds of list are described in |
| 5544 | chapter ~~CHAPdomhosaddlists. |
| 5545 | .endp |
| 5546 | It is easy to confuse the two different kinds of lookup, especially as the |
| 5547 | lists that may contain the second kind are always expanded before being |
| 5548 | processed as lists. Therefore, they may also contain lookups of the first kind. |
| 5549 | Be careful to distinguish between the following two examples: |
| 5550 | .display asis |
| 5551 | domains = ${lookup{$sender_host_address}lsearch{/some/file}} |
| 5552 | domains = lsearch;/some/file |
| 5553 | .endd |
| 5554 | The first uses a string expansion, the result of which must be a domain list. |
| 5555 | String expansions are described in detail in chapter ~~CHAPexpand. The |
| 5556 | expansion takes place first, and the file that is searched could contain lines |
| 5557 | like this: |
| 5558 | .display asis |
| 5559 | 192.168.3.4: domain1 : domain2 : ... |
| 5560 | 192.168.1.9: domain3 : domain4 : ... |
| 5561 | .endd |
| 5562 | Thus, the result of the expansion is a list of domains (and possibly other |
| 5563 | types of item that are allowed in domain lists). |
| 5564 | |
| 5565 | In the second case, the lookup is a single item in a domain list. It causes |
| 5566 | Exim to use a lookup to see if the domain that is being processed can be found |
| 5567 | in the file. The file could contains lines like this: |
| 5568 | .display asis |
| 5569 | domain1: |
| 5570 | domain2: |
| 5571 | .endd |
| 5572 | Any data that follows the keys is not relevant when checking that the domain |
| 5573 | matches the list item. |
| 5574 | |
| 5575 | It is possible to use both kinds of lookup at once. Consider a file containing |
| 5576 | lines like this: |
| 5577 | .display asis |
| 5578 | 192.168.5.6: lsearch;/another/file |
| 5579 | .endd |
| 5580 | If the value of \$sender@_host@_address$\ is 192.168.5.6, expansion of the |
| 5581 | first \domains\ setting above generates the second setting, which therefore |
| 5582 | causes a second lookup to occur. |
| 5583 | |
| 5584 | The rest of this chapter describes the different lookup types that are |
| 5585 | available. Any of them can be used in either of the circumstances described |
| 5586 | above. The syntax requirements for the two cases are described in chapters |
| 5587 | ~~CHAPexpand and ~~CHAPdomhosaddlists, respectively. |
| 5588 | |
| 5589 | .section Lookup types |
| 5590 | .index lookup||types of |
| 5591 | .index single-key lookup||definition of |
| 5592 | Two different styles of data lookup are implemented: |
| 5593 | .numberpars $. |
| 5594 | The \*single-key*\ style requires the specification of a file in which to look, |
| 5595 | and a single key to search for. The lookup type determines how the file is |
| 5596 | searched. |
| 5597 | .nextp |
| 5598 | .index query-style lookup||definition of |
| 5599 | The \*query*\ style accepts a generalized database query. |
| 5600 | No particular key value is assumed by Exim for query-style lookups. You can |
| 5601 | use whichever Exim variable(s) you need to construct the database query. |
| 5602 | .endp |
| 5603 | The code for each lookup type is in a separate source file that is included in |
| 5604 | the binary of Exim only if the corresponding compile-time option is set. The |
| 5605 | default settings in \(src/EDITME)\ are: |
| 5606 | .display asis |
| 5607 | LOOKUP_DBM=yes |
| 5608 | LOOKUP_LSEARCH=yes |
| 5609 | .endd |
| 5610 | which means that only linear searching and DBM lookups are included by default. |
| 5611 | For some types of lookup (e.g. SQL databases), you need to install appropriate |
| 5612 | libraries and header files before building Exim. |
| 5613 | |
| 5614 | |
| 5615 | |
| 5616 | .section Single-key lookup types |
| 5617 | .rset SECTsinglekeylookups "~~chapter.~~section" |
| 5618 | .index lookup||single-key types |
| 5619 | .index single-key lookup||list of types |
| 5620 | The following single-key lookup types are implemented: |
| 5621 | .numberpars $. |
| 5622 | .index cdb||description of |
| 5623 | .index lookup||cdb |
| 5624 | .index binary zero||in lookup key |
| 5625 | \%cdb%\: The given file is searched as a Constant DataBase file, using the key |
| 5626 | string without a terminating binary zero. The cdb format is designed for |
| 5627 | indexed files that are read frequently and never updated, except by total |
| 5628 | re-creation. As such, it is particulary suitable for large files containing |
| 5629 | aliases or other indexed data referenced by an MTA. Information about cdb can |
| 5630 | be found in several places: |
| 5631 | .display rm |
| 5632 | \?http://www.pobox.com/@~djb/cdb.html?\ |
| 5633 | \?ftp://ftp.corpit.ru/pub/tinycdb/?\ |
| 5634 | \?http://packages.debian.org/stable/utils/freecdb.html?\ |
| 5635 | .endd |
| 5636 | A cdb distribution is not needed in order to build Exim with cdb support, |
| 5637 | because the code for reading cdb files is included directly in Exim itself. |
| 5638 | However, no means of building or testing cdb files is provided with Exim, so |
| 5639 | you need to obtain a cdb distribution in order to do this. |
| 5640 | .nextp |
| 5641 | .index DBM||lookup type |
| 5642 | .index lookup||dbm |
| 5643 | .index binary zero||in lookup key |
| 5644 | \%dbm%\: Calls to DBM library functions are used to extract data from the given |
| 5645 | DBM file by looking up the record with the given key. A terminating binary |
| 5646 | zero is included in the key that is passed to the DBM library. See section |
| 5647 | ~~SECTdb for a discussion of DBM libraries. |
| 5648 | .index Berkeley DB library||file format |
| 5649 | For all versions of Berkeley DB, Exim uses the \\DB@_HASH\\ style of database |
| 5650 | when building DBM files using the \exim@_dbmbuild\ utility. However, when using |
| 5651 | Berkeley DB versions 3 or 4, it opens existing databases for reading with the |
| 5652 | \\DB@_UNKNOWN\\ option. This enables it to handle any of the types of database |
| 5653 | that the library supports, and can be useful for accessing DBM files created by |
| 5654 | other applications. (For earlier DB versions, \\DB@_HASH\\ is always used.) |
| 5655 | |
| 5656 | .nextp |
| 5657 | .index lookup||dbmnz |
| 5658 | .index lookup||dbm, terminating zero |
| 5659 | .index binary zero||in lookup key |
| 5660 | .index Courier |
| 5661 | .index \(/etc/userdbshadow.dat)\ |
| 5662 | .index dmbnz lookup type |
| 5663 | \%dbmnz%\: This is the same as \%dbm%\, except that a terminating binary zero |
| 5664 | is not included in the key that is passed to the DBM library. You may need this |
| 5665 | if you want to look up data in files that are created by or shared with some |
| 5666 | other application that does not use terminating zeros. For example, you need to |
| 5667 | use \%dbmnz%\ rather than \%dbm%\ if you want to authenticate incoming SMTP |
| 5668 | calls using the passwords from Courier's \(/etc/userdbshadow.dat)\ file. Exim's |
| 5669 | utility program for creating DBM files (\*exim@_dbmbuild*\) includes the zeros |
| 5670 | by default, but has an option to omit them (see section ~~SECTdbmbuild). |
| 5671 | .nextp |
| 5672 | .index lookup||dsearch |
| 5673 | .index dsearch lookup type |
| 5674 | \%dsearch%\: The given file must be a directory; this is searched for a file |
| 5675 | whose name is the key. The key may not contain any forward slash characters. |
| 5676 | The result of a successful lookup is the name of the file. An example of how |
| 5677 | this lookup can be used to support virtual domains is given in section |
| 5678 | ~~SECTvirtualdomains. |
| 5679 | .nextp |
| 5680 | .index lookup||iplsearch |
| 5681 | .index iplsearch lookup type |
| 5682 | \%iplsearch%\: The given file is a text file containing keys and data. A key is |
| 5683 | terminated by a colon or white space or the end of the line. The keys in the |
| 5684 | file must be IP addresses, or IP addresses with CIDR masks. Keys that involve |
| 5685 | IPv6 addresses must be enclosed in quotes to prevent the first internal colon |
| 5686 | being interpreted as a key terminator. For example: |
| 5687 | .display asis |
| 5688 | 1.2.3.4: data for 1.2.3.4 |
| 5689 | 192.168.0.0/16 data for 192.168.0.0/16 |
| 5690 | "abcd::cdab": data for abcd::cdab |
| 5691 | "abcd:abcd::/32" data for abcd:abcd::/32 |
| 5692 | .endd |
| 5693 | The key for an \%iplsearch%\ lookup must be an IP address (without a mask). The |
| 5694 | file is searched linearly, using the CIDR masks where present, until a matching |
| 5695 | key is found. The first key that matches is used; there is no attempt to find a |
| 5696 | `best' match. Apart from the way the keys are matched, the processing for |
| 5697 | \%iplsearch%\ is the same as for \%lsearch%\. |
| 5698 | |
| 5699 | \**Warning 1**\: Unlike most other single-key lookup types, a file of data for |
| 5700 | \%iplsearch%\ can \*not*\ be turned into a DBM or cdb file, because those |
| 5701 | lookup types support only literal keys. |
| 5702 | |
| 5703 | \**Warning 2**\: In a host list, you must always use \%net-iplsearch%\ so that |
| 5704 | the implicit key is the host's IP address rather than its name (see section |
| 5705 | ~~SECThoslispatsikey). |
| 5706 | |
| 5707 | .nextp |
| 5708 | .index linear search |
| 5709 | .index lookup||lsearch |
| 5710 | .index lsearch lookup type |
| 5711 | \%lsearch%\: The given file is a text file that is searched linearly for a |
| 5712 | line beginning with the search key, terminated by a colon or white space or the |
| 5713 | end of the line. The first occurrence that is found in the file is used. White |
| 5714 | space between the key and the colon is permitted. The remainder of the line, |
| 5715 | with leading and trailing white space removed, is the data. This can be |
| 5716 | continued onto subsequent lines by starting them with any amount of white |
| 5717 | space, but only a single space character is included in the data at such a |
| 5718 | junction. If the data begins with a colon, the key must be terminated by a |
| 5719 | colon, for example: |
| 5720 | .display |
| 5721 | baduser: :fail: |
| 5722 | .endd |
| 5723 | Empty lines and lines beginning with @# are ignored, even if they occur in the |
| 5724 | middle of an item. This is the traditional textual format of alias files. Note |
| 5725 | that the keys in an \%lsearch%\ file are literal strings. There is no |
| 5726 | wildcarding of any kind. |
| 5727 | |
| 5728 | .index lookup||lsearch, colons in keys |
| 5729 | In most \%lsearch%\ files, keys are not required to contain colons |
| 5730 | or @# characters, or |
| 5731 | whitespace. However, if you need this feature, it is available. If a key begins |
| 5732 | with a doublequote character, it is terminated only by a matching quote (or end |
| 5733 | of line), and the normal escaping rules apply to its contents (see section |
| 5734 | ~~SECTstrings). An optional colon is permitted after quoted keys (exactly as |
| 5735 | for unquoted keys). There is no special handling of quotes for the data part of |
| 5736 | an \%lsearch%\ line. |
| 5737 | .nextp |
| 5738 | .index NIS lookup type |
| 5739 | .index lookup||NIS |
| 5740 | .index binary zero||in lookup key |
| 5741 | \%nis%\: The given file is the name of a NIS map, and a NIS lookup is done with |
| 5742 | the given key, without a terminating binary zero. There is a variant called |
| 5743 | \%nis0%\ which does include the terminating binary zero in the key. This is |
| 5744 | reportedly needed for Sun-style alias files. Exim does not recognize NIS |
| 5745 | aliases; the full map names must be used. |
| 5746 | .nextp |
| 5747 | .index wildlsearch lookup type |
| 5748 | .index lookup||wildlsearch |
| 5749 | .index nwildlsearch lookup type |
| 5750 | .index lookup||nwildlsearch |
| 5751 | \%wildlsearch%\ or \%nwildlsearch%\: These search a file linearly, like |
| 5752 | \%lsearch%\, but instead of being interpreted as a literal string, each key may |
| 5753 | be wildcarded. The difference between these two lookup types is that for |
| 5754 | \%wildlsearch%\, each key in the file is string-expanded before being used, |
| 5755 | whereas for \%nwildlsearch%\, no expansion takes place. |
| 5756 | |
| 5757 | Like \%lsearch%\, the testing is done case-insensitively. The following forms |
| 5758 | of wildcard are recognized: |
| 5759 | .numberpars "$*$" |
| 5760 | The string may begin with an asterisk to mean `begins with'. For example: |
| 5761 | .display asis |
| 5762 | *.a.b.c data for anything.a.b.c |
| 5763 | *fish data for anythingfish |
| 5764 | .endd |
| 5765 | .nextp |
| 5766 | The string may begin with a circumflex to indicate a regular expression. For |
| 5767 | example, for \%wildlsearch%\: |
| 5768 | .display asis |
| 5769 | ^\N\d+\.a\.b\N data for <digits>.a.b |
| 5770 | .endd |
| 5771 | Note the use of \"@\N"\ to disable expansion of the contents of the regular |
| 5772 | expression. If you are using \%nwildlsearch%\, where the keys are not |
| 5773 | string-expanded, the equivalent entry is: |
| 5774 | .display asis |
| 5775 | ^\d+\.a\.b data for <digits>.a.b |
| 5776 | .endd |
| 5777 | |
| 5778 | If the regular expression contains white space or colon characters, you must |
| 5779 | either quote it (see \%lsearch%\ above), or represent these characters in other |
| 5780 | ways. For example, \"@\s"\ can be used for white space and \"@\x3A"\ for a |
| 5781 | colon. This may be easier than quoting, because if you quote, you have to |
| 5782 | escape all the backslashes inside the quotes. |
| 5783 | .nextp |
| 5784 | Although I cannot see it being of much use, the general matching function |
| 5785 | that is used to implement |
| 5786 | \%(n)wildlsearch%\ |
| 5787 | means that the string may begin with a lookup name terminated by a semicolon, |
| 5788 | and followed by lookup data. For example: |
| 5789 | .display asis |
| 5790 | cdb;/some/file data for keys that match the file |
| 5791 | .endd |
| 5792 | The data that is obtained from the nested lookup is discarded. |
| 5793 | .endp |
| 5794 | Keys that do not match any of these patterns are interpreted literally. The |
| 5795 | continuation rules for the data are the same as for \%lsearch%\, and keys may |
| 5796 | be followed by optional colons. |
| 5797 | |
| 5798 | \**Warning**\: Unlike most other single-key lookup types, a file of data for |
| 5799 | \%(n)wildlsearch%\ can \*not*\ be turned into a DBM or cdb file, because those |
| 5800 | lookup types support only literal keys. |
| 5801 | .endp |
| 5802 | |
| 5803 | .section Query-style lookup types |
| 5804 | .index lookup||query-style types |
| 5805 | .index query-style lookup||list of types |
| 5806 | The supported query-style lookup types are listed below. Further details about |
| 5807 | many of them are given in later sections. |
| 5808 | .numberpars $. |
| 5809 | .index DNS||as a lookup type |
| 5810 | .index lookup||DNS |
| 5811 | \%dnsdb%\: This does a DNS search for a record whose domain name is the supplied |
| 5812 | query. The resulting data is the contents of the record. See section |
| 5813 | ~~SECTdnsdb. |
| 5814 | .nextp |
| 5815 | .index Interbase lookup type |
| 5816 | .index lookup||Interbase |
| 5817 | \%ibase%\: This does a lookup in an Interbase database. |
| 5818 | .nextp |
| 5819 | .index LDAP||lookup type |
| 5820 | .index lookup||LDAP |
| 5821 | \%ldap%\: This does an LDAP lookup using a query in the form of a URL, and |
| 5822 | returns attributes from a single entry. There is a variant called \%ldapm%\ |
| 5823 | that permits values from multiple entries to be returned. A third variant |
| 5824 | called \%ldapdn%\ returns the Distinguished Name of a single entry instead of |
| 5825 | any attribute values. See section ~~SECTldap. |
| 5826 | .nextp |
| 5827 | .index MySQL||lookup type |
| 5828 | .index lookup||MySQL |
| 5829 | \%mysql%\: The format of the query is an SQL statement that is passed to a MySQL |
| 5830 | database. See section ~~SECTsql. |
| 5831 | .nextp |
| 5832 | .index NIS@+ lookup type |
| 5833 | .index lookup||NIS+ |
| 5834 | \%nisplus%\: This does a NIS+ lookup using a query that can specify the name of |
| 5835 | the field to be returned. See section ~~SECTnisplus. |
| 5836 | .nextp |
| 5837 | .index Oracle||lookup type |
| 5838 | .index lookup||Oracle |
| 5839 | \%oracle%\: The format of the query is an SQL statement that is passed to an |
| 5840 | Oracle database. See section ~~SECTsql. |
| 5841 | .nextp |
| 5842 | .index lookup||passwd |
| 5843 | .index passwd lookup type |
| 5844 | \%passwd%\ is a query-style lookup with queries that are just user names. The |
| 5845 | lookup calls \*getpwnam()*\ to interrogate the system password data, and on |
| 5846 | success, the result string is the same as you would get from an \%lsearch%\ |
| 5847 | lookup on a traditional \(/etc/passwd file)\, though with \"*"\ for the |
| 5848 | password value. For example: |
| 5849 | .display asis |
| 5850 | *:42:42:King Rat:/home/kr:/bin/bash |
| 5851 | .endd |
| 5852 | .nextp |
| 5853 | .index PostgreSQL lookup type |
| 5854 | .index lookup||PostgreSQL |
| 5855 | \%pgsql%\: The format of the query is an SQL statement that is passed to a |
| 5856 | PostgreSQL database. See section ~~SECTsql. |
| 5857 | .nextp |
| 5858 | \%testdb%\: This is a lookup type that is used for testing Exim. It is |
| 5859 | not likely to be useful in normal operation. |
| 5860 | .nextp |
| 5861 | .index whoson lookup type |
| 5862 | .index lookup||whoson |
| 5863 | \%whoson%\: \*Whoson*\ (\?http://whoson.sourceforge.net?\) is a proposed |
| 5864 | Internet protocol that allows Internet server programs to check whether a |
| 5865 | particular (dynamically allocated) IP address is currently allocated to a known |
| 5866 | (trusted) user and, optionally, to obtain the identity of the said user. In |
| 5867 | Exim, this can be used to implement `POP before SMTP' checking using ACL |
| 5868 | statements such as |
| 5869 | .display asis |
| 5870 | require condition = \ |
| 5871 | ${lookup whoson {$sender_host_address}{yes}{no}} |
| 5872 | .endd |
| 5873 | The query consists of a single IP address. The value returned is the name of |
| 5874 | the authenticated user. |
| 5875 | .endp |
| 5876 | |
| 5877 | .section Temporary errors in lookups |
| 5878 | .index lookup||temporary error in |
| 5879 | Lookup functions can return temporary error codes if the lookup cannot be |
| 5880 | completed. For example, a NIS or LDAP database might be unavailable. For this |
| 5881 | reason, it is not advisable to use a lookup that might do this for critical |
| 5882 | options such as a list of local domains. |
| 5883 | |
| 5884 | When a lookup cannot be completed in a router or transport, delivery |
| 5885 | of the message (to the relevant address) is deferred, as for any other |
| 5886 | temporary error. In other circumstances Exim may assume the lookup has failed, |
| 5887 | or may give up altogether. |
| 5888 | |
| 5889 | |
| 5890 | .section Default values in single-key lookups |
| 5891 | .rset SECTdefaultvaluelookups "~~chapter.~~section" |
| 5892 | .index wildcard lookups |
| 5893 | .index lookup||default values |
| 5894 | .index lookup||wildcard |
| 5895 | .index lookup||$*$ added to type |
| 5896 | .index default||in single-key lookups |
| 5897 | In this context, a `default value' is a value specified by the administrator |
| 5898 | that is to be used if a lookup fails. |
| 5899 | |
| 5900 | If `$*$' is added to a single-key lookup type (for example, \lsearch$*$\) and |
| 5901 | the initial lookup fails, the key `$*$' is looked up in the file to provide |
| 5902 | a default value. See also the section on partial matching below. |
| 5903 | |
| 5904 | .index @*@@ with single-key lookup |
| 5905 | .index lookup||$*$@@ added to type |
| 5906 | .index alias file||per-domain default |
| 5907 | Alternatively, if `$*$@@' is added to a single-key lookup type (for example |
| 5908 | \dbm$*$@@\) then, if the initial lookup fails and the key contains an @@ |
| 5909 | character, a second lookup is done with everything before the last @@ replaced |
| 5910 | by $*$. This makes it possible to provide per-domain defaults in alias files |
| 5911 | that include the domains in the keys. If the second lookup fails (or doesn't |
| 5912 | take place because there is no @@ in the key), `$*$' is looked up. |
| 5913 | For example, a \%redirect%\ router might contain: |
| 5914 | .display asis |
| 5915 | data = ${lookup{$local_part@$domain}lsearch*@{/etc/mixed-aliases}} |
| 5916 | .endd |
| 5917 | Suppose the address that is being processed is \*jane@@eyre.example*\. Exim |
| 5918 | looks up these keys, in this order: |
| 5919 | .display asis |
| 5920 | jane@eyre.example |
| 5921 | *@eyre.example |
| 5922 | * |
| 5923 | .endd |
| 5924 | The data is taken from whichever key it finds first. \**Note**\: in an |
| 5925 | \%lsearch%\ file, this does not mean the first of these keys in the file. A |
| 5926 | complete scan is done for each key, and only if it is not found at all does |
| 5927 | Exim move on to try the next key. |
| 5928 | |
| 5929 | |
| 5930 | .section Partial matching in single-key lookups |
| 5931 | .rset SECTpartiallookup "~~chapter.~~section" |
| 5932 | .index partial matching |
| 5933 | .index wildcard lookups |
| 5934 | .index lookup||partial matching |
| 5935 | .index lookup||wildcard |
| 5936 | .index asterisk||in search type |
| 5937 | The normal operation of a single-key lookup is to search the file for an exact |
| 5938 | match with the given key. However, in a number of situations where domains are |
| 5939 | being looked up, it is useful to be able to do partial matching. In this case, |
| 5940 | information in the file that has a key starting with `$*$.' is matched by any |
| 5941 | domain that ends with the components that follow the full stop. For example, if |
| 5942 | a key in a DBM file is |
| 5943 | .display |
| 5944 | *.dates.fict.example |
| 5945 | .endd |
| 5946 | then when partial matching is enabled this is matched by (amongst others) |
| 5947 | \*2001.dates.fict.example*\ and \*1984.dates.fict.example*\. It is also matched |
| 5948 | by \*dates.fict.example*\, if that does not appear as a separate key in the |
| 5949 | file. |
| 5950 | |
| 5951 | \**Note**\: Partial matching is not available for query-style lookups. It is |
| 5952 | also not available for any lookup items in address lists (see section |
| 5953 | ~~SECTaddresslist). |
| 5954 | |
| 5955 | Partial matching is implemented by doing a series of separate lookups using |
| 5956 | keys constructed by modifying the original subject key. This means that it can |
| 5957 | be used with any of the single-key lookup types, provided that |
| 5958 | partial matching keys |
| 5959 | beginning with a special prefix (default `$*$.') are included in the data file. |
| 5960 | Keys in the file that do not begin with the prefix are matched only by |
| 5961 | unmodified subject keys when partial matching is in use. |
| 5962 | |
| 5963 | Partial matching is requested by adding the string `partial-' to the front of |
| 5964 | the name of a single-key lookup type, for example, \partial-dbm\. When this is |
| 5965 | done, the subject key is first looked up unmodified; if that fails, `$*$.' |
| 5966 | is added at the start of the subject key, and it is looked up again. If that |
| 5967 | fails, further lookups are tried with dot-separated components removed |
| 5968 | from the start of the subject key, one-by-one, and `$*$.' added on the front of |
| 5969 | what remains. |
| 5970 | |
| 5971 | A minimum number of two non-$*$ components are required. This can be adjusted |
| 5972 | by including a number before the hyphen in the search type. For example, |
| 5973 | \partial3-lsearch\ specifies a minimum of three non-$*$ components in the |
| 5974 | modified keys. Omitting the number is equivalent to `partial2-'. If the subject |
| 5975 | key is \*2250.dates.fict.example*\ then the following keys are looked up when |
| 5976 | the minimum number of non-$*$ components is two: |
| 5977 | .display asis |
| 5978 | 2250.dates.fict.example |
| 5979 | *.2250.dates.fict.example |
| 5980 | *.dates.fict.example |
| 5981 | *.fict.example |
| 5982 | .endd |
| 5983 | As soon as one key in the sequence is successfully looked up, the lookup |
| 5984 | finishes. |
| 5985 | |
| 5986 | .index lookup||partial matching, changing prefix |
| 5987 | .index prefix||for partial matching |
| 5988 | The use of `$*$.' as the partial matching prefix is a default that can be |
| 5989 | changed. The motivation for this feature is to allow Exim to operate with file |
| 5990 | formats that are used by other MTAs. A different prefix can be supplied in |
| 5991 | parentheses instead of the hyphen after `partial'. For example: |
| 5992 | .display asis |
| 5993 | domains = partial(.)lsearch;/some/file |
| 5994 | .endd |
| 5995 | In this example, if the domain is \*a.b.c*\, the sequence of lookups is |
| 5996 | \"a.b.c"\, \".a.b.c"\, and \".b.c"\ (the default minimum of 2 non-wild |
| 5997 | components is unchanged). The prefix may consist of any punctuation characters |
| 5998 | other than a closing parenthesis. It may be empty, for example: |
| 5999 | .display asis |
| 6000 | domains = partial1()cdb;/some/file |
| 6001 | .endd |
| 6002 | For this example, if the domain is \*a.b.c*\, the sequence of lookups is |
| 6003 | \"a.b.c"\, \"b.c"\, and \"c"\. |
| 6004 | |
| 6005 | If `partial0' is specified, what happens at the end (when the lookup with just |
| 6006 | one non-wild component has failed, and the original key is shortened right down |
| 6007 | to the null string) depends on the prefix: |
| 6008 | .numberpars $. |
| 6009 | If the prefix has zero length, the whole lookup fails. |
| 6010 | .nextp |
| 6011 | If the prefix has length 1, a lookup for just the prefix is done. For |
| 6012 | example, the final lookup for `partial0(.)' is for \"."\ alone. |
| 6013 | .nextp |
| 6014 | Otherwise, if the prefix ends in a dot, the dot is removed, and the |
| 6015 | remainder is looked up. With the default prefix, therefore, the final lookup is |
| 6016 | for `$*$' on its own. |
| 6017 | .nextp |
| 6018 | Otherwise, the whole prefix is looked up. |
| 6019 | .endp |
| 6020 | |
| 6021 | If the search type ends in `$*$' or `$*$@@' (see section |
| 6022 | ~~SECTdefaultvaluelookups above), the search for an ultimate default that this |
| 6023 | implies happens after all partial lookups have failed. If `partial0' is |
| 6024 | specified, adding `$*$' to the search type has no effect with the default |
| 6025 | prefix, because the `$*$' key is already included in the sequence of partial |
| 6026 | lookups. However, there might be a use for lookup types such as |
| 6027 | `partial0(.)lsearch$*$'. |
| 6028 | |
| 6029 | The use of `$*$' in lookup partial matching differs from its use as a wildcard |
| 6030 | in domain lists and the like. Partial matching works only in terms of |
| 6031 | dot-separated components; a key such as \"*fict.example"\ |
| 6032 | in a database file is useless, because the asterisk in a partial matching |
| 6033 | subject key is always followed by a dot. |
| 6034 | |
| 6035 | |
| 6036 | |
| 6037 | .section Lookup caching |
| 6038 | .index lookup||caching |
| 6039 | .index caching||lookup data |
| 6040 | An Exim process |
| 6041 | caches the most recent lookup result on a per-file basis for single-key |
| 6042 | lookup types, and keeps the relevant files open. In some types of configuration |
| 6043 | this can lead to many files being kept open for messages with many recipients. |
| 6044 | To avoid hitting the operating system limit on the number of simultaneously |
| 6045 | open files, Exim closes the least recently used file when it needs to open more |
| 6046 | files than its own internal limit, which can be changed via the |
| 6047 | \lookup@_open@_max\ option. |
| 6048 | |
| 6049 | For query-style lookups, a single data cache per lookup type is kept. The files |
| 6050 | are closed and the caches flushed at strategic points during delivery -- for |
| 6051 | example, after all routing is complete. |
| 6052 | |
| 6053 | |
| 6054 | .section Quoting lookup data |
| 6055 | .index lookup||quoting |
| 6056 | .index quoting||in lookups |
| 6057 | When data from an incoming message is included in a query-style lookup, there |
| 6058 | is the possibility of special characters in the data messing up the syntax of |
| 6059 | the query. For example, a NIS+ query that contains |
| 6060 | .display asis |
| 6061 | [name=$local_part] |
| 6062 | .endd |
| 6063 | will be broken if the local part happens to contain a closing square bracket. |
| 6064 | For NIS+, data can be enclosed in double quotes like this: |
| 6065 | .display asis |
| 6066 | [name="$local_part"] |
| 6067 | .endd |
| 6068 | but this still leaves the problem of a double quote in the data. The rule for |
| 6069 | NIS+ is that double quotes must be doubled. Other lookup types have different |
| 6070 | rules, and to cope with the differing requirements, an expansion operator |
| 6071 | of the following form is provided: |
| 6072 | .display |
| 6073 | @$@{quote@_<<lookup-type>>:<<string>>@} |
| 6074 | .endd |
| 6075 | For example, the safest way to write the NIS+ query is |
| 6076 | .display asis |
| 6077 | [name="${quote_nisplus:$local_part}"] |
| 6078 | .endd |
| 6079 | See chapter ~~CHAPexpand for full coverage of string expansions. The quote |
| 6080 | operator can be used for all lookup types, but has no effect for single-key |
| 6081 | lookups, since no quoting is ever needed in their key strings. |
| 6082 | |
| 6083 | |
| 6084 | |
| 6085 | .section More about dnsdb |
| 6086 | .rset SECTdnsdb "~~chapter.~~section" |
| 6087 | .index dnsdb lookup |
| 6088 | .index lookup||dnsdb |
| 6089 | .index DNS||as a lookup type |
| 6090 | The \%dnsdb%\ lookup type uses the DNS as its database. A query consists of a |
| 6091 | record type and a domain name, separated by an equals sign. For example, an |
| 6092 | expansion string could contain: |
| 6093 | .display asis |
| 6094 | ${lookup dnsdb{mx=a.b.example}{$value}fail} |
| 6095 | .endd |
| 6096 | The supported record types are A, CNAME, MX, NS, PTR, SRV, and TXT, |
| 6097 | and, when Exim is compiled with IPv6 support, AAAA (and A6 if that is also |
| 6098 | configured). If no type is given, TXT is assumed. When the type is PTR, the |
| 6099 | address should be given as normal; it is converted to the necessary inverted |
| 6100 | format internally. For example: |
| 6101 | .display asis |
| 6102 | ${lookup dnsdb{ptr=192.168.4.5}{$value}fail} |
| 6103 | .endd |
| 6104 | |
| 6105 | .index MX record||in \%dnsdb%\ lookup |
| 6106 | For MX records, both the preference value and the host name are returned, |
| 6107 | separated by a space. |
| 6108 | .index SRV record||in \%dnsdb%\ lookup |
| 6109 | For SRV records, the priority, weight, port, and host name are returned, |
| 6110 | separated by spaces. For any record type, |
| 6111 | if multiple records are found (or, for A6 lookups, if a single record leads to |
| 6112 | multiple addresses), the data is returned as a concatenation, separated by |
| 6113 | newlines. The order, of course, depends on the DNS resolver. |
| 6114 | |
| 6115 | |
| 6116 | |
| 6117 | |
| 6118 | .section More about LDAP |
| 6119 | .rset SECTldap "~~chapter.~~section" |
| 6120 | .index LDAP lookup |
| 6121 | .index lookup||LDAP |
| 6122 | .index Solaris||LDAP |
| 6123 | The original LDAP implementation came from the University of Michigan; this has |
| 6124 | become `Open LDAP', and there are now two different releases. Another |
| 6125 | implementation comes from Netscape, and Solaris 7 and subsequent releases |
| 6126 | contain inbuilt LDAP support. Unfortunately, though these are all compatible at |
| 6127 | the lookup function level, their error handling is different. For this reason |
| 6128 | it is necessary to set a compile-time variable when building Exim with LDAP, to |
| 6129 | indicate which LDAP library is in use. One of the following should appear in |
| 6130 | your \(Local/Makefile)\: |
| 6131 | .display asis |
| 6132 | LDAP_LIB_TYPE=UMICHIGAN |
| 6133 | LDAP_LIB_TYPE=OPENLDAP1 |
| 6134 | LDAP_LIB_TYPE=OPENLDAP2 |
| 6135 | LDAP_LIB_TYPE=NETSCAPE |
| 6136 | LDAP_LIB_TYPE=SOLARIS |
| 6137 | .endd |
| 6138 | If \\LDAP@_LIB@_TYPE\\ is not set, Exim assumes \"OPENLDAP1"\, which has the |
| 6139 | same interface as the University of Michigan version. |
| 6140 | |
| 6141 | There are three LDAP lookup types in Exim. These behave slightly differently in |
| 6142 | the way they handle the results of a query: |
| 6143 | .numberpars $. |
| 6144 | \%ldap%\ requires the result to contain just one entry; if there are more, it |
| 6145 | gives an error. |
| 6146 | .nextp |
| 6147 | \%ldapdn%\ also requires the result to contain just one entry, but it is the |
| 6148 | Distinguished Name that is returned rather than any attribute values. |
| 6149 | .nextp |
| 6150 | \%ldapm%\ permits the result to contain more than one entry; the attributes from |
| 6151 | all of them are returned. |
| 6152 | .endp |
| 6153 | |
| 6154 | For \%ldap%\ and \%ldapm%\, if a query finds only entries with no attributes, |
| 6155 | Exim behaves as if the entry did not exist, and the lookup fails. The format of |
| 6156 | the data returned by a successful lookup is described in the next section. |
| 6157 | First we explain how LDAP queries are coded. |
| 6158 | |
| 6159 | .section Format of LDAP queries |
| 6160 | .rset SECTforldaque "~~chapter.~~section" |
| 6161 | .index LDAP||query format |
| 6162 | An LDAP query takes the form of a URL as defined in RFC 2255. For example, in |
| 6163 | the configuration of a \%redirect%\ router one might have this setting: |
| 6164 | .display asis |
| 6165 | data = ${lookup ldap \ |
| 6166 | {ldap:///cn=$local_part,o=University%20of%20Cambridge,\ |
| 6167 | c=UK?mailbox?base?}} |
| 6168 | .endd |
| 6169 | .index LDAP||with TLS |
| 6170 | The URL may begin with \"ldap"\ or \"ldaps"\ if your LDAP library supports |
| 6171 | secure (encrypted) LDAP connections. The second of these ensures that an |
| 6172 | encrypted TLS connection is used. |
| 6173 | |
| 6174 | .section LDAP quoting |
| 6175 | .index LDAP||quoting |
| 6176 | Two levels of quoting are required in LDAP queries, the first for LDAP itself |
| 6177 | and the second because the LDAP query is represented as a URL. Furthermore, |
| 6178 | within an LDAP query, two different kinds of quoting are required. For this |
| 6179 | reason, there are two different LDAP-specific quoting operators. |
| 6180 | |
| 6181 | The \quote@_ldap\ operator is designed for use on strings that are part of |
| 6182 | filter specifications. Conceptually, it first does the following conversions on |
| 6183 | the string: |
| 6184 | .display asis |
| 6185 | * => \2A |
| 6186 | ( => \28 |
| 6187 | ) => \29 |
| 6188 | \ => \5C |
| 6189 | .endd |
| 6190 | in accordance with RFC 2254. The resulting string is then quoted according |
| 6191 | to the rules for URLs, that is, all characters except |
| 6192 | .display asis |
| 6193 | ! $ ' - . _ ( ) * + |
| 6194 | .endd |
| 6195 | are converted to their hex values, preceded by a percent sign. For example: |
| 6196 | .display asis |
| 6197 | ${quote_ldap: a(bc)*, a<yz>; } |
| 6198 | .endd |
| 6199 | yields |
| 6200 | .display asis |
| 6201 | %20a%5C28bc%5C29%5C2A%2C%20a%3Cyz%3E%3B%20 |
| 6202 | .endd |
| 6203 | Removing the URL quoting, this is (with a leading and a trailing space): |
| 6204 | .display asis |
| 6205 | a\28bc\29\2A, a<yz>; |
| 6206 | .endd |
| 6207 | |
| 6208 | The \quote@_ldap@_dn\ operator is designed for use on strings that are part of |
| 6209 | base DN specifications in queries. Conceptually, it first converts the string |
| 6210 | by inserting a backslash in front of any of the following characters: |
| 6211 | .display asis |
| 6212 | , + " \ < > ; |
| 6213 | .endd |
| 6214 | It also inserts a backslash before any leading spaces or @# characters, and |
| 6215 | before any trailing spaces. (These rules are in RFC 2253.) The resulting string |
| 6216 | is then quoted according to the rules for URLs. For example: |
| 6217 | .display asis |
| 6218 | ${quote_ldap_dn: a(bc)*, a<yz>; } |
| 6219 | .endd |
| 6220 | yields |
| 6221 | .display asis |
| 6222 | %5C%20a(bc)*%5C%2C%20a%5C%3Cyz%5C%3E%5C%3B%5C%20 |
| 6223 | .endd |
| 6224 | Removing the URL quoting, this is (with a trailing space): |
| 6225 | .display asis |
| 6226 | \ a(bc)*\, a\<yz\>\;\ |
| 6227 | .endd |
| 6228 | There are some further comments about quoting in the section on LDAP |
| 6229 | authentication below. |
| 6230 | |
| 6231 | .section LDAP connections |
| 6232 | .index LDAP||connections |
| 6233 | The connection to an LDAP server may either be over TCP/IP, or, when OpenLDAP |
| 6234 | is in use, via a Unix domain socket. The example given above does not specify |
| 6235 | an LDAP server. A server that is reached by TCP/IP can be specified in a query |
| 6236 | by starting it with |
| 6237 | .display |
| 6238 | ldap://<<hostname>>:<<port>>/... |
| 6239 | .endd |
| 6240 | If the port (and preceding colon) are omitted, the standard LDAP port (389) is |
| 6241 | used. When no server is specified in a query, a list of default servers is |
| 6242 | taken from the \ldap@_default@_servers\ configuration option. This supplies a |
| 6243 | colon-separated list of servers which are tried in turn until one successfully |
| 6244 | handles a query, or there is a serious error. Successful handling either |
| 6245 | returns the requested data, or indicates that it does not exist. Serious errors |
| 6246 | are syntactical, or multiple values when only a single value is expected. |
| 6247 | Errors which cause the next server to be tried are connection failures, bind |
| 6248 | failures, and timeouts. |
| 6249 | |
| 6250 | For each server name in the list, a port number can be given. The standard way |
| 6251 | of specifing a host and port is to use a colon separator (RFC 1738). Because |
| 6252 | \ldap@_default@_servers\ is a colon-separated list, such colons have to be |
| 6253 | doubled. For example |
| 6254 | .display asis |
| 6255 | ldap_default_servers = ldap1.example.com::145:ldap2.example.com |
| 6256 | .endd |
| 6257 | If \ldap@_default@_servers\ is unset, a URL with no server name is passed |
| 6258 | to the LDAP library with no server name, and the library's default (normally |
| 6259 | the local host) is used. |
| 6260 | |
| 6261 | If you are using the OpenLDAP library, you can connect to an LDAP server using |
| 6262 | a Unix domain socket instead of a TCP/IP connection. This is specified by using |
| 6263 | \"ldapi"\ instead of \"ldap"\ in LDAP queries. What follows here applies only |
| 6264 | to OpenLDAP. If Exim is compiled with a different LDAP library, this feature is |
| 6265 | not available. |
| 6266 | |
| 6267 | For this type of connection, instead of a host name for the server, a pathname |
| 6268 | for the socket is required, and the port number is not relevant. The pathname |
| 6269 | can be specified either as an item in \ldap@_default@_servers\, or inline in |
| 6270 | the query. In the former case, you can have settings such as |
| 6271 | .display asis |
| 6272 | ldap_default_servers = /tmp/ldap.sock : backup.ldap.your.domain |
| 6273 | .endd |
| 6274 | When the pathname is given in the query, you have to escape the slashes as |
| 6275 | \"%2F"\ to fit in with the LDAP URL syntax. For example: |
| 6276 | .display asis |
| 6277 | ${lookup ldap {ldapi://%2Ftmp%2Fldap.sock/o=... |
| 6278 | .endd |
| 6279 | When Exim processes an LDAP lookup and finds that the `hostname' is really |
| 6280 | a pathname, it uses the Unix domain socket code, even if the query actually |
| 6281 | specifies \"ldap"\ or \"ldaps"\. In particular, no encryption is used for a |
| 6282 | socket connection. This behaviour means that you can use a setting of |
| 6283 | \ldap@_default@_servers\ such as in the example above with traditional \"ldap"\ |
| 6284 | or \"ldaps"\ queries, and it will work. First, Exim tries a connection via |
| 6285 | the Unix domain socket; if that fails, it tries a TCP/IP connection to the |
| 6286 | backup host. |
| 6287 | |
| 6288 | If an explicit \"ldapi"\ type is given in a query when a host name is |
| 6289 | specified, an error is diagnosed. However, if there are more items in |
| 6290 | \ldap@_default@_servers\, they are tried. In other words: |
| 6291 | .numberpars $. |
| 6292 | Using a pathname with \"ldap"\ or \"ldaps"\ forces the use of the Unix domain |
| 6293 | interface. |
| 6294 | .nextp |
| 6295 | Using \"ldapi"\ with a host name causes an error. |
| 6296 | .endp |
| 6297 | |
| 6298 | Using \"ldapi"\ with no host or path in the query, and no setting of |
| 6299 | \ldap@_default@_servers\, does whatever the library does by default. |
| 6300 | |
| 6301 | |
| 6302 | .section LDAP authentication and control information |
| 6303 | .index LDAP||authentication |
| 6304 | The LDAP URL syntax provides no way of passing authentication and other control |
| 6305 | information to the server. To make this possible, the URL in an LDAP query may |
| 6306 | be preceded by any number of `<<name>>=<<value>>' settings, separated by |
| 6307 | spaces. If a value contains spaces it must be enclosed in double quotes, and |
| 6308 | when double quotes are used, backslash is interpreted in the usual way inside |
| 6309 | them. |
| 6310 | |
| 6311 | The following names are recognized: |
| 6312 | .display |
| 6313 | CONNECT $rm{set a connection timeout} |
| 6314 | .newline |
| 6315 | DEREFERENCE $rm{set the dereferencing parameter} |
| 6316 | USER $rm{set the DN, for authenticating the LDAP bind} |
| 6317 | PASS $rm{set the password, likewise} |
| 6318 | SIZE $rm{set the limit for the number of entries returned} |
| 6319 | TIME $rm{set the maximum waiting time for a query} |
| 6320 | .endd |
| 6321 | The value of the \\DEREFERENCE\\ parameter must be one of the words `never', |
| 6322 | `searching', `finding', or `always'. |
| 6323 | |
| 6324 | Here is an example of an LDAP query in an Exim lookup that uses some of these |
| 6325 | values. This is a single line, folded for ease of reading: |
| 6326 | .display asis |
| 6327 | .indent 0 |
| 6328 | ${lookup ldap |
| 6329 | {user="cn=manager,o=University of Cambridge,c=UK" pass=secret |
| 6330 | ldap:///o=University%20of%20Cambridge,c=UK?sn?sub?(cn=foo)} |
| 6331 | {$value}fail} |
| 6332 | .endd |
| 6333 | The encoding of spaces as %20 is a URL thing which should not be done for any |
| 6334 | of the auxiliary data. Exim configuration settings that include lookups which |
| 6335 | contain password information should be preceded by `hide' to prevent non-admin |
| 6336 | users from using the \-bP-\ option to see their values. |
| 6337 | |
| 6338 | The auxiliary data items may be given in any order. The default is no |
| 6339 | connection timeout (the system timeout is used), no user or password, no limit |
| 6340 | on the number of entries returned, and no time limit on queries. |
| 6341 | |
| 6342 | The time limit for connection is given in seconds; zero means use the default. |
| 6343 | This facility is available in Netscape SDK 4.1; it may not be available in |
| 6344 | other LDAP implementations. Exim uses the given value if |
| 6345 | \\LDAP@_X@_OPT@_CONNECT@_TIMEOUT\\ is defined in the LDAP headers. |
| 6346 | |
| 6347 | When a DN is quoted in the \\USER=\\ setting for LDAP authentication, Exim |
| 6348 | removes any URL quoting that it may contain before passing it LDAP. Apparently |
| 6349 | some libraries do this for themselves, but some do not. Removing the URL |
| 6350 | quoting has two advantages: |
| 6351 | .numberpars $. |
| 6352 | It makes it possible to use the same \quote@_ldap@_dn\ expansion for \\USER=\\ |
| 6353 | DNs as with DNs inside actual queries. |
| 6354 | .nextp |
| 6355 | It permits spaces inside \\USER=\\ DNs. |
| 6356 | .endp |
| 6357 | For example, a setting such as |
| 6358 | .display asis |
| 6359 | USER=cn=${quote_ldap_dn:$1} |
| 6360 | .endd |
| 6361 | should work even if \$1$\ contains spaces. |
| 6362 | |
| 6363 | Expanded data for the \\PASS=\\ value should be quoted using the \quote\ |
| 6364 | expansion operator, rather than the LDAP quote operators. The only reason this |
| 6365 | field needs quoting is to ensure that it conforms to the Exim syntax, which |
| 6366 | does not allow unquoted spaces. For example: |
| 6367 | .display asis |
| 6368 | PASS=${quote:$3} |
| 6369 | .endd |
| 6370 | |
| 6371 | The LDAP authentication mechanism can be used to check passwords as part of |
| 6372 | SMTP authentication. See the \ldapauth\ expansion string condition in chapter |
| 6373 | ~~CHAPexpand. |
| 6374 | |
| 6375 | |
| 6376 | .section Format of data returned by LDAP |
| 6377 | .index LDAP||returned data formats |
| 6378 | The \%ldapdn%\ lookup type returns the Distinguished Name from a single entry as |
| 6379 | a sequence of values, for example |
| 6380 | .display asis |
| 6381 | cn=manager, o=University of Cambridge, c=UK |
| 6382 | .endd |
| 6383 | |
| 6384 | The \%ldap%\ lookup type generates an error if more than one entry matches the |
| 6385 | search filter, whereas \%ldapm%\ permits this case, and inserts a newline in the |
| 6386 | result between the data from different entries. It is possible for multiple |
| 6387 | values to be returned for both \%ldap%\ and \%ldapm%\, but in the former case you |
| 6388 | know that whatever values are returned all came from a single entry in the |
| 6389 | directory. |
| 6390 | |
| 6391 | In the common case where you specify a single attribute in your LDAP query, the |
| 6392 | result is not quoted, and does not contain the attribute name. If the attribute |
| 6393 | has multiple values, they are separated by commas. |
| 6394 | |
| 6395 | If you specify multiple attributes, the result contains space-separated, quoted |
| 6396 | strings, each preceded by the attribute name and an equals sign. Within the |
| 6397 | quotes, the quote character, backslash, and newline are escaped with |
| 6398 | backslashes, and commas are used to separate multiple values for the attribute. |
| 6399 | Apart from the escaping, the string within quotes takes the same form as the |
| 6400 | output when a single attribute is requested. Specifying no attributes is the |
| 6401 | same as specifying all of an entry's attributes. |
| 6402 | |
| 6403 | Here are some examples of the output format. The first line of each pair is an |
| 6404 | LDAP query, and the second is the data that is returned. The attribute called |
| 6405 | \attr1\ has two values, whereas \attr2\ has only one value: |
| 6406 | .display asis |
| 6407 | ldap:///o=base?attr1?sub?(uid=fred) |
| 6408 | value1.1, value1.2 |
| 6409 | |
| 6410 | ldap:///o=base?attr2?sub?(uid=fred) |
| 6411 | value two |
| 6412 | |
| 6413 | ldap:///o=base?attr1,attr2?sub?(uid=fred) |
| 6414 | attr1="value1.1, value1.2" attr2="value two" |
| 6415 | |
| 6416 | ldap:///o=base??sub?(uid=fred) |
| 6417 | objectClass="top" attr1="value1.1, value1.2" attr2="value two" |
| 6418 | .endd |
| 6419 | The \extract\ operator in string expansions can be used to pick out individual |
| 6420 | fields from data that consists of $it{key}=$it{value} pairs. You can make use |
| 6421 | of Exim's \-be-\ option to run expansion tests and thereby check the results of |
| 6422 | LDAP lookups. |
| 6423 | |
| 6424 | |
| 6425 | |
| 6426 | .section More about NIS+ |
| 6427 | .rset SECTnisplus "~~chapter.~~section" |
| 6428 | .index NIS@+ lookup type |
| 6429 | .index lookup||NIS+ |
| 6430 | NIS+ queries consist of a NIS+ \*indexed name*\ followed by an optional colon |
| 6431 | and field name. If this is given, the result of a successful query is the |
| 6432 | contents of the named field; otherwise the result consists of a concatenation |
| 6433 | of \*field-name=field-value*\ pairs, separated by spaces. Empty values and |
| 6434 | values containing spaces are quoted. For example, the query |
| 6435 | .display asis |
| 6436 | [name=mg1456],passwd.org_dir |
| 6437 | .endd |
| 6438 | might return the string |
| 6439 | .display asis |
| 6440 | name=mg1456 passwd="" uid=999 gid=999 gcos="Martin Guerre" |
| 6441 | home=/home/mg1456 shell=/bin/bash shadow="" |
| 6442 | .endd |
| 6443 | (split over two lines here to fit on the page), whereas |
| 6444 | .display asis |
| 6445 | [name=mg1456],passwd.org_dir:gcos |
| 6446 | .endd |
| 6447 | would just return |
| 6448 | .display asis |
| 6449 | Martin Guerre |
| 6450 | .endd |
| 6451 | with no quotes. A NIS+ lookup fails if NIS+ returns more than one table entry |
| 6452 | for the given indexed key. The effect of the \quote@_nisplus\ expansion |
| 6453 | operator is to double any quote characters within the text. |
| 6454 | |
| 6455 | |
| 6456 | .section More about MySQL, PostgreSQL, Oracle, and Interbase |
| 6457 | .rset SECTsql "~~chapter.~~section" |
| 6458 | .index MySQL||lookup type |
| 6459 | .index PostgreSQL lookup type |
| 6460 | .index lookup||MySQL |
| 6461 | .index lookup||PostgreSQL |
| 6462 | .index Oracle||lookup type |
| 6463 | .index lookup||Oracle |
| 6464 | .index Interbase lookup type |
| 6465 | .index lookup||Interbase |
| 6466 | If any MySQL, PostgreSQL, Oracle, or Interbase lookups are used, the |
| 6467 | \mysql@_servers\, \pgsql@_servers\, \oracle@_servers\, or \ibase@_servers\ |
| 6468 | option (as appropriate) must be set to a colon-separated list of server |
| 6469 | information. Each item in the list is a slash-separated list of four items: |
| 6470 | host name, database name, user name, and password. In the case of Oracle, the |
| 6471 | host name field is used for the `service name', and the database name field is |
| 6472 | not used and should be empty. For example: |
| 6473 | .display asis |
| 6474 | hide oracle_servers = oracle.plc.example//ph10/abcdwxyz |
| 6475 | .endd |
| 6476 | Because password data is sensitive, you should always precede the setting with |
| 6477 | `hide', to prevent non-admin users from obtaining the setting via the \-bP-\ |
| 6478 | option. Here is an example where two MySQL servers are listed: |
| 6479 | .display asis |
| 6480 | hide mysql_servers = localhost/users/root/secret:\ |
| 6481 | otherhost/users/root/othersecret |
| 6482 | .endd |
| 6483 | For MySQL and PostgreSQL, a host may be specified as <<name>>:<<port>> but |
| 6484 | because this is a colon-separated list, the colon has to be doubled. |
| 6485 | |
| 6486 | For each query, these parameter groups are tried in order until a connection |
| 6487 | and a query succeeds. Queries for these databases are SQL statements, so an |
| 6488 | example might be |
| 6489 | .display asis |
| 6490 | .indent 0 |
| 6491 | ${lookup mysql{select mailbox from users where id='ph10'}{$value}fail} |
| 6492 | .endd |
| 6493 | If the result of the query contains more than one field, the data for |
| 6494 | each field in the row is returned, preceded by its name, so the result |
| 6495 | of |
| 6496 | .display asis |
| 6497 | .indent 0 |
| 6498 | ${lookup pgsql{select home,name from users where id='ph10'}{$value}} |
| 6499 | .endd |
| 6500 | might be |
| 6501 | .display asis |
| 6502 | home=/home/ph10 name="Philip Hazel" |
| 6503 | .endd |
| 6504 | Values containing spaces and empty values are double quoted, with embedded |
| 6505 | quotes escaped by a backslash. |
| 6506 | |
| 6507 | If the result of the query contains just one field, the value is passed back |
| 6508 | verbatim, without a field name, for example: |
| 6509 | .display asis |
| 6510 | Philip Hazel |
| 6511 | .endd |
| 6512 | If the result of the query yields more than one row, it is all concatenated, |
| 6513 | with a newline between the data for each row. |
| 6514 | |
| 6515 | The \quote@_mysql\, \quote@_pgsql\, and \quote@_oracle\ expansion operators |
| 6516 | convert newline, tab, carriage return, and backspace to @\n, @\t, @\r, and @\b |
| 6517 | respectively, and the characters single-quote, double-quote, and backslash |
| 6518 | itself are escaped with backslashes. The \quote@_pgsql\ expansion operator, in |
| 6519 | addition, escapes the percent and underscore characters. This cannot be done |
| 6520 | for MySQL because these escapes are not recognized in contexts where these |
| 6521 | characters are not special. |
| 6522 | |
| 6523 | |
| 6524 | .section Special MySQL features |
| 6525 | For MySQL, an empty host name or the use of `localhost' in \mysql@_servers\ |
| 6526 | causes a connection to the server on the local host by means of a Unix domain |
| 6527 | socket. An alternate socket can be specified in parentheses. The full syntax of |
| 6528 | each item in \mysql@_servers\ is: |
| 6529 | .display |
| 6530 | <<hostname>>@:@:<<port>>(<<socket name>>)/<<database>>/<<user>>/<<password>> |
| 6531 | .endd |
| 6532 | Any of the three sub-parts of the first field can be omitted. For normal use on |
| 6533 | the local host it can be left blank or set to just `localhost'. |
| 6534 | |
| 6535 | No database need be supplied -- but if it is absent here, it must be given in |
| 6536 | the queries. |
| 6537 | |
| 6538 | If a MySQL query is issued that does not request any data (an insert, update, |
| 6539 | or delete command), the result of the lookup is the number of rows affected. |
| 6540 | |
| 6541 | |
| 6542 | |
| 6543 | .section Special PostgreSQL features |
| 6544 | PostgreSQL lookups can also use Unix domain socket connections to the database. |
| 6545 | This is usually faster and costs less CPU time than a TCP/IP connection. |
| 6546 | However it can be used only if the mail server runs on the same machine as the |
| 6547 | database server. A configuration line for PostgreSQL via Unix domain sockets |
| 6548 | looks like this: |
| 6549 | .display asis |
| 6550 | hide pgsql_servers = (/tmp/.s.PGSQL.5432)/db/user/password : ... |
| 6551 | .endd |
| 6552 | In other words, instead of supplying a host name, a path to the socket is |
| 6553 | given. The path name is enclosed in parentheses so that its slashes aren't |
| 6554 | visually confused with the delimiters for the other server parameters. |
| 6555 | |
| 6556 | If a PostgreSQL query is issued that does not request any data (an insert, |
| 6557 | update, or delete command), the result of the lookup is the number of rows |
| 6558 | affected. |
| 6559 | |
| 6560 | |
| 6561 | |
| 6562 | |
| 6563 | . |
| 6564 | . |
| 6565 | . |
| 6566 | . |
| 6567 | . ============================================================================ |
| 6568 | .chapter Domain, host, address, and local part lists |
| 6569 | .set runningfoot "domain, host, and address lists" |
| 6570 | .rset CHAPdomhosaddlists "~~chapter" |
| 6571 | .index list||of domains, hosts, etc. |
| 6572 | A number of Exim configuration options contain lists of domains, hosts, |
| 6573 | email addresses, or local parts. For example, the \hold@_domains\ option |
| 6574 | contains a list of domains whose delivery is currently suspended. These lists |
| 6575 | are also used as data in ACL statements (see chapter ~~CHAPACL). |
| 6576 | |
| 6577 | Each item in one of these lists is a pattern to be matched against a domain, |
| 6578 | host, email address, or local part, respectively. In the sections below, the |
| 6579 | different types of pattern for each case are described, but first we cover some |
| 6580 | general facilities that apply to all four kinds of list. |
| 6581 | |
| 6582 | |
| 6583 | .section Expansion of lists |
| 6584 | .index expansion||of lists |
| 6585 | Each list is expanded as a single string before it is used. If the expansion is |
| 6586 | forced to fail, Exim behaves as if the item it is testing (domain, host, |
| 6587 | address, or local part) is not in the list. Other expansion failures cause |
| 6588 | temporary errors. |
| 6589 | |
| 6590 | If an item in a list is a regular expression, backslashes, dollars and possibly |
| 6591 | other special characters in the expression must be protected against |
| 6592 | misinterpretation by the string expander. The easiest way to do this is to use |
| 6593 | the \"@\N"\ expansion feature to indicate that the contents of the regular |
| 6594 | expression should not be expanded. For example, in an ACL you might have: |
| 6595 | .display asis |
| 6596 | deny senders = \N^\d{8}\w@.*\.baddomain\.example$\N : |
| 6597 | ${lookup{$domain}lsearch{/badsenders/bydomain}} |
| 6598 | .endd |
| 6599 | The first item is a regular expression that is protected from expansion by |
| 6600 | \"@\N"\, whereas the second uses the expansion to obtain a list of unwanted |
| 6601 | senders based on the receiving domain. |
| 6602 | |
| 6603 | After expansion, the list is split up into separate items for matching. |
| 6604 | Normally, colon is used as the separator character, but this can be varied if |
| 6605 | necessary, as described in section ~~SECTlistconstruct. |
| 6606 | |
| 6607 | |
| 6608 | .section Negated items in lists |
| 6609 | .index list||negation |
| 6610 | .index negation in lists |
| 6611 | Items in a list may be positive or negative. Negative items are indicated by a |
| 6612 | leading exclamation mark, which may be followed by optional white space. A list |
| 6613 | defines a set of items (domains, etc). When Exim processes one of these lists, |
| 6614 | it is trying to find out whether a domain, host, address, or local part |
| 6615 | (respectively) is in the set that is defined by the list. It works like this: |
| 6616 | |
| 6617 | The list is scanned from left to right. If a positive item is matched, the |
| 6618 | subject that is being checked is in the set; if a negative item is matched, the |
| 6619 | subject is not in the set. If the end of the list is reached without the |
| 6620 | subject having matched any of the patterns, it is in the set if the last item |
| 6621 | was a negative one, but not if it was a positive one. For example, the list in |
| 6622 | .display asis |
| 6623 | domainlist relay_domains = !a.b.c : *.b.c |
| 6624 | .endd |
| 6625 | matches any domain ending in \*.b.c*\ except for \*a.b.c*\. Domains that match |
| 6626 | neither \*a.b.c*\ nor \*@*.b.c*\ do not match, because the last item in the |
| 6627 | list is positive. However, if the setting were |
| 6628 | .display asis |
| 6629 | domainlist relay_domains = !a.b.c |
| 6630 | .endd |
| 6631 | then all domains other than \*a.b.c*\ would match because the last item in the |
| 6632 | list is negative. In other words, a list that ends with a negative item behaves |
| 6633 | as if it had an extra item \":*"\ on the end. |
| 6634 | |
| 6635 | Another way of thinking about positive and negative items in lists is to read |
| 6636 | the connector as `or' after a positive item and as `and' after a negative |
| 6637 | item. |
| 6638 | |
| 6639 | |
| 6640 | .section File names in lists |
| 6641 | .rset SECTfilnamlis "~~chapter.~~section" |
| 6642 | .index list||file name in |
| 6643 | If an item in a domain, host, address, or local part list is an absolute file |
| 6644 | name (beginning with a slash character), each line of the file is read and |
| 6645 | processed as if it were an independent item in the list, except that further |
| 6646 | file names are not allowed, |
| 6647 | and no expansion of the data from the file takes place. |
| 6648 | Empty lines in the file are ignored, and the file may also contain comment |
| 6649 | lines: |
| 6650 | .numberpars $. |
| 6651 | For domain and host lists, if a @# character appears anywhere in a line of the |
| 6652 | file, it and all following characters are ignored. |
| 6653 | .nextp |
| 6654 | Because local parts may legitimately contain @# characters, a comment in an |
| 6655 | address list or local part list file is recognized only if @# is preceded by |
| 6656 | white space or the start of the line. For example: |
| 6657 | .display asis |
| 6658 | not#comment@x.y.z # but this is a comment |
| 6659 | .endd |
| 6660 | .endp |
| 6661 | Putting a file name in a list has the same effect as inserting each line of the |
| 6662 | file as an item in the list (blank lines and comments excepted). However, there |
| 6663 | is one important difference: the file is read each time the list is processed, |
| 6664 | so if its contents vary over time, Exim's behaviour changes. |
| 6665 | |
| 6666 | If a file name is preceded by an exclamation mark, the sense of any match |
| 6667 | within the file is inverted. For example, if |
| 6668 | .display asis |
| 6669 | hold_domains = !/etc/nohold-domains |
| 6670 | .endd |
| 6671 | and the file contains the lines |
| 6672 | .display asis |
| 6673 | !a.b.c |
| 6674 | *.b.c |
| 6675 | .endd |
| 6676 | then \*a.b.c*\ is in the set of domains defined by \hold@_domains\, whereas any |
| 6677 | domain matching \"*.b.c"\ is not. |
| 6678 | |
| 6679 | |
| 6680 | .section An lsearch file is not an out-of-line list |
| 6681 | As will be described in the sections that follow, lookups can be used in lists |
| 6682 | to provide indexed methods of checking list membership. There has been some |
| 6683 | confusion about the way \%lsearch%\ lookups work in lists. Because |
| 6684 | an \%lsearch%\ file contains plain text and is scanned sequentially, it is |
| 6685 | sometimes thought that it is allowed to contain wild cards and other kinds of |
| 6686 | non-constant pattern. This is not the case. The keys in an \%lsearch%\ file are |
| 6687 | always fixed strings, just as for any other single-key lookup type. |
| 6688 | |
| 6689 | If you want to use a file to contain wild-card patterns that form part of a |
| 6690 | list, just give the file name on its own, without a search type, as described |
| 6691 | in the previous section. |
| 6692 | |
| 6693 | |
| 6694 | |
| 6695 | .section Named lists |
| 6696 | .rset SECTnamedlists "~~chapter.~~section" |
| 6697 | .index named lists |
| 6698 | .index list||named |
| 6699 | A list of domains, hosts, email addresses, or local parts can be given a name |
| 6700 | which is then used to refer to the list elsewhere in the configuration. This is |
| 6701 | particularly convenient if the same list is required in several different |
| 6702 | places. It also allows lists to be given meaningful names, which can improve |
| 6703 | the readability of the configuration. For example, it is conventional to define |
| 6704 | a domain list called \*local@_domains*\ for all the domains that are handled |
| 6705 | locally on a host, using a configuration line such as |
| 6706 | .display asis |
| 6707 | domainlist local_domains = localhost:my.dom.example |
| 6708 | .endd |
| 6709 | Named lists are referenced by giving their name preceded by a plus sign, so, |
| 6710 | for example, a router that is intended to handle local domains would be |
| 6711 | configured with the line |
| 6712 | .display asis |
| 6713 | domains = +local_domains |
| 6714 | .endd |
| 6715 | The first router in a configuration is often one that handles all domains |
| 6716 | except the local ones, using a configuration with a negated item like this: |
| 6717 | .display asis |
| 6718 | dnslookup: |
| 6719 | driver = dnslookup |
| 6720 | domains = ! +local_domains |
| 6721 | transport = remote_smtp |
| 6722 | no_more |
| 6723 | .endd |
| 6724 | The four kinds of named list are created by configuration lines starting with |
| 6725 | the words \domainlist\, \hostlist\, \addresslist\, or \localpartlist\, |
| 6726 | respectively. Then there follows the name that you are defining, followed by an |
| 6727 | equals sign and the list itself. For example: |
| 6728 | .display asis |
| 6729 | hostlist relay_hosts = 192.168.23.0/24 : my.friend.example |
| 6730 | addresslist bad_senders = cdb;/etc/badsenders |
| 6731 | .endd |
| 6732 | A named list may refer to other named lists: |
| 6733 | .display asis |
| 6734 | domainlist dom1 = first.example : second.example |
| 6735 | domainlist dom2 = +dom1 : third.example |
| 6736 | domainlist dom3 = fourth.example : +dom2 : fifth.example |
| 6737 | .endd |
| 6738 | |
| 6739 | \**Warning**\: If the last item in a referenced list is a negative one, the |
| 6740 | effect may not be what you intended, because the negation does not propagate |
| 6741 | out to the higher level. For example, consider: |
| 6742 | .display asis |
| 6743 | domainlist dom1 = !a.b |
| 6744 | domainlist dom2 = +dom1 : *.b |
| 6745 | .endd |
| 6746 | The second list specifies `either in the \dom1\ list or \*@*.b*\'. The first |
| 6747 | list specifies just `not \*a.b*\', so the domain \*x.y*\ matches it. That means |
| 6748 | it matches the second list as well. The effect is not the same as |
| 6749 | .display asis |
| 6750 | domainlist dom2 = !a.b : *.b |
| 6751 | .endd |
| 6752 | where \*x.y*\ does not match. It's best to avoid negation altogether in |
| 6753 | referenced lists if you can. |
| 6754 | |
| 6755 | Named lists may have a performance advantage. When Exim is routing an |
| 6756 | address or checking an incoming message, it caches the result of tests on named |
| 6757 | lists. So, if you have a setting such as |
| 6758 | .display asis |
| 6759 | domains = +local_domains |
| 6760 | .endd |
| 6761 | on several of your routers |
| 6762 | or in several ACL statements, |
| 6763 | the actual test is done only for the first one. However, the caching works only |
| 6764 | if there are no expansions within the list itself or any sublists that it |
| 6765 | references. In other words, caching happens only for lists that are known to be |
| 6766 | the same each time they are referenced. |
| 6767 | |
| 6768 | By default, there may be up to 16 named lists of each type. This limit can be |
| 6769 | extended by changing a compile-time variable. The use of domain and host lists |
| 6770 | is recommended for concepts such as local domains, relay domains, and relay |
| 6771 | hosts. The default configuration is set up like this. |
| 6772 | |
| 6773 | |
| 6774 | .section Named lists compared with macros |
| 6775 | .index list||named compared with macro |
| 6776 | .index macro||compared with named list |
| 6777 | At first sight, named lists might seem to be no different from macros in the |
| 6778 | configuration file. However, macros are just textual substitutions. If you |
| 6779 | write |
| 6780 | .display asis |
| 6781 | ALIST = host1 : host2 |
| 6782 | auth_advertise_hosts = !ALIST |
| 6783 | .endd |
| 6784 | it probably won't do what you want, because that is exactly the same as |
| 6785 | .display asis |
| 6786 | auth_advertise_hosts = !host1 : host2 |
| 6787 | .endd |
| 6788 | Notice that the second host name is not negated. However, if you use a host |
| 6789 | list, and write |
| 6790 | .display asis |
| 6791 | hostlist alist = host1 : host2 |
| 6792 | auth_advertise_hosts = ! +alist |
| 6793 | .endd |
| 6794 | the negation applies to the whole list, and so that is equivalent to |
| 6795 | .display asis |
| 6796 | auth_advertise_hosts = !host1 : !host2 |
| 6797 | .endd |
| 6798 | |
| 6799 | |
| 6800 | .section Named list caching |
| 6801 | .index list||caching of named |
| 6802 | .index caching||named lists |
| 6803 | While processing a message, Exim caches the result of checking a named list if |
| 6804 | it is sure that the list is the same each time. In practice, this means that |
| 6805 | the cache operates only if the list contains no @$ characters, which guarantees |
| 6806 | that it will not change when it is expanded. Sometimes, however, you may have |
| 6807 | an expanded list that you know will be the same each time within a given |
| 6808 | message. For example: |
| 6809 | .display asis |
| 6810 | domainlist special_domains = \ |
| 6811 | ${lookup{$sender_host_address}cdb{/some/file}} |
| 6812 | .endd |
| 6813 | This provides a list of domains that depends only on the sending host's IP |
| 6814 | address. If this domain list is referenced a number of times (for example, |
| 6815 | in several ACL lines, or in several routers) the result of the check is not |
| 6816 | cached by default, because Exim does not know that it is going to be the |
| 6817 | same list each time. |
| 6818 | |
| 6819 | By appending \"@_cache"\ to \"domainlist"\ you can tell Exim to go ahead and |
| 6820 | cache the result anyway. For example: |
| 6821 | .display asis |
| 6822 | domainlist_cache special_domains = ${lookup{... |
| 6823 | .endd |
| 6824 | If you do this, you should be absolutely sure that caching is going to do |
| 6825 | the right thing in all cases. When in doubt, leave it out. |
| 6826 | |
| 6827 | |
| 6828 | .section Domain lists |
| 6829 | .rset SECTdomainlist "~~chapter.~~section" |
| 6830 | .index domain list||patterns for |
| 6831 | .index list||domain list |
| 6832 | Domain lists contain patterns that are to be matched against a mail domain. |
| 6833 | The following types of item may appear in domain lists: |
| 6834 | .numberpars $. |
| 6835 | .index primary host name |
| 6836 | .index host||name, matched in domain list |
| 6837 | .index \primary@_hostname\ |
| 6838 | .index domain list||matching primary host name |
| 6839 | .index @@ in a domain list |
| 6840 | If a pattern consists of a single @@ character, it matches the local host name, |
| 6841 | as set by the \primary@_hostname\ option (or defaulted). This makes it possible |
| 6842 | to use the same configuration file on several different hosts that differ only |
| 6843 | in their names. |
| 6844 | .nextp |
| 6845 | .index @@[] in a domain list |
| 6846 | .index domain list||matching local IP interfaces |
| 6847 | .index domain literal |
| 6848 | If a pattern consists of the string \"@@[]"\ it matches any local IP interface |
| 6849 | address, enclosed in square brackets, as in an email address that contains a |
| 6850 | domain literal. |
| 6851 | In today's Internet, the use of domain literals is controversial. |
| 6852 | .nextp |
| 6853 | .index @@mx@_any |
| 6854 | .index @@mx@_primary |
| 6855 | .index @@mx@_secondary |
| 6856 | .index domain list||matching MX pointers to local host |
| 6857 | If a pattern consists of the string \"@@mx@_any"\ it matches any domain that |
| 6858 | has an MX record pointing to the local host or to any host that is listed in |
| 6859 | .index \hosts@_treat@_as@_local\ |
| 6860 | \hosts@_treat@_as@_local\. The items \"@@mx@_primary"\ and \"@@mx@_secondary"\ |
| 6861 | are similar, except that the first matches only when a primary MX target is the |
| 6862 | local host, and the second only when no primary MX target is the local host, |
| 6863 | but a secondary MX target is. `Primary' means an MX record with the lowest |
| 6864 | preference value -- there may of course be more than one of them. |
| 6865 | |
| 6866 | The MX lookup that takes place when matching a pattern of this type is |
| 6867 | performed with the resolver options for widening names turned off. Thus, for |
| 6868 | example, a single-component domain will \*not*\ be expanded by adding the |
| 6869 | resolver's default domain. See the \qualify@_single\ and \search@_parents\ |
| 6870 | options of the \%dnslookup%\ router for a discussion of domain widening. |
| 6871 | |
| 6872 | Sometimes you may want to ignore certain IP addresses when using one of these |
| 6873 | patterns. You can specify this by following the pattern with \"/ignore=<<ip |
| 6874 | list>>"\, where <<ip list>> is a list of IP addresses. These addresses are |
| 6875 | ignored when processing the pattern (compare the \ignore@_target@_hosts\ option |
| 6876 | on a router). For example: |
| 6877 | .display asis |
| 6878 | domains = @mx_any/ignore=127.0.0.1 |
| 6879 | .endd |
| 6880 | This example matches any domain that has an MX record pointing to one of |
| 6881 | the local host's IP addresses other than 127.0.0.1. |
| 6882 | |
| 6883 | The list of IP addresses is in fact processed by the same code that processes |
| 6884 | host lists, so it may contain CIDR-coded network specifications and it may also |
| 6885 | contain negative items. |
| 6886 | |
| 6887 | Because the list of IP addresses is a sublist within a domain list, you have to |
| 6888 | be careful about delimiters if there is more than one address. Like any other |
| 6889 | list, the default delimiter can be changed. Thus, you might have: |
| 6890 | .display asis |
| 6891 | domains = @mx_any/ignore=<;127.0.0.1;0.0.0.0 : \ |
| 6892 | an.other.domain : ... |
| 6893 | .endd |
| 6894 | so that the sublist uses semicolons for delimiters. When IPv6 addresses are |
| 6895 | involved, it is easiest to change the delimiter for the main list as well: |
| 6896 | .display asis |
| 6897 | domains = <? @mx_any/ignore=<;127.0.0.1;::1 ? \ |
| 6898 | an.other.domain ? ... |
| 6899 | .endd |
| 6900 | |
| 6901 | .nextp |
| 6902 | .index asterisk||in domain list |
| 6903 | .index domain list||asterisk in |
| 6904 | .index domain list||matching `ends with' |
| 6905 | If a pattern starts with an asterisk, the remaining characters of the pattern |
| 6906 | are compared with the terminating characters of the domain. The use of `$*$' in |
| 6907 | domain lists differs from its use in partial matching lookups. In a domain |
| 6908 | list, the character following the asterisk need not be a dot, whereas partial |
| 6909 | matching works only in terms of dot-separated components. For example, a domain |
| 6910 | list item such as \"*key.ex"\ matches \*donkey.ex*\ as well as |
| 6911 | \*cipher.key.ex*\. |
| 6912 | .nextp |
| 6913 | .index regular expressions||in domain list |
| 6914 | .index domain list||matching regular expression |
| 6915 | If a pattern starts with a circumflex character, it is treated as a regular |
| 6916 | expression, and matched against the domain using a regular expression matching |
| 6917 | function. The circumflex is treated as part of the regular expression. |
| 6918 | References to descriptions of the syntax of regular expressions are given in |
| 6919 | chapter ~~CHAPregexp. |
| 6920 | |
| 6921 | \**Warning**\: Because domain lists are expanded before being processed, you |
| 6922 | must escape any backslash and dollar characters in the regular expression, or |
| 6923 | use the special \"@\N"\ sequence (see chapter ~~CHAPexpand) to specify that it |
| 6924 | is not to be expanded (unless you really do want to build a regular expression |
| 6925 | by expansion, of course). |
| 6926 | .nextp |
| 6927 | .index lookup||in domain list |
| 6928 | .index domain list||matching by lookup |
| 6929 | If a pattern starts with the name of a single-key lookup type followed by a |
| 6930 | semicolon (for example, `dbm;' or `lsearch;'), the remainder of the pattern |
| 6931 | must be a file name in a suitable format for the lookup type. For example, for |
| 6932 | `cdb;' it must be an absolute path: |
| 6933 | .display asis |
| 6934 | domains = cdb;/etc/mail/local_domains.cdb |
| 6935 | .endd |
| 6936 | The appropriate type of lookup is done on the file using the domain name as the |
| 6937 | key. In most cases, the data that is looked up is not used; Exim is interested |
| 6938 | only in whether or not the key is present in the file. However, when a lookup |
| 6939 | is used for the \domains\ option on a router |
| 6940 | or a \domains\ condition in an ACL statement, the data is preserved in the |
| 6941 | \$domain@_data$\ variable and can be referred to in other router options or |
| 6942 | other statements in the same ACL. |
| 6943 | .nextp |
| 6944 | Any of the single-key lookup type names may be preceded by `partial<<n>>-', |
| 6945 | where the <<n>> is optional, for example, |
| 6946 | .display asis |
| 6947 | domains = partial-dbm;/partial/domains |
| 6948 | .endd |
| 6949 | This causes partial matching logic to be invoked; a description of how this |
| 6950 | works is given in section ~~SECTpartiallookup. |
| 6951 | .nextp |
| 6952 | .index asterisk||in lookup type |
| 6953 | Any of the single-key lookup types may be followed by an asterisk. This causes |
| 6954 | a default lookup for a key consisting of a single asterisk to be done if the |
| 6955 | original lookup fails. This is not a useful feature when using a domain list to |
| 6956 | select particular domains (because any domain would match), but it might have |
| 6957 | value if the result of the lookup is being used via the \$domain@_data$\ |
| 6958 | expansion variable. |
| 6959 | .nextp |
| 6960 | If the pattern starts with the name of a query-style lookup type followed by a |
| 6961 | semicolon (for example, `nisplus;' or `ldap;'), the remainder of the pattern |
| 6962 | must be an appropriate query for the lookup type, as described in chapter |
| 6963 | ~~CHAPfdlookup. For example: |
| 6964 | .display asis |
| 6965 | hold_domains = mysql;select domain from holdlist \ |
| 6966 | where domain = '$domain'; |
| 6967 | .endd |
| 6968 | In most cases, the data that is looked up is not used (so for an SQL query, for |
| 6969 | example, it doesn't matter what field you select). Exim is interested only in |
| 6970 | whether or not the query succeeds. However, when a lookup is used for the |
| 6971 | \domains\ option on a router, the data is preserved in the \$domain@_data$\ |
| 6972 | variable and can be referred to in other options. |
| 6973 | .nextp |
| 6974 | .index domain list||matching literal domain name |
| 6975 | If none of the above cases apply, a caseless textual comparison is made between |
| 6976 | the pattern and the domain. |
| 6977 | .endp |
| 6978 | |
| 6979 | Here is an example that uses several different kinds of pattern: |
| 6980 | .display asis |
| 6981 | domainlist funny_domains = \ |
| 6982 | @ : \ |
| 6983 | lib.unseen.edu : \ |
| 6984 | *.foundation.fict.example : \ |
| 6985 | \N^[1-2]\d{3}\.fict\.example$\N : \ |
| 6986 | partial-dbm;/opt/data/penguin/book : \ |
| 6987 | nis;domains.byname : \ |
| 6988 | nisplus;[name=$domain,status=local],domains.org_dir |
| 6989 | .endd |
| 6990 | There are obvious processing trade-offs among the various matching modes. Using |
| 6991 | an asterisk is faster than a regular expression, and listing a few names |
| 6992 | explicitly probably is too. The use of a file or database lookup is expensive, |
| 6993 | but may be the only option if hundreds of names are required. Because the |
| 6994 | patterns are tested in order, it makes sense to put the most commonly matched |
| 6995 | patterns earlier. |
| 6996 | |
| 6997 | |
| 6998 | .section Host lists |
| 6999 | .rset SECThostlist "~~chapter.~~section" |
| 7000 | .index host list||patterns in |
| 7001 | .index list||host list |
| 7002 | Host lists are used to control what remote hosts are allowed to do. For |
| 7003 | example, some hosts may be allowed to use the local host as a relay, and some |
| 7004 | may be permitted to use the SMTP \\ETRN\\ command. Hosts can be identified in |
| 7005 | two different ways, by name or by IP address. In a host list, some types of |
| 7006 | pattern are matched to a host name, and some are matched to an IP address. |
| 7007 | You need to be particularly careful with this when single-key lookups are |
| 7008 | involved, to ensure that the right value is being used as the key. |
| 7009 | |
| 7010 | .section Special host list patterns |
| 7011 | .index empty item in hosts list |
| 7012 | .index host list||empty string in |
| 7013 | If a host list item is the empty string, it matches only when no remote host is |
| 7014 | involved. This is the case when a message is being received from a local |
| 7015 | process using SMTP on the standard input, that is, when a TCP/IP connection is |
| 7016 | not used. |
| 7017 | |
| 7018 | .index asterisk||in host list |
| 7019 | The special pattern `$*$' in a host list matches any host or no host. Neither |
| 7020 | the IP address nor the name is actually inspected. |
| 7021 | |
| 7022 | |
| 7023 | .section Host list patterns that match by IP address |
| 7024 | .rset SECThoslispatip "~~chapter.~~section" |
| 7025 | .index host list||matching IP addresses |
| 7026 | If an IPv4 host calls an IPv6 host and the call is accepted on an IPv6 socket, |
| 7027 | the incoming address actually appears in the IPv6 host as |
| 7028 | `@:@:$tt{ffff}:<<v4address>>'. When such an address is tested against a host |
| 7029 | list, it is converted into a traditional IPv4 address first. (Not all operating |
| 7030 | systems accept IPv4 calls on IPv6 sockets, as there have been some security |
| 7031 | concerns.) |
| 7032 | |
| 7033 | The following types of pattern in a host list check the remote host by |
| 7034 | inspecting its IP address: |
| 7035 | .numberpars $. |
| 7036 | If the pattern is a plain domain name (not a regular expression, not starting |
| 7037 | with $*$, not a lookup of any kind), Exim calls the operating system function |
| 7038 | to find the associated IP address(es). Exim uses the newer |
| 7039 | \*getipnodebyname()*\ function when available, otherwise \*gethostbyname()*\. |
| 7040 | This typically causes a forward DNS lookup of the name. The result is compared |
| 7041 | with the IP address of the subject host. |
| 7042 | |
| 7043 | If there is a temporary problem (such as a DNS timeout) with the host name |
| 7044 | lookup, a temporary error occurs. For example, if the list is being used in an |
| 7045 | ACL condition, the ACL gives a `defer' response, usually leading to a temporary |
| 7046 | SMTP error code. If no IP address can be found for the host name, what happens |
| 7047 | is described in section ~~SECTbehipnot below. |
| 7048 | |
| 7049 | .nextp |
| 7050 | .index @@ in a host list |
| 7051 | If the pattern is `@@', the primary host name is substituted and used as a |
| 7052 | domain name, as just described. |
| 7053 | .nextp |
| 7054 | If the pattern is an IP address, it is matched against the IP address of the |
| 7055 | subject host. IPv4 addresses are given in the normal `dotted-quad' notation. |
| 7056 | IPv6 addresses can be given in colon-separated format, but the colons have to |
| 7057 | be doubled so as not to be taken as item separators when the default list |
| 7058 | separator is used. IPv6 addresses are recognized even when Exim is compiled |
| 7059 | without IPv6 support. This means that if they appear in a host list on an |
| 7060 | IPv4-only host, Exim will not treat them as host names. They are just addresses |
| 7061 | that can never match a client host. |
| 7062 | .nextp |
| 7063 | .index @@[] in a host list |
| 7064 | If the pattern is `@@[]', it matches the IP address of any IP interface on |
| 7065 | the local host. For example, if the local host is an IPv4 host with one |
| 7066 | interface address 10.45.23.56, these two ACL statements have the same effect: |
| 7067 | .display asis |
| 7068 | accept hosts = 127.0.0.1 : 10.45.23.56 |
| 7069 | accept hosts = @[] |
| 7070 | .endd |
| 7071 | .nextp |
| 7072 | If the pattern is an IP address followed by a slash and a mask length (for |
| 7073 | example 10.11.42.0/24), it is matched against the IP address of the subject |
| 7074 | host under the given mask. |
| 7075 | This allows, an entire network of hosts to be included (or excluded) by a |
| 7076 | single item. |
| 7077 | .index CIDR notation |
| 7078 | The mask uses CIDR notation; it specifies the number of address bits that must |
| 7079 | match, starting from the most significant end of the address. |
| 7080 | |
| 7081 | \**Note**\: the mask is \*not*\ a count of addresses, nor is it the high number |
| 7082 | of a range of addresses. It is the number of bits in the network portion of the |
| 7083 | address. The above example specifies a 24-bit netmask, so it matches all 256 |
| 7084 | addresses in the 10.11.42.0 network. An item such as |
| 7085 | .display asis |
| 7086 | 192.168.23.236/31 |
| 7087 | .endd |
| 7088 | matches just two addresses, 192.168.23.236 and 192.168.23.237. A mask value of |
| 7089 | 32 for an IPv4 address is the same as no mask at all; just a single address |
| 7090 | matches. |
| 7091 | |
| 7092 | Here is another example which shows an IPv4 and an IPv6 network: |
| 7093 | .display asis |
| 7094 | recipient_unqualified_hosts = 192.168.0.0/16: \ |
| 7095 | 3ffe::ffff::836f::::/48 |
| 7096 | .endd |
| 7097 | The doubling of list separator characters applies only when these items |
| 7098 | appear inline in a host list. It is not required when indirecting via a file. |
| 7099 | For example, |
| 7100 | .display asis |
| 7101 | recipient_unqualified_hosts = /opt/exim/unqualnets |
| 7102 | .endd |
| 7103 | could make use of a file containing |
| 7104 | .display asis |
| 7105 | 172.16.0.0/12 |
| 7106 | 3ffe:ffff:836f::/48 |
| 7107 | .endd |
| 7108 | to have exactly the same effect as the previous example. When listing IPv6 |
| 7109 | addresses inline, it is usually more convenient to use the facility for |
| 7110 | changing separator characters. This list contains the same two networks: |
| 7111 | .display asis |
| 7112 | recipient_unqualified_hosts = <; 172.16.0.0/12; \ |
| 7113 | 3ffe:ffff:836f::/48 |
| 7114 | .endd |
| 7115 | The separator is changed to semicolon by the leading `<;' at the start of the |
| 7116 | list. |
| 7117 | .endp |
| 7118 | |
| 7119 | |
| 7120 | .section Host list patterns for single-key lookups by host address |
| 7121 | .rset SECThoslispatsikey "~~chapter.~~section" |
| 7122 | .index host list||lookup of IP address |
| 7123 | When a host is to be identified by a single-key lookup of its complete IP |
| 7124 | address, the pattern takes this form: |
| 7125 | .display |
| 7126 | net-<<single-key-search-type>>;<<search-data>> |
| 7127 | .endd |
| 7128 | For example: |
| 7129 | .display asis |
| 7130 | hosts_lookup = net-cdb;/hosts-by-ip.db |
| 7131 | .endd |
| 7132 | The text form of the IP address of the subject host is used as the lookup key. |
| 7133 | IPv6 addresses are converted to an unabbreviated form, using lower case |
| 7134 | letters, with dots as separators because colon is the key terminator in |
| 7135 | \%lsearch%\ files. [Colons can in fact be used in keys in \%lsearch%\ files by |
| 7136 | quoting the keys, but this is a facility that was added later.] The data |
| 7137 | returned by the lookup is not used. |
| 7138 | |
| 7139 | .index IP address||masking |
| 7140 | .index host list||masked IP address |
| 7141 | Single-key lookups can also be performed using masked IP addresses, using |
| 7142 | patterns of this form: |
| 7143 | .display |
| 7144 | net<<number>>-<<single-key-search-type>>;<<search-data>> |
| 7145 | .endd |
| 7146 | For example: |
| 7147 | .display asis |
| 7148 | net24-dbm;/networks.db |
| 7149 | .endd |
| 7150 | The IP address of the subject host is masked using <<number>> as the mask |
| 7151 | length. A textual string is constructed from the masked value, followed by the |
| 7152 | mask, and this is used as the lookup key. For example, if the host's IP address |
| 7153 | is 192.168.34.6, the key that is looked up for the above example is |
| 7154 | `192.168.34.0/24'. IPv6 addresses are converted to a text value using lower |
| 7155 | case letters and dots as separators instead of the more usual colon, because |
| 7156 | colon is the key terminator in \%lsearch%\ files. Full, unabbreviated IPv6 |
| 7157 | addresses are always used. |
| 7158 | |
| 7159 | \**Warning**\: Specifing \net32@-\ (for an IPv4 address) or \net128@-\ (for an |
| 7160 | IPv6 address) is not the same as specifing just \net@-\ without a number. In |
| 7161 | the former case the key strings include the mask value, whereas in the latter |
| 7162 | case the IP address is used on its own. |
| 7163 | |
| 7164 | |
| 7165 | .section Host list patterns that match by host name |
| 7166 | .rset SECThoslispatnam "~~chapter.~~section" |
| 7167 | .index host||lookup failures |
| 7168 | .index unknown host name |
| 7169 | .index host list||matching host name |
| 7170 | There are several types of pattern that require Exim to know the name of the |
| 7171 | remote host. These are either wildcard patterns or lookups by name. (If a |
| 7172 | complete hostname is given without any wildcarding, it is used to find an IP |
| 7173 | address to match against, as described in the section ~~SECThoslispatip above.) |
| 7174 | |
| 7175 | If the remote host name is not already known when Exim encounters one of these |
| 7176 | patterns, it has to be found from the IP address. |
| 7177 | Although many sites on the Internet are conscientious about maintaining reverse |
| 7178 | DNS data for their hosts, there are also many that do not do this. |
| 7179 | Consequently, a name cannot always be found, and this may lead to unwanted |
| 7180 | effects. Take care when configuring host lists with wildcarded name patterns. |
| 7181 | Consider what will happen if a name cannot be found. |
| 7182 | |
| 7183 | Because of the problems of determining host names from IP addresses, matching |
| 7184 | against host names is not as common as matching against IP addresses. |
| 7185 | |
| 7186 | By default, in order to find a host name, Exim first does a reverse DNS lookup; |
| 7187 | if no name is found in the DNS, the system function (\*gethostbyaddr()*\ or |
| 7188 | \*getipnodebyaddr()*\ if available) is tried. The order in which these lookups |
| 7189 | are done can be changed by setting the \host@_lookup@_order\ option. |
| 7190 | |
| 7191 | There are some options that control what happens if a host name cannot be |
| 7192 | found. These are described in section ~~SECTbehipnot below. |
| 7193 | |
| 7194 | |
| 7195 | .index host||alias for |
| 7196 | .index alias for host |
| 7197 | As a result of aliasing, hosts may have more than one name. When processing any |
| 7198 | of the following types of pattern, all the host's names are checked: |
| 7199 | .numberpars $. |
| 7200 | .index asterisk||in host list |
| 7201 | If a pattern starts with `$*$' the remainder of the item must match the end of |
| 7202 | the host name. For example, \"*.b.c"\ matches all hosts whose names end in |
| 7203 | \*.b.c*\. This special simple form is provided because this is a very common |
| 7204 | requirement. Other kinds of wildcarding require the use of a regular |
| 7205 | expression. |
| 7206 | .nextp |
| 7207 | .index regular expressions||in host list |
| 7208 | .index host list||regular expression in |
| 7209 | If the item starts with `@^' it is taken to be a regular expression which is |
| 7210 | matched against the host name. For example, |
| 7211 | .display asis |
| 7212 | ^(a|b)\.c\.d$ |
| 7213 | .endd |
| 7214 | is a regular expression that matches either of the two hosts \*a.c.d*\ or |
| 7215 | \*b.c.d*\. When a regular expression is used in a host list, you must take care |
| 7216 | that backslash and dollar characters are not misinterpreted as part of the |
| 7217 | string expansion. The simplest way to do this is to use \"@\N"\ to mark that |
| 7218 | part of the string as non-expandable. For example: |
| 7219 | .display asis |
| 7220 | sender_unqualified_hosts = \N^(a|b)\.c\.d$\N : .... |
| 7221 | .endd |
| 7222 | \**Warning**\: If you want to match a complete host name, you must include the |
| 7223 | \"@$"\ terminating metacharacter in the regular expression, as in the above |
| 7224 | example. Without it, a match at the start of the host name is all that is |
| 7225 | required. |
| 7226 | .endp |
| 7227 | |
| 7228 | |
| 7229 | .section Behaviour when an IP address or name cannot be found |
| 7230 | .rset SECTbehipnot "~~chapter.~~section" |
| 7231 | .index host||lookup failures |
| 7232 | While processing a host list, Exim may need to look up an IP address from a |
| 7233 | name (see section ~~SECThoslispatip), or it may need to look up a host name |
| 7234 | from an IP address (see section ~~SECThoslispatnam). In either case, the |
| 7235 | behaviour when it fails to find the information it is seeking is the same. |
| 7236 | |
| 7237 | .index \"+include@_unknown"\ |
| 7238 | .index \"+ignore@_unknown"\ |
| 7239 | By default, Exim behaves as if the host does not match the list. This may not |
| 7240 | always be what you want to happen. To change Exim's behaviour, the special |
| 7241 | items \"+include@_unknown"\ or \"+ignore@_unknown"\ may appear in the list (at |
| 7242 | top level -- they are not recognized in an indirected file). |
| 7243 | .numberpars $. |
| 7244 | If any item that follows \"+include@_unknown"\ requires information that |
| 7245 | cannot found, Exim behaves as if the host does match the list. For example, |
| 7246 | .display asis |
| 7247 | host_reject_connection = +include_unknown:*.enemy.ex |
| 7248 | .endd |
| 7249 | rejects connections from any host whose name matches \"*.enemy.ex"\, and also |
| 7250 | any hosts whose name it cannot find. |
| 7251 | .nextp |
| 7252 | If any item that follows \"+ignore@_unknown"\ requires information that cannot |
| 7253 | be found, Exim ignores that item and proceeds to the rest of the list. For |
| 7254 | example: |
| 7255 | .display asis |
| 7256 | accept hosts = +ignore_unknown : friend.example : \ |
| 7257 | 192.168.4.5 |
| 7258 | .endd |
| 7259 | accepts from any host whose name is \*friend.example*\ and from 192.168.4.5, |
| 7260 | whether or not its host name can be found. Without \"+ignore@_unknown"\, if no |
| 7261 | name can be found for 192.168.4.5, it is rejected. |
| 7262 | .endp |
| 7263 | Both \"+include@_unknown"\ and \"+ignore@_unknown"\ may appear in the same |
| 7264 | list. The effect of each one lasts until the next, or until the end of the |
| 7265 | list. |
| 7266 | |
| 7267 | \**Note**\: This section applies to permanent lookup failures. It does \*not*\ |
| 7268 | apply to temporary DNS errors. They always cause a defer action. |
| 7269 | |
| 7270 | |
| 7271 | .section Host list patterns for single-key lookups by host name |
| 7272 | .rset SECThoslispatnamsk "~~chapter.~~section" |
| 7273 | .index host||lookup failures |
| 7274 | .index unknown host name |
| 7275 | .index host list||matching host name |
| 7276 | If a pattern is of the form |
| 7277 | .display |
| 7278 | <<single-key-search-type>>;<<search-data>> |
| 7279 | .endd |
| 7280 | for example |
| 7281 | .display asis |
| 7282 | dbm;/host/accept/list |
| 7283 | .endd |
| 7284 | a single-key lookup is performend, using the host name as its key. If the |
| 7285 | lookup succeeds, the host matches the item. The actual data that is looked up |
| 7286 | is not used. |
| 7287 | |
| 7288 | \**Reminder**\: With this kind of pattern, you must have host $it{names} as |
| 7289 | keys in the file, not IP addresses. If you want to do lookups based on IP |
| 7290 | addresses, you must precede the search type with `net-' (see section |
| 7291 | ~~SECThoslispatsikey). There is, however, no reason why you could not use two |
| 7292 | items in the same list, one doing an address lookup and one doing a name |
| 7293 | lookup, both using the same file. |
| 7294 | |
| 7295 | |
| 7296 | .section Host list patterns for query-style lookups |
| 7297 | If a pattern is of the form |
| 7298 | .display |
| 7299 | <<query-style-search-type>>;<<query>> |
| 7300 | .endd |
| 7301 | the query is obeyed, and if it succeeds, the host matches the item. The actual |
| 7302 | data that is looked up is not used. The variables \$sender@_host@_address$\ and |
| 7303 | \$sender@_host@_name$\ can be used in the query. For example: |
| 7304 | .display asis |
| 7305 | hosts_lookup = pgsql;\ |
| 7306 | select ip from hostlist where ip='$sender_host_address' |
| 7307 | .endd |
| 7308 | The value of \$sender@_host@_address$\ for an IPv6 address uses colon |
| 7309 | separators. You can use the \sg\ expansion item to change this if you need to. |
| 7310 | If you want to use masked IP addresses in database queries, you can use the |
| 7311 | \mask\ expansion operator. |
| 7312 | |
| 7313 | If the query contains a reference to \$sender@_host@_name$\, Exim automatically |
| 7314 | looks up the host name if has not already done so. (See section |
| 7315 | ~~SECThoslispatnam for comments on finding host names.) |
| 7316 | |
| 7317 | Historical note: prior to release 4.30, Exim would always attempt to find a |
| 7318 | host name before running the query, unless the search type was preceded by |
| 7319 | \"net-"\. This is no longer the case. For backwards compatibility, \"net-"\ is |
| 7320 | still recognized for query-style lookups, but its presence or absence has no |
| 7321 | effect. (Of course, for single-key lookups, \"net-"\ $it{is} important.) |
| 7322 | |
| 7323 | |
| 7324 | .section Mixing wildcarded host names and addresses in host lists |
| 7325 | .rset SECTmixwilhos "~~chapter.~~section" |
| 7326 | .index host list||mixing names and addresses in |
| 7327 | If you have name lookups or wildcarded host names and IP addresses in the same |
| 7328 | host list, you should normally put the IP addresses first. For example, in an |
| 7329 | ACL you could have: |
| 7330 | .display asis |
| 7331 | accept hosts = 10.9.8.7 : *.friend.example |
| 7332 | .endd |
| 7333 | The reason for this lies in the left-to-right way that Exim processes lists. |
| 7334 | It can test IP addresses without doing any DNS lookups, but when it reaches an |
| 7335 | item that requires a host name, it fails if it cannot find a host name to |
| 7336 | compare with the pattern. If the above list is given in the opposite order, the |
| 7337 | \accept\ statement fails for a host whose name cannot be found, even if its |
| 7338 | IP address is 10.9.8.7. |
| 7339 | |
| 7340 | If you really do want to do the name check first, and still recognize the IP |
| 7341 | address, you can rewrite the ACL like this: |
| 7342 | .display asis |
| 7343 | accept hosts = *.friend.example |
| 7344 | accept hosts = 10.9.8.7 |
| 7345 | .endd |
| 7346 | If the first \accept\ fails, Exim goes on to try the second one. See chapter |
| 7347 | ~~CHAPACL for details of ACLs. |
| 7348 | |
| 7349 | |
| 7350 | |
| 7351 | |
| 7352 | .section Address lists |
| 7353 | .index list||address list |
| 7354 | .index address list||empty item |
| 7355 | .index address list||patterns |
| 7356 | .rset SECTaddresslist "~~chapter.~~section" |
| 7357 | Address lists contain patterns that are matched against mail addresses. There |
| 7358 | is one special case to be considered: the sender address of a bounce message is |
| 7359 | always empty. You can test for this by providing an empty item in an address |
| 7360 | list. For example, you can set up a router to process bounce messages by |
| 7361 | using this option setting: |
| 7362 | .display asis |
| 7363 | senders = : |
| 7364 | .endd |
| 7365 | The presence of the colon creates an empty item. If you do not provide any |
| 7366 | data, the list is empty and matches nothing. The empty sender can also be |
| 7367 | detected by a regular expression that matches an empty string. |
| 7368 | |
| 7369 | The following kinds of pattern are supported in address lists: |
| 7370 | .numberpars $. |
| 7371 | .index regular expressions||in address list |
| 7372 | .index address list||regular expression in |
| 7373 | If (after expansion) a pattern starts with `@^', a regular expression match is |
| 7374 | done against the complete address, with the pattern as the regular expression. |
| 7375 | You must take care that backslash and dollar characters are not misinterpreted |
| 7376 | as part of the string expansion. The simplest way to do this is to use \"@\N"\ |
| 7377 | to mark that part of the string as non-expandable. For example: |
| 7378 | .display asis |
| 7379 | deny senders = \N^\d{8}.+@spamhaus.example$\N : ... |
| 7380 | .endd |
| 7381 | The \"@\N"\ sequences are removed by the expansion, so the item does start |
| 7382 | with `@^' by the time it is being interpreted as an address pattern. |
| 7383 | .nextp |
| 7384 | .index @@@@ with single-key lookup |
| 7385 | .index address list||@@@@ lookup type |
| 7386 | .index address list||split local part and domain |
| 7387 | If a pattern starts with `@@@@' followed by a single-key lookup item |
| 7388 | (for example, \"@@@@lsearch;/some/file"\), the address that is being checked is |
| 7389 | split into a local part and a domain. The domain is looked up in the file. If |
| 7390 | it is not found, there is no match. If it is found, the data that is looked up |
| 7391 | from the file is treated as a colon-separated list of local part patterns, each |
| 7392 | of which is matched against the subject local part in turn. |
| 7393 | |
| 7394 | .index asterisk||in address list |
| 7395 | The lookup may be a partial one, and/or one involving a search for a default |
| 7396 | keyed by `$*$' (see section ~~SECTdefaultvaluelookups). The local part patterns |
| 7397 | that are looked up can be regular expressions or begin with `$*$', or even be |
| 7398 | further lookups. They may also be independently negated. For example, with |
| 7399 | .display asis |
| 7400 | deny senders = @@dbm;/etc/reject-by-domain |
| 7401 | .endd |
| 7402 | the data from which the DBM file is built could contain lines like |
| 7403 | .display asis |
| 7404 | baddomain.com: !postmaster : * |
| 7405 | .endd |
| 7406 | to reject all senders except \postmaster\ from that domain. |
| 7407 | .index local part||starting with ! |
| 7408 | If a local part that actually begins with an exclamation mark is required, it |
| 7409 | has to be specified using a regular expression. In \%lsearch%\ files, an entry |
| 7410 | may be split over several lines by indenting the second and subsequent lines, |
| 7411 | but the separating colon must still be included at line breaks. White space |
| 7412 | surrounding the colons is ignored. For example: |
| 7413 | .display asis |
| 7414 | aol.com: spammer1 : spammer2 : ^[0-9]+$ : |
| 7415 | spammer3 : spammer4 |
| 7416 | .endd |
| 7417 | As in all colon-separated lists in Exim, a colon can be included in an item by |
| 7418 | doubling. |
| 7419 | |
| 7420 | If the last item in the list starts with a right angle-bracket, the remainder |
| 7421 | of the item is taken as a new key to look up in order to obtain a continuation |
| 7422 | list of local parts. The new key can be any sequence of characters. Thus one |
| 7423 | might have entries like |
| 7424 | .display asis |
| 7425 | aol.com: spammer1 : spammer 2 : >* |
| 7426 | xyz.com: spammer3 : >* |
| 7427 | *: ^\d{8}$ |
| 7428 | .endd |
| 7429 | in a file that was searched with \@@@@dbm$*$\, to specify a match for 8-digit |
| 7430 | local parts for all domains, in addition to the specific local parts listed for |
| 7431 | each domain. Of course, using this feature costs another lookup each time a |
| 7432 | chain is followed, but the effort needed to maintain the data is reduced. |
| 7433 | .index loop||in lookups |
| 7434 | It is possible to construct loops using this facility, and in order to catch |
| 7435 | them, the chains may be no more than fifty items long. |
| 7436 | .nextp |
| 7437 | The @@@@<<lookup>> style of item can also be used with a query-style |
| 7438 | lookup, but in this case, the chaining facility is not available. The lookup |
| 7439 | can only return a single list of local parts. |
| 7440 | .nextp |
| 7441 | .index address list||lookup for complete address |
| 7442 | Complete addresses can be looked up by using a pattern that |
| 7443 | starts with a lookup type terminated by a semicolon, follwed by the data for |
| 7444 | the lookup. |
| 7445 | For example: |
| 7446 | .display asis |
| 7447 | deny senders = cdb;/etc/blocked.senders : \ |
| 7448 | mysql;select address from blocked where \ |
| 7449 | address='${quote_mysql:$sender_address}' |
| 7450 | .endd |
| 7451 | For a single-key lookup type, Exim uses the complete address as the key. |
| 7452 | Partial matching (section ~~SECTpartiallookup) cannot be used, and is ignored |
| 7453 | if specified, with an entry being written to the panic log. |
| 7454 | |
| 7455 | .index @*@@ with single-key lookup |
| 7456 | You can configure lookup defaults, as described in section |
| 7457 | ~~SECTdefaultvaluelookups, but this is useful only for the `$*$@@' type of |
| 7458 | default. For example, with this lookup: |
| 7459 | .display asis |
| 7460 | accept senders = lsearch*@;/some/file |
| 7461 | .endd |
| 7462 | the file could contains lines like this: |
| 7463 | .display asis |
| 7464 | user1@domain1.example |
| 7465 | *@domain2.example |
| 7466 | .endd |
| 7467 | and for the sender address \*nimrod@@jaeger.example*\, the sequence of keys |
| 7468 | that are tried is: |
| 7469 | .display asis |
| 7470 | nimrod@jaeger.example |
| 7471 | *@jaeger.example |
| 7472 | * |
| 7473 | .endd |
| 7474 | \**Warning 1**\: Do not include a line keyed by `$*$' in the file, because that |
| 7475 | would mean that every address matches, thus rendering the test useless. |
| 7476 | |
| 7477 | \**Warning 2**\: Do not confuse these two kinds of item: |
| 7478 | .display asis |
| 7479 | deny recipients = dbm*@;/some/file |
| 7480 | deny recipients = *@dbm;/some/file |
| 7481 | .endd |
| 7482 | The first does a whole address lookup, with defaulting, as just described, |
| 7483 | because it starts with a lookup type. The second matches the local part and |
| 7484 | domain independently, as described in the next paragraph. |
| 7485 | .nextp |
| 7486 | If a pattern contains an @@ character, but is not a regular expression |
| 7487 | and does not begin with a lookup type |
| 7488 | as described above, the local part of the subject address is compared with the |
| 7489 | local part of the pattern, which may start with an asterisk. If the local parts |
| 7490 | match, the domain is checked in exactly the same way as for a pattern in a |
| 7491 | domain list. For example, the domain can be wildcarded, refer to a named list, |
| 7492 | or be a lookup: |
| 7493 | .display asis |
| 7494 | deny senders = *@*.spamming.site:\ |
| 7495 | *@+hostile_domains:\ |
| 7496 | bozo@partial-lsearch;/list/of/dodgy/sites:\ |
| 7497 | .newline |
| 7498 | *@dbm;/bad/domains.db |
| 7499 | .endd |
| 7500 | .index local part||starting with ! |
| 7501 | .index address list||local part starting with ! |
| 7502 | If a local part that begins with an exclamation mark is required, it has to be |
| 7503 | specified using a regular expression, because otherwise the exclamation mark is |
| 7504 | treated as a sign of negation. |
| 7505 | .nextp |
| 7506 | If a pattern is not one of the above syntax forms, that is, if a pattern which |
| 7507 | is not a regular expression or a lookup does not contain an @@ character, it is |
| 7508 | matched against the domain part of the subject address. The only two formats |
| 7509 | that are recognized this way are a literal domain, or a domain pattern that |
| 7510 | starts with $*$. In both these cases, the effect is the same as if \"*@@"\ |
| 7511 | preceded the pattern. |
| 7512 | .endp |
| 7513 | |
| 7514 | \**Warning**\: there is an important difference between the address list items |
| 7515 | in these two examples: |
| 7516 | .display asis |
| 7517 | senders = +my_list |
| 7518 | senders = *@+my_list |
| 7519 | .endd |
| 7520 | In the first one, \"my@_list"\ is a named address list, whereas in the second |
| 7521 | example it is a named domain list. |
| 7522 | |
| 7523 | |
| 7524 | |
| 7525 | .section Case of letters in address lists |
| 7526 | .rset SECTcasletadd "~~chapter.~~section" |
| 7527 | .index case of local parts |
| 7528 | .index address list||case forcing |
| 7529 | .index case forcing in address lists |
| 7530 | Domains in email addresses are always handled caselessly, but for local parts |
| 7531 | case may be significant on some systems (see \caseful@_local@_part\ for how |
| 7532 | Exim deals with this when routing addresses). However, RFC 2505 ($it{Anti-Spam |
| 7533 | Recommendations for SMTP MTAs}) suggests that matching of addresses to blocking |
| 7534 | lists should be done in a case-independent manner. Since most address lists in |
| 7535 | Exim are used for this kind of control, Exim attempts to do this by default. |
| 7536 | |
| 7537 | The domain portion of an address is always lowercased before matching it to an |
| 7538 | address list. The local part is lowercased by default, and any string |
| 7539 | comparisons that take place are done caselessly. This means that the data in |
| 7540 | the address list itself, in files included as plain file names, and in any file |
| 7541 | that is looked up using the `@@@@' mechanism, can be in any case. However, the |
| 7542 | keys in files that are looked up by a search type other than \%lsearch%\ (which |
| 7543 | works caselessly) must be in lower case, because these lookups are not |
| 7544 | case-independent. |
| 7545 | |
| 7546 | .index \"+caseful"\ |
| 7547 | To allow for the possibility of caseful address list matching, if an item in |
| 7548 | an address list is the string `+caseful', the original case of the local |
| 7549 | part is restored for any comparisons that follow, and string comparisons are no |
| 7550 | longer case-independent. This does not affect the domain, which remains in |
| 7551 | lower case. However, although independent matches on the domain alone are still |
| 7552 | performed caselessly, regular expressions that match against an entire address |
| 7553 | become case-sensitive after `+caseful' has been seen. |
| 7554 | |
| 7555 | |
| 7556 | .section Local part lists |
| 7557 | .rset SECTlocparlis "~~chapter.~~section" |
| 7558 | .index list||local part list |
| 7559 | .index local part||list |
| 7560 | Case-sensitivity in local part lists is handled in the same way as for address |
| 7561 | lists, as just described. The `+caseful' item can be used if required. In a |
| 7562 | setting of the \local@_parts\ option in a router with \caseful@_local@_part\ |
| 7563 | set false, the subject is lowercased and the matching is initially |
| 7564 | case-insensitive. In this case, `+caseful' will restore case-sensitive matching |
| 7565 | in the local part list, but not elsewhere in the router. If |
| 7566 | \caseful@_local@_part\ is set true in a router, matching in the \local@_parts\ |
| 7567 | option is case-sensitive from the start. |
| 7568 | |
| 7569 | If a local part list is indirected to a file (see section ~~SECTfilnamlis), |
| 7570 | comments are handled in the same way as address lists -- they are recognized |
| 7571 | only if the @# is preceded by white space or the start of the line. |
| 7572 | Otherwise, local part lists are matched in the same way as domain lists, except |
| 7573 | that the special items that refer to the local host (\"@@"\, \"@@[]"\, |
| 7574 | \"@@mx@_any"\, \"@@mx@_primary"\, and \"@@mx@_secondary"\) are not recognized. |
| 7575 | Refer to section ~~SECTdomainlist for details of the other available item |
| 7576 | types. |
| 7577 | |
| 7578 | |
| 7579 | |
| 7580 | . |
| 7581 | . |
| 7582 | . |
| 7583 | . |
| 7584 | . ============================================================================ |
| 7585 | .chapter String expansions |
| 7586 | .set runningfoot "string expansions" |
| 7587 | .rset CHAPexpand ~~chapter |
| 7588 | .index expansion||of strings |
| 7589 | Many strings in Exim's run time configuration are expanded before use. Some of |
| 7590 | them are expanded every time they are used; others are expanded only once. |
| 7591 | |
| 7592 | When a string is being expanded it is copied verbatim from left to right except |
| 7593 | when a dollar or backslash character is encountered. A dollar specifies the |
| 7594 | start of a portion of the string which is interpreted and replaced as described |
| 7595 | below in section ~~SECTexpansionitems onwards. Backslash is used as an escape |
| 7596 | character, as described in the following section. |
| 7597 | |
| 7598 | |
| 7599 | .section Literal text in expanded strings |
| 7600 | .rset SECTlittext "~~chapter.~~section" |
| 7601 | .index expansion||including literal text |
| 7602 | An uninterpreted dollar can be included in an expanded string by putting a |
| 7603 | backslash in front of it. A backslash can be used to prevent any special |
| 7604 | character being treated specially in an expansion, including itself. If the |
| 7605 | string appears in quotes in the configuration file, two backslashes are |
| 7606 | required because the quotes themselves cause interpretation of backslashes when |
| 7607 | the string is read in (see section ~~SECTstrings). |
| 7608 | |
| 7609 | .index expansion||non-expandable substrings |
| 7610 | A portion of the string can specified as non-expandable by placing it between |
| 7611 | two occurrences of \"@\N"\. This is particularly useful for protecting regular |
| 7612 | expressions, which often contain backslashes and dollar signs. For example: |
| 7613 | .display asis |
| 7614 | deny senders = \N^\d{8}[a-z]@some\.site\.example$\N |
| 7615 | .endd |
| 7616 | On encountering the first \"@\N"\, the expander copies subsequent characters |
| 7617 | without interpretation until it reaches the next \"@\N"\ or the end of the |
| 7618 | string. |
| 7619 | |
| 7620 | |
| 7621 | .section Character escape sequences in expanded strings |
| 7622 | .index expansion||escape sequences |
| 7623 | A backslash followed by one of the letters `n', `r', or `t' in an expanded |
| 7624 | string is recognized as an escape sequence for the character newline, carriage |
| 7625 | return, or tab, respectively. A backslash followed by up to three octal digits |
| 7626 | is recognized as an octal encoding for a single character, and a backslash |
| 7627 | followed by `x' and up to two hexadecimal digits is a hexadecimal encoding. |
| 7628 | |
| 7629 | These escape sequences are also recognized in quoted strings when they are read |
| 7630 | in. Their interpretation in expansions as well is useful for unquoted strings, |
| 7631 | and for other cases such as looked-up strings that are then expanded. |
| 7632 | |
| 7633 | .section Testing string expansions |
| 7634 | .index expansion||testing |
| 7635 | .index testing||string expansion |
| 7636 | .index \-be-\ option |
| 7637 | Many expansions can be tested by calling Exim with the \-be-\ option. This takes |
| 7638 | the command arguments, or lines from the standard input if there are no |
| 7639 | arguments, runs them through the string expansion code, and writes the results |
| 7640 | to the standard output. Variables based on configuration values are set up, but |
| 7641 | since no message is being processed, variables such as \$local@_part$\ have no |
| 7642 | value. Nevertheless the \-be-\ option can be useful for checking out file and |
| 7643 | database lookups, and the use of expansion operators such as \sg\, \substr\ and |
| 7644 | \nhash\. |
| 7645 | |
| 7646 | Exim gives up its root privilege when it is called with the \-be-\ option, and |
| 7647 | instead runs under the uid and gid it was called with, to prevent users from |
| 7648 | using \-be-\ for reading files to which they do not have access. |
| 7649 | |
| 7650 | |
| 7651 | .section Expansion items |
| 7652 | .rset SECTexpansionitems "~~chapter.~~section" |
| 7653 | The following items are recognized in expanded strings. White space may be used |
| 7654 | between sub-items that are keywords or substrings enclosed in braces inside an |
| 7655 | outer set of braces, to improve readability. \**Warning**\: Within braces, |
| 7656 | white space is significant. |
| 7657 | |
| 7658 | .startitems |
| 7659 | |
| 7660 | .item "@$<<variable name>>#$rm{or}#@$@{<<variable name>>@}" |
| 7661 | .index expansion||variables |
| 7662 | Substitute the contents of the named variable, for example |
| 7663 | .display asis |
| 7664 | $local_part |
| 7665 | ${domain} |
| 7666 | .endd |
| 7667 | The second form can be used to separate the name from subsequent alphanumeric |
| 7668 | characters. This form (using curly brackets) is available only for variables; |
| 7669 | it does $it{not} apply to message headers. The names of the variables are given |
| 7670 | in section ~~SECTexpvar below. If the name of a non-existent variable is given, |
| 7671 | the expansion fails. |
| 7672 | |
| 7673 | .item "@$@{<<op>>:<<string>>@}" |
| 7674 | .index expansion||operators |
| 7675 | The string is first itself expanded, and then the operation specified by <<op>> |
| 7676 | is applied to it. For example, |
| 7677 | .display asis |
| 7678 | ${lc:$local_part} |
| 7679 | .endd |
| 7680 | The string starts with the first character after the colon, which may be |
| 7681 | leading white space. A list of operators is given in section ~~SECTexpop below. |
| 7682 | The operator notation is used for simple expansion items that have just one |
| 7683 | argument, because it reduces the number of braces and therefore makes the |
| 7684 | string easier to understand. |
| 7685 | |
| 7686 | .item "@$@{extract@{<<key>>@}@{<<string1>>@}@{<<string2>>@}@{<<string3>>@}@}" |
| 7687 | .index expansion||extracting substrings by key |
| 7688 | The key and <<string1>> are first expanded separately. |
| 7689 | Leading and trailing whitespace is removed from the key (but not from any of |
| 7690 | the strings). |
| 7691 | The key must not consist entirely of digits. The expanded <<string1>> must be |
| 7692 | of the form: |
| 7693 | .display |
| 7694 | <<key1>> = <<value1>> <<key2>> = <<value2>> ... |
| 7695 | .endd |
| 7696 | where the equals signs and spaces (but not both) are optional. If any of the |
| 7697 | values contain white space, they must be enclosed in double quotes, and any |
| 7698 | values that are enclosed in double quotes are subject to escape processing as |
| 7699 | described in section ~~SECTstrings. The expanded <<string1>> is searched for |
| 7700 | the value that corresponds to the key. The search is case-insensitive. If the |
| 7701 | key is found, <<string2>> is expanded, and replaces the whole item; otherwise |
| 7702 | <<string3>> is used. During the expansion of <<string2>> the variable \$value$\ |
| 7703 | contains the value that has been extracted. Afterwards, it is restored to any |
| 7704 | previous value it might have had. |
| 7705 | |
| 7706 | If @{<<string3>>@} is omitted, the item is replaced by an empty string if the |
| 7707 | key is not found. If @{<<string2>>@} is also omitted, the value that was |
| 7708 | extracted is used. Thus, for example, these two expansions are identical, and |
| 7709 | yield `2001': |
| 7710 | .display |
| 7711 | @$@{extract@{gid@}{uid=1984 gid=2001@}@} |
| 7712 | @$@{extract@{gid@}{uid=1984 gid=2001@}@{@$value@}@} |
| 7713 | .endd |
| 7714 | Instead of @{<<string3>>@} the word `fail' (not in curly brackets) can appear, |
| 7715 | for example: |
| 7716 | .display |
| 7717 | @$@{extract@{Z@}@{A=... B=...@}@{@$value@} fail @} |
| 7718 | .endd |
| 7719 | @{<<string2>>@} must be present for `fail' to be recognized. When this syntax |
| 7720 | is used, if the extraction fails, the entire string expansion fails in a way |
| 7721 | that can be detected by the code in Exim which requested the expansion. This is |
| 7722 | called `forced expansion failure', and its consequences depend on the |
| 7723 | circumstances. In some cases it is no different from any other expansion |
| 7724 | failure, but in others a different action may be taken. Such variations are |
| 7725 | mentioned in the documentation of the option which is expanded. |
| 7726 | |
| 7727 | |
| 7728 | .item "@$@{extract@{<<number>>@}@{<<separators>>@}@{<<string1>>@}@{<<string2>>@}@{<<string3>>@}@}" |
| 7729 | .index expansion||extracting substrings by number |
| 7730 | The <<number>> argument must consist entirely of decimal digits, |
| 7731 | apart from leading and trailing whitespace, which is ignored. |
| 7732 | This is what distinguishes this form of \extract\ from the previous kind. It |
| 7733 | behaves in the same way, except that, instead of extracting a named field, it |
| 7734 | extracts from <<string1>> the field whose number is given as the first |
| 7735 | argument. You can use \$value$\ in <<string2>> or \"fail"\ instead of |
| 7736 | <<string3>> as before. |
| 7737 | |
| 7738 | The fields in the string are separated by any one of the characters in the |
| 7739 | separator string. These may include space or tab characters. |
| 7740 | The first field is numbered one. If the number is negative, the fields are |
| 7741 | counted from the end of the string, with the rightmost one numbered -1. If the |
| 7742 | number given is zero, the entire string is returned. If the modulus of the |
| 7743 | number is greater than the number of fields in the string, the result is the |
| 7744 | expansion of <<string3>>, or the empty string if <<string3>> is not provided. |
| 7745 | For example: |
| 7746 | .display asis |
| 7747 | ${extract{2}{:}{x:42:99:& Mailer::/bin/bash}} |
| 7748 | .endd |
| 7749 | yields `42', and |
| 7750 | .display asis |
| 7751 | ${extract{-4}{:}{x:42:99:& Mailer::/bin/bash}} |
| 7752 | .endd |
| 7753 | yields `99'. Two successive separators mean that the field between them is |
| 7754 | empty (for example, the fifth field above). |
| 7755 | |
| 7756 | |
| 7757 | .item "@$@{hash@{<<string1>>@}@{<<string2>>@}@{<<string3>>@}@}" |
| 7758 | .index hash function||textual |
| 7759 | .index expansion||textual hash |
| 7760 | This is a textual hashing function, and was the first to be implemented in |
| 7761 | early versions of Exim. In current releases, there are other hashing functions |
| 7762 | (numeric, MD5, and SHA-1), which are described below. |
| 7763 | |
| 7764 | The first two strings, after expansion, must be numbers. Call them <<m>> and |
| 7765 | <<n>>. If you are using fixed values for these numbers, that is, if <<string1>> |
| 7766 | and <<string2>> do not change when they are expanded, you can use the |
| 7767 | simpler operator notation that avoids some of the braces: |
| 7768 | .display |
| 7769 | @$@{hash@_<<n>>@_<<m>>:<<string>>@} |
| 7770 | .endd |
| 7771 | The second number is optional (in both notations). |
| 7772 | |
| 7773 | If <<n>> is greater than or equal to the length of the string, the expansion |
| 7774 | item returns the string. Otherwise it computes a new string of length <<n>> by |
| 7775 | applying a hashing function to the string. The new string consists of |
| 7776 | characters taken from the first <<m>> characters of the string |
| 7777 | .display asis |
| 7778 | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQWRSTUVWXYZ0123456789 |
| 7779 | .endd |
| 7780 | If <<m>> is not present the value 26 is used, so that only lower case |
| 7781 | letters appear. For example: |
| 7782 | .display |
| 7783 | @$@{hash@{3@}@{monty@}@} $rm{yields} \"jmg"\ |
| 7784 | @$@{hash@{5@}@{monty@}@} $rm{yields} \"monty"\ |
| 7785 | @$@{hash@{4@}@{62@}@{monty python@}@} $rm{yields} \"fbWx"\ |
| 7786 | .endd |
| 7787 | |
| 7788 | |
| 7789 | .item "@$header@_<<header name>>:#$rm{or}#@$h@_<<header name>>:" |
| 7790 | .item "@$bheader@_<<header name>>:#$rm{or}#@$bh@_<<header name>>:" |
| 7791 | .item "@$rheader@_<<header name>>:#$rm{or}#@$rh@_<<header name>>:" |
| 7792 | .index expansion||header insertion |
| 7793 | .index \$header@_$\ |
| 7794 | .index \$bheader@_$\ |
| 7795 | .index \$rheader@_$\ |
| 7796 | .index header lines||in expansion strings |
| 7797 | .index header lines||character sets |
| 7798 | .index header lines||decoding |
| 7799 | Substitute the contents of the named message header line, for example |
| 7800 | .display asis |
| 7801 | $header_reply-to: |
| 7802 | .endd |
| 7803 | The newline that terminates a header line is not included in the expansion, but |
| 7804 | internal newlines (caused by splitting the header line over several physical |
| 7805 | lines) may be present. |
| 7806 | |
| 7807 | The difference between \rheader\, \bheader\, and \header\ is in the way the |
| 7808 | data in the header line is interpreted. |
| 7809 | .numberpars $. |
| 7810 | \rheader\ gives the original `raw' content of the header line, with no |
| 7811 | processing at all, and without the removal of leading and trailing whitespace. |
| 7812 | .nextp |
| 7813 | .index base64 encoding||in header lines |
| 7814 | \bheader\ removes leading and trailing whitespace, and then decodes base64 or |
| 7815 | quoted-printable MIME `words' within the header text, but does no character |
| 7816 | set translation. If decoding of what looks superficially like a MIME `word' |
| 7817 | fails, the raw string is returned. |
| 7818 | .index binary zero||in header line |
| 7819 | If decoding produces a binary zero character, it is replaced by a question mark |
| 7820 | -- this is what Exim does for binary zeros that are actually received in header |
| 7821 | lines. |
| 7822 | .nextp |
| 7823 | \header\ tries to translate the string as decoded by \bheader\ to a standard |
| 7824 | character set. This is an attempt to produce the same string as would be |
| 7825 | displayed on a user's MUA. If translation fails, the \bheader\ string is |
| 7826 | returned. Translation is attempted only on operating systems that support the |
| 7827 | \*iconv()*\ function. This is indicated by the compile-time macro |
| 7828 | \\HAVE@_ICONV\\ in a system Makefile or in \(Local/Makefile)\. |
| 7829 | .endp |
| 7830 | |
| 7831 | In a filter file, the target character set for \header\ can be specified by a |
| 7832 | command of the following form: |
| 7833 | .display asis |
| 7834 | headers charset "UTF-8" |
| 7835 | .endd |
| 7836 | This command affects all references to \$h@_$\ (or \$header@_$\) expansions in |
| 7837 | subsequently obeyed filter commands. In the absence of this command, the target |
| 7838 | character set in a filter is taken from the setting of the \headers@_charset\ |
| 7839 | option in the runtime configuration. The value of this option defaults to the |
| 7840 | value of \\HEADERS@_CHARSET\\ in \(Local/Makefile)\. The ultimate default is |
| 7841 | ISO-8859-1. |
| 7842 | |
| 7843 | Header names follow the syntax of RFC 2822, which states that they may contain |
| 7844 | any printing characters except space and colon. Consequently, curly brackets |
| 7845 | $it{do not} terminate header names, and should not be used to enclose them as |
| 7846 | if they were variables. Attempting to do so causes a syntax error. |
| 7847 | |
| 7848 | Only header lines that are common to all copies of a message are visible to |
| 7849 | this mechanism. These are the original header lines that are received with the |
| 7850 | message, and any that are added by |
| 7851 | an ACL \warn\ statement or by |
| 7852 | a system filter. Header lines that are added to a particular copy of a message |
| 7853 | by a router or transport are not accessible. |
| 7854 | |
| 7855 | For incoming SMTP messages, no header lines are visible in ACLs that are obeyed |
| 7856 | before the \\DATA\\ ACL, because the header structure is not set up until the |
| 7857 | message is received. Header lines that are added by \warn\ statements in a |
| 7858 | \\RCPT\\ ACL (for example) are saved until the message's incoming header lines |
| 7859 | are available, at which point they are added. When a \\DATA\\ ACL is running, |
| 7860 | however, header lines added by earlier ACLs are visible. |
| 7861 | |
| 7862 | Upper case and lower case letters are synonymous in header names. If the |
| 7863 | following character is white space, the terminating colon may be omitted, but |
| 7864 | this is not recommended, because you may then forget it when it is needed. When |
| 7865 | white space terminates the header name, it is included in the expanded string. |
| 7866 | If the message does not contain the given header, the expansion item is |
| 7867 | replaced by an empty string. (See the \def\ condition in section ~~SECTexpcond |
| 7868 | for a means of testing for the existence of a header.) |
| 7869 | |
| 7870 | If there is more than one header with the same name, they are all concatenated |
| 7871 | to form the substitution string, up to a maximum length of 64K. A newline |
| 7872 | character is inserted between each line. |
| 7873 | For the \header\ expansion, for those headers that contain lists of addresses, |
| 7874 | a comma is also inserted at the junctions between lines. This does not happen |
| 7875 | for the \rheader\ expansion. |
| 7876 | |
| 7877 | |
| 7878 | |
| 7879 | .item "@$@{hmac@{<<hashname>>@}@{<<secret>>@}@{<<string>>@}@}" |
| 7880 | .index expansion||hmac hashing |
| 7881 | This function uses cryptographic hashing (either MD5 or SHA-1) to convert a |
| 7882 | shared secret and some text into a message authentication code, as specified in |
| 7883 | RFC 2104. |
| 7884 | This differs from \"@$@{md5:secret@_text...@}"\ or |
| 7885 | \"@$@{sha1:secret@_text...@}"\ in that the hmac step adds a signature to the |
| 7886 | cryptographic hash, allowing for authentication that is not possible with MD5 |
| 7887 | or SHA-1 alone. |
| 7888 | The hash name must expand to either \"md5"\ or \"sha1"\ at present. For |
| 7889 | example: |
| 7890 | .display asis |
| 7891 | ${hmac{md5}{somesecret}{$primary_hostname $tod_log}} |
| 7892 | .endd |
| 7893 | For the hostname \*mail.example.com*\ and time 2002-10-17 11:30:59, this |
| 7894 | produces: |
| 7895 | .display asis |
| 7896 | dd97e3ba5d1a61b5006108f8c8252953 |
| 7897 | .endd |
| 7898 | As an example of how this might be used, you might put in the main part of |
| 7899 | an Exim configuration: |
| 7900 | .display asis |
| 7901 | SPAMSCAN_SECRET=cohgheeLei2thahw |
| 7902 | .endd |
| 7903 | In a router or a transport you could then have: |
| 7904 | .display asis |
| 7905 | headers_add = \ |
| 7906 | X-Spam-Scanned: ${primary_hostname} ${message_id} \ |
| 7907 | ${hmac{md5}{SPAMSCAN_SECRET}\ |
| 7908 | {${primary_hostname},${message_id},$h_message-id:}} |
| 7909 | .endd |
| 7910 | Then given a message, you can check where it was scanned by looking at the |
| 7911 | ::X-Spam-Scanned:: header line. If you know the secret, you can check that this |
| 7912 | header line is authentic by recomputing the authentication code from the host |
| 7913 | name, message ID and the ::Message-id:: header line. This can be done using |
| 7914 | Exim's \-be-\ option, or by other means, for example by using the |
| 7915 | \*hmac@_md5@_hex()*\ function in Perl. |
| 7916 | |
| 7917 | |
| 7918 | |
| 7919 | .item "@${if <<condition>> @{<<string1>>@}@{<<string2>>@}@}" |
| 7920 | .index expansion||conditional |
| 7921 | If <<condition>> is true, <<string1>> is expanded and replaces the whole item; |
| 7922 | otherwise <<string2>> is used. For example, |
| 7923 | .display asis |
| 7924 | ${if eq {$local_part}{postmaster} {yes}{no} } |
| 7925 | .endd |
| 7926 | The second string need not be present; if it is not and the condition is not |
| 7927 | true, the item is replaced with nothing. Alternatively, the word `fail' may be |
| 7928 | present instead of the second string (without any curly brackets). In this |
| 7929 | case, the expansion is forced to fail if the condition is not true. The |
| 7930 | available conditions are described in section ~~SECTexpcond below. |
| 7931 | |
| 7932 | |
| 7933 | .item "@$@{length@{<<string1>>@}@{<<string2>>@}@}" |
| 7934 | .index expansion||string truncation |
| 7935 | The \length\ item is used to extract the initial portion of a string. Both |
| 7936 | strings are expanded, and the first one must yield a number, <<n>>, say. If you |
| 7937 | are using a fixed value for the number, that is, if <<string1>> does not change |
| 7938 | when expanded, you can use the simpler operator notation that avoids some of |
| 7939 | the braces: |
| 7940 | .display |
| 7941 | @$@{length@_<<n>>:<<string>>@} |
| 7942 | .endd |
| 7943 | The result of this item is either the first <<n>> characters or the whole |
| 7944 | of <<string2>>, whichever is the shorter. Do not confuse \length\ with |
| 7945 | \strlen\, which gives the length of a string. |
| 7946 | |
| 7947 | |
| 7948 | .item "@${lookup@{<<key>>@} <<search type>> @{<<file>>@} @{<<string1>>@} @{<<string2>>@}@}" |
| 7949 | .item "@${lookup <<search type>> @{<<query>>@} @{<<string1>>@} @{<<string2>>@}@}" |
| 7950 | .index expansion||lookup in |
| 7951 | .index file||lookup |
| 7952 | .index lookup||in expanded string |
| 7953 | These items specify data lookups in files and databases, as discussed in |
| 7954 | chapter ~~CHAPfdlookup. The first form is used for single-key lookups, and the |
| 7955 | second is used for query-style lookups. The <<key>>, <<file>>, and <<query>> |
| 7956 | strings are expanded before use. |
| 7957 | |
| 7958 | If there is any white space in a lookup item which is part of a filter command, |
| 7959 | a retry or rewrite rule, a routing rule for the \%manualroute%\ router, or any |
| 7960 | other place where white space is significant, the lookup item must be enclosed |
| 7961 | in double quotes. The use of data lookups in users' filter files may be locked |
| 7962 | out by the system administrator. |
| 7963 | |
| 7964 | .index \$value$\ |
| 7965 | If the lookup succeeds, <<string1>> is expanded and replaces the entire item. |
| 7966 | During its expansion, the variable \$value$\ contains the data returned by the |
| 7967 | lookup. Afterwards it reverts to the value it had previously (at the outer |
| 7968 | level it is empty). If the lookup fails, <<string2>> is expanded and replaces |
| 7969 | the entire item. If @{<<string2>>@} is omitted, the replacement is null on |
| 7970 | failure. Alternatively, <<string2>> can itself be a nested lookup, thus |
| 7971 | providing a mechanism for looking up a default value when the original lookup |
| 7972 | fails. |
| 7973 | |
| 7974 | If a nested lookup is used as part of <<string1>>, \$value$\ contains the data |
| 7975 | for the outer lookup while the parameters of the second lookup are expanded, |
| 7976 | and also while <<string2>> of the second lookup is expanded, should the second |
| 7977 | lookup fail. |
| 7978 | |
| 7979 | Instead of @{<<string2>>@} the word `fail' can appear, and in this case, if the |
| 7980 | lookup fails, the entire expansion is forced to fail. If both @{<<string1>>@} |
| 7981 | and @{<<string2>>@} are omitted, the result is the looked up value in the case |
| 7982 | of a successful lookup, and nothing in the case of failure. |
| 7983 | |
| 7984 | For single-key lookups, the string `partial' is permitted to precede the |
| 7985 | search type in order to do partial matching, and $*$ or $*$@@ may follow a |
| 7986 | search type to request default lookups if the key does not match (see sections |
| 7987 | ~~SECTdefaultvaluelookups and ~~SECTpartiallookup for details). |
| 7988 | |
| 7989 | .index numerical variables (\$1$\, \$2$\, etc)||in lookup expansion |
| 7990 | If a partial search is used, the variables \$1$\ and \$2$\ contain the wild |
| 7991 | and non-wild parts of the key during the expansion of the replacement text. |
| 7992 | They return to their previous values at the end of the lookup item. |
| 7993 | |
| 7994 | This example looks up the postmaster alias in the conventional alias file: |
| 7995 | .display asis |
| 7996 | ${lookup {postmaster} lsearch {/etc/aliases} {$value}} |
| 7997 | .endd |
| 7998 | This example uses NIS+ to look up the full name of the user corresponding to |
| 7999 | the local part of an address, forcing the expansion to fail if it is not found: |
| 8000 | .display asis |
| 8001 | ${lookup nisplus {[name=$local_part],passwd.org_dir:gcos} \ |
| 8002 | {$value}fail} |
| 8003 | .endd |
| 8004 | |
| 8005 | |
| 8006 | .item "@$@{nhash@{<<string1>>@}@{<<string2>>@}@{<<string3>>@}@}" |
| 8007 | .index expansion||numeric hash |
| 8008 | .index hash function||numeric |
| 8009 | The three strings are expanded; the first two must yield numbers. Call them |
| 8010 | <<n>> and <<m>>. If you are using fixed values for these numbers, that is, if |
| 8011 | <<string1>> and <<string2>> do not change when they are expanded, you can use |
| 8012 | the simpler operator notation that avoids some of the braces: |
| 8013 | .display |
| 8014 | @$@{nhash@_<<n>>@_<<m>>:<<string>>@} |
| 8015 | .endd |
| 8016 | The second number is optional (in both notations). If there is only one number, |
| 8017 | the result is a number in the range 0--<<n>>-1. Otherwise, the string is |
| 8018 | processed by a div/mod hash function that returns two numbers, separated by a |
| 8019 | slash, in the ranges 0 to <<n>>-1 and 0 to <<m>>-1, respectively. For example, |
| 8020 | .display asis |
| 8021 | ${nhash{8}{64}{supercalifragilisticexpialidocious}} |
| 8022 | .endd |
| 8023 | returns the string `6/33'. |
| 8024 | |
| 8025 | |
| 8026 | |
| 8027 | .item "@$@{perl@{<<subroutine>>@}@{<<arg>>@}@{<<arg>>@}...@}" |
| 8028 | .index Perl||use in expanded string |
| 8029 | .index expansion||calling Perl from |
| 8030 | This item is available only if Exim has been built to include an embedded Perl |
| 8031 | interpreter. The subroutine name and the arguments are first separately |
| 8032 | expanded, and then the Perl subroutine is called with those arguments. No |
| 8033 | additional arguments need be given; the maximum number permitted, including the |
| 8034 | name of the subroutine, is nine. |
| 8035 | |
| 8036 | The return value of the subroutine is inserted into the expanded string, unless |
| 8037 | the return value is \undef\. In that case, the expansion fails in the same way |
| 8038 | as an explicit `fail' on a lookup item. |
| 8039 | The return value is a scalar. Whatever you return is evaluated in a scalar |
| 8040 | context. For example, if you return the name of a Perl vector, the |
| 8041 | return value is the size of the vector, not its contents. |
| 8042 | |
| 8043 | If the subroutine exits by calling Perl's \die\ function, the expansion fails |
| 8044 | with the error message that was passed to \die\. More details of the embedded |
| 8045 | Perl facility are given in chapter ~~CHAPperl. |
| 8046 | |
| 8047 | The \%redirect%\ router has an option called \forbid@_filter@_perl\ which locks |
| 8048 | out the use of this expansion item in filter files. |
| 8049 | |
| 8050 | |
| 8051 | .item "@$@{readfile@{<<file name>>@}@{<<eol string>>@}@}" |
| 8052 | .index expansion||inserting an entire file |
| 8053 | .index file||inserting into expansion |
| 8054 | The file name and end-of-line string are first expanded separately. The file is |
| 8055 | then read, and its contents replace the entire item. All newline characters in |
| 8056 | the file are replaced by the end-of-line string if it is present. Otherwise, |
| 8057 | newlines are left in the string. |
| 8058 | String expansion is not applied to the contents of the file. If you want this, |
| 8059 | you must wrap the item in an \expand\ operator. If the file cannot be read, the |
| 8060 | string expansion fails. |
| 8061 | |
| 8062 | The \%redirect%\ router has an option called \forbid@_filter@_readfile\ which |
| 8063 | locks out the use of this expansion item in filter files. |
| 8064 | |
| 8065 | |
| 8066 | |
| 8067 | .item "@$@{readsocket@{<<name>>@}@{<<request>>@}@{<<timeout>>@}@{<<eol string>>@}@{<<fail string>>@}@}" |
| 8068 | .index expansion||inserting from a socket |
| 8069 | .index socket, use of in expansion |
| 8070 | This item inserts data that is read from a Unix domain socket into the expanded |
| 8071 | string. The minimal way of using it uses just two arguments: |
| 8072 | .display asis |
| 8073 | ${readsocket{/socket/name}{request string}} |
| 8074 | .endd |
| 8075 | Exim connects to the socket, writes the request string (unless it is an |
| 8076 | empty string) and reads from the socket until an end-of-file is read. A timeout |
| 8077 | of 5 seconds is applied. Additional, optional arguments extend what can be |
| 8078 | done. Firstly, you can vary the timeout. For example: |
| 8079 | .display asis |
| 8080 | ${readsocket{/socket/name}{request-string}{3s}} |
| 8081 | .endd |
| 8082 | A fourth argument allows you to change any newlines that are in the data |
| 8083 | that is read, in the same way as for \readfile\ (see above). This example turns |
| 8084 | them into spaces: |
| 8085 | .display asis |
| 8086 | ${readsocket{/socket/name}{request-string}{3s}{ }} |
| 8087 | .endd |
| 8088 | As with all expansions, the substrings are expanded before the processing |
| 8089 | happens. Errors in these sub-expansions cause the expansion to fail. In |
| 8090 | addition, the following errors can occur: |
| 8091 | .numberpars $. |
| 8092 | Failure to create a socket file descriptor; |
| 8093 | .nextp |
| 8094 | Failure to connect the socket; |
| 8095 | .nextp |
| 8096 | Failure to write the request-string; |
| 8097 | .nextp |
| 8098 | Timeout on reading from the socket. |
| 8099 | .endp |
| 8100 | By default, any of these errors causes the expansion to fail. However, if |
| 8101 | you supply a fifth substring, it is expanded and used when any of the above |
| 8102 | errors occurs. For example: |
| 8103 | .display asis |
| 8104 | ${readsocket{/socket/name}{request-string}{3s}{\n}\ |
| 8105 | {socket failure}} |
| 8106 | .endd |
| 8107 | You can test for the existence of the socket by wrapping this expansion in |
| 8108 | \"@$@{if exists"\, but there is a race condition between that test and the |
| 8109 | actual opening of the socket, so it is safer to use the fifth argument if you |
| 8110 | want to be absolutely sure of avoiding an expansion error for a non-existent |
| 8111 | socket. |
| 8112 | |
| 8113 | The \%redirect%\ router has an option called \forbid@_filter@_readsocket\ which |
| 8114 | locks out the use of this expansion item in filter files. |
| 8115 | |
| 8116 | .item "@$rheader@_<<header name>>:#$rm{or}#@$rh@_<<header name>>:" |
| 8117 | This item inserts `raw' header lines. It is described with the \header\ |
| 8118 | expansion item above. |
| 8119 | |
| 8120 | |
| 8121 | |
| 8122 | .item "@$@{run@{<<command>> <<args>>@}@{<<string1>>@}@{<<string2>>@}@}" |
| 8123 | .index expansion||running a command |
| 8124 | The command and its arguments are first expanded separately, and then the |
| 8125 | command is run in a separate process, but under the same uid and gid. As in |
| 8126 | other command executions from Exim, a shell is not used by default. If you want |
| 8127 | a shell, you must explicitly code it. |
| 8128 | .index return code||from \run\ expansion |
| 8129 | If the command succeeds (gives a zero return code) <<string1>> is expanded and |
| 8130 | replaces the entire item; during this expansion, the standard output from the |
| 8131 | command is in the variable \$value$\. If the command fails, <<string2>>, if |
| 8132 | present, is expanded. If it is absent, the result is empty. Alternatively, |
| 8133 | <<string2>> can be the word `fail' (not in braces) to force expansion failure |
| 8134 | if the command does not succeed. If both strings are omitted, the result is the |
| 8135 | standard output on success, and nothing on failure. |
| 8136 | |
| 8137 | The return code from the command is put in the variable \$runrc$\, and this |
| 8138 | remains set afterwards, so in a filter file you can do things like this: |
| 8139 | .display asis |
| 8140 | if "${run{x y z}{}}$runrc" is 1 then ... |
| 8141 | elif $runrc is 2 then ... |
| 8142 | ... |
| 8143 | endif |
| 8144 | .endd |
| 8145 | If execution of the command fails (for example, the command does not exist), |
| 8146 | the return code is 127 -- the same code that shells use for non-existent |
| 8147 | commands. |
| 8148 | |
| 8149 | \**Warning**\: In a router or transport, you cannot assume the order in which |
| 8150 | option values are expanded, except for those pre-conditions whose order of |
| 8151 | testing is documented. Therefore, you cannot reliably expect to set \$runrc$\ |
| 8152 | by the expansion of one option, and use it in another. |
| 8153 | |
| 8154 | The \%redirect%\ router has an option called \forbid@_filter@_run\ which locks |
| 8155 | out the use of this expansion item in filter files. |
| 8156 | |
| 8157 | |
| 8158 | .item "@$@{sg@{<<subject>>@}@{<<regex>>@}@{<<replacement>>@}@}" |
| 8159 | .index expansion||string substitution |
| 8160 | This item works like Perl's substitution operator (s) with the global (/g) |
| 8161 | option; hence its name. However, unlike the Perl equivalent, Exim does not |
| 8162 | modify the subject string; instead it returns the modified string for insertion |
| 8163 | into the overall expansion. The item takes three arguments: the subject string, |
| 8164 | a regular expression, and a substitution string. For example |
| 8165 | .display asis |
| 8166 | ${sg{abcdefabcdef}{abc}{xyz}} |
| 8167 | .endd |
| 8168 | yields `xyzdefxyzdef'. Because all three arguments are expanded before use, if |
| 8169 | any @$ or @\ characters are required in the regular expression or in the |
| 8170 | substitution string, they have to be escaped. For example |
| 8171 | .display asis |
| 8172 | ${sg{abcdef}{^(...)(...)\$}{\$2\$1}} |
| 8173 | .endd |
| 8174 | yields `defabc', and |
| 8175 | .display asis |
| 8176 | ${sg{1=A 4=D 3=C}{\N(\d+)=\N}{K\$1=}} |
| 8177 | .endd |
| 8178 | yields `K1=A K4=D K3=C'. |
| 8179 | Note the use of \"@\N"\ to protect the contents of the regular expression from |
| 8180 | string expansion. |
| 8181 | |
| 8182 | |
| 8183 | |
| 8184 | .item "@$@{substr@{<<string1>>@}@{<<string2>>@}@{<<string3>>@}@}" |
| 8185 | .index \substr\ |
| 8186 | .index substring extraction |
| 8187 | .index expansion||substring extraction |
| 8188 | The three strings are expanded; the first two must yield numbers. Call them |
| 8189 | <<n>> and <<m>>. If you are using fixed values for these numbers, that is, if |
| 8190 | <<string1>> and <<string2>> do not change when they are expanded, you can use |
| 8191 | the simpler operator notation that avoids some of the braces: |
| 8192 | .display |
| 8193 | @$@{substr@_<<n>>@_<<m>>:<<string>>@} |
| 8194 | .endd |
| 8195 | The second number is optional (in both notations). |
| 8196 | |
| 8197 | The \substr\ item can be used to extract more general substrings than \length\. |
| 8198 | The first number, <<n>>, is a starting offset, and <<m>> is the length |
| 8199 | required. For example |
| 8200 | .display asis |
| 8201 | ${substr{3}{2}{$local_part}} |
| 8202 | .endd |
| 8203 | If the starting offset is greater than the string length the result is the null |
| 8204 | string; if the length plus starting offset is greater than the string length, |
| 8205 | the result is the right-hand part of the string, starting from the given |
| 8206 | offset. The first character in the string has offset zero. |
| 8207 | |
| 8208 | The \substr\ expansion item can take negative offset values to count |
| 8209 | from the right-hand end of its operand. The last character is offset -1, the |
| 8210 | second-last is offset -2, and so on. Thus, for example, |
| 8211 | .display asis |
| 8212 | ${substr{-5}{2}{1234567}} |
| 8213 | .endd |
| 8214 | yields `34'. If the absolute value of a negative offset is greater than the |
| 8215 | length of the string, the substring starts at the beginning of the string, and |
| 8216 | the length is reduced by the amount of overshoot. Thus, for example, |
| 8217 | .display asis |
| 8218 | ${substr{-5}{2}{12}} |
| 8219 | .endd |
| 8220 | yields an empty string, but |
| 8221 | .display asis |
| 8222 | ${substr{-3}{2}{12}} |
| 8223 | .endd |
| 8224 | yields `1'. |
| 8225 | |
| 8226 | If the second number is omitted from \substr\, the remainder of the string is |
| 8227 | taken if the offset was positive. If it was negative, all characters in the |
| 8228 | string preceding the offset point are taken. For example, an offset of -1 and |
| 8229 | no length yields all but the last character of the string. |
| 8230 | |
| 8231 | |
| 8232 | |
| 8233 | .item "@$@{tr@{<<subject>>@}@{<<characters>>@}@{<<replacements>>@}@}" |
| 8234 | .index expansion||character translation |
| 8235 | This item does single-character translation on its subject string. The second |
| 8236 | argument is a list of characters to be translated in the subject string. Each |
| 8237 | matching character is replaced by the corresponding character from the |
| 8238 | replacement list. For example |
| 8239 | .display asis |
| 8240 | ${tr{abcdea}{ac}{13}} |
| 8241 | .endd |
| 8242 | yields `1b3de1'. If there are duplicates in the second character string, the |
| 8243 | last occurrence is used. If the third string is shorter than the second, its |
| 8244 | last character is replicated. However, if it is empty, no translation takes |
| 8245 | place. |
| 8246 | |
| 8247 | .enditems |
| 8248 | |
| 8249 | |
| 8250 | .section Expansion operators |
| 8251 | .rset SECTexpop "~~chapter.~~section" |
| 8252 | .index expansion||operators |
| 8253 | For expansion items that perform transformations on a single argument string, |
| 8254 | the `operator' notation is used because it is simpler and uses fewer braces. |
| 8255 | The substring is first expanded before the operation is applied to it. The |
| 8256 | following operations can be performed: |
| 8257 | |
| 8258 | .startitems |
| 8259 | |
| 8260 | .item "@$@{address:<<string>>@}" |
| 8261 | .index expansion||RFC 2822 address handling |
| 8262 | The string is interpreted as an RFC 2822 address, as it might appear in a |
| 8263 | header line, and the effective address is extracted from it. If the string does |
| 8264 | not parse successfully, the result is empty. |
| 8265 | |
| 8266 | |
| 8267 | .item "@$@{base62:<<digits>>@}" |
| 8268 | .index base62 |
| 8269 | .index expansion||conversion to base 62 |
| 8270 | The string must consist entirely of decimal digits. The number is converted to |
| 8271 | base 62 (sic) and output as a string of six characters, including leading |
| 8272 | zeros. \**Note**\: Just to be absolutely clear: this is \*not*\ base64 |
| 8273 | encoding. |
| 8274 | |
| 8275 | .item "@$@{base62d:<<base-62 digits>>@}" |
| 8276 | .index base62 |
| 8277 | .index expansion||conversion to base 62 |
| 8278 | The string must consist entirely of base-62 digits. The number is converted to |
| 8279 | decimal and output as a string. |
| 8280 | |
| 8281 | |
| 8282 | .item "@$@{domain:<<string>>@}" |
| 8283 | .index domain||extraction |
| 8284 | .index expansion||domain extraction |
| 8285 | The string is interpreted as an RFC 2822 address and the domain is extracted |
| 8286 | from it. If the string does not parse successfully, the result is empty. |
| 8287 | |
| 8288 | |
| 8289 | .item "@$@{escape:<<string>>@}" |
| 8290 | .index expansion||escaping non-printing characters |
| 8291 | If the string contains any non-printing characters, they are converted to |
| 8292 | escape sequences starting with a backslash. Whether characters with the most |
| 8293 | significant bit set (so-called `8-bit characters') count as printing or not is |
| 8294 | controlled by the \print@_topbitchars\ option. |
| 8295 | |
| 8296 | |
| 8297 | .item "@$@{eval:<<string>>@}" |
| 8298 | .item "@$@{eval10:<<string>>@}" |
| 8299 | .index expansion||expression evaluation |
| 8300 | .index expansion||arithmetic expression |
| 8301 | These items supports simple arithmetic in expansion strings. The string (after |
| 8302 | expansion) must be a conventional arithmetic expression, but it is limited to |
| 8303 | the four basic operators (plus, minus, times, divide) and parentheses. All |
| 8304 | operations are carried out using integer arithmetic. Plus and minus have a |
| 8305 | lower priority than times and divide; operators with the same priority are |
| 8306 | evaluated from left to right. |
| 8307 | |
| 8308 | For \eval\, numbers may be decimal, octal (starting with `0') or hexadecimal |
| 8309 | (starting with `0x'). For \eval10\, all numbers are taken as decimal, even if |
| 8310 | they start with a leading zero. This can be useful when processing numbers |
| 8311 | extracted from dates or times, which often do have leading zeros. |
| 8312 | |
| 8313 | A number may be followed by `K' or `M' to multiply it by 1024 or 1024$*$1024, |
| 8314 | respectively. Negative numbers are supported. The result of the computation is |
| 8315 | a decimal representation of the answer (without `K' or `M'). For example: |
| 8316 | .display |
| 8317 | @$@{eval:1+1@} $rm{yields} 2 |
| 8318 | @$@{eval:1+2*3@} $rm{yields} 7 |
| 8319 | @$@{eval:(1+2)*3@} $rm{yields} 9 |
| 8320 | .endd |
| 8321 | As a more realistic example, in an ACL you might have |
| 8322 | .display asis |
| 8323 | deny message = Too many bad recipients |
| 8324 | condition = \ |
| 8325 | ${if and { \ |
| 8326 | {>{$rcpt_count}{10}} \ |
| 8327 | { \ |
| 8328 | < \ |
| 8329 | {$recipients_count} \ |
| 8330 | {${eval:$rcpt_count/2}} \ |
| 8331 | } \ |
| 8332 | }{yes}{no}} |
| 8333 | .endd |
| 8334 | The condition is true if there have been more than 10 \\RCPT\\ commands and |
| 8335 | fewer than half of them have resulted in a valid recipient. |
| 8336 | |
| 8337 | |
| 8338 | .item "@$@{expand:<<string>>@}" |
| 8339 | .index expansion||re-expansion of substring |
| 8340 | The \expand\ operator causes a string to be expanded for a second time. For |
| 8341 | example, |
| 8342 | .display asis |
| 8343 | ${expand:${lookup{$domain}dbm{/some/file}{$value}}} |
| 8344 | .endd |
| 8345 | first looks up a string in a file while expanding the operand for \expand\, and |
| 8346 | then re-expands what it has found. |
| 8347 | |
| 8348 | |
| 8349 | .item "@$@{from@_utf8:<<string>>@}" |
| 8350 | .index Unicode |
| 8351 | .index UTF-8||conversion from |
| 8352 | .index expansion||UTF-8 conversion |
| 8353 | The world is slowly moving towards Unicode, although there are no standards for |
| 8354 | email yet. However, other applications (including some databases) are starting |
| 8355 | to store data in Unicode, using UTF-8 encoding. This operator converts from a |
| 8356 | UTF-8 string to an ISO-8859-1 string. UTF-8 code values greater than 255 are |
| 8357 | converted to underscores. The input must be a valid UTF-8 string. If it is not, |
| 8358 | the result is an undefined sequence of bytes. |
| 8359 | |
| 8360 | Unicode code points with values less than 256 are compatible with ASCII and |
| 8361 | ISO-8859-1 (also known as Latin-1). |
| 8362 | For example, character 169 is the copyright symbol in both cases, though the |
| 8363 | way it is encoded is different. In UTF-8, more than one byte is needed for |
| 8364 | characters with code values greater than 127, whereas ISO-8859-1 is a |
| 8365 | single-byte encoding (but thereby limited to 256 characters). This makes |
| 8366 | translation from UTF-8 to ISO-8859-1 straightforward. |
| 8367 | |
| 8368 | |
| 8369 | .item "@$@{hash@_<<n>>@_<<m>>:<<string>>@}" |
| 8370 | .index hash function||textual |
| 8371 | .index expansion||textual hash |
| 8372 | The \hash\ operator is a simpler interface to the hashing function that can be |
| 8373 | used when the two parameters are fixed numbers (as opposed to strings that |
| 8374 | change when expanded). The effect is the same as |
| 8375 | .display |
| 8376 | @$@{hash@{<<n>>@}@{<<m>>@}@{<<string>>@}@} |
| 8377 | .endd |
| 8378 | See the description of the general \hash\ item above for details. The |
| 8379 | abbreviation \h\ can be used when \hash\ is used as an operator. |
| 8380 | |
| 8381 | |
| 8382 | |
| 8383 | .item "@$@{hex2b64:<<hexstring>>@}" |
| 8384 | .index base64 encoding||conversion from hex |
| 8385 | .index expansion||hex to base64 |
| 8386 | This operator converts a hex string into one that is base64 encoded. This can |
| 8387 | be useful for processing the output of the MD5 and SHA-1 hashing functions. |
| 8388 | |
| 8389 | |
| 8390 | .item "@$@{lc:<<string>>@}" |
| 8391 | .index case forcing in strings |
| 8392 | .index string||case forcing |
| 8393 | .index lower casing |
| 8394 | .index expansion||case forcing |
| 8395 | This forces the letters in the string into lower-case, for example: |
| 8396 | .display asis |
| 8397 | ${lc:$local_part} |
| 8398 | .endd |
| 8399 | |
| 8400 | |
| 8401 | .item "@$@{length@_<<number>>:<<string>>@}" |
| 8402 | .index expansion||string truncation |
| 8403 | The \length\ operator is a simpler interface to the \length\ function that can |
| 8404 | be used when the parameter is a fixed number (as opposed to a string that |
| 8405 | changes when expanded). The effect is the same as |
| 8406 | .display |
| 8407 | @$@{length@{<<number>>@}@{<<string>>@}@} |
| 8408 | .endd |
| 8409 | See the description of the general \length\ item above for details. Note that |
| 8410 | \length\ is not the same as \strlen\. The abbreviation \l\ can be used when |
| 8411 | \length\ is used as an operator. |
| 8412 | |
| 8413 | |
| 8414 | .item "@$@{local@_part:<<string>>@}" |
| 8415 | .index expansion||local part extraction |
| 8416 | The string is interpreted as an RFC 2822 address and the local part is |
| 8417 | extracted from it. If the string does not parse successfully, the result is |
| 8418 | empty. |
| 8419 | |
| 8420 | |
| 8421 | .item "@$@{mask:<<IP address>>/<<bit count>>@}" |
| 8422 | .index masked IP address |
| 8423 | .index IP address||masking |
| 8424 | .index CIDR notation |
| 8425 | .index expansion||IP address masking |
| 8426 | If the form of the string to be operated on is not an IP address followed by a |
| 8427 | slash and an integer (that is, a network address in CIDR notation), the |
| 8428 | expansion fails. Otherwise, this operator converts the IP address to binary, |
| 8429 | masks off the least significant bits according to the bit count, and converts |
| 8430 | the result back to text, with mask appended. For example, |
| 8431 | .display asis |
| 8432 | ${mask:10.111.131.206/28} |
| 8433 | .endd |
| 8434 | returns the string `10.111.131.192/28'. Since this operation is expected to be |
| 8435 | mostly used for looking up masked addresses in files, the result for an IPv6 |
| 8436 | address uses dots to separate components instead of colons, because colon |
| 8437 | terminates a key string in lsearch files. So, for example, |
| 8438 | .display asis |
| 8439 | ${mask:3ffe:ffff:836f:0a00:000a:0800:200a:c031/99} |
| 8440 | .endd |
| 8441 | returns the string |
| 8442 | .display asis |
| 8443 | 3ffe.ffff.836f.0a00.000a.0800.2000.0000/99 |
| 8444 | .endd |
| 8445 | Letters in IPv6 addresses are always output in lower case. |
| 8446 | |
| 8447 | |
| 8448 | .item "@$@{md5:<<string>>@}" |
| 8449 | .index MD5 hash |
| 8450 | .index expansion||MD5 hash |
| 8451 | The \md5\ operator computes the MD5 hash value of the string, and returns it as |
| 8452 | a 32-digit hexadecimal number, |
| 8453 | in which any letters are in lower case. |
| 8454 | |
| 8455 | |
| 8456 | .item "@$@{nhash@_<<n>>@_<<m>>:<<string>>@}" |
| 8457 | .index expansion||numeric hash |
| 8458 | .index hash function||numeric |
| 8459 | The \nhash\ operator is a simpler interface to the numeric hashing function |
| 8460 | that can be used when the two parameters are fixed numbers (as opposed to |
| 8461 | strings that change when expanded). The effect is the same as |
| 8462 | .display |
| 8463 | @$@{nhash@{<<n>>@}@{<<m>>@}@{<<string>>@}@} |
| 8464 | .endd |
| 8465 | See the description of the general \nhash\ item above for details. |
| 8466 | |
| 8467 | |
| 8468 | .item "@$@{quote:<<string>>@}" |
| 8469 | .index quoting||in string expansions |
| 8470 | .index expansion||quoting |
| 8471 | The \quote\ operator puts its argument into double quotes if it |
| 8472 | is an empty string or |
| 8473 | contains anything other than letters, digits, underscores, dots, and hyphens. |
| 8474 | Any occurrences of double quotes and backslashes are escaped with a backslash. |
| 8475 | Newlines and carriage returns are converted to \"@\n"\ and \"@\r"\, |
| 8476 | respectively For example, |
| 8477 | .display asis |
| 8478 | ${quote:ab"*"cd} |
| 8479 | .endd |
| 8480 | becomes |
| 8481 | .display asis |
| 8482 | "ab\"*\"cd" |
| 8483 | .endd |
| 8484 | The place where this is useful is when the argument is a substitution from a |
| 8485 | variable or a message header. |
| 8486 | |
| 8487 | .item "@$@{quote@_local@_part:<<string>>@}" |
| 8488 | This operator is like \quote\, except that it quotes the string only if |
| 8489 | required to do so by the rules of RFC 2822 for quoting local parts. For |
| 8490 | example, a plus sign would not cause quoting (but it would for \quote\). |
| 8491 | If you are creating a new email address from the contents of \$local@_part$\ |
| 8492 | (or any other unknown data), you should always use this operator. |
| 8493 | |
| 8494 | |
| 8495 | .item "@$@{quote@_<<lookup-type>>:<<string>>@}" |
| 8496 | .index quoting||lookup-specific |
| 8497 | This operator applies lookup-specific quoting rules to the string. Each |
| 8498 | query-style lookup type has its own quoting rules which are described with |
| 8499 | the lookups in chapter ~~CHAPfdlookup. For example, |
| 8500 | .display asis |
| 8501 | ${quote_ldap:two * two} |
| 8502 | .endd |
| 8503 | returns |
| 8504 | .display asis |
| 8505 | two%20%5C2A%20two |
| 8506 | .endd |
| 8507 | For single-key lookup types, no quoting is ever necessary and this operator |
| 8508 | yields an unchanged string. |
| 8509 | |
| 8510 | |
| 8511 | .item "@$@{rxquote:<<string>>@}" |
| 8512 | .index quoting||in regular expressions |
| 8513 | .index regular expressions||quoting |
| 8514 | The \rxquote\ operator inserts a backslash before any non-alphanumeric |
| 8515 | characters in its argument. This is useful when substituting the values of |
| 8516 | variables or headers inside regular expressions. |
| 8517 | |
| 8518 | |
| 8519 | .item "@$@{rfc2047:<<string>>@}" |
| 8520 | .index expansion||RFC 2047 |
| 8521 | This operator encodes text according to the rules of RFC 2047. This is an |
| 8522 | encoding that is used in header lines to encode non-ASCII characters. It is |
| 8523 | assumed that the input string is in the encoding specified by the |
| 8524 | \headers@_charset\ option, which defaults to ISO-8859-1. |
| 8525 | If the string contains only characters in the range 33--126, and no instances |
| 8526 | of the characters |
| 8527 | .display asis |
| 8528 | ? = ( ) < > @ , ; : \ " . [ ] _ |
| 8529 | .endd |
| 8530 | it is not modified. Otherwise, the result is the RFC 2047 encoding, as a single |
| 8531 | `coded word'. |
| 8532 | |
| 8533 | |
| 8534 | .item "@$@{sha1:<<string>>@}" |
| 8535 | .index SHA-1 hash |
| 8536 | .index expansion||SHA-1 hashing |
| 8537 | The \sha1\ operator computes the SHA-1 hash value of the string, and returns it |
| 8538 | as a 40-digit hexadecimal number, in which any letters are in upper case. |
| 8539 | |
| 8540 | |
| 8541 | .item "@$@{stat:<<string>>@}" |
| 8542 | .index expansion||statting a file |
| 8543 | .index file||extracting characteristics |
| 8544 | The string, after expansion, must be a file path. A call to the \*stat()*\ |
| 8545 | function is made for this path. If \*stat()*\ fails, an error occurs and the |
| 8546 | expansion fails. If it succeeds, the data from the stat replaces the item, as a |
| 8547 | series of <<name>>=<<value>> pairs, where the values are all numerical, |
| 8548 | except for the value of `smode'. The names are: `mode' (giving the mode as a |
| 8549 | 4-digit octal number), `smode' (giving the mode in symbolic format as a |
| 8550 | 10-character string, as for the \*ls*\ command), `inode', `device', `links', |
| 8551 | `uid', `gid', `size', `atime', `mtime', and `ctime'. You can extract individual |
| 8552 | fields using the \extract\ expansion item. \**Warning**\: The file size may be |
| 8553 | incorrect on 32-bit systems for files larger than 2GB. |
| 8554 | |
| 8555 | |
| 8556 | .item "@$@{strlen:<<string>>@}" |
| 8557 | .index expansion||string length |
| 8558 | .index string||length in expansion |
| 8559 | The item is replace by the length of the expanded string, expressed as a |
| 8560 | decimal number. \**Note**\: Do not confuse \strlen\ with \length\. |
| 8561 | |
| 8562 | |
| 8563 | .item "@$@{substr@_<<start>>@_<<length>>:<<string>>@}" |
| 8564 | .index \substr\ |
| 8565 | .index substring extraction |
| 8566 | .index expansion||substring expansion |
| 8567 | The \substr\ operator is a simpler interface to the \substr\ function that can |
| 8568 | be used when the two parameters are fixed numbers (as opposed to strings that |
| 8569 | change when expanded). The effect is the same as |
| 8570 | .display |
| 8571 | @$@{substr@{<<start>>@}@{<<length>>@}@{<<string>>@}@} |
| 8572 | .endd |
| 8573 | See the description of the general \substr\ item above for details. The |
| 8574 | abbreviation \s\ can be used when \substr\ is used as an operator. |
| 8575 | |
| 8576 | .item "@$@{time@_interval:<<string>>@}" |
| 8577 | .index \time@_interval\ |
| 8578 | .index time interval||formatting |
| 8579 | The argument (after sub-expansion) must be a sequence of decimal digits that |
| 8580 | represents an interval of time as a number of seconds. It is converted into a |
| 8581 | number of larger units and output in Exim's normal time format, for example, |
| 8582 | \"1w3d4h2m6s"\. |
| 8583 | |
| 8584 | .item "@$@{uc:<<string>>@}" |
| 8585 | .index case forcing in strings |
| 8586 | .index string||case forcing |
| 8587 | .index upper casing |
| 8588 | .index expansion||case forcing |
| 8589 | This forces the letters in the string into upper-case. |
| 8590 | |
| 8591 | .enditems |
| 8592 | |
| 8593 | |
| 8594 | |
| 8595 | .section Expansion conditions |
| 8596 | .rset SECTexpcond "~~chapter.~~section" |
| 8597 | .index expansion||conditions |
| 8598 | The following conditions are available for testing by the \@$@{if\ construct |
| 8599 | while expanding strings: |
| 8600 | |
| 8601 | .startitems |
| 8602 | |
| 8603 | .item "!<<condition>>" |
| 8604 | .index expansion||negating a condition |
| 8605 | Preceding any condition with an exclamation mark negates the result of the |
| 8606 | condition. |
| 8607 | |
| 8608 | .item "<<symbolic operator>> @{<<string1>>@}@{<<string2>>@}" |
| 8609 | .index numeric comparison |
| 8610 | .index expansion||numeric comparison |
| 8611 | There are a number of symbolic operators for doing numeric comparisons. They |
| 8612 | are: |
| 8613 | .display |
| 8614 | .tabs 8 |
| 8615 | = $t $rm{equal} |
| 8616 | == $t $rm{equal} |
| 8617 | > $t $rm{greater} |
| 8618 | >= $t $rm{greater or equal} |
| 8619 | < $t $rm{less} |
| 8620 | <= $t $rm{less or equal} |
| 8621 | .endd |
| 8622 | For example, |
| 8623 | .display asis |
| 8624 | ${if >{$message_size}{10M} ... |
| 8625 | .endd |
| 8626 | Note that the general negation operator provides for inequality testing. The |
| 8627 | two strings must take the form of optionally signed decimal integers, |
| 8628 | optionally followed by one of the letters `K' or `M' (in either upper or lower |
| 8629 | case), signifying multiplication by 1024 or 1024$*$1024, respectively. |
| 8630 | |
| 8631 | .item "crypteq @{<<string1>>@}@{<<string2>>@}" |
| 8632 | .index expansion||encrypted comparison |
| 8633 | .index encrypted strings, comparing |
| 8634 | This condition is included in the Exim binary if it is built to support any |
| 8635 | authentication mechanisms (see chapter ~~CHAPSMTPAUTH). Otherwise, it is |
| 8636 | necessary to define \\SUPPORT@_CRYPTEQ\\ in \(Local/Makefile)\ to get \crypteq\ |
| 8637 | included in the binary. |
| 8638 | |
| 8639 | The \crypteq\ condition has two arguments. The first is encrypted and compared |
| 8640 | against the second, which is already encrypted. The second string may be in the |
| 8641 | LDAP form for storing encrypted strings, which starts with the encryption type |
| 8642 | in curly brackets, followed by the data. If the second string does not begin |
| 8643 | with `{' it is assumed to be encrypted with \*crypt()*\ |
| 8644 | or \*crypt16()*\ (see below), |
| 8645 | since such strings cannot begin with `{'. Typically this will be a field from a |
| 8646 | password file. |
| 8647 | |
| 8648 | An example of an encrypted string in LDAP form is: |
| 8649 | .display asis |
| 8650 | {md5}CY9rzUYh03PK3k6DJie09g== |
| 8651 | .endd |
| 8652 | If such a string appears directly in an expansion, the curly brackets have to |
| 8653 | be quoted, because they are part of the expansion syntax. For example: |
| 8654 | .display asis |
| 8655 | ${if crypteq {test}{\{md5\}CY9rzUYh03PK3k6DJie09g==}{yes}{no}} |
| 8656 | .endd |
| 8657 | The following encryption types |
| 8658 | (whose names are matched case-independently) |
| 8659 | are supported: |
| 8660 | .numberpars $. |
| 8661 | .index MD5 hash |
| 8662 | .index base64 encoding||in encrypted password |
| 8663 | \@{md5@}\ computes the MD5 digest of the first string, and expresses this as |
| 8664 | printable characters to compare with the remainder of the second string. If the |
| 8665 | length of the comparison string is 24, Exim assumes that it is base64 encoded |
| 8666 | (as in the above example). If the length is 32, Exim assumes that it is a |
| 8667 | hexadecimal encoding of the MD5 digest. If the length not 24 or 32, the |
| 8668 | comparison fails. |
| 8669 | .nextp |
| 8670 | .index SHA-1 hash |
| 8671 | \@{sha1@}\ computes the SHA-1 digest of the first string, and expresses this as |
| 8672 | printable characters to compare with the remainder of the second string. If the |
| 8673 | length of the comparison string is 28, Exim assumes that it is base64 encoded. |
| 8674 | If the length is 40, Exim assumes that it is a hexadecimal encoding of the |
| 8675 | SHA-1 digest. If the length is not 28 or 40, the comparison fails. |
| 8676 | .nextp |
| 8677 | .index \*crypt()*\ |
| 8678 | \@{crypt@}\ calls the \*crypt()*\ function, which uses only the first eight |
| 8679 | characters of the password. |
| 8680 | .nextp |
| 8681 | .index \*crypt16()*\ |
| 8682 | \@{crypt16@}\ calls the \*crypt16()*\ function (also known as \*bigcrypt()*\), |
| 8683 | which uses up to 16 characters of the password. |
| 8684 | .endp |
| 8685 | Exim has its own version of \*crypt16()*\ (which is just a double call to |
| 8686 | \*crypt()*\). For operating systems that have their own version, setting |
| 8687 | \\HAVE@_CRYPT16\\ in \(Local/Makefile)\ when building Exim causes it to use the |
| 8688 | operating system version instead of its own. This option is set by default in |
| 8689 | the OS-dependent \(Makefile)\ for those operating systems that are known to |
| 8690 | support \*crypt16()*\. |
| 8691 | |
| 8692 | If you do not put any curly bracket encryption type in a \crypteq\ comparison, |
| 8693 | the default is either \"@{crypt@}"\ or \"@{crypt16@}"\, as determined by the |
| 8694 | setting of \\DEFAULT@_CRYPT\\ in \(Local/Makefile)\. The default default is |
| 8695 | \"@{crypt@}"\. Whatever the default, you can always use either function by |
| 8696 | specifying it explicitly in curly brackets. |
| 8697 | |
| 8698 | Note that if a password is no longer than 8 characters, the results of |
| 8699 | encrypting it with \*crypt()*\ and \*crypt16()*\ are identical. That means that |
| 8700 | \*crypt16()*\ is backwards compatible, as long as nobody feeds it a password |
| 8701 | longer than 8 characters. |
| 8702 | |
| 8703 | |
| 8704 | .item "def:<<variable name>>" |
| 8705 | .index expansion||checking for empty variable |
| 8706 | The \def\ condition must be followed by the name of one of the expansion |
| 8707 | variables defined in section ~~SECTexpvar. The condition is true if the named |
| 8708 | expansion variable does not contain the empty string, for example |
| 8709 | .display asis |
| 8710 | ${if def:sender_ident {from $sender_ident}} |
| 8711 | .endd |
| 8712 | Note that the variable name is given without a leading \@$\ character. If the |
| 8713 | variable does not exist, the expansion fails. |
| 8714 | |
| 8715 | .item "def:header@_<<header name>>:##or##def:h@_<<header name>>:" |
| 8716 | .index expansion||checking header line existence |
| 8717 | This condition is true if a message is being processed and the named header |
| 8718 | exists in the message. For example, |
| 8719 | .display asis |
| 8720 | ${if def:header_reply-to:{$h_reply-to:}{$h_from:}} |
| 8721 | .endd |
| 8722 | Note that no \@$\ appears before \header@_\ or \h@_\ in the condition, |
| 8723 | and that header names must be terminated by colons if white space does not |
| 8724 | follow. |
| 8725 | |
| 8726 | .item "eq @{<<string1>>@}@{<<string2>>@}" |
| 8727 | .item "eqi @{<<string1>>@}@{<<string2>>@}" |
| 8728 | .index string||comparison |
| 8729 | .index expansion||string comparison |
| 8730 | The two substrings are first expanded. The condition is true if the two |
| 8731 | resulting strings are identical: for \eq\ the comparison includes the case of |
| 8732 | letters, whereas for \eqi\ the comparison is case-independent. |
| 8733 | |
| 8734 | .item "exists @{<<file name>>@}" |
| 8735 | .index expansion||file existence test |
| 8736 | .index file||existence test |
| 8737 | The substring is first expanded and then interpreted as an absolute path. The |
| 8738 | condition is true if the named file (or directory) exists. The existence test |
| 8739 | is done by calling the \*stat()*\ function. The use of the \exists\ test in |
| 8740 | users' filter files may be locked out by the system administrator. |
| 8741 | |
| 8742 | .item "first@_delivery" |
| 8743 | .index delivery||first |
| 8744 | .index first delivery |
| 8745 | .index expansion||first delivery test |
| 8746 | This condition, which has no data, is true during a message's first delivery |
| 8747 | attempt. It is false during any subsequent delivery attempts. |
| 8748 | |
| 8749 | .item "ge @{<<string1>>@}@{<<string2>>@}" |
| 8750 | .item "gei @{<<string1>>@}@{<<string2>>@}" |
| 8751 | .index string||comparison |
| 8752 | .index expansion||string comparison |
| 8753 | The two substrings are first expanded. The condition is true if the first |
| 8754 | string is lexically greater than or equal to the second string: for \ge\ the |
| 8755 | comparison includes the case of letters, whereas for \gei\ the comparison is |
| 8756 | case-independent. |
| 8757 | |
| 8758 | .item "gt @{<<string1>>@}@{<<string2>>@}" |
| 8759 | .item "gti @{<<string1>>@}@{<<string2>>@}" |
| 8760 | .index string||comparison |
| 8761 | .index expansion||string comparison |
| 8762 | The two substrings are first expanded. The condition is true if the first |
| 8763 | string is lexically greater than the second string: for \gt\ the comparison |
| 8764 | includes the case of letters, whereas for \gti\ the comparison is |
| 8765 | case-independent. |
| 8766 | |
| 8767 | .item "isip @{<<string>>@}" 8 |
| 8768 | .item "isip4 @{<<string>>@}" |
| 8769 | .item "isip6 @{<<string>>@}" |
| 8770 | .index IP address||testing string format |
| 8771 | .index string||testing for IP address |
| 8772 | The substring is first expanded, and then tested to see if it has the form of |
| 8773 | an IP address. Both IPv4 and IPv6 addresses are valid for \isip\, whereas |
| 8774 | \isip4\ and \isip6\ test just for IPv4 or IPv6 addresses, respectively. For |
| 8775 | example, you could use |
| 8776 | .display asis |
| 8777 | ${if isip4{$sender_host_address}... |
| 8778 | .endd |
| 8779 | to test which version of IP an incoming SMTP connection is using. |
| 8780 | |
| 8781 | |
| 8782 | .item "ldapauth @{<<ldap query>>@}" |
| 8783 | .index LDAP||use for authentication |
| 8784 | .index expansion||LDAP authentication test |
| 8785 | This condition supports user authentication using LDAP. See section ~~SECTldap |
| 8786 | for details of how to use LDAP in lookups and the syntax of queries. For this |
| 8787 | use, the query must contain a user name and password. The query itself is not |
| 8788 | used, and can be empty. The condition is true if |
| 8789 | the password is not empty, and the user name and password are accepted by the |
| 8790 | LDAP server. An empty password is rejected without calling LDAP because LDAP |
| 8791 | binds with an empty password are considered anonymous regardless of |
| 8792 | the username, and will succeed in most configurations. |
| 8793 | See chapter ~~CHAPSMTPAUTH for details of SMTP authentication, and chapter |
| 8794 | ~~CHAPplaintext for an example of how this can be used. |
| 8795 | |
| 8796 | |
| 8797 | .item "le @{<<string1>>@}@{<<string2>>@}" |
| 8798 | .item "lei @{<<string1>>@}@{<<string2>>@}" |
| 8799 | .index string||comparison |
| 8800 | .index expansion||string comparison |
| 8801 | The two substrings are first expanded. The condition is true if the first |
| 8802 | string is lexically less than or equal to the second string: for \le\ the |
| 8803 | comparison includes the case of letters, whereas for \lei\ the comparison is |
| 8804 | case-independent. |
| 8805 | |
| 8806 | .item "lt @{<<string1>>@}@{<<string2>>@}" |
| 8807 | .item "lti @{<<string1>>@}@{<<string2>>@}" |
| 8808 | .index string||comparison |
| 8809 | .index expansion||string comparison |
| 8810 | The two substrings are first expanded. The condition is true if the first |
| 8811 | string is lexically less than the second string: for \lt\ the comparison |
| 8812 | includes the case of letters, whereas for \lti\ the comparison is |
| 8813 | case-independent. |
| 8814 | |
| 8815 | |
| 8816 | .item "match @{<<string1>>@}@{<<string2>>@}" |
| 8817 | .index expansion||regular expression comparison |
| 8818 | .index regular expressions||match in expanded string |
| 8819 | The two substrings are first expanded. The second is then treated as a regular |
| 8820 | expression and applied to the first. Because of the pre-expansion, if the |
| 8821 | regular expression contains dollar, or backslash characters, they must be |
| 8822 | escaped. Care must also be taken if the regular expression contains braces |
| 8823 | (curly brackets). A closing brace must be escaped so that it is not taken as a |
| 8824 | premature termination of <<string2>>. The easiest approach is to use the |
| 8825 | \"@\N"\ feature to disable expansion of the regular expression. |
| 8826 | For example, |
| 8827 | .display asis |
| 8828 | ${if match {$local_part}{\N^\d{3}\N} ... |
| 8829 | .endd |
| 8830 | If the whole expansion string is in double quotes, further escaping of |
| 8831 | backslashes is also required. |
| 8832 | |
| 8833 | The condition is true if the regular expression match succeeds. |
| 8834 | The regular expression is not required to begin with a circumflex |
| 8835 | metacharacter, but if there is no circumflex, the expression is not anchored, |
| 8836 | and it may match anywhere in the subject, not just at the start. If you want |
| 8837 | the pattern to match at the end of the subject, you must include the \"@$"\ |
| 8838 | metacharacter at an appropriate point. |
| 8839 | |
| 8840 | .index numerical variables (\$1$\, \$2$\, etc)||in \if\ expansion |
| 8841 | At the start of an \if\ expansion the values of the numeric variable |
| 8842 | substitutions \$1$\ etc. are remembered. Obeying a \match\ condition that |
| 8843 | succeeds causes them to be reset to the substrings of that condition and they |
| 8844 | will have these values during the expansion of the success string. At the end |
| 8845 | of the \if\ expansion, the previous values are restored. After testing a |
| 8846 | combination of conditions using \or\, the subsequent values of the numeric |
| 8847 | variables are those of the condition that succeeded. |
| 8848 | |
| 8849 | .item "match@_domain @{<<string1>>@}@{<<string2>>@}" |
| 8850 | .item "match@_address @{<<string1>>@}@{<<string2>>@}" |
| 8851 | .item "match@_local@_part @{<<string1>>@}@{<<string2>>@}" |
| 8852 | .index domain list||in expansion condition |
| 8853 | .index address list||in expansion condition |
| 8854 | .index local part list||in expansion condition |
| 8855 | These conditions make it possible to test domain, address, and local |
| 8856 | part lists within expansions. Each condition requires two arguments: an item |
| 8857 | and a list to match. A trivial example is: |
| 8858 | .display asis |
| 8859 | ${if match_domain{a.b.c}{x.y.z:a.b.c:p.q.r}{yes}{no}} |
| 8860 | .endd |
| 8861 | In each case, the second argument may contain any of the allowable items for a |
| 8862 | list of the appropriate type. Also, because the second argument (after |
| 8863 | expansion) is a standard form of list, it is possible to refer to a named list. |
| 8864 | Thus, you can use conditions like this: |
| 8865 | .display asis |
| 8866 | ${if match_domain{$domain}{+local_domains}{... |
| 8867 | .endd |
| 8868 | .index \"+caseful"\ |
| 8869 | For address lists, the matching starts off caselessly, but the \"+caseful"\ |
| 8870 | item can be used, as in all address lists, to cause subsequent items to |
| 8871 | have their local parts matched casefully. Domains are always matched |
| 8872 | caselessly. |
| 8873 | |
| 8874 | \**Note**\: Host lists are \*not*\ supported in this way. This is because |
| 8875 | hosts have two identities: a name and an IP address, and it is not clear |
| 8876 | how to specify cleanly how such a test would work. At least, I haven't come |
| 8877 | up with anything yet. |
| 8878 | |
| 8879 | .item "pam {<<string1>>:<<string2>>:...@}" |
| 8880 | .index PAM authentication |
| 8881 | .index \\AUTH\\||with PAM |
| 8882 | .index Solaris||PAM support |
| 8883 | .index expansion||PAM authentication test |
| 8884 | \*Pluggable Authentication Modules*\ |
| 8885 | (\?http://www.kernel.org/pub/linux/libs/pam/?\) |
| 8886 | are a facility which is available in the latest releases of Solaris and in some |
| 8887 | GNU/Linux distributions. The Exim support, which is intended for use in |
| 8888 | conjunction with the SMTP \\AUTH\\ command, is available only if Exim is |
| 8889 | compiled with |
| 8890 | .display asis |
| 8891 | SUPPORT_PAM=yes |
| 8892 | .endd |
| 8893 | in \(Local/Makefile)\. You probably need to add \-lpam-\ to \\EXTRALIBS\\, and |
| 8894 | in some releases of GNU/Linux \-ldl-\ is also needed. |
| 8895 | |
| 8896 | The argument string is first expanded, and the result must be a colon-separated |
| 8897 | list of strings. |
| 8898 | Leading and trailing whitespace is ignored. |
| 8899 | The PAM module is initialized with the service name `exim' and the user name |
| 8900 | taken from the first item in the colon-separated data string (<<string1>>). The |
| 8901 | remaining items in the data string are passed over in response to requests from |
| 8902 | the authentication function. In the simple case there will only be one request, |
| 8903 | for a password, so the data consists of just two strings. |
| 8904 | |
| 8905 | There can be problems if any of the strings are permitted to contain colon |
| 8906 | characters. In the usual way, these have to be doubled to avoid being taken as |
| 8907 | separators. If the data is being inserted from a variable, the \sg\ expansion |
| 8908 | item can be used to double any existing colons. For example, the configuration |
| 8909 | of a LOGIN authenticator might contain this setting: |
| 8910 | .display asis |
| 8911 | server_condition = ${if pam{$1:${sg{$2}{:}{::}}}{yes}{no}} |
| 8912 | .endd |
| 8913 | For a PLAIN authenticator you could use: |
| 8914 | .display asis |
| 8915 | server_condition = ${if pam{$2:${sg{$3}{:}{::}}}{yes}{no}} |
| 8916 | .endd |
| 8917 | In some operating systems, PAM authentication can be done only from a process |
| 8918 | running as root. Since Exim is running as the Exim user when receiving |
| 8919 | messages, this means that PAM cannot be used directly in those systems. |
| 8920 | A patched version of the \*pam@_unix*\ module that comes with the |
| 8921 | Linux PAM package is available from \?http:@/@/www.e-admin.de/pam@_exim/?\. |
| 8922 | The patched module allows one special uid/gid combination, in addition to root, |
| 8923 | to authenticate. If you build the patched module to allow the Exim user and |
| 8924 | group, PAM can then be used from an Exim authenticator. |
| 8925 | |
| 8926 | |
| 8927 | .item "pwcheck {<<string1>>:<<string2>>@}" |
| 8928 | .index \*pwcheck*\ daemon |
| 8929 | .index Cyrus |
| 8930 | .index expansion||\*pwcheck*\ authentication test |
| 8931 | This condition supports user authentication using the Cyrus \*pwcheck*\ daemon. |
| 8932 | This is one way of making it possible for passwords to be checked by a process |
| 8933 | that is not running as root. |
| 8934 | \**Note:**\ The use of \*pwcheck*\ is now deprecated. Its replacement is |
| 8935 | \*saslauthd*\ (see below). |
| 8936 | |
| 8937 | The pwcheck support is not included in Exim by default. You need to specify |
| 8938 | the location of the pwcheck daemon's socket in \(Local/Makefile)\ before |
| 8939 | building Exim. For example: |
| 8940 | .display asis |
| 8941 | CYRUS_PWCHECK_SOCKET=/var/pwcheck/pwcheck |
| 8942 | .endd |
| 8943 | You do not need to install the full Cyrus software suite in order to use |
| 8944 | the pwcheck daemon. You can compile and install just the daemon alone |
| 8945 | from the Cyrus SASL library. Ensure that \*exim*\ is the only user that has |
| 8946 | access to the \(/var/pwcheck)\ directory. |
| 8947 | |
| 8948 | The \pwcheck\ condition takes one argument, which must be the user name and |
| 8949 | password, separated by a colon. For example, in a LOGIN authenticator |
| 8950 | configuration, you might have this: |
| 8951 | .display asis |
| 8952 | server_condition = ${if pwcheck{$1:$2}{1}{0}} |
| 8953 | .endd |
| 8954 | |
| 8955 | .item "queue@_running" |
| 8956 | .index queue runner||detecting when delivering from |
| 8957 | .index expansion||queue runner test |
| 8958 | This condition, which has no data, is true during delivery attempts that are |
| 8959 | initiated by queue runner processes, and false otherwise. |
| 8960 | |
| 8961 | |
| 8962 | .item "radius {<<authentication string>>@}" |
| 8963 | .index Radius |
| 8964 | .index expansion||Radius authentication |
| 8965 | Radius authentication (RFC 2865) is supported in a similar way to PAM. You must |
| 8966 | set \\RADIUS@_CONFIG@_FILE\\ in \(Local/Makefile)\ to specify the location of |
| 8967 | the Radius client configuration file in order to build Exim with Radius |
| 8968 | support. |
| 8969 | You may also have to supply a suitable setting in \\EXTRALIBS\\ so that the |
| 8970 | Radius library can be found when Exim is linked. |
| 8971 | The string specified by \\RADIUS@_CONFIG@_FILE\\ is expanded and passed to the |
| 8972 | Radius client library, which calls the Radius server. The condition is true if |
| 8973 | the authentication is successful. For example |
| 8974 | .display |
| 8975 | server@_condition = @$@{if radius@{<<arguments>>@}@{yes@}@{no@}@} |
| 8976 | .endd |
| 8977 | |
| 8978 | |
| 8979 | |
| 8980 | .item "saslauthd @{@{<<user>>@}@{<<password>>@}@{<<service>>@}@{<<realm>>@}@}" |
| 8981 | .index \*saslauthd*\ daemon |
| 8982 | .index Cyrus |
| 8983 | .index expansion||\*saslauthd*\ authentication test |
| 8984 | This condition supports user authentication using the Cyrus \*saslauthd*\ |
| 8985 | daemon. This replaces the older \*pwcheck*\ daemon, which is now deprecated. |
| 8986 | Using this daemon is one way of making it possible for passwords to be checked |
| 8987 | by a process that is not running as root. |
| 8988 | |
| 8989 | The saslauthd support is not included in Exim by default. You need to specify |
| 8990 | the location of the saslauthd daemon's socket in \(Local/Makefile)\ before |
| 8991 | building Exim. For example: |
| 8992 | .display asis |
| 8993 | CYRUS_SASLAUTHD_SOCKET=/var/state/saslauthd/mux |
| 8994 | .endd |
| 8995 | You do not need to install the full Cyrus software suite in order to use |
| 8996 | the saslauthd daemon. You can compile and install just the daemon alone |
| 8997 | from the Cyrus SASL library. |
| 8998 | |
| 8999 | Up to four arguments can be supplied to the \saslauthd\ condition, but only two |
| 9000 | are mandatory. For example: |
| 9001 | .display asis |
| 9002 | server_condition = ${if saslauthd{{$1}{$2}}{1}{0}} |
| 9003 | .endd |
| 9004 | The service and the realm are optional (which is why the arguments are enclosed |
| 9005 | in their own set of braces). For details of the meaning of the service and |
| 9006 | realm, and how to run the daemon, consult the Cyrus documentation. |
| 9007 | |
| 9008 | .enditems |
| 9009 | |
| 9010 | |
| 9011 | |
| 9012 | .section Combining expansion conditions |
| 9013 | .index expansion||combining conditions |
| 9014 | Several conditions can be tested at once by combining them using the \and\ and |
| 9015 | \or\ combination conditions. Note that \and\ and \or\ are complete conditions |
| 9016 | on their own, and precede their lists of sub-conditions. Each sub-condition |
| 9017 | must be enclosed in braces within the overall braces that contain the list. No |
| 9018 | repetition of \if\ is used. |
| 9019 | |
| 9020 | .startitems |
| 9021 | |
| 9022 | .item "or @{@{<<cond1>>@}@{<<cond2>>@}...@}" |
| 9023 | .index `or' expansion condition |
| 9024 | .index expansion||`or' of conditions |
| 9025 | The sub-conditions are evaluated from left to right. The condition is true if |
| 9026 | any one of the sub-conditions is true. |
| 9027 | For example, |
| 9028 | .display asis |
| 9029 | ${if or {{eq{$local_part}{spqr}}{eq{$domain}{testing.com}}}... |
| 9030 | .endd |
| 9031 | When a true sub-condition is found, the following ones are parsed but not |
| 9032 | evaluated. If there are several `match' sub-conditions the values of the |
| 9033 | numeric variables afterwards are taken from the first one that succeeds. |
| 9034 | |
| 9035 | .item "and @{@{<<cond1>>@}@{<<cond2>>@}...@}" |
| 9036 | .index `and' expansion condition |
| 9037 | .index expansion||`and' of conditions |
| 9038 | The sub-conditions are evaluated from left to right. The condition is true if |
| 9039 | all of the sub-conditions are true. If there are several `match' |
| 9040 | sub-conditions, the values of the numeric variables afterwards are taken from |
| 9041 | the last one. When a false sub-condition is found, the following ones are |
| 9042 | parsed but not evaluated. |
| 9043 | |
| 9044 | .enditems |
| 9045 | |
| 9046 | |
| 9047 | |
| 9048 | .section Expansion variables |
| 9049 | .rset SECTexpvar "~~chapter.~~section" |
| 9050 | .index expansion||variables, list of |
| 9051 | |
| 9052 | The variables that are available for use in expansion strings are: |
| 9053 | |
| 9054 | .push |
| 9055 | .indent 2em |
| 9056 | .tempindent 0 |
| 9057 | .index numerical variables (\$1$\, \$2$\, etc) |
| 9058 | \$0$\, \$1$\, etc: When a \match\ expansion condition succeeds, these |
| 9059 | variables contain the captured substrings identified by the regular expression |
| 9060 | during subsequent processing of the success string of the containing \if\ |
| 9061 | expansion item. They may also be set externally by some other matching process |
| 9062 | which precedes the expansion of the string. For example, the commands available |
| 9063 | in Exim filter files include an \if\ command with its own regular expression |
| 9064 | matching condition. |
| 9065 | |
| 9066 | .tempindent 0 |
| 9067 | \$acl@_c0$\ -- \$acl@_c9$\: Values can be placed in these variables by the |
| 9068 | \set\ modifier in an ACL. The values persist throughout the lifetime of an SMTP |
| 9069 | connection. They can be used to pass information between ACLs and different |
| 9070 | invocations of the same ACL. |
| 9071 | When a message is received, the values of these variables are saved with the |
| 9072 | message, and can be accessed by filters, routers, and transports during |
| 9073 | subsequent delivery. |
| 9074 | |
| 9075 | .tempindent 0 |
| 9076 | \$acl@_m0$\ -- \$acl@_m9$\: Values can be placed in these variables by the |
| 9077 | \set\ modifier in an ACL. They retain their values while a message is being |
| 9078 | received, but are reset afterwards. They are also reset by \\MAIL\\, \\RSET\\, |
| 9079 | \\EHLO\\, \\HELO\\, and after starting a TLS session. |
| 9080 | When a message is received, the values of these variables are saved with the |
| 9081 | message, and can be accessed by filters, routers, and transports during |
| 9082 | subsequent delivery. |
| 9083 | |
| 9084 | |
| 9085 | .tempindent 0 |
| 9086 | \$acl@_verify@_message$\: During the expansion of the \message\ and |
| 9087 | \log@_message\ modifiers in an ACL statement after an address verification has |
| 9088 | failed, this variable contains the original failure message that will be |
| 9089 | overridden by the expanded string. |
| 9090 | |
| 9091 | .tempindent 0 |
| 9092 | \$address@_data$\: This variable is set by means of the \address@_data\ |
| 9093 | option in routers. The value then remains with the address while it is |
| 9094 | processed by subsequent routers and eventually a transport. If the transport is |
| 9095 | handling multiple addresses, the value from the first address is used. See |
| 9096 | chapter ~~CHAProutergeneric for more details. |
| 9097 | \**Note**\: the contents of \$address@_data$\ are visible in user filter files. |
| 9098 | |
| 9099 | If \$address@_data$\ is set when the routers are called to verify an address |
| 9100 | from an ACL, the final value remains available in subsequent conditions in the |
| 9101 | ACL statement. If routing the address caused it to be redirected to a single |
| 9102 | address, the child address is also routed as part of the verification, and in |
| 9103 | this case the final value of \$address@_data$\ is from the child's routing. |
| 9104 | |
| 9105 | .tempindent 0 |
| 9106 | \$address@_file$\: When, as a result of aliasing, forwarding, or filtering, a |
| 9107 | message is directed to a specific file, this variable holds the name of the |
| 9108 | file when the transport is running. At other times, the variable is empty. For |
| 9109 | example, using the default configuration, if user \r2d2\ has a \(.forward)\ |
| 9110 | file containing |
| 9111 | .display asis |
| 9112 | /home/r2d2/savemail |
| 9113 | .endd |
| 9114 | then when the \%address@_file%\ transport is running, \$address@_file$\ |
| 9115 | contains `/home/r2d2/savemail'. |
| 9116 | .index Sieve filter||value of \$address@_file$\ |
| 9117 | For Sieve filters, the value may be `inbox' or a relative folder name. It is |
| 9118 | then up to the transport configuration to generate an appropriate absolute path |
| 9119 | to the relevant file. |
| 9120 | |
| 9121 | |
| 9122 | .tempindent 0 |
| 9123 | \$address@_pipe$\: When, as a result of aliasing or forwarding, a message is |
| 9124 | directed to a pipe, this variable holds the pipe command when the transport is |
| 9125 | running. |
| 9126 | |
| 9127 | .index authentication||id |
| 9128 | .tempindent 0 |
| 9129 | \$authenticated@_id$\: When a server successfully authenticates a client it may |
| 9130 | be configured to preserve some of the authentication information in the |
| 9131 | variable \$authenticated@_id$\ (see chapter ~~CHAPSMTPAUTH). For example, a |
| 9132 | user/password authenticator configuration might preserve the user name for use |
| 9133 | in the routers. When a message is submitted locally (that is, not over a TCP |
| 9134 | connection), the value of \$authenticated@_id$\ is the login name of the |
| 9135 | calling process. |
| 9136 | |
| 9137 | .index sender||authenticated |
| 9138 | .index authentication||sender |
| 9139 | .index \\AUTH\\||on \\MAIL\\ command |
| 9140 | .tempindent 0 |
| 9141 | \$authenticated@_sender$\: |
| 9142 | When acting as a server, Exim takes note of the \\AUTH=\\ parameter on an |
| 9143 | incoming SMTP \\MAIL\\ command |
| 9144 | if it believes the sender is sufficiently trusted, as described in section |
| 9145 | ~~SECTauthparamail. Unless the data is the string `@<@>', it is set as the |
| 9146 | authenticated sender of the message, and the value is available during delivery |
| 9147 | in the \$authenticated@_sender$\ variable. If the sender is not trusted, Exim |
| 9148 | accepts the syntax of \\AUTH=\\, but ignores the data. |
| 9149 | |
| 9150 | When a message is submitted locally (that is, not over a TCP connection), the |
| 9151 | value of \$authenticated@_sender$\ is an address constructed from the login |
| 9152 | name of the calling process and \$qualify@_domain$\. |
| 9153 | |
| 9154 | |
| 9155 | .index authentication||failure |
| 9156 | .tempindent 0 |
| 9157 | \$authentication@_failed$\: |
| 9158 | This variable is set to `1' in an Exim server if a client issues an \\AUTH\\ |
| 9159 | command that does not succeed. Otherwise it is set to `0'. This makes it |
| 9160 | possible to distinguish between `did not try to authenticate' |
| 9161 | (\$sender@_host@_authenticated$\ is empty and \$authentication__failed$\ is set |
| 9162 | to `0') and `tried to authenticate but failed' (\$sender@_host@_authenticated$\ |
| 9163 | is empty and \$authentication@_failed$\ is set to `1'). Failure includes any |
| 9164 | negative response to an \\AUTH\\ command, including (for example) an attempt to |
| 9165 | use an undefined mechanism. |
| 9166 | |
| 9167 | |
| 9168 | .index message||body, line count |
| 9169 | .index body of message||line count |
| 9170 | .tempindent 0 |
| 9171 | \$body@_linecount$\: |
| 9172 | When a message is being received or delivered, this variable contains the |
| 9173 | number of lines in the message's body. |
| 9174 | |
| 9175 | .index message||body, binary zero count |
| 9176 | .index body of message||binary zero count |
| 9177 | .index binary zero||in message body |
| 9178 | .tempindent 0 |
| 9179 | \$body@_zerocount$\: |
| 9180 | When a message is being received or delivered, this variable contains the |
| 9181 | number of binary zero bytes in the message's body. |
| 9182 | |
| 9183 | .tempindent 0 |
| 9184 | \$bounce@_recipient$\: |
| 9185 | This is set to the recipient address of a bounce message while Exim is creating |
| 9186 | it. It is useful if a customized bounce message text file is in use (see |
| 9187 | chapter ~~CHAPemsgcust). |
| 9188 | |
| 9189 | .tempindent 0 |
| 9190 | \$bounce@_return@_size@_limit$\: This contains the value set in the |
| 9191 | \bounce@_return@_size@_limit\ option, rounded up to a multiple of 1000. It is |
| 9192 | useful when a customized error message text file is in use (see chapter |
| 9193 | ~~CHAPemsgcust). |
| 9194 | |
| 9195 | .index gid (group id)||caller |
| 9196 | .tempindent 0 |
| 9197 | \$caller@_gid$\: The |
| 9198 | real |
| 9199 | group id under which the process that called Exim was |
| 9200 | running. This is not the same as the group id of the originator of a message |
| 9201 | (see \$originator@_gid$\). If Exim re-execs itself, this variable in the new |
| 9202 | incarnation normally contains the Exim gid. |
| 9203 | |
| 9204 | .index uid (user id)||caller |
| 9205 | .tempindent 0 |
| 9206 | \$caller@_uid$\: The |
| 9207 | real |
| 9208 | user id under which the process that called Exim was |
| 9209 | running. This is not the same as the user id of the originator of a message |
| 9210 | (see \$originator@_uid$\). If Exim re-execs itself, this variable in the new |
| 9211 | incarnation normally contains the Exim uid. |
| 9212 | |
| 9213 | .tempindent 0 |
| 9214 | \$compile@_date$\: The date on which the Exim binary was compiled. |
| 9215 | |
| 9216 | .tempindent 0 |
| 9217 | \$compile@_number$\: The building process for Exim keeps a count of the number |
| 9218 | of times it has been compiled. This serves to distinguish different |
| 9219 | compilations of the same version of the program. |
| 9220 | |
| 9221 | .index black list (DNS) |
| 9222 | .tempindent 0 |
| 9223 | \$dnslist@_domain$\: When a client host is found to be on a DNS (black) list, |
| 9224 | the list's domain name is put into this variable so that it can be included in |
| 9225 | the rejection message. |
| 9226 | |
| 9227 | .tempindent 0 |
| 9228 | \$dnslist@_text$\: When a client host is found to be on a DNS (black) list, the |
| 9229 | contents of any associated TXT record are placed in this variable. |
| 9230 | |
| 9231 | .tempindent 0 |
| 9232 | \$dnslist@_value$\: When a client host is found to be on a DNS (black) list, |
| 9233 | the IP address from the resource record is placed in this variable. |
| 9234 | If there are multiple records, all the addresses are included, comma-space |
| 9235 | separated. |
| 9236 | |
| 9237 | .tempindent 0 |
| 9238 | \$domain$\: When an address is being routed, or delivered on its own, this |
| 9239 | variable contains the domain. Global address rewriting happens when a message |
| 9240 | is received, so the value of \$domain$\ during routing and delivery is the |
| 9241 | value after rewriting. \$domain$\ is set during user filtering, but not during |
| 9242 | system filtering, because a message may have many recipients and the system |
| 9243 | filter is called just once. |
| 9244 | |
| 9245 | When more than one address is being delivered at once (for example, several |
| 9246 | \\RCPT\\ commands in one SMTP delivery), \$domain$\ is set only if they all |
| 9247 | have the same domain. Transports can be restricted to handling only one domain |
| 9248 | at a time if the value of \$domain$\ is required at transport time -- this is |
| 9249 | the default for local transports. For further details of the environment in |
| 9250 | which local transports are run, see chapter ~~CHAPenvironment. |
| 9251 | |
| 9252 | .index \delay@_warning@_condition\ |
| 9253 | At the end of a delivery, if all deferred addresses have the same domain, it is |
| 9254 | set in \$domain$\ during the expansion of \delay@_warning@_condition\. |
| 9255 | |
| 9256 | The \$domain$\ variable is also used in some other circumstances: |
| 9257 | .numberpars $. |
| 9258 | When an ACL is running for a \\RCPT\\ command, \$domain$\ contains the domain |
| 9259 | of the recipient address. |
| 9260 | \**Note:**\ the domain of the sender address is in \$sender@_address@_domain$\ |
| 9261 | at \\MAIL\\ time and at \\RCPT\\ time. \$domain$\ is not set for the \\MAIL\\ |
| 9262 | ACL. |
| 9263 | .nextp |
| 9264 | When a rewrite item is being processed (see chapter ~~CHAPrewrite), \$domain$\ |
| 9265 | contains the domain portion of the address that is being rewritten; it can be |
| 9266 | used in the expansion of the replacement address, for example, to rewrite |
| 9267 | domains by file lookup. |
| 9268 | .nextp |
| 9269 | With one important exception, whenever a domain list is being scanned, |
| 9270 | \$domain$\ contains the subject domain. \**Exception**\: When a domain list in |
| 9271 | a \sender@_domains\ condition in an ACL is being processed, the subject domain |
| 9272 | is in \$sender@_address@_domain$\ and not in \$domain$\. It works this way so |
| 9273 | that, in a \\RCPT\\ ACL, the sender domain list can be dependent on the |
| 9274 | recipient domain (which is what is in \$domain$\ at this time). |
| 9275 | .nextp |
| 9276 | .index \\ETRN\\||value of \$domain$\ |
| 9277 | .index \smtp@_etrn@_command\ |
| 9278 | When the \smtp@_etrn@_command\ option is being expanded, \$domain$\ contains |
| 9279 | the complete argument of the \\ETRN\\ command (see section ~~SECTETRN). |
| 9280 | .endp |
| 9281 | |
| 9282 | .tempindent 0 |
| 9283 | \$domain@_data$\: When the \domains\ option on a router matches a domain by |
| 9284 | means of a lookup, the data read by the lookup is available during the running |
| 9285 | of the router as \$domain@_data$\. In addition, if the driver routes the |
| 9286 | address to a transport, the value is available in that transport. If the |
| 9287 | transport is handling multiple addresses, the value from the first address is |
| 9288 | used. |
| 9289 | |
| 9290 | \$domain@_data$\ is also set when the \domains\ condition in an ACL matches a |
| 9291 | domain by means of a lookup. The data read by the lookup is available during |
| 9292 | the rest of the ACL statement. In all other situations, this variable expands |
| 9293 | to nothing. |
| 9294 | |
| 9295 | .tempindent 0 |
| 9296 | \$exim@_gid$\: This variable contains the numerical value of the Exim group id. |
| 9297 | |
| 9298 | .tempindent 0 |
| 9299 | \$exim@_path$\: This variable contains the path to the Exim binary. |
| 9300 | |
| 9301 | .tempindent 0 |
| 9302 | \$exim@_uid$\: This variable contains the numerical value of the Exim user id. |
| 9303 | |
| 9304 | .tempindent 0 |
| 9305 | \$header@_<<name>>$\: This is not strictly an expansion variable. It is |
| 9306 | expansion syntax for inserting the message header line with the given name. |
| 9307 | Note that the name must be terminated by colon or white space, because it may |
| 9308 | contain a wide variety of characters. |
| 9309 | Note also that braces must \*not*\ be used. |
| 9310 | |
| 9311 | .tempindent 0 |
| 9312 | \$home$\: |
| 9313 | When the \check@_local@_user\ option is set for a router, the user's home |
| 9314 | directory is placed in \$home$\ when the check succeeds. In particular, this |
| 9315 | means it is set during the running of users' filter files. A router may also |
| 9316 | explicitly set a home directory for use by a transport; this can be overridden |
| 9317 | by a setting on the transport itself. |
| 9318 | |
| 9319 | When running a filter test via the \-bf-\ option, \$home$\ is set to the value |
| 9320 | of the environment variable \\HOME\\. |
| 9321 | |
| 9322 | .tempindent 0 |
| 9323 | \$host$\: |
| 9324 | When the \%smtp%\ transport is expanding its options for encryption using TLS, |
| 9325 | \$host$\ contains the name of the host to which it is connected. Likewise, when |
| 9326 | used in the client part of an authenticator configuration (see chapter |
| 9327 | ~~CHAPSMTPAUTH), \$host$\ contains the name of the server to which the client |
| 9328 | is connected. |
| 9329 | .index transport||filter |
| 9330 | .index filter||transport filter |
| 9331 | When used in a transport filter (see chapter ~~CHAPtransportgeneric) \$host$\ |
| 9332 | refers to the host involved in the current connection. When a local transport |
| 9333 | is run as a result of a router that sets up a host list, \$host$\ contains the |
| 9334 | name of the first host. |
| 9335 | |
| 9336 | .tempindent 0 |
| 9337 | \$host@_address$\: |
| 9338 | This variable is set to the remote host's IP address whenever \$host$\ is set |
| 9339 | for a remote connection. |
| 9340 | |
| 9341 | .tempindent 0 |
| 9342 | \$host@_data$\: |
| 9343 | If a \hosts\ condition in an ACL is satisfied by means of a lookup, the result |
| 9344 | of the lookup is made available in the \$host@_data$\ variable. This |
| 9345 | allows you, for example, to do things like this: |
| 9346 | .display asis |
| 9347 | deny hosts = net-lsearch;/some/file |
| 9348 | message = $host_data |
| 9349 | .endd |
| 9350 | |
| 9351 | .index host||name lookup, failure of |
| 9352 | .tempindent 0 |
| 9353 | \$host@_lookup@_failed$\: |
| 9354 | This variable contains `1' if the message came from a remote host and there was |
| 9355 | an attempt to look up the host's name from its IP address, but the attempt |
| 9356 | failed. Otherwise the value of the variable is `0'. |
| 9357 | Exim checks that a forward lookup of at least one of the names it receives from |
| 9358 | a reverse lookup yields the original IP address. If this is not the case, Exim |
| 9359 | does not accept the looked up name(s), and \$host@_lookup@_failed$\ is set to |
| 9360 | `1'. Thus, being able to find a name from an IP address (for example, the |
| 9361 | existence of a PTR record in the DNS) is not sufficient on its own for the |
| 9362 | success of a host name lookup. |
| 9363 | |
| 9364 | .tempindent 0 |
| 9365 | \$inode$\: |
| 9366 | The only time this variable is set is while expanding the \directory@_file\ |
| 9367 | option in the \%appendfile%\ transport. The variable contains the inode number |
| 9368 | of the temporary file which is about to be renamed. It can be used to construct |
| 9369 | a unique name for the file. |
| 9370 | |
| 9371 | .tempindent 0 |
| 9372 | \$interface@_address$\: |
| 9373 | When a message is received over a TCP/IP connection, this variable contains the |
| 9374 | address of the local IP interface. See also the \-oMi-\ command line option. |
| 9375 | This variable can be used in ACLs and also, for example, to make the file name |
| 9376 | for a TLS certificate depend on which interface is being used. |
| 9377 | |
| 9378 | .tempindent 0 |
| 9379 | \$interface@_port$\: |
| 9380 | When a message is received over a TCP/IP connection, this variable contains the |
| 9381 | local port number. See also the \-oMi-\ command line option. |
| 9382 | This variable can be used in ACLs and also, for example, to make the file name |
| 9383 | for a TLS certificate depend on which port is being used. |
| 9384 | |
| 9385 | .tempindent 0 |
| 9386 | \$ldap@_dn$\: |
| 9387 | This variable, which is available only when Exim is compiled with LDAP support, |
| 9388 | contains the DN from the last entry in the most recently successful LDAP |
| 9389 | lookup. |
| 9390 | |
| 9391 | |
| 9392 | .tempindent 0 |
| 9393 | \$load@_average$\: |
| 9394 | This variable contains the system load average, multiplied by 1000 to that it |
| 9395 | is an integer. For example, if the load average is 0.21, the value of the |
| 9396 | variable is 210. The value is recomputed every time the variable is referenced. |
| 9397 | |
| 9398 | .tempindent 0 |
| 9399 | \$local@_part$\: When an address is being routed, or delivered on its own, this |
| 9400 | variable contains the local part. When a number of addresses are being |
| 9401 | delivered together (for example, multiple \\RCPT\\ commands in an SMTP |
| 9402 | session), \$local@_part$\ is not set. |
| 9403 | |
| 9404 | Global address rewriting happens when a message is received, so the value of |
| 9405 | \$local@_part$\ during routing and delivery is the value after rewriting. |
| 9406 | \$local@_part$\ is set during user filtering, but not during system filtering, |
| 9407 | because a message may have many recipients and the system filter is called just |
| 9408 | once. |
| 9409 | |
| 9410 | If a local part prefix or suffix has been recognized, it is not included in the |
| 9411 | value of \$local@_part$\ during routing and subsequent delivery. The values of |
| 9412 | any prefix or suffix are in \$local@_part@_prefix$\ and |
| 9413 | \$local@_part@_suffix$\, respectively. |
| 9414 | |
| 9415 | When a message is being delivered to a file, pipe, or autoreply transport as a |
| 9416 | result of aliasing or forwarding, \$local@_part$\ is set to the local part of |
| 9417 | the parent address, not to the file name or command (see \$address@_file$\ and |
| 9418 | \$address@_pipe$\). |
| 9419 | |
| 9420 | When an ACL is running for a \\RCPT\\ command, \$local@_part$\ contains the |
| 9421 | local part of the recipient address. |
| 9422 | |
| 9423 | When a rewrite item is being processed (see chapter ~~CHAPrewrite), |
| 9424 | \$local@_part$\ contains the local part of the address that is being rewritten; |
| 9425 | it can be used in the expansion of the replacement address, for example. |
| 9426 | |
| 9427 | In all cases, all quoting is removed from the local part. For example, for both |
| 9428 | the addresses |
| 9429 | .display asis |
| 9430 | "abc:xyz"@test.example |
| 9431 | abc\:xyz@test.example |
| 9432 | .endd |
| 9433 | the value of \$local@_part$\ is |
| 9434 | .display asis |
| 9435 | abc:xyz |
| 9436 | .endd |
| 9437 | If you use \$local@_part$\ to create another address, you should always wrap it |
| 9438 | inside a quoting operator. For example, in a \%redirect%\ router you could have: |
| 9439 | .display asis |
| 9440 | data = ${quote_local_part:$local_part}@new.domain.example |
| 9441 | .endd |
| 9442 | \**Note**\: The value of \$local@_part$\ is normally lower cased. If you want |
| 9443 | to process local parts in a case-dependent manner in a router, you can set the |
| 9444 | \caseful@_local@_part\ option (see chapter ~~CHAProutergeneric). |
| 9445 | |
| 9446 | .tempindent 0 |
| 9447 | \$local@_part@_data$\: |
| 9448 | When the \local@_parts\ option on a router matches a local part by means of a |
| 9449 | lookup, the data read by the lookup is available during the running of the |
| 9450 | router as \$local@_part@_data$\. In addition, if the driver routes the address |
| 9451 | to a transport, the value is available in that transport. If the transport is |
| 9452 | handling multiple addresses, the value from the first address is used. |
| 9453 | |
| 9454 | \$local@_part@_data$\ is also set when the \local@_parts\ condition in an ACL |
| 9455 | matches a local part by means of a lookup. The data read by the lookup is |
| 9456 | available during the rest of the ACL statement. In all other situations, this |
| 9457 | variable expands to nothing. |
| 9458 | |
| 9459 | .tempindent 0 |
| 9460 | \$local@_part@_prefix$\: When an address is being routed or delivered, and a |
| 9461 | specific prefix for the local part was recognized, it is available in this |
| 9462 | variable, having been removed from \$local@_part$\. |
| 9463 | |
| 9464 | .tempindent 0 |
| 9465 | \$local@_part@_suffix$\: When an address is being routed or delivered, and a |
| 9466 | specific suffix for the local part was recognized, it is available in this |
| 9467 | variable, having been removed from \$local@_part$\. |
| 9468 | |
| 9469 | .tempindent 0 |
| 9470 | \$local@_scan@_data$\: This variable contains the text returned by the |
| 9471 | \*local@_scan()*\ function when a message is received. See chapter |
| 9472 | ~~CHAPlocalscan for more details. |
| 9473 | |
| 9474 | .tempindent 0 |
| 9475 | \$local@_user@_gid$\: See \$local@_user@_uid$\. |
| 9476 | |
| 9477 | .tempindent 0 |
| 9478 | \$local@_user@_uid$\: This variable and \$local@_user@_gid$\ are set to |
| 9479 | the uid and gid after the \check__local__user\ router precondition succeeds. |
| 9480 | This means that their values are available for the remaining preconditions |
| 9481 | (\senders\, \require@_files\, and \condition\), for the \address@_data\ |
| 9482 | expansion, and for any router-specific expansions. At all other times, the |
| 9483 | values in these variables are \"(uid@_t)(-1)"\ and \"(gid@_t)(-1)"\, |
| 9484 | respectively. |
| 9485 | |
| 9486 | |
| 9487 | .tempindent 0 |
| 9488 | \$localhost@_number$\: This contains the expanded value of the |
| 9489 | \localhost@_number\ option. The expansion happens after the main options have |
| 9490 | been read. |
| 9491 | |
| 9492 | .tempindent 0 |
| 9493 | \$mailstore@_basename$\: This variable is set only when doing deliveries in |
| 9494 | `mailstore' format in the \%appendfile%\ transport. During the expansion of the |
| 9495 | \mailstore@_prefix\, \mailstore@_suffix\, \message__prefix\, and |
| 9496 | \message@_suffix\ options, it contains the basename of the files that are being |
| 9497 | written, that is, the name without the `.tmp', `.env', or `.msg' suffix. At all |
| 9498 | other times, this variable is empty. |
| 9499 | |
| 9500 | .index message||age of |
| 9501 | .tempindent 0 |
| 9502 | \$message@_age$\: This variable is set at the start of a delivery attempt to |
| 9503 | contain the number of seconds since the message was received. It does not |
| 9504 | change during a single delivery attempt. |
| 9505 | |
| 9506 | .index body of message||expansion variable |
| 9507 | .index message||body, in expansion |
| 9508 | .index binary zero||in message body |
| 9509 | .tempindent 0 |
| 9510 | \$message@_body$\: This variable contains the initial portion of a message's |
| 9511 | body while it is being delivered, and is intended mainly for use in filter |
| 9512 | files. The maximum number of characters of the body that are put into the |
| 9513 | variable is set by the \message@_body@_visible\ configuration option; the |
| 9514 | default is 500. Newlines are converted into spaces to make it easier to search |
| 9515 | for phrases that might be split over a line break. |
| 9516 | Binary zeros are also converted into spaces. |
| 9517 | |
| 9518 | .index body of message||expansion variable |
| 9519 | .index message||body, in expansion |
| 9520 | .tempindent 0 |
| 9521 | \$message@_body@_end$\: This variable contains the final portion of a message's |
| 9522 | body while it is being delivered. The format and maximum size are as for |
| 9523 | \$message@_body$\. |
| 9524 | |
| 9525 | .index body of message||size |
| 9526 | .index message||body, size |
| 9527 | .tempindent 0 |
| 9528 | \$message@_body@_size$\: When a message is being processed, this variable |
| 9529 | contains the size of the body in bytes. The count starts from the character |
| 9530 | after the blank line that separates the body from the header. Newlines are |
| 9531 | included in the count. See also \$message@_size$\ and \$body@_linecount$\. |
| 9532 | |
| 9533 | .tempindent 0 |
| 9534 | \$message@_headers$\: |
| 9535 | This variable contains a concatenation of all the header lines when a message |
| 9536 | is being processed, except for lines added by routers or transports. The header |
| 9537 | lines are separated by newline characters. |
| 9538 | |
| 9539 | .tempindent 0 |
| 9540 | \$message@_id$\: |
| 9541 | When a message is being received or delivered, this variable contains the |
| 9542 | unique message id that is used by Exim to identify the message. |
| 9543 | An id is not created for a message until after its header has been |
| 9544 | successfully received. |
| 9545 | \**Note**\: This is \*not*\ the contents of the ::Message-ID:: header line; it |
| 9546 | is the local id that Exim assigns to the message, for example: |
| 9547 | \"1BXTIK-0001yO-VA"\. |
| 9548 | |
| 9549 | .index size||of message |
| 9550 | .index message||size |
| 9551 | .tempindent 0 |
| 9552 | \$message@_size$\: |
| 9553 | When a message is being processed, this variable contains its size in bytes. In |
| 9554 | most cases, the size includes those headers that were received with the |
| 9555 | message, but not those (such as ::Envelope-to::) that are added to individual |
| 9556 | deliveries as they are written. However, there is one special case: during the |
| 9557 | expansion of the \maildir@_tag\ option in the \%appendfile%\ transport while |
| 9558 | doing a delivery in maildir format, the value of \$message@_size$\ is the |
| 9559 | precise size of the file that has been written. See also |
| 9560 | \$message@_body@_size$\ and \$body@_linecount$\. |
| 9561 | |
| 9562 | .index \\RCPT\\||value of \$message@_size$\ |
| 9563 | While running an ACL at the time of an SMTP \\RCPT\\ command, \$message@_size$\ |
| 9564 | contains the size supplied on the \\MAIL\\ command, or |
| 9565 | -1 |
| 9566 | if no size was given. The value may not, of course, be truthful. |
| 9567 | |
| 9568 | .tempindent 0 |
| 9569 | \$n0$\ -- \$n9$\: These variables are counters that can be incremented by means |
| 9570 | of the \add\ command in filter files. |
| 9571 | |
| 9572 | .tempindent 0 |
| 9573 | \$original@_domain$\: When a top-level address is being processed for delivery, |
| 9574 | this contains the same value as \$domain$\. However, if a `child' address (for |
| 9575 | example, generated by an alias, forward, or filter file) is being processed, |
| 9576 | this variable contains the domain of the original address. This differs from |
| 9577 | \$parent@_domain$\ only when there is more than one level of aliasing or |
| 9578 | forwarding. When more than one address is being delivered in a single transport |
| 9579 | run, \$original@_domain$\ is not set. |
| 9580 | |
| 9581 | If new an address is created by means of a \deliver\ command in a system |
| 9582 | filter, it is set up with an artificial `parent' address. This has the local |
| 9583 | part \*system-filter*\ and the default qualify domain. |
| 9584 | |
| 9585 | .tempindent 0 |
| 9586 | \$original@_local@_part$\: When a top-level address is being processed for |
| 9587 | delivery, this contains the same value as \$local@_part$\, unless a prefix or |
| 9588 | suffix was removed from the local part, in which case \$original@_local@_part$\ |
| 9589 | contains the full local part. When a `child' address (for example, generated by |
| 9590 | an alias, forward, or filter file) is being processed, this variable contains |
| 9591 | the full local part of the original address. If the router that did the |
| 9592 | redirection processed the local part case-insensitively, the value in |
| 9593 | \$original@_local@_part$\ is in lower case. This variable differs from |
| 9594 | \$parent@_local@_part$\ only when there is more than one level of aliasing or |
| 9595 | forwarding. When more than one address is being delivered in a single transport |
| 9596 | run, \$original@_local@_part$\ is not set. |
| 9597 | |
| 9598 | If new an address is created by means of a \deliver\ command in a system |
| 9599 | filter, it is set up with an artificial `parent' address. This has the local |
| 9600 | part \*system-filter*\ and the default qualify domain. |
| 9601 | |
| 9602 | |
| 9603 | .index gid (group id)||of originating user |
| 9604 | .index sender||gid |
| 9605 | .tempindent 0 |
| 9606 | \$originator@_gid$\: The value of \$caller@_gid$\ that was set when the message |
| 9607 | was received. For messages received via the command line, this is the gid of |
| 9608 | the sending user. For messages received by SMTP over TCP/IP, this is normally |
| 9609 | the gid of the Exim user. |
| 9610 | |
| 9611 | .index uid (user id)||of originating user |
| 9612 | .index sender||uid |
| 9613 | .tempindent 0 |
| 9614 | \$originator@_uid$\: The value of \$caller@_uid$\ that was set when the message |
| 9615 | was received. For messages received via the command line, this is the uid of |
| 9616 | the sending user. For messages received by SMTP over TCP/IP, this is normally |
| 9617 | the uid of the Exim user. |
| 9618 | |
| 9619 | .tempindent 0 |
| 9620 | \$parent@_domain$\: This variable is similar to \$original@_domain$\ (see |
| 9621 | above), except that it refers to the immediately preceding parent address. |
| 9622 | |
| 9623 | .tempindent 0 |
| 9624 | \$parent@_local@_part$\: This variable is similar to \$original@_local@_part$\ |
| 9625 | (see above), except that it refers to the immediately preceding parent address. |
| 9626 | |
| 9627 | .index pid (process id)||of current process |
| 9628 | .tempindent 0 |
| 9629 | \$pid$\: This variable contains the current process id. |
| 9630 | |
| 9631 | .index filter||transport filter |
| 9632 | .index transport||filter |
| 9633 | .tempindent 0 |
| 9634 | \$pipe@_addresses$\: This is not an expansion variable, but is mentioned here |
| 9635 | because the string `@$pipe@_addresses' is handled specially in the command |
| 9636 | specification for the \%pipe%\ transport (chapter ~~CHAPpipetransport) and in |
| 9637 | transport filters (described under \transport@_filter\ in chapter |
| 9638 | ~~CHAPtransportgeneric). It cannot be used in general expansion strings, and |
| 9639 | provokes an `unknown variable' error if encountered. |
| 9640 | |
| 9641 | .tempindent 0 |
| 9642 | \$primary@_hostname$\: The value set in the configuration file, or read by the |
| 9643 | \*uname()*\ function. If \*uname()*\ returns a single-component name, Exim |
| 9644 | calls \*gethostbyname()*\ (or \*getipnodebyname()*\ where available) in an |
| 9645 | attempt to acquire a fully qualified host name. |
| 9646 | See also \$smtp@_active@_hostname$\. |
| 9647 | |
| 9648 | .tempindent 0 |
| 9649 | \$qualify@_domain$\: The value set for this option in the configuration file. |
| 9650 | |
| 9651 | .tempindent 0 |
| 9652 | \$qualify@_recipient$\: The value set for this option in the configuration file, |
| 9653 | or if not set, the value of \$qualify@_domain$\. |
| 9654 | |
| 9655 | .tempindent 0 |
| 9656 | \$rcpt@_count$\: When a message is being received by SMTP, this variable |
| 9657 | contains the number of \\RCPT\\ commands received for the current message. If |
| 9658 | this variable is used in a \\RCPT\\ ACL, its value includes the current |
| 9659 | command. |
| 9660 | |
| 9661 | .tempindent 0 |
| 9662 | \$rcpt@_defer@_count$\: When a message is being received by SMTP, this variable |
| 9663 | contains the number of \\RCPT\\ commands in the current message that have |
| 9664 | previously been rejected with a temporary (4\*xx*\) response. |
| 9665 | |
| 9666 | .tempindent 0 |
| 9667 | \$rcpt@_fail@_count$\: When a message is being received by SMTP, this variable |
| 9668 | contains the number of \\RCPT\\ commands in the current message that have |
| 9669 | previously been rejected with a permanent (5\*xx*\) response. |
| 9670 | |
| 9671 | .tempindent 0 |
| 9672 | \$received@_count$\: This variable contains the number of ::Received:: header |
| 9673 | lines in the message, including the one added by Exim (so its value is always |
| 9674 | greater than zero). It is available in the \\DATA\\ ACL, the non-SMTP ACL, and |
| 9675 | while routing and delivering. |
| 9676 | |
| 9677 | .tempindent 0 |
| 9678 | \$received@_for$\: If there is only a single recipient address in an incoming |
| 9679 | message, this variable contains that address when the ::Received:: header line |
| 9680 | is being built. |
| 9681 | The value is copied after recipient rewriting has happened, but before the |
| 9682 | \*local@_scan()*\ function is run. |
| 9683 | |
| 9684 | .tempindent 0 |
| 9685 | \$received@_protocol$\: When a message is being processed, this variable |
| 9686 | contains the name of the protocol by which it was received. See also the |
| 9687 | \-oMr-\ option. |
| 9688 | |
| 9689 | .tempindent 0 |
| 9690 | \$recipient@_data$\: This variable is set after an indexing lookup success in |
| 9691 | an ACL \recipients\ condition. It contains the data from the lookup, and the |
| 9692 | value remains set until the next \recipients\ test. Thus, you can do things |
| 9693 | like this: |
| 9694 | .display |
| 9695 | require recipients = cdb*@@;/some/file |
| 9696 | deny \*some further test involving*\ @$recipient@_data |
| 9697 | .endd |
| 9698 | \**Warning**\: This variable is set only when a lookup is used as an indexing |
| 9699 | method in the address list, using the semicolon syntax as in the example above. |
| 9700 | The variable is not set for a lookup that is used as part of the string |
| 9701 | expansion that all such lists undergo before being interpreted. |
| 9702 | |
| 9703 | .tempindent 0 |
| 9704 | \$recipients$\: This variable contains a list of envelope recipients for a |
| 9705 | message. A comma and a space separate the addresses in the replacement text. |
| 9706 | However, the variable is not generally available, to prevent exposure of Bcc |
| 9707 | recipients in unprivileged users' filter files. You can use \$recipients$\ only |
| 9708 | .numberpars |
| 9709 | In a system filter file. |
| 9710 | .nextp |
| 9711 | In the \\DATA\\ or non-SMTP ACL, that is, in the final ACL for accepting a |
| 9712 | message. |
| 9713 | .endp |
| 9714 | |
| 9715 | .tempindent 0 |
| 9716 | \$recipients@_count$\: When a message is being processed, this variable |
| 9717 | contains the number of envelope recipients that came with the message. |
| 9718 | Duplicates are not excluded from the count. While a message is being received |
| 9719 | over SMTP, the number increases for each accepted recipient. It can be |
| 9720 | referenced in an ACL. |
| 9721 | |
| 9722 | .tempindent 0 |
| 9723 | \$reply@_address$\: When a message is being processed, this variable contains |
| 9724 | the contents of the ::Reply-To:: header line if one exists |
| 9725 | and it is not empty, |
| 9726 | or otherwise the contents of the ::From:: header line. |
| 9727 | |
| 9728 | .tempindent 0 |
| 9729 | \$return@_path$\: When a message is being delivered, this variable contains the |
| 9730 | return path -- the sender field that will be sent as part of the envelope. It |
| 9731 | is not enclosed in @<@> characters. |
| 9732 | At the start of routing an address, |
| 9733 | \$return@_path$\ has the same value as \$sender@_address$\, but if, for |
| 9734 | example, an incoming message to a mailing list has been expanded by a router |
| 9735 | which specifies a different address for bounce messages, \$return@_path$\ |
| 9736 | subsequently contains the new bounce address, whereas \$sender@_address$\ |
| 9737 | always contains the original sender address that was received with the message. |
| 9738 | In other words, \$sender@_address$\ contains the incoming envelope sender, and |
| 9739 | \$return@_path$\ contains the outgoing envelope sender. |
| 9740 | |
| 9741 | .tempindent 0 |
| 9742 | \$return@_size@_limit$\: This is an obsolete name for |
| 9743 | \$bounce@_return@_size@_limit$\. |
| 9744 | |
| 9745 | .index return code||from \run\ expansion |
| 9746 | .tempindent 0 |
| 9747 | \$runrc$\: This variable contains the return code from a command that is run by |
| 9748 | the \@$@{run...@}\ expansion item. |
| 9749 | \**Warning**\: In a router or transport, you cannot assume the order in which |
| 9750 | option values are expanded, except for those pre-conditions whose order of |
| 9751 | testing is documented. Therefore, you cannot reliably expect to set \$runrc$\ |
| 9752 | by the expansion of one option, and use it in another. |
| 9753 | |
| 9754 | .tempindent 0 |
| 9755 | \$self@_hostname$\: When an address is routed to a supposedly remote host that |
| 9756 | turns out to be the local host, what happens is controlled by the |
| 9757 | .index \self\ option||value of host name |
| 9758 | \self\ generic router option. One of its values causes the address to be passed |
| 9759 | to another router. When this happens, \$self@_hostname$\ is set to the name of |
| 9760 | the local host that the original router encountered. In other circumstances its |
| 9761 | contents are null. |
| 9762 | |
| 9763 | .tempindent 0 |
| 9764 | \$sender@_address$\: When a message is being processed, this variable contains |
| 9765 | the sender's address that was received in the message's envelope. For bounce |
| 9766 | messages, the value of this variable is the empty string. |
| 9767 | See also \$return@_path$\. |
| 9768 | |
| 9769 | .tempindent 0 |
| 9770 | \$sender@_address@_domain$\: The domain portion of \$sender@_address$\. |
| 9771 | |
| 9772 | .tempindent 0 |
| 9773 | \$sender@_address@_local@_part$\: The local part portion of \$sender@_address$\. |
| 9774 | |
| 9775 | .tempindent 0 |
| 9776 | \$sender@_data$\: This variable is set after a lookup success in an ACL |
| 9777 | \senders\ condition or in a router \senders\ option. It contains the data from |
| 9778 | the lookup, and the value remains set until the next \senders\ test. Thus, you |
| 9779 | can do things like this: |
| 9780 | .display |
| 9781 | require senders = cdb*@@;/some/file |
| 9782 | deny \*some further test involving*\ @$sender@_data |
| 9783 | .endd |
| 9784 | \**Warning**\: This variable is set only when a lookup is used as an indexing |
| 9785 | method in the address list, using the semicolon syntax as in the example above. |
| 9786 | The variable is not set for a lookup that is used as part of the string |
| 9787 | expansion that all such lists undergo before being interpreted. |
| 9788 | |
| 9789 | .tempindent 0 |
| 9790 | \$sender@_fullhost$\: When a message is received from a remote host, this |
| 9791 | variable contains the host name and IP address in a single string. It ends |
| 9792 | with the IP address in square brackets, followed by a colon and a port number |
| 9793 | if the logging of ports is enabled. The format of the rest of the string |
| 9794 | depends on whether the host issued a \\HELO\\ or \\EHLO\\ SMTP command, and |
| 9795 | whether the host name was verified by looking up its IP address. (Looking up |
| 9796 | the IP address can be forced by the \host@_lookup\ option, independent of |
| 9797 | verification.) A plain host name at the start of the string is a verified host |
| 9798 | name; if this is not present, verification either failed or was not requested. |
| 9799 | A host name in parentheses is the argument of a \\HELO\\ or \\EHLO\\ command. |
| 9800 | This is omitted if it is identical to the verified host name or to the host's |
| 9801 | IP address in square brackets. |
| 9802 | |
| 9803 | .tempindent 0 |
| 9804 | \$sender@_helo@_name$\: When a message is received from a remote host that has |
| 9805 | issued a \\HELO\\ or \\EHLO\\ command, the argument of that command is placed |
| 9806 | in this variable. It is also set if \\HELO\\ or \\EHLO\\ is used when a message |
| 9807 | is received using SMTP locally via the \-bs-\ or \-bS-\ options. |
| 9808 | |
| 9809 | .tempindent 0 |
| 9810 | \$sender@_host@_address$\: When a message is received from a remote host, this |
| 9811 | variable contains that host's IP address. For locally submitted messages, it is |
| 9812 | empty. |
| 9813 | |
| 9814 | .tempindent 0 |
| 9815 | \$sender@_host@_authenticated$\: This variable contains the name (not the |
| 9816 | public name) of the authenticator driver which successfully authenticated the |
| 9817 | client from which the message was received. It is empty if there was no |
| 9818 | successful authentication. |
| 9819 | |
| 9820 | .tempindent 0 |
| 9821 | \$sender@_host@_name$\: When a message is received from a remote host, this |
| 9822 | variable contains the host's name as obtained by looking up its IP address. |
| 9823 | For messages received by other means, this variable is empty. |
| 9824 | |
| 9825 | If the host name has not previously been looked up, a reference to |
| 9826 | \$sender@_host@_name$\ triggers a lookup (for messages from remote hosts). |
| 9827 | A looked up name is accepted only if it leads back to the original IP address |
| 9828 | via a forward lookup. If either the reverse or the forward lookup fails, or if |
| 9829 | the forward lookup does not yield the original IP address, |
| 9830 | \$sender@_host@_name$\ remains empty, and \$host@_lookup@_failed$\ is set to |
| 9831 | `1'. |
| 9832 | |
| 9833 | Exim does not automatically look up every calling host's name. If you want |
| 9834 | maximum efficiency, you should arrange your configuration so that it avoids |
| 9835 | these lookups altogether. The lookup happens only if one or more of the |
| 9836 | following are true: |
| 9837 | .numberpars |
| 9838 | A string containing \$sender@_host@_name$\ is expanded. |
| 9839 | .nextp |
| 9840 | The calling host matches the list in \host@_lookup\. In the default |
| 9841 | configuration, this option is set to $*$, so it must be changed if lookups are |
| 9842 | to be avoided. (In the code, the default for \host@_lookup\ is unset.) |
| 9843 | .nextp |
| 9844 | Exim needs the host name in order to test an item in a host list. The items |
| 9845 | that require this are described in sections ~~SECThoslispatnam and |
| 9846 | ~~SECThoslispatnamsk. |
| 9847 | .nextp |
| 9848 | The calling host matches \helo@_try@_verify@_hosts\ or \helo@_verify@_hosts\. |
| 9849 | In this case, the host name is required to compare with the name quoted in any |
| 9850 | \\EHLO\\ or \\HELO\\ commands that the client issues. |
| 9851 | .nextp |
| 9852 | The remote host issues a \\EHLO\\ or \\HELO\\ command that quotes one of the |
| 9853 | domains in \helo@_lookup@_domains\. The default value of this option is |
| 9854 | .display asis |
| 9855 | helo_lookup_domains = @ : @[] |
| 9856 | .endd |
| 9857 | which causes a lookup if a remote host (incorrectly) gives the server's name or |
| 9858 | IP address in an \\EHLO\\ or \\HELO\\ command. |
| 9859 | .endp |
| 9860 | |
| 9861 | .tempindent 0 |
| 9862 | \$sender@_host@_port$\: When a message is received from a remote host, this |
| 9863 | variable contains the port number that was used on the remote host. |
| 9864 | |
| 9865 | .tempindent 0 |
| 9866 | \$sender@_ident$\: When a message is received from a remote host, this variable |
| 9867 | contains the identification received in response to an RFC 1413 request. When a |
| 9868 | message has been received locally, this variable contains the login name of the |
| 9869 | user that called Exim. |
| 9870 | |
| 9871 | .tempindent 0 |
| 9872 | \$sender@_rcvhost$\: This is provided specifically for use in ::Received:: |
| 9873 | headers. It starts with either the verified host name (as obtained from a |
| 9874 | .index DNS||reverse lookup |
| 9875 | .index reverse DNS lookup |
| 9876 | reverse DNS lookup) or, if there is no verified host name, the IP address in |
| 9877 | square brackets. After that there may be text in parentheses. When the first |
| 9878 | item is a verified host name, the first thing in the parentheses is the IP |
| 9879 | address in square brackets, followed by a colon and a port number if port |
| 9880 | logging is enabled. When the first item is an IP address, the port is recorded |
| 9881 | as `port=$it{xxxx}' inside the parentheses. |
| 9882 | |
| 9883 | There may also be items of the form `helo=$it{xxxx}' if \\HELO\\ or \\EHLO\\ |
| 9884 | was used and its argument was not identical to the real host name or IP |
| 9885 | address, and `ident=$it{xxxx}' if an RFC 1413 ident string is available. If all |
| 9886 | three items are present in the parentheses, a newline and tab are inserted into |
| 9887 | the string, to improve the formatting of the ::Received:: header. |
| 9888 | |
| 9889 | .index \\AUTH\\||argument |
| 9890 | .index \\EXPN\\||argument |
| 9891 | .index \\ETRN\\||argument |
| 9892 | .index \\VRFY\\||argument |
| 9893 | .tempindent 0 |
| 9894 | \$smtp@_command@_argument$\: While an ACL is running to check an \\AUTH\\, |
| 9895 | \\EHLO\\, \\EXPN\\, \\ETRN\\, \\HELO\\, or \\VRFY\\ command, this variable |
| 9896 | contains the argument for the SMTP command. |
| 9897 | |
| 9898 | .tempindent 0 |
| 9899 | \$sn0$\ -- \$sn9$\: These variables are copies of the values of the \$n0$\ |
| 9900 | -- \$n9$\ accumulators that were current at the end of the system filter file. |
| 9901 | This allows a system filter file to set values that can be tested in users' |
| 9902 | filter files. For example, a system filter could set a value indicating how |
| 9903 | likely it is that a message is junk mail. |
| 9904 | |
| 9905 | .tempindent 0 |
| 9906 | \$spool@_directory$\: The name of Exim's spool directory. |
| 9907 | |
| 9908 | .tempindent 0 |
| 9909 | \$thisaddress$\: This variable is set only during the processing of the |
| 9910 | \foranyaddress\ command in a filter file. Its use is explained in the |
| 9911 | description of that command. |
| 9912 | |
| 9913 | .tempindent 0 |
| 9914 | \$tls@_certificate@_verified$\: |
| 9915 | This variable is set to `1' if a TLS certificate was verified when the message |
| 9916 | was received, and `0' otherwise. |
| 9917 | |
| 9918 | .tempindent 0 |
| 9919 | \$tls@_cipher$\: When a message is received from a remote host over an |
| 9920 | encrypted SMTP connection, this variable is set to the cipher suite that was |
| 9921 | negotiated, for example DES-CBC3-SHA. |
| 9922 | In other circumstances, in particular, for message received over unencrypted |
| 9923 | connections, the variable is empty. |
| 9924 | See chapter ~~CHAPTLS for details of TLS support. |
| 9925 | |
| 9926 | .tempindent 0 |
| 9927 | \$tls@_peerdn$\: When a message is received from a remote host over an |
| 9928 | encrypted SMTP connection, |
| 9929 | and Exim is configured to request a certificate from the client, |
| 9930 | the value of the Distinguished Name of the certificate is made available in the |
| 9931 | \$tls@_peerdn$\ during subsequent processing. |
| 9932 | |
| 9933 | .tempindent 0 |
| 9934 | \$tod@_bsdinbox$\: The time of day and date, in the format required for |
| 9935 | BSD-style mailbox files, for example: Thu Oct 17 17:14:09 1995. |
| 9936 | |
| 9937 | .tempindent 0 |
| 9938 | \$tod@_epoch$\: The time and date as a number of seconds since the start of the |
| 9939 | Unix epoch. |
| 9940 | |
| 9941 | .tempindent 0 |
| 9942 | \$tod@_full$\: A full version of the time and date, for example: Wed, 16 Oct |
| 9943 | 1995 09:51:40 +0100. The timezone is always given as a numerical offset from |
| 9944 | UTC, with positive values used for timezones that are ahead (east) of UTC, and |
| 9945 | negative values for those that are behind (west). |
| 9946 | |
| 9947 | .tempindent 0 |
| 9948 | \$tod@_log$\: The time and date in the format used for writing Exim's log |
| 9949 | files, for example: 1995-10-12 15:32:29, |
| 9950 | but without a timezone. |
| 9951 | |
| 9952 | .tempindent 0 |
| 9953 | \$tod@_logfile$\: |
| 9954 | This variable contains the date in the format yyyymmdd. This is the format that |
| 9955 | is used for datestamping log files when \log@_file@_path\ contains the \"%D"\ |
| 9956 | flag. |
| 9957 | |
| 9958 | .tempindent 0 |
| 9959 | \$tod@_zone$\: This variable contains the numerical value of the local |
| 9960 | timezone, for example: -0500. |
| 9961 | |
| 9962 | .tempindent 0 |
| 9963 | \$tod@_zulu$\: |
| 9964 | This variable contains the UTC date and time in `Zulu' format, as specified by |
| 9965 | ISO 8601, for example: 20030221154023Z. |
| 9966 | |
| 9967 | .index \$value$\ |
| 9968 | .tempindent 0 |
| 9969 | \$value$\: This variable contains the result of an expansion lookup, extraction |
| 9970 | operation, or external command, as described above. |
| 9971 | |
| 9972 | .tempindent 0 |
| 9973 | \$version@_number$\: The version number of Exim. |
| 9974 | |
| 9975 | .tempindent 0 |
| 9976 | \$warn@_message@_delay$\: This variable is set only during the creation of a |
| 9977 | message warning about a delivery delay. Details of its use are explained in |
| 9978 | section ~~SECTcustwarn. |
| 9979 | |
| 9980 | .tempindent 0 |
| 9981 | \$warn@_message@_recipients$\: This variable is set only during the creation of |
| 9982 | a message warning about a delivery delay. Details of its use are explained in |
| 9983 | section ~~SECTcustwarn. |
| 9984 | .pop |
| 9985 | |
| 9986 | |
| 9987 | |
| 9988 | . |
| 9989 | . |
| 9990 | . ============================================================================ |
| 9991 | .chapter Embedded Perl |
| 9992 | .set runningfoot "embedded Perl" |
| 9993 | .rset CHAPperl "~~chapter" |
| 9994 | .index Perl||calling from Exim |
| 9995 | |
| 9996 | Exim can be built to include an embedded Perl interpreter. When this is done, |
| 9997 | Perl subroutines can be called as part of the string expansion process. To make |
| 9998 | use of the Perl support, you need version 5.004 or later of Perl installed on |
| 9999 | your system. To include the embedded interpreter in the Exim binary, include |
| 10000 | the line |
| 10001 | .display asis |
| 10002 | EXIM_PERL = perl.o |
| 10003 | .endd |
| 10004 | in your \(Local/Makefile)\ and then build Exim in the normal way. |
| 10005 | |
| 10006 | Access to Perl subroutines is via a global configuration option called |
| 10007 | .index \perl@_startup\ |
| 10008 | \perl@_startup\ and an expansion string operator \@$@{perl ...@}\. If there is |
| 10009 | no \perl@_startup\ option in the Exim configuration file then no Perl |
| 10010 | interpreter is started and there is almost no overhead for Exim (since none of |
| 10011 | the Perl library will be paged in unless used). If there is a \perl@_startup\ |
| 10012 | option then the associated value is taken to be Perl code which is executed in |
| 10013 | a newly created Perl interpreter. |
| 10014 | |
| 10015 | The value of \perl@_startup\ is not expanded in the Exim sense, so you do not |
| 10016 | need backslashes before any characters to escape special meanings. The option |
| 10017 | should usually be something like |
| 10018 | .display asis |
| 10019 | perl_startup = do '/etc/exim.pl' |
| 10020 | .endd |
| 10021 | where \(/etc/exim.pl)\ is Perl code which defines any subroutines you want to |
| 10022 | use from Exim. Exim can be configured either to start up a Perl interpreter as |
| 10023 | soon as it is entered, or to wait until the first time it is needed. Starting |
| 10024 | the interpreter at the beginning ensures that it is done while Exim still has |
| 10025 | its setuid privilege, but can impose an unnecessary overhead if Perl is not in |
| 10026 | fact used in a particular run. Also, note that this does not mean that Exim is |
| 10027 | necessarily running as root when Perl is called at a later time. By default, |
| 10028 | the interpreter is started only when it is needed, but this can be changed in |
| 10029 | two ways: |
| 10030 | .numberpars $. |
| 10031 | .index \perl@_at@_start\ |
| 10032 | Setting \perl@_at@_start\ (a boolean option) in the configuration requests |
| 10033 | a startup when Exim is entered. |
| 10034 | .nextp |
| 10035 | The command line option \-ps-\ also requests a startup when Exim is entered, |
| 10036 | overriding the setting of \perl@_at@_start\. |
| 10037 | .endp |
| 10038 | There is also a command line option \-pd-\ (for delay) which suppresses the |
| 10039 | initial startup, even if \perl@_at@_start\ is set. |
| 10040 | |
| 10041 | When the configuration file includes a \perl@_startup\ option you can make use |
| 10042 | of the string expansion item to call the Perl subroutines that are defined |
| 10043 | by the \perl@_startup\ code. The operator is used in any of the following |
| 10044 | forms: |
| 10045 | .display asis |
| 10046 | ${perl{foo}} |
| 10047 | ${perl{foo}{argument}} |
| 10048 | ${perl{foo}{argument1}{argument2} ... } |
| 10049 | .endd |
| 10050 | which calls the subroutine \foo\ with the given arguments. A maximum of eight |
| 10051 | arguments may be passed. Passing more than this results in an expansion failure |
| 10052 | with an error message of the form |
| 10053 | .display asis |
| 10054 | Too many arguments passed to Perl subroutine "foo" (max is 8) |
| 10055 | .endd |
| 10056 | The return value of the Perl subroutine is evaluated in a scalar context before |
| 10057 | it is passed back to Exim to be inserted into the expanded string. If the |
| 10058 | return value is \*undef*\, the expansion fails in the same way as an explicit |
| 10059 | `fail' on an \@$@{if ...@}\ or \@$@{lookup...@}\ item. |
| 10060 | If the subroutine aborts by obeying Perl's \die\ function, the expansion fails |
| 10061 | with the error message that was passed to \die\. |
| 10062 | |
| 10063 | Within any Perl code called from Exim, the function \*Exim@:@:expand@_string*\ |
| 10064 | is available to call back into Exim's string expansion function. For example, |
| 10065 | the Perl code |
| 10066 | .display asis |
| 10067 | my $lp = Exim::expand_string('$local_part'); |
| 10068 | .endd |
| 10069 | makes the current Exim \$local@_part$\ available in the Perl variable \$lp$\. |
| 10070 | Note those are single quotes and not double quotes to protect against |
| 10071 | \$local@_part$\ being interpolated as a Perl variable. |
| 10072 | |
| 10073 | If the string expansion is forced to fail by a `fail' item, the result of |
| 10074 | \*Exim@:@:expand@_string*\ is \undef\. If there is a syntax error in the |
| 10075 | expansion string, the Perl call from the original expansion string fails with |
| 10076 | an appropriate error message, in the same way as if \die\ were used. |
| 10077 | |
| 10078 | .index debugging||from embedded Perl |
| 10079 | .index log||writing from embedded Perl |
| 10080 | Two other Exim functions are available for use from within Perl code. |
| 10081 | \*Exim@:@:debug@_write(<<string>>)*\ writes the string to the standard error |
| 10082 | stream if Exim's debugging is enabled. If you want a newline at the end, you |
| 10083 | must supply it. \*Exim@:@:log@_write(<<string>>)*\ writes the string to Exim's |
| 10084 | main log, adding a leading timestamp. In this case, you should not supply a |
| 10085 | terminating newline. |
| 10086 | |
| 10087 | |
| 10088 | |
| 10089 | . |
| 10090 | . |
| 10091 | . |
| 10092 | . |
| 10093 | . ============================================================================ |
| 10094 | .chapter Starting the daemon and the use of network interfaces |
| 10095 | .set runningfoot "starting the daemon" |
| 10096 | .rset CHAPinterfaces "~~chapter" |
| 10097 | .index daemon||starting |
| 10098 | .index interface||listening |
| 10099 | .index network interface |
| 10100 | .index interface||network |
| 10101 | .index IP address||for listening |
| 10102 | .index daemon||listening IP addresses |
| 10103 | .index TCP/IP||setting listening interfaces |
| 10104 | .index TCP/IP||setting listening ports |
| 10105 | |
| 10106 | A host that is connected to a TCP/IP network may have one or more physical |
| 10107 | hardware network interfaces. Each of these interfaces may be configured as one |
| 10108 | or more `logical' interfaces, which are the entities that a program actually |
| 10109 | works with. Each of these logical interfaces is associated with an IP address. |
| 10110 | In addition, TCP/IP software supports `loopback' interfaces (127.0.0.1 in IPv4 |
| 10111 | and @:@:1 in IPv6), which do not use any physical hardware. Exim requires |
| 10112 | knowledge about the host's interfaces for use in three different circumstances: |
| 10113 | .numberpars |
| 10114 | When a listening daemon is started, Exim needs to know which interfaces |
| 10115 | and ports to listen on. |
| 10116 | .nextp |
| 10117 | When Exim is routing an address, it needs to know which IP addresses |
| 10118 | are associated with local interfaces. This is required for the correct |
| 10119 | processing of MX lists by removing the local host and others with the |
| 10120 | same or higher priority values. Also, Exim needs to detect cases |
| 10121 | when an address is routed to an IP address that in fact belongs to the |
| 10122 | local host. Unless the \self\ router option or the \allow@_localhost\ |
| 10123 | option of the smtp transport is set (as appropriate), this is treated |
| 10124 | as an error situation. |
| 10125 | .nextp |
| 10126 | When Exim connects to a remote host, it may need to know which interface to use |
| 10127 | for the outgoing connection. |
| 10128 | .endp |
| 10129 | |
| 10130 | Exim's default behaviour is likely to be appropriate in the vast majority |
| 10131 | of cases. If your host has only one interface, and you want all its IP |
| 10132 | addresses to be treated in the same way, and you are using only the |
| 10133 | standard SMTP port, you should not need to take any special action. The |
| 10134 | rest of this chapter does not apply to you. |
| 10135 | |
| 10136 | In a more complicated situation you may want to listen only on certain |
| 10137 | interfaces, or on different ports, and for this reason there are a number of |
| 10138 | options that can be used to influence Exim's behaviour. The rest of this |
| 10139 | chapter describes how they operate. |
| 10140 | |
| 10141 | When a message is received over TCP/IP, the interface and port that were |
| 10142 | actually used are set in \$interface@_address$\ and \$interface@_port$\. |
| 10143 | |
| 10144 | |
| 10145 | .section Starting a listening daemon |
| 10146 | When a listening daemon is started (by means of the \-bd-\ command line |
| 10147 | option), the interfaces and ports on which it listens are controlled by the |
| 10148 | following options: |
| 10149 | .numberpars $. |
| 10150 | \daemon@_smtp@_ports\ contains a list of default ports. (For backward |
| 10151 | compatibility, this option can also be specified in the singular.) |
| 10152 | .nextp |
| 10153 | \local@_interfaces\ contains list of interface IP addresses on which to |
| 10154 | listen. Each item may optionally also specify a port. |
| 10155 | .endp |
| 10156 | The default list separator in both cases is a colon, but this can be changed as |
| 10157 | described in section ~~SECTlistconstruct. When IPv6 addresses are involved, it |
| 10158 | is usually best to change the separator to avoid having to double all the |
| 10159 | colons. For example: |
| 10160 | .display asis |
| 10161 | local_interfaces = <; 127.0.0.1 ; \ |
| 10162 | 192.168.23.65 ; \ |
| 10163 | ::1 ; \ |
| 10164 | 3ffe:ffff:836f::fe86:a061 |
| 10165 | .endd |
| 10166 | There are two different formats for specifying a port along with an IP address |
| 10167 | in \local@_interfaces\: |
| 10168 | .numberpars |
| 10169 | The port is added onto the address with a dot separator. For example, to listen |
| 10170 | on port 1234 on two different IP addresses: |
| 10171 | .display asis |
| 10172 | local_interfaces = <; 192.168.23.65.1234 ; \ |
| 10173 | 3ffe:ffff:836f::fe86:a061.1234 |
| 10174 | .endd |
| 10175 | .nextp |
| 10176 | The IP address is enclosed in square brackets, and the port is added |
| 10177 | with a colon separator, for example: |
| 10178 | .display asis |
| 10179 | local_interfaces = <; [192.168.23.65]:1234 ; \ |
| 10180 | [3ffe:ffff:836f::fe86:a061]:1234 |
| 10181 | .endd |
| 10182 | .endp |
| 10183 | When a port is not specified, the value of \daemon@_smtp@_ports\ is used. The |
| 10184 | default setting contains just one port: |
| 10185 | .display asis |
| 10186 | daemon_smtp_ports = smtp |
| 10187 | .endd |
| 10188 | If more than one port is listed, each interface that does not have its own port |
| 10189 | specified listens on all of them. Ports that are listed in |
| 10190 | \daemon@_smtp@_ports\ can be identified either by name (defined in |
| 10191 | \(/etc/services)\) or by number. However, when ports are given with individual |
| 10192 | IP addresses in \local@_interfaces\, only numbers (not names) can be used. |
| 10193 | |
| 10194 | |
| 10195 | .section Special IP listening addresses |
| 10196 | The addresses 0.0.0.0 and @:@:0 are treated specially. They are interpreted |
| 10197 | as `all IPv4 interfaces' and `all IPv6 interfaces', respectively. In each |
| 10198 | case, Exim tells the TCP/IP stack to `listen on all IPv\*x*\ interfaces' |
| 10199 | instead of setting up separate listening sockets for each interface. The |
| 10200 | default value of \local@_interfaces\ is |
| 10201 | .display asis |
| 10202 | local_interfaces = 0.0.0.0 |
| 10203 | .endd |
| 10204 | when Exim is built without IPv6 support; otherwise it is: |
| 10205 | .display asis |
| 10206 | local_interfaces = <; ::0 ; 0.0.0.0 |
| 10207 | .endd |
| 10208 | Thus, by default, Exim listens on all available interfaces, on the SMTP port. |
| 10209 | |
| 10210 | |
| 10211 | .section Overriding local@_interfaces and daemon@_smtp@_ports |
| 10212 | The \-oX-\ command line option can be used to override the values of |
| 10213 | \daemon@_smtp@_ports\ and/or \local@_interfaces\ for a particular daemon |
| 10214 | instance. Another way of doing this would be to use macros and the \-D-\ |
| 10215 | option. However, \-oX-\ can be used by any admin user, whereas modification of |
| 10216 | the runtime configuration by \-D-\ is allowed only when the caller is root or |
| 10217 | exim. |
| 10218 | |
| 10219 | The value of \-oX-\ is a list of items. The default colon separator can be |
| 10220 | changed in the usual way if required. If there are any items that do not |
| 10221 | contain dots or colons (that is, are not IP addresses), the value of |
| 10222 | \daemon@_smtp@_ports\ is replaced by the list of those items. If there are any |
| 10223 | items that do contain dots or colons, the value of \local@_interfaces\ is |
| 10224 | replaced by those items. Thus, for example, |
| 10225 | .display asis |
| 10226 | -oX 1225 |
| 10227 | .endd |
| 10228 | overrides \daemon@_smtp@_ports\, but leaves \local@_interfaces\ unchanged, |
| 10229 | whereas |
| 10230 | .display asis |
| 10231 | -oX 192.168.34.5.1125 |
| 10232 | .endd |
| 10233 | overrides \local@_interfaces\, leaving \daemon@_smtp@_ports\ unchanged. |
| 10234 | (However, since \local@_interfaces\ now contains no items without ports, the |
| 10235 | value of \daemon@_smtp@_ports\ is no longer relevant in this example.) |
| 10236 | |
| 10237 | |
| 10238 | .section IPv6 address scopes |
| 10239 | IPv6 addresses have `scopes', and a host with multiple hardware interfaces |
| 10240 | can, in principle, have the same link-local IPv6 address on different |
| 10241 | interfaces. Thus, additional information is needed, over and above the IP |
| 10242 | address, to distinguish individual interfaces. A convention of using a |
| 10243 | percent sign followed by something (often the interface name) has been |
| 10244 | adopted in some cases, leading to addresses like this: |
| 10245 | .display asis |
| 10246 | 3ffe:2101:12:1:a00:20ff:fe86:a061%eth0 |
| 10247 | .endd |
| 10248 | To accommodate this usage, a percent sign followed by an arbitrary string is |
| 10249 | allowed at the end of an IPv6 address. By default, Exim calls \*getaddrinfo()*\ |
| 10250 | to convert a textual IPv6 address for actual use. This function recognizes the |
| 10251 | percent convention in operating systems that support it, and it processes the |
| 10252 | address appropriately. Unfortunately, some older libraries have problems with |
| 10253 | \*getaddrinfo()*\. If |
| 10254 | .display asis |
| 10255 | IPV6_USE_INET_PTON=yes |
| 10256 | .endd |
| 10257 | is set in \(Local/Makefile)\ (or an OS-dependent Makefile) when Exim is built, |
| 10258 | Exim uses \*inet@_pton()*\ to convert a textual IPv6 address for actual use, |
| 10259 | instead of \*getaddrinfo()*\. (Before version 4.14, it always used this |
| 10260 | function.) Of course, this means that the additional functionality of |
| 10261 | \*getaddrinfo()*\ -- recognizing scoped addresses -- is lost. |
| 10262 | |
| 10263 | |
| 10264 | .section Examples of starting a listening daemon |
| 10265 | The default case in an IPv6 environment is |
| 10266 | .display asis |
| 10267 | daemon_smtp_port = smtp |
| 10268 | local_interfaces = <; ::0 ; 0.0.0.0 |
| 10269 | .endd |
| 10270 | This specifies listening on the smtp port on all IPv6 and IPv4 interfaces. |
| 10271 | Either one or two sockets may be used, depending on the characteristics of |
| 10272 | the TCP/IP stack. (This is complicated and messy; for more information, |
| 10273 | read the comments in the \(daemon.c)\ source file.) |
| 10274 | |
| 10275 | To specify listening on ports 25 and 26 on all interfaces: |
| 10276 | .display asis |
| 10277 | daemon_smtp_ports = 25 : 26 |
| 10278 | .endd |
| 10279 | (leaving \local@_interfaces\ at the default setting) or, more explicitly: |
| 10280 | .display asis |
| 10281 | local_interfaces = <; ::0.25 ; ::0.26 \ |
| 10282 | 0.0.0.0.25 ; 0.0.0.0.26 |
| 10283 | .endd |
| 10284 | To listen on the default port on all IPv4 interfaces, and on port 26 on the |
| 10285 | IPv4 loopback address only: |
| 10286 | .display asis |
| 10287 | local_interfaces = 0.0.0.0 : 127.0.0.1.26 |
| 10288 | .endd |
| 10289 | To specify listening on the default port on specific interfaces only: |
| 10290 | .display asis |
| 10291 | local_interfaces = 192.168.34.67 : 192.168.34.67 |
| 10292 | .endd |
| 10293 | \**Note**\: such a setting excludes listening on the loopback interfaces. |
| 10294 | |
| 10295 | |
| 10296 | .section Recognising the local host |
| 10297 | .rset SECTreclocipadd "~~chapter.~~section" |
| 10298 | The \local@_interfaces\ option is also used when Exim needs to determine |
| 10299 | whether or not an IP address refers to the local host. That is, the IP |
| 10300 | addresses of all the interfaces on which a daemon is listening are always |
| 10301 | treated as local. |
| 10302 | |
| 10303 | For this usage, port numbers in \local@_interfaces\ are ignored. If either of |
| 10304 | the items 0.0.0.0 or @:@:0 are encountered, Exim gets a complete list of |
| 10305 | available interfaces from the operating system, and extracts the relevant |
| 10306 | (that is, IPv4 or IPv6) addresses to use for checking. |
| 10307 | |
| 10308 | Some systems set up large numbers of virtual interfaces in order to provide |
| 10309 | many virtual web servers. In this situation, you may want to listen for |
| 10310 | email on only a few of the available interfaces, but nevertheless treat all |
| 10311 | interfaces as local when routing. You can do this by setting |
| 10312 | \extra@_local@_interfaces\ to a list of IP addresses, possibly including the |
| 10313 | `all' wildcard values. These addresses are recognized as local, but are not |
| 10314 | used for listening. Consider this example: |
| 10315 | .display asis |
| 10316 | local_interfaces = <; 127.0.0.1 ; ::1 ; \ |
| 10317 | 192.168.53.235 ; \ |
| 10318 | 3ffe:2101:12:1:a00:20ff:fe86:a061 |
| 10319 | |
| 10320 | extra_local_interfaces = <; ::0 ; 0.0.0.0 |
| 10321 | .endd |
| 10322 | The daemon listens on the loopback interfaces and just one IPv4 and one IPv6 |
| 10323 | address, but all available interface addresses are treated as local when |
| 10324 | Exim is routing. |
| 10325 | |
| 10326 | In some environments the local host name may be in an MX list, but with an IP |
| 10327 | address that is not assigned to any local interface. In other cases it may be |
| 10328 | desirable to treat other host names as if they referred to the local host. Both |
| 10329 | these cases can be handled by setting the \hosts@_treat@_as@_local\ option. |
| 10330 | This contains host names rather than IP addresses. When a host is referenced |
| 10331 | during routing, either via an MX record or directly, it is treated as the local |
| 10332 | host if its name matches \hosts@_treat@_as@_local\, or if any of its IP |
| 10333 | addresses match \local@_interfaces\ or \extra@_local@_interfaces\. |
| 10334 | |
| 10335 | |
| 10336 | .section Delivering to a remote host |
| 10337 | Delivery to a remote host is handled by the smtp transport. By default, it |
| 10338 | allows the system's TCP/IP functions to choose which interface to use (if |
| 10339 | there is more than one) when connecting to a remote host. However, the |
| 10340 | \interface\ option can be set to specify which interface is used. See the |
| 10341 | description of the smtp transport in chapter ~~CHAPsmtptrans for more details. |
| 10342 | |
| 10343 | |
| 10344 | |
| 10345 | |
| 10346 | |
| 10347 | . |
| 10348 | . |
| 10349 | . |
| 10350 | . |
| 10351 | . ============================================================================ |
| 10352 | .chapter Main configuration |
| 10353 | .set runningfoot "main configuration" |
| 10354 | .rset CHAPmainconfig "~~chapter" |
| 10355 | .index configuration file||main section |
| 10356 | .index main configuration |
| 10357 | The first part of the run time configuration file contains three types of item: |
| 10358 | .numberpars $. |
| 10359 | Macro definitions: These lines start with an upper case letter. See section |
| 10360 | ~~SECTmacrodefs for details of macro processing. |
| 10361 | .nextp |
| 10362 | Named list definitions: These lines start with one of the words `domainlist', |
| 10363 | `hostlist', `addresslist', or `localpartlist'. Their use is described in |
| 10364 | section ~~SECTnamedlists. |
| 10365 | .nextp |
| 10366 | Main configuration settings: Each setting occupies one line of the file |
| 10367 | (with possible continuations). If any setting is preceded by the word |
| 10368 | `hide', the \-bP-\ command line option displays its value to admin users only. |
| 10369 | See section ~~SECTcos for a description of the syntax of these option settings. |
| 10370 | .endp |
| 10371 | This chapter specifies all the main configuration options, along with their |
| 10372 | types and default values. For ease of finding a particular option, they appear |
| 10373 | in alphabetical order in section ~~SECTalomo below. However, because there are |
| 10374 | now so many options, they are first listed briefly in functional groups, as an |
| 10375 | aid to finding the name of the option you are looking for. |
| 10376 | Some options are listed in more than one group. |
| 10377 | |
| 10378 | .set savedisplayflowcheck ~~displayflowcheck |
| 10379 | .set displayflowcheck 0 |
| 10380 | |
| 10381 | .section Miscellaneous |
| 10382 | .display flow rm |
| 10383 | .tabs 31 |
| 10384 | \bi@_command\ $t$rm{to run for \-bi-\ command line option} |
| 10385 | \keep@_malformed\ $t$rm{for broken files -- should not happen} |
| 10386 | \localhost@_number\ $t$rm{for unique message ids in clusters} |
| 10387 | \message@_body@_visible\ $t$rm{how much to show in \$message@_body$\} |
| 10388 | \print@_topbitchars\ $t$rm{top-bit characters are printing} |
| 10389 | \timezone\ $t$rm{force time zone} |
| 10390 | .endd |
| 10391 | |
| 10392 | .section Exim parameters |
| 10393 | .display flow rm |
| 10394 | .tabs 31 |
| 10395 | \exim@_group\ $t$rm{override compiled-in value} |
| 10396 | \exim@_path\ $t$rm{override compiled-in value} |
| 10397 | \exim@_user\ $t$rm{override compiled-in value} |
| 10398 | \primary@_hostname\ $t$rm{default from \*uname()*\} |
| 10399 | \split@_spool@_directory\ $t$rm{use multiple directories} |
| 10400 | \spool@_directory\ $t$rm{override compiled-in value} |
| 10401 | .endd |
| 10402 | |
| 10403 | .section Privilege controls |
| 10404 | .display flow rm |
| 10405 | .tabs 31 |
| 10406 | \admin@_groups\ $t$rm{groups that are Exim admin users} |
| 10407 | \deliver@_drop@_privilege\ $t$rm{drop root for delivery processes} |
| 10408 | \local@_from@_check\ $t$rm{insert ::Sender:: if necessary} |
| 10409 | \local@_from@_prefix\ $t$rm{for testing ::From:: for local sender} |
| 10410 | \local@_from@_suffix\ $t$rm{for testing ::From:: for local sender} |
| 10411 | \local@_sender@_retain\ $t$rm{keep ::Sender:: from untrusted user} |
| 10412 | \never@_users\ $t$rm{do not run deliveries as these} |
| 10413 | \prod@_requires@_admin\ $t$rm{forced delivery requires admin user} |
| 10414 | \queue@_list@_requires@_admin\ $t$rm{queue listing requires admin user} |
| 10415 | \trusted@_groups\ $t$rm{groups that are trusted} |
| 10416 | \trusted@_users\ $t$rm{users that are trusted} |
| 10417 | .endd |
| 10418 | |
| 10419 | .section Logging |
| 10420 | .display flow rm |
| 10421 | .tabs 31 |
| 10422 | \log@_file@_path\ $t$rm{override compiled-in value} |
| 10423 | \log@_selector\ $t$rm{set/unset optional logging} |
| 10424 | \log@_timezone\ $t$rm{add timezone to log lines} |
| 10425 | \message@_logs\ $t$rm{create per-message logs} |
| 10426 | \preserve@_message@_logs\ $t$rm{after message completion} |
| 10427 | \process@_log@_path\ $t$rm{for SIGUSR1 and \*exiwhat*\} |
| 10428 | \syslog@_duplication\ $t$rm{controls duplicate log lines on syslog } |
| 10429 | \syslog@_facility\ $t$rm{set syslog `facility' field} |
| 10430 | \syslog@_processname\ $t$rm{set syslog `ident' field} |
| 10431 | \syslog@_timestamp\ $t$rm{timestamp syslog lines} |
| 10432 | .newline |
| 10433 | \write@_rejectlog\ $t$rm{control use of message log} |
| 10434 | .newline |
| 10435 | .endd |
| 10436 | |
| 10437 | .section Frozen messages |
| 10438 | .display flow rm |
| 10439 | .tabs 31 |
| 10440 | \auto@_thaw\ $t$rm{sets time for retrying frozen messages} |
| 10441 | \freeze@_tell\ $t$rm{send message when freezing} |
| 10442 | \move@_frozen@_messages\ $t$rm{to another directory} |
| 10443 | \timeout@_frozen@_after\ $t$rm{keep frozen messages only so long} |
| 10444 | .endd |
| 10445 | |
| 10446 | .section Data lookups |
| 10447 | .display flow rm |
| 10448 | .tabs 31 |
| 10449 | \ldap@_default@_servers\ $t$rm{used if no server in query} |
| 10450 | \ldap@_version\ $t$rm{set protocol version} |
| 10451 | \lookup@_open@_max\ $t$rm{lookup files held open} |
| 10452 | \mysql@_servers\ $t$rm{as it says} |
| 10453 | \oracle@_servers\ $t$rm{as it says} |
| 10454 | \pgsql@_servers\ $t$rm{as it says} |
| 10455 | .endd |
| 10456 | |
| 10457 | .section Message ids |
| 10458 | .display flow rm |
| 10459 | .tabs 31 |
| 10460 | \message@_id@_header@_domain\ $t$rm{used to build ::Message-ID:: header} |
| 10461 | \message@_id@_header@_text\ $t$rm{ditto} |
| 10462 | .endd |
| 10463 | |
| 10464 | .section Embedded Perl Startup |
| 10465 | .display flow rm |
| 10466 | .tabs 31 |
| 10467 | \perl@_at@_start\ $t$rm{always start the interpreter} |
| 10468 | \perl@_startup\ $t$rm{code to obey when starting Perl} |
| 10469 | .endd |
| 10470 | |
| 10471 | .section Daemon |
| 10472 | .display flow rm |
| 10473 | .tabs 31 |
| 10474 | \daemon@_smtp@_ports\ $t$rm{default ports} |
| 10475 | \extra@_local@_interfaces\ $t$rm{not necessarily listened on} |
| 10476 | \local@_interfaces\ $t$rm{on which to listen, with optional ports} |
| 10477 | \pid@_file@_path\ $t$rm{override compiled-in value} |
| 10478 | \queue@_run@_max\ $t$rm{maximum simultaneous queue runners} |
| 10479 | .endd |
| 10480 | |
| 10481 | .section Resource control |
| 10482 | .display flow rm |
| 10483 | .tabs 31 |
| 10484 | \check@_log@_inodes\ $t$rm{before accepting a message} |
| 10485 | \check@_log@_space\ $t$rm{before accepting a message} |
| 10486 | \check@_spool@_inodes\ $t$rm{before accepting a message} |
| 10487 | \check@_spool@_space\ $t$rm{before accepting a message} |
| 10488 | \deliver@_queue@_load@_max\ $t$rm{no queue deliveries if load high} |
| 10489 | \queue@_only@_load\ $t$rm{queue incoming if load high} |
| 10490 | \queue@_run@_max\ $t$rm{maximum simultaneous queue runners} |
| 10491 | \remote@_max@_parallel\ $t$rm{parallel SMTP delivery per message} |
| 10492 | \smtp@_accept@_max\ $t$rm{simultaneous incoming connections} |
| 10493 | \smtp@_accept@_max@_nommail\ $t$rm{non-mail commands} |
| 10494 | \smtp@_accept@_max@_nonmail@_hosts\ $t$rm{hosts to which the limit applies} |
| 10495 | \smtp@_accept@_max@_per@_connection\ $t$rm{messages per connection} |
| 10496 | \smtp@_accept@_max@_per@_host\ $t$rm{connections from one host} |
| 10497 | \smtp@_accept@_queue\ $t$rm{queue mail if more connections} |
| 10498 | \smtp@_accept@_queue@_per@_connection\ $t$rm{queue if more messages per connection} |
| 10499 | \smtp@_accept@_reserve\ $t$rm{only reserve hosts if more connections} |
| 10500 | \smtp@_check@_spool@_space\ $t$rm{from \\SIZE\\ on \\MAIL\\ command} |
| 10501 | \smtp@_connect@_backlog\ $t$rm{passed to TCP/IP stack} |
| 10502 | \smtp@_load@_reserve\ $t$rm{SMTP from reserved hosts if load high} |
| 10503 | \smtp@_reserve@_hosts\ $t$rm{these are the reserve hosts} |
| 10504 | .endd |
| 10505 | |
| 10506 | .section Policy controls |
| 10507 | .display flow rm |
| 10508 | .tabs 31 |
| 10509 | \acl@_not@_smtp\ $t$rm{set ACL for non-SMTP messages} |
| 10510 | \acl@_smtp@_auth\ $t$rm{set ACL for \\AUTH\\} |
| 10511 | \acl@_smtp@_connect\ $t$rm{set ACL for connection} |
| 10512 | \acl@_smtp@_data\ $t$rm{set ACL for \\DATA\\} |
| 10513 | \acl@_smtp@_etrn\ $t$rm{set ACL for \\ETRN\\} |
| 10514 | \acl@_smtp@_expn\ $t$rm{set ACL for \\EXPN\\} |
| 10515 | \acl@_smtp@_helo\ $t$rm{set ACL for \\EHLO\\ or \\HELO\\} |
| 10516 | \acl@_smtp@_mail\ $t$rm{set ACL for \\MAIL\\} |
| 10517 | \acl@_smtp@_mailauth\ $t$rm{set ACL for \\AUTH\\ on \\MAIL\\ command} |
| 10518 | \acl@_smtp@_rcpt\ $t$rm{set ACL for \\RCPT\\} |
| 10519 | \acl@_smtp@_starttls\ $t$rm{set ACL for \\STARTTLS\\} |
| 10520 | \acl@_smtp@_vrfy\ $t$rm{set ACL for \\VRFY\\} |
| 10521 | \header@_maxsize\ $t$rm{total size of message header} |
| 10522 | \header@_line@_maxsize\ $t$rm{individual header line limit} |
| 10523 | \helo@_accept@_junk@_hosts\ $t$rm{allow syntactic junk from these hosts} |
| 10524 | \helo@_allow@_chars\ $t$rm{allow illegal chars in \\HELO\\ names} |
| 10525 | \helo@_lookup@_domains\ $t$rm{lookup hostname for these \\HELO\\ names} |
| 10526 | \helo@_try@_verify@_hosts\ $t$rm{\\HELO\\ soft-checked for these hosts} |
| 10527 | \helo@_verify@_hosts\ $t$rm{\\HELO\\ hard-checked for these hosts} |
| 10528 | \host@_lookup\ $t$rm{host name looked up for these hosts} |
| 10529 | \host@_lookup@_order\ $t$rm{order of DNS and local name lookups} |
| 10530 | \host@_reject@_connection\ $t$rm{reject connection from these hosts} |
| 10531 | \hosts@_treat@_as@_local\ $t$rm{useful in some cluster configurations} |
| 10532 | \local@_scan@_timeout\ $t$rm{timeout for \*local@_scan()*\} |
| 10533 | \message@_size@_limit\ $t$rm{for all messages} |
| 10534 | \percent@_hack@_domains\ $t$rm{recognize %-hack for these domains} |
| 10535 | .endd |
| 10536 | |
| 10537 | .section Callout cache |
| 10538 | .display flow rm |
| 10539 | .tabs 31 |
| 10540 | \callout@_domain@_negative@_expire\ $t$rm{timeout for negative domain cache item} |
| 10541 | \callout@_domain@_positive@_expire\ $t$rm{timeout for positive domain cache item} |
| 10542 | \callout@_negative@_expire\ $t$rm{timeout for negative address cache item} |
| 10543 | \callout@_positive@_expire\ $t$rm{timeout for positive address cache item} |
| 10544 | \callout@_random@_local@_part\ $t$rm{string to use for `random' testing} |
| 10545 | .endd |
| 10546 | |
| 10547 | .section TLS |
| 10548 | .display flow rm |
| 10549 | .tabs 31 |
| 10550 | \tls@_advertise@_hosts\ $t$rm{advertise TLS to these hosts} |
| 10551 | \tls@_certificate\ $t$rm{location of server certificate} |
| 10552 | .newline |
| 10553 | \tls@_crl\ $t$rm{certificate revocation list} |
| 10554 | .newline |
| 10555 | \tls@_dhparam\ $t$rm{DH parameters for server} |
| 10556 | \tls@_privatekey\ $t$rm{location of server private key} |
| 10557 | \tls@_remember@_esmtp\ $t$rm{don't reset after starting TLS} |
| 10558 | .newline |
| 10559 | \tls@_require@_ciphers\ $t$rm{specify acceptable cipers} |
| 10560 | .newline |
| 10561 | \tls@_try@_verify@_hosts\ $t$rm{try to verify client certificate} |
| 10562 | \tls@_verify@_certificates\ $t$rm{expected client certificates} |
| 10563 | \tls@_verify@_hosts\ $t$rm{insist on client certificate verify} |
| 10564 | .endd |
| 10565 | |
| 10566 | .section Local user handling |
| 10567 | .display flow rm |
| 10568 | .tabs 31 |
| 10569 | \finduser@_retries\ $t$rm{useful in NIS environments} |
| 10570 | \gecos@_name\ $t$rm{used when creating ::Sender::} |
| 10571 | \gecos@_pattern\ $t$rm{ditto} |
| 10572 | \max@_username@_length\ $t$rm{for systems that truncate} |
| 10573 | \unknown@_login\ $t$rm{used when no login name found} |
| 10574 | \unknown@_username\ $t$rm{ditto} |
| 10575 | \uucp@_from@_pattern\ $t$rm{for recognizing `From ' lines} |
| 10576 | \uucp@_from@_sender\ $t$rm{ditto} |
| 10577 | .endd |
| 10578 | |
| 10579 | .section All incoming messages (SMTP and non-SMTP) |
| 10580 | .display flow rm |
| 10581 | .tabs 31 |
| 10582 | \header@_maxsize\ $t$rm{total size of message header} |
| 10583 | \header@_line@_maxsize\ $t$rm{individual header line limit} |
| 10584 | \message@_size@_limit\ $t$rm{applies to all messages} |
| 10585 | \percent@_hack@_domains\ $t$rm{recognize %-hack for these domains} |
| 10586 | \received@_header@_text\ $t$rm{expanded to make ::Received::} |
| 10587 | \received@_headers@_max\ $t$rm{for mail loop detection} |
| 10588 | \recipients@_max\ $t$rm{limit per message} |
| 10589 | \recipients@_max@_reject\ $t$rm{permanently reject excess} |
| 10590 | .endd |
| 10591 | |
| 10592 | |
| 10593 | .section Non-SMTP incoming messages |
| 10594 | .display rm |
| 10595 | .tabs 31 |
| 10596 | \receive@_timeout\ $t$rm{for non-SMTP messages} |
| 10597 | .endd |
| 10598 | |
| 10599 | |
| 10600 | |
| 10601 | .section Incoming SMTP messages |
| 10602 | See also the \*Policy controls*\ section above. |
| 10603 | .display flow rm |
| 10604 | .tabs 31 |
| 10605 | \host@_lookup\ $t$rm{host name looked up for these hosts} |
| 10606 | \host@_lookup@_order\ $t$rm{order of DNS and local name lookups} |
| 10607 | \recipient@_unqualified@_hosts\ $t$rm{may send unqualified recipients} |
| 10608 | \rfc1413@_hosts\ $t$rm{make ident calls to these hosts} |
| 10609 | \rfc1413@_query@_timeout\ $t$rm{zero disables ident calls} |
| 10610 | \sender@_unqualified@_hosts\ $t$rm{may send unqualified senders} |
| 10611 | \smtp@_accept@_keepalive\ $t$rm{some TCP/IP magic} |
| 10612 | \smtp@_accept@_max\ $t$rm{simultaneous incoming connections} |
| 10613 | \smtp@_accept@_max@_nommail\ $t$rm{non-mail commands} |
| 10614 | \smtp@_accept@_max@_nonmail@_hosts\ $t$rm{hosts to which the limit applies} |
| 10615 | \smtp@_accept@_max@_per@_connection\ $t$rm{messages per connection} |
| 10616 | \smtp@_accept@_max@_per@_host\ $t$rm{connections from one host} |
| 10617 | \smtp@_accept@_queue\ $t$rm{queue mail if more connections} |
| 10618 | \smtp@_accept@_queue@_per@_connection\ $t$rm{queue if more messages per connection} |
| 10619 | \smtp@_accept@_reserve\ $t$rm{only reserve hosts if more connections} |
| 10620 | .newline |
| 10621 | \smtp@_active@_hostname\ $t$rm{host name to use in messages} |
| 10622 | .newline |
| 10623 | \smtp@_banner\ $t$rm{text for welcome banner} |
| 10624 | \smtp@_check@_spool@_space\ $t$rm{from \\SIZE\\ on \\MAIL\\ command} |
| 10625 | \smtp@_connect@_backlog\ $t$rm{passed to TCP/IP stack} |
| 10626 | \smtp@_enforce@_sync\ $t$rm{of SMTP command/responses} |
| 10627 | \smtp@_etrn@_command\ $t$rm{what to run for \\ETRN\\} |
| 10628 | \smtp@_etrn@_serialize\ $t$rm{only one at once} |
| 10629 | \smtp@_load@_reserve\ $t$rm{only reserve hosts if this load} |
| 10630 | \smtp@_max@_unknown@_commands\ $t$rm{before dropping connection} |
| 10631 | \smtp@_ratelimit@_hosts\ $t$rm{apply ratelimiting to these hosts} |
| 10632 | \smtp@_ratelimit@_mail\ $t$rm{ratelimit for \\MAIL\\ commands} |
| 10633 | \smtp@_ratelimit@_rcpt\ $t$rm{ratelimit for \\RCPT\\ commands} |
| 10634 | \smtp@_receive@_timeout\ $t$rm{per command or data line} |
| 10635 | \smtp@_reserve@_hosts\ $t$rm{these are the reserve hosts} |
| 10636 | \smtp@_return@_error@_details\ $t$rm{give detail on rejections} |
| 10637 | .endd |
| 10638 | |
| 10639 | .section SMTP extensions |
| 10640 | .display flow rm |
| 10641 | .tabs 31 |
| 10642 | \accept@_8bitmime\ $t$rm{advertise \\8BITMIME\\} |
| 10643 | \auth@_advertise@_hosts\ $t$rm{advertise \\AUTH\\ to these hosts} |
| 10644 | \ignore@_fromline@_hosts\ $t$rm{allow `From ' from these hosts} |
| 10645 | \ignore@_fromline@_local\ $t$rm{allow `From ' from local SMTP} |
| 10646 | \pipelining@_advertise@_hosts\ $t$rm{advertise pipelining to these hosts} |
| 10647 | \tls@_advertise@_hosts\ $t$rm{advertise TLS to these hosts} |
| 10648 | .endd |
| 10649 | |
| 10650 | .section Processing messages |
| 10651 | .display flow rm |
| 10652 | .tabs 31 |
| 10653 | \allow@_domain@_literals\ $t$rm{recognize domain literal syntax} |
| 10654 | \allow@_mx@_to@_ip\ $t$rm{allow MX to point to IP address} |
| 10655 | \allow@_utf8@_domains\ $t$rm{in addresses} |
| 10656 | \delivery@_date@_remove\ $t$rm{from incoming messages} |
| 10657 | \envelope@_to@_remote\ $t$rm{from incoming messages} |
| 10658 | \extract@_addresses@_remove@_arguments\ $t$rm{affects \-t-\ processing} |
| 10659 | \headers@_charset\ $t$rm{default for translations} |
| 10660 | \qualify@_domain\ $t$rm{default for senders} |
| 10661 | \qualify@_recipient\ $t$rm{default for recipients} |
| 10662 | \return@_path@_remove\ $t$rm{from incoming messages} |
| 10663 | \strip@_excess@_angle@_brackets\ $t$rm{in addresses} |
| 10664 | \strip@_trailing@_dot\ $t$rm{at end of addresses} |
| 10665 | \untrusted@_set@_sender\ $t$rm{untrusted can set envelope sender} |
| 10666 | .endd |
| 10667 | |
| 10668 | .section System filter |
| 10669 | .display flow rm |
| 10670 | .tabs 31 |
| 10671 | \system@_filter\ $t$rm{locate system filter} |
| 10672 | \system@_filter@_directory@_transport\ $t$rm{transport for delivery to a directory} |
| 10673 | \system@_filter@_file@_transport\ $t$rm{transport for delivery to a file} |
| 10674 | \system@_filter@_group\ $t$rm{group for filter running} |
| 10675 | \system@_filter@_pipe@_transport\ $t$rm{transport for delivery to a pipe} |
| 10676 | \system@_filter@_reply@_transport\ $t$rm{transport for autoreply delivery} |
| 10677 | \system@_filter@_user\ $t$rm{user for filter running} |
| 10678 | .endd |
| 10679 | |
| 10680 | .section Routing and delivery |
| 10681 | .display flow rm |
| 10682 | .tabs 31 |
| 10683 | \dns@_again@_means@_nonexist\ $t$rm{for broken domains} |
| 10684 | \dns@_check@_names@_pattern\ $t$rm{pre-DNS syntax check} |
| 10685 | \dns@_ipv4@_lookup\ $t$rm{only v4 lookup for these domains} |
| 10686 | \dns@_retrans\ $t$rm{parameter for resolver} |
| 10687 | \dns@_retry\ $t$rm{parameter for resolver} |
| 10688 | \hold@_domains\ $t$rm{hold delivery for these domains} |
| 10689 | \local@_interfaces\ $t$rm{for routing checks} |
| 10690 | \queue@_domains\ $t$rm{no immediate delivery for these} |
| 10691 | \queue@_only\ $t$rm{no immediate delivery at all} |
| 10692 | \queue@_only@_file\ $t$rm{no immediate deliveryif file exists} |
| 10693 | \queue@_only@_load\ $t$rm{no immediate delivery if load is high} |
| 10694 | \queue@_only@_override\ $t$rm{allow command line to override} |
| 10695 | \queue@_run@_in@_order\ $t$rm{order of arrival} |
| 10696 | \queue@_run@_max\ $t$rm{of simultaneous queue runners} |
| 10697 | \queue@_smtp@_domains\ $t$rm{no immediate SMTP delivery for these} |
| 10698 | \remote@_max@_parallel\ $t$rm{parallel SMTP delivery per message} |
| 10699 | \remote@_sort@_domains\ $t$rm{order of remote deliveries} |
| 10700 | \retry@_data@_expire\ $t$rm{timeout for retry data} |
| 10701 | \retry@_interval@_max\ $t$rm{safety net for retry rules} |
| 10702 | .endd |
| 10703 | |
| 10704 | .section Bounce and warning messages |
| 10705 | .display flow rm |
| 10706 | .tabs 31 |
| 10707 | \bounce@_message@_file\ $t$rm{content of bounce} |
| 10708 | \bounce@_message@_text\ $t$rm{content of bounce} |
| 10709 | \bounce@_return@_body\ $t$rm{include body if returning message} |
| 10710 | \bounce@_return@_message\ $t$rm{include original message in bounce} |
| 10711 | \bounce@_return@_size@_limit\ $t$rm{limit on returned message} |
| 10712 | \bounce@_sender@_authentication\ $t$rm{send authenticated sender with bounce} |
| 10713 | \errors@_copy\ $t$rm{copy bounce messages} |
| 10714 | \errors@_reply@_to\ $t$rm{::Reply-to:: in bounces} |
| 10715 | \delay@_warning\ $t$rm{time schedule} |
| 10716 | \delay@_warning@_condition\ $t$rm{condition for warning messages} |
| 10717 | \ignore@_bounce@_errors@_after\ $t$rm{discard undeliverable bounces} |
| 10718 | \warn@_message@_file\ $t$rm{content of warning message} |
| 10719 | .endd |
| 10720 | |
| 10721 | .set displayflowcheck ~~savedisplayflowcheck |
| 10722 | |
| 10723 | .section Alphabetical list of main options |
| 10724 | .rset SECTalomo "~~chapter.~~section" |
| 10725 | .if ~~sgcal |
| 10726 | Those options that undergo string expansion before use are marked with $**$. |
| 10727 | .fi |
| 10728 | |
| 10729 | .startconf |
| 10730 | |
| 10731 | .index \\8BITMIME\\ |
| 10732 | .index 8-bit characters |
| 10733 | .conf accept@_8bitmime boolean false |
| 10734 | This option causes Exim to send \\8BITMIME\\ in its response to an SMTP |
| 10735 | \\EHLO\\ command, and to accept the \\BODY=\\ parameter on \\MAIL\\ commands. |
| 10736 | However, though Exim is 8-bit clean, it is not a protocol converter, and it |
| 10737 | takes no steps to do anything special with messages received by this route. |
| 10738 | Consequently, this option is turned off by default. |
| 10739 | |
| 10740 | .index ~~ACL||for non-SMTP messages |
| 10741 | .index non-SMTP messages, ACL for |
| 10742 | .conf acl@_not@_smtp string$**$ unset |
| 10743 | This option defines the ACL that is run when a non-SMTP message is on the point |
| 10744 | of being accepted. See chapter ~~CHAPACL for further details. |
| 10745 | |
| 10746 | .index ~~ACL||on SMTP connection |
| 10747 | .conf acl@_smtp@_connect string$**$ unset |
| 10748 | This option defines the ACL that is run when an SMTP connection is received. |
| 10749 | See chapter ~~CHAPACL for further details. |
| 10750 | |
| 10751 | .index ~~ACL||setting up for SMTP commands |
| 10752 | .index \\AUTH\\||ACL for |
| 10753 | .conf acl@_smtp@_auth string$**$ unset |
| 10754 | This option defines the ACL that is run when an SMTP \\AUTH\\ command is |
| 10755 | received. See chapter ~~CHAPACL for further details. |
| 10756 | |
| 10757 | .index \\DATA\\, ACL for |
| 10758 | .conf acl@_smtp@_data string$**$ unset |
| 10759 | This option defines the ACL that is run after an SMTP \\DATA\\ command has been |
| 10760 | processed and the message itself has been received, but before the final |
| 10761 | acknowledgement is sent. See chapter ~~CHAPACL for further details. |
| 10762 | |
| 10763 | .index \\ETRN\\||ACL for |
| 10764 | .conf acl@_smtp@_etrn string$**$ unset |
| 10765 | This option defines the ACL that is run when an SMTP \\ETRN\\ command is |
| 10766 | received. See chapter ~~CHAPACL for further details. |
| 10767 | |
| 10768 | .index \\EXPN\\||ACL for |
| 10769 | .conf acl@_smtp@_expn string$**$ unset |
| 10770 | This option defines the ACL that is run when an SMTP \\EXPN\\ command is |
| 10771 | received. See chapter ~~CHAPACL for further details. |
| 10772 | |
| 10773 | .index \\EHLO\\||ACL for |
| 10774 | .index \\HELO\\||ACL for |
| 10775 | .conf acl@_smtp@_helo string$**$ unset |
| 10776 | This option defines the ACL that is run when an SMTP \\EHLO\\ or \\HELO\\ |
| 10777 | command is received. See chapter ~~CHAPACL for further details. |
| 10778 | |
| 10779 | .index \\MAIL\\||ACL for |
| 10780 | .conf acl@_smtp@_mail string$**$ unset |
| 10781 | This option defines the ACL that is run when an SMTP \\MAIL\\ command is |
| 10782 | received. See chapter ~~CHAPACL for further details. |
| 10783 | |
| 10784 | .index \\AUTH\\||on \\MAIL\\ command |
| 10785 | .conf acl@_smtp@_mailauth string$**$ unset |
| 10786 | This option defines the ACL that is run when there is an \\AUTH\\ parameter on |
| 10787 | a \\MAIL\\ command. See chapter ~~CHAPACL for details of ACLs, and chapter |
| 10788 | ~~CHAPSMTPAUTH for details of authentication. |
| 10789 | |
| 10790 | .index \\RCPT\\||ACL for |
| 10791 | .conf acl@_smtp@_rcpt string$**$ unset |
| 10792 | This option defines the ACL that is run when an SMTP \\RCPT\\ command is |
| 10793 | received. See chapter ~~CHAPACL for further details. |
| 10794 | |
| 10795 | .index \\STARTTLS\\, ACL for |
| 10796 | .conf acl@_smtp@_starttls string$**$ unset |
| 10797 | This option defines the ACL that is run when an SMTP \\STARTTLS\\ command is |
| 10798 | received. See chapter ~~CHAPACL for further details. |
| 10799 | |
| 10800 | .index \\VRFY\\||ACL for |
| 10801 | .conf acl@_smtp@_vrfy string$**$ unset |
| 10802 | This option defines the ACL that is run when an SMTP \\VRFY\\ command is |
| 10803 | received. See chapter ~~CHAPACL for further details. |
| 10804 | |
| 10805 | .conf admin@_groups "string list" unset |
| 10806 | .index admin user |
| 10807 | If the current group or any of the supplementary groups of the caller is in |
| 10808 | this colon-separated list, the caller has admin privileges. If all your system |
| 10809 | programmers are in a specific group, for example, you can give them all Exim |
| 10810 | admin privileges by putting that group in \admin@_groups\. However, this does |
| 10811 | not permit them to read Exim's spool files (whose group owner is the Exim gid). |
| 10812 | To permit this, you have to add individuals to the Exim group. |
| 10813 | |
| 10814 | .conf allow@_domain@_literals boolean false |
| 10815 | .index domain literal |
| 10816 | If this option is set, the RFC 2822 domain literal format is permitted in |
| 10817 | email addresses. The option is not set by default, because the domain literal |
| 10818 | format is not normally required these days, and few people know about it. It |
| 10819 | has, however, been exploited by mail abusers. |
| 10820 | |
| 10821 | Unfortunately, it seems that some DNS black list maintainers are using this |
| 10822 | format to report black listing to postmasters. If you want to accept messages |
| 10823 | addressed to your hosts by IP address, you need to set |
| 10824 | \allow@_domain@_literals\ true, and also to add \"@@[]"\ to the list of local |
| 10825 | domains (defined in the named domain list \local@_domains\ in the default |
| 10826 | configuration). This `magic string' matches the domain literal form of all the |
| 10827 | local host's IP addresses. |
| 10828 | |
| 10829 | .conf allow@_mx@_to@_ip boolean false |
| 10830 | .index MX record||pointing to IP address |
| 10831 | It appears that more and more DNS zone administrators are breaking the rules |
| 10832 | and putting domain names that look like IP addresses on the right hand side of |
| 10833 | MX records. Exim follows the rules and rejects this, giving an error message |
| 10834 | that explains the mis-configuration. However, some other MTAs support this |
| 10835 | practice, so to avoid `Why can't Exim do this?' complaints, \allow@_mx@_to@_ip\ |
| 10836 | exists, in order to enable this heinous activity. It is not recommended, except |
| 10837 | when you have no other choice. |
| 10838 | |
| 10839 | .index domain||UTF-8 characters in |
| 10840 | .index UTF-8||in domain name |
| 10841 | .conf allow@_utf8@_domains boolean false |
| 10842 | Lots of discussion is going on about internationalized domain names. One |
| 10843 | camp is strongly in favour of just using UTF-8 characters, and it seems |
| 10844 | that at least two other MTAs permit this. This option allows Exim users to |
| 10845 | experiment if they wish. |
| 10846 | |
| 10847 | If it is set true, Exim's domain parsing function allows valid |
| 10848 | UTF-8 multicharacters to appear in domain name components, in addition to |
| 10849 | letters, digits, and hyphens. However, just setting this option is not |
| 10850 | enough; if you want to look up these domain names in the DNS, you must also |
| 10851 | adjust the value of \dns@_check@_names@_pattern\ to match the extended form. A |
| 10852 | suitable setting is: |
| 10853 | .display asis |
| 10854 | dns_check_names_pattern = (?i)^(?>(?(1)\.|())[a-z0-9\xc0-\xff]\ |
| 10855 | (?>[-a-z0-9\x80-\xff]*[a-z0-9\x80-\xbf])?)+$ |
| 10856 | .endd |
| 10857 | Alternatively, you can just disable this feature by setting |
| 10858 | .display asis |
| 10859 | dns_check_names_pattern = |
| 10860 | .endd |
| 10861 | That is, set the option to an empty string so that no check is done. |
| 10862 | |
| 10863 | .conf auth@_advertise@_hosts "host list$**$" $*$ |
| 10864 | .index authentication||advertising |
| 10865 | .index \\AUTH\\||advertising |
| 10866 | If any server authentication mechanisms are configured, Exim advertises them in |
| 10867 | response to an \\EHLO\\ command only if the calling host matches this list. |
| 10868 | Otherwise, Exim does not advertise \\AUTH\\. |
| 10869 | Exim does not accept \\AUTH\\ commands from clients to which it has not |
| 10870 | advertised the availability of \\AUTH\\. The advertising of individual |
| 10871 | authentication mechanisms can be controlled by the use of the |
| 10872 | \server@_advertise@_condition\ generic authenticator option on the individual |
| 10873 | authenticators. See chapter ~~CHAPSMTPAUTH for further details. |
| 10874 | |
| 10875 | Certain mail clients (for example, Netscape) require the user to provide a name |
| 10876 | and password for authentication if \\AUTH\\ is advertised, even though it may |
| 10877 | not be needed (the host may accept messages from hosts on its local LAN without |
| 10878 | authentication, for example). The \auth@_advertise@_hosts\ option can be used |
| 10879 | to make these clients more friendly by excluding them from the set of hosts to |
| 10880 | which Exim advertises \\AUTH\\. |
| 10881 | |
| 10882 | .index \\AUTH\\||advertising when encrypted |
| 10883 | If you want to advertise the availability of \\AUTH\\ only when the connection |
| 10884 | is encrypted using TLS, you can make use of the fact that the value of this |
| 10885 | option is expanded, with a setting like this: |
| 10886 | .display asis |
| 10887 | auth_advertise_hosts = ${if eq{$tls_cipher}{}{}{*}} |
| 10888 | .endd |
| 10889 | If \$tls@_cipher$\ is empty, the session is not encrypted, and the result of |
| 10890 | the expansion is empty, thus matching no hosts. Otherwise, the result of the |
| 10891 | expansion is $*$, which matches all hosts. |
| 10892 | |
| 10893 | .conf auto@_thaw time 0s |
| 10894 | .index thawing messages |
| 10895 | .index unfreezing messages |
| 10896 | If this option is set to a time greater than zero, a queue runner will try a |
| 10897 | new delivery attempt on any frozen message if this much time has passed since |
| 10898 | it was frozen. This may result in the message being re-frozen if nothing has |
| 10899 | changed since the last attempt. It is a way of saying `keep on trying, even |
| 10900 | though there are big problems'. See also \timeout@_frozen@_after\ and |
| 10901 | \ignore@_bounce@_errors@_after\. |
| 10902 | |
| 10903 | .conf bi@_command string unset |
| 10904 | .index \-bi-\ option |
| 10905 | This option supplies the name of a command that is run when Exim is called with |
| 10906 | the \-bi-\ option (see chapter ~~CHAPcommandline). The string value is just the |
| 10907 | command name, it is not a complete command line. If an argument is required, it |
| 10908 | must come from the \-oA-\ command line option. |
| 10909 | |
| 10910 | .conf bounce@_message@_file string unset |
| 10911 | .index bounce message||customizing |
| 10912 | .index customizing||bounce message |
| 10913 | This option defines a template file containing paragraphs of text to be used |
| 10914 | for constructing bounce messages. Details of the file's contents are given in |
| 10915 | chapter ~~CHAPemsgcust. See also \warn@_message@_file\. |
| 10916 | |
| 10917 | .conf bounce@_message@_text string unset |
| 10918 | When this option is set, its contents are included in the default bounce |
| 10919 | message immediately after `This message was created automatically by mail |
| 10920 | delivery software.' It is not used if \bounce@_message@_file\ is set. |
| 10921 | |
| 10922 | .index bounce message||including body |
| 10923 | .conf bounce@_return@_body boolean true |
| 10924 | This option controls whether the body of an incoming message is included in a |
| 10925 | bounce message when \bounce@_return@_message\ is true. If it is not set, only |
| 10926 | the message header is included. |
| 10927 | |
| 10928 | .index bounce message||including original |
| 10929 | .conf bounce@_return@_message boolean true |
| 10930 | If this option is set false, the original message is not included in bounce |
| 10931 | messages generated by Exim. See also \bounce@_return@_size@_limit\. |
| 10932 | |
| 10933 | .conf bounce@_return@_size@_limit integer 100K |
| 10934 | .index size||of bounce, limit |
| 10935 | .index bounce message||size limit |
| 10936 | .index limit||bounce message size |
| 10937 | This option sets a limit in bytes on the size of messages that are returned to |
| 10938 | senders as part of bounce messages when \bounce@_return@_message\ is true. The |
| 10939 | limit should be less than the value of the global \message@_size@_limit\ and of |
| 10940 | any \message@_size@_limit\ settings on transports, to allow for the bounce text |
| 10941 | that Exim generates. If this option is set to zero there is no limit. |
| 10942 | |
| 10943 | When the body of any message that is to be included in a bounce message is |
| 10944 | greater than the limit, it is truncated, and a comment pointing this out is |
| 10945 | added at the top. The actual cutoff may be greater than the value given, owing |
| 10946 | to the use of buffering for transferring the message in chunks (typically 8K in |
| 10947 | size). The idea is to save bandwidth on those undeliverable 15-megabyte |
| 10948 | messages. |
| 10949 | |
| 10950 | .index bounce message||sender authentication |
| 10951 | .index authentication||bounce message |
| 10952 | .index \\AUTH\\||on bounce message |
| 10953 | .conf bounce@_sender@_authentication string unset |
| 10954 | This option provides an authenticated sender address that is sent with any |
| 10955 | bounce messages generated by Exim that are sent over an authenticated SMTP |
| 10956 | connection. A typical setting might be: |
| 10957 | .display asis |
| 10958 | bounce_sender_authentication = mailer-daemon@my.domain.example |
| 10959 | .endd |
| 10960 | which would cause bounce messages to be sent using the SMTP command: |
| 10961 | .display asis |
| 10962 | MAIL FROM:<> AUTH=mailer-daemon@my.domain.example |
| 10963 | .endd |
| 10964 | The value of \bounce@_sender@_authentication\ must always be a complete email |
| 10965 | address. |
| 10966 | |
| 10967 | .index caching||callout, timeouts |
| 10968 | .index callout||caching timeouts |
| 10969 | .conf callout@_domain@_negative@_expire time 3h |
| 10970 | This option specifies the expiry time for negative callout cache data for a |
| 10971 | domain. See section ~~SECTcallver for details of callout verification, and |
| 10972 | section ~~SECTcallvercache for details of the caching. |
| 10973 | |
| 10974 | .conf callout@_domain@_positive@_expire time 7d |
| 10975 | This option specifies the expiry time for positive callout cache data for a |
| 10976 | domain. See section ~~SECTcallver for details of callout verification, and |
| 10977 | section ~~SECTcallvercache for details of the caching. |
| 10978 | |
| 10979 | .conf callout@_negative@_expire time 2h |
| 10980 | This option specifies the expiry time for negative callout cache data for an |
| 10981 | address. See section ~~SECTcallver for details of callout verification, and |
| 10982 | section ~~SECTcallvercache for details of the caching. |
| 10983 | |
| 10984 | .conf callout@_positive@_expire time 24h |
| 10985 | This option specifies the expiry time for positive callout cache data for an |
| 10986 | address. See section ~~SECTcallver for details of callout verification, and |
| 10987 | section ~~SECTcallvercache for details of the caching. |
| 10988 | |
| 10989 | .conf callout@_random@_local@_part string$**$ "see below" |
| 10990 | This option defines the `random' local part that can be used as part of callout |
| 10991 | verification. The default value is |
| 10992 | .display asis |
| 10993 | $primary_host_name-$tod_epoch-testing |
| 10994 | .endd |
| 10995 | See section ~~CALLaddparcall for details of how this value is used. |
| 10996 | |
| 10997 | .conf check@_log@_inodes integer 0 |
| 10998 | See \check@_spool@_space\ below. |
| 10999 | |
| 11000 | .conf check@_log@_space integer 0 |
| 11001 | See \check@_spool@_space\ below. |
| 11002 | |
| 11003 | .conf check@_spool@_inodes integer 0 |
| 11004 | See \check@_spool@_space\ below. |
| 11005 | |
| 11006 | .conf check@_spool@_space integer 0 |
| 11007 | .index checking disk space |
| 11008 | .index disk space, checking |
| 11009 | .index spool directory||checking space |
| 11010 | The four \check@_...\ options allow for checking of disk resources before a |
| 11011 | message is accepted. \check@_spool@_space\ and \check@_spool@_inodes\ check the |
| 11012 | spool partition if either value is greater than zero, for example: |
| 11013 | .display asis |
| 11014 | check_spool_space = 10M |
| 11015 | check_spool_inodes = 100 |
| 11016 | .endd |
| 11017 | The spool partition is the one which contains the directory defined by |
| 11018 | \\SPOOL@_DIRECTORY\\ in \(Local/Makefile)\. It is used for holding messages in |
| 11019 | transit. |
| 11020 | |
| 11021 | \check@_log@_space\ and \check@_log@_inodes\ check the partition in which log |
| 11022 | files are written if either is greater than zero. These should be set only if |
| 11023 | \log@_file@_path\ and \spool@_directory\ refer to different partitions. |
| 11024 | |
| 11025 | If there is less space or fewer inodes than requested, Exim refuses to accept |
| 11026 | incoming mail. In the case of SMTP input this is done by giving a 452 temporary |
| 11027 | error response to the \\MAIL\\ command. If ESMTP is in use and there was a |
| 11028 | \\SIZE\\ parameter on the \\MAIL\\ command, its value is added to the |
| 11029 | \check@_spool@_space\ value, and the check is performed even if |
| 11030 | \check@_spool@_space\ is zero, unless \no@_smtp@_check@_spool@_space\ is set. |
| 11031 | |
| 11032 | The values for \check@_spool@_space\ and \check@_log@_space\ are held as a |
| 11033 | number of kilobytes. If a non-multiple of 1024 is specified, it is rounded up. |
| 11034 | |
| 11035 | For non-SMTP input and for batched SMTP input, the test is done at start-up; on |
| 11036 | failure a message is written to stderr and Exim exits with a non-zero code, as |
| 11037 | it obviously cannot send an error message of any kind. |
| 11038 | |
| 11039 | .index port||for daemon |
| 11040 | .index TCP/IP||setting listening ports |
| 11041 | .conf daemon@_smtp@_ports string "$tt{smtp}" |
| 11042 | This option specifies one or more default SMTP ports on which the Exim daemon |
| 11043 | listens. See chapter ~~CHAPinterfaces for details of how it is used. For |
| 11044 | backward compatibility, \daemon@_smtp@_port\ (singular) is a synonym. |
| 11045 | |
| 11046 | .conf delay@_warning "time list" 24h |
| 11047 | .index warning of delay |
| 11048 | .index delay warning, specifying |
| 11049 | When a message is delayed, Exim sends a warning message to the sender at |
| 11050 | intervals specified by this option. If it is set to a zero, no warnings are |
| 11051 | sent. The data is a colon-separated list of times after which to send warning |
| 11052 | messages. Up to 10 times may be given. If a message has been on the queue for |
| 11053 | longer than the last time, the last interval between the times is used to |
| 11054 | compute subsequent warning times. For example, with |
| 11055 | .display asis |
| 11056 | delay_warning = 4h:8h:24h |
| 11057 | .endd |
| 11058 | the first message is sent after 4 hours, the second after 8 hours, and |
| 11059 | the third one after 24 hours. After that, messages are sent every 16 hours, |
| 11060 | because that is the interval between the last two times on the list. If you set |
| 11061 | just one time, it specifies the repeat interval. For example, with: |
| 11062 | .display asis |
| 11063 | delay_warning = 6h |
| 11064 | .endd |
| 11065 | messages are repeated every six hours. To stop warnings after a given time, set |
| 11066 | a very large time at the end of the list. For example: |
| 11067 | .display asis |
| 11068 | delay_warning = 2h:12h:99d |
| 11069 | .endd |
| 11070 | |
| 11071 | .conf delay@_warning@_condition string$**$ "see below" |
| 11072 | The string is expanded at the time a warning message might be sent. If all the |
| 11073 | deferred addresses have the same domain, it is set in \$domain$\ during the |
| 11074 | expansion. Otherwise \$domain$\ is empty. If the result of the expansion is a |
| 11075 | forced failure, an empty string, or a string matching any of `0', `no' or |
| 11076 | `false' (the comparison being done caselessly) then the warning message is not |
| 11077 | sent. The default is |
| 11078 | .display asis |
| 11079 | delay_warning_condition = \ |
| 11080 | ${if match{$h_precedence:}{(?i)bulk|list|junk}{no}{yes}} |
| 11081 | .endd |
| 11082 | which suppresses the sending of warnings about messages that have `bulk', |
| 11083 | `list' or `junk' in a ::Precedence:: header. |
| 11084 | |
| 11085 | .index unprivileged delivery |
| 11086 | .index delivery||unprivileged |
| 11087 | .conf deliver@_drop@_privilege boolean false |
| 11088 | If this option is set true, Exim drops its root privilege at the start of a |
| 11089 | delivery process, and runs as the Exim user throughout. This severely restricts |
| 11090 | the kinds of local delivery that are possible, but is viable in certain types |
| 11091 | of configuration. There is a discussion about the use of root privilege in |
| 11092 | chapter ~~CHAPsecurity. |
| 11093 | |
| 11094 | .index load average |
| 11095 | .index queue runner||abandoning |
| 11096 | .conf deliver@_queue@_load@_max fixed-point unset |
| 11097 | When this option is set, a queue run is abandoned if the system load average |
| 11098 | becomes greater than the value of the option. The option has no effect on |
| 11099 | ancient operating systems on which Exim cannot determine the load average. |
| 11100 | See also \queue@_only@_load\ and \smtp@_load@_reserve\. |
| 11101 | |
| 11102 | .conf delivery@_date@_remove boolean true |
| 11103 | .index ::Delivery-date:: header line |
| 11104 | Exim's transports have an option for adding a ::Delivery-date:: header to a |
| 11105 | message when it is delivered -- in exactly the same way as ::Return-path:: is |
| 11106 | handled. ::Delivery-date:: records the actual time of delivery. Such headers |
| 11107 | should not be present in incoming messages, and this option causes them to be |
| 11108 | removed at the time the message is received, to avoid any problems that might |
| 11109 | occur when a delivered message is subsequently sent on to some other recipient. |
| 11110 | |
| 11111 | .index DNS||`try again' response, overriding |
| 11112 | .conf dns@_again@_means@_nonexist "domain list$**$" unset |
| 11113 | DNS lookups give a `try again' response for the DNS errors `non-authoritative |
| 11114 | host not found' and `\\SERVERFAIL\\'. This can cause Exim to keep trying to |
| 11115 | deliver a message, or to give repeated temporary errors to incoming mail. |
| 11116 | Sometimes the effect is caused by a badly set up name server and may persist |
| 11117 | for a long time. If a domain which exhibits this problem matches anything in |
| 11118 | \dns__again__means__nonexist\, it is treated as if it did not exist. This |
| 11119 | option should be used with care. |
| 11120 | You can make it apply to reverse lookups by a setting such as this: |
| 11121 | .display asis |
| 11122 | dns_again_means_nonexist = *.in-addr.arpa |
| 11123 | .endd |
| 11124 | |
| 11125 | .index DNS||pre-check of name syntax |
| 11126 | .conf dns@_check@_names@_pattern string "see below" |
| 11127 | When this option is set to a non-empty string, it causes Exim to check domain |
| 11128 | names for illegal characters before handing them to the DNS resolver, because |
| 11129 | some resolvers give temporary errors for malformed names. If a domain name |
| 11130 | contains any illegal characters, a `not found' result is forced, and the |
| 11131 | resolver is not called. The check is done by matching the domain name against a |
| 11132 | regular expression, which is the value of this option. The default pattern is |
| 11133 | .display asis |
| 11134 | dns_check_names_pattern = \ |
| 11135 | (?i)^(?>(?(1)\.|())[^\W_](?>[a-z0-9-]*[^\W_])?)+$ |
| 11136 | .endd |
| 11137 | which permits only letters, digits, and hyphens in components, but they may not |
| 11138 | start or end with a hyphen. |
| 11139 | If you set \allow@_utf8@_domains\, you must modify this pattern, or set the |
| 11140 | option to an empty string. |
| 11141 | |
| 11142 | .conf dns@_ipv4@_lookup "domain list$**$" unset |
| 11143 | .index IPv6||DNS lookup for AAAA records |
| 11144 | .index DNS||IPv6 lookup for AAAA records |
| 11145 | When Exim is compiled with IPv6 support, it looks for IPv6 address records |
| 11146 | (AAAA and, if configured, A6) as well as IPv4 address records when trying to |
| 11147 | find IP addresses for hosts, unless the host's domain matches this list. |
| 11148 | |
| 11149 | This is a fudge to help with name servers that give big delays or otherwise do |
| 11150 | not work for the new IPv6 record types. If Exim is handed an IPv6 address |
| 11151 | record as a result of an MX lookup, it always recognizes it, and may as a |
| 11152 | result make an outgoing IPv6 connection. All this option does is to make Exim |
| 11153 | look only for IPv4-style A records when it needs to find an IP address for a |
| 11154 | host name. In due course, when the world's name servers have all been upgraded, |
| 11155 | there should be no need for this option. |
| 11156 | |
| 11157 | .conf dns@_retrans time 0s |
| 11158 | .index DNS||resolver options |
| 11159 | The options \dns@_retrans\ and \dns@_retry\ can be used to set the |
| 11160 | retransmission and retry parameters for DNS lookups. Values of zero (the |
| 11161 | defaults) leave the system default settings unchanged. The first value is the |
| 11162 | time between retries, and the second is the number of retries. It isn't |
| 11163 | totally clear exactly how these settings affect the total time a DNS lookup may |
| 11164 | take. I haven't found any documentation about timeouts on DNS lookups; these |
| 11165 | parameter values are available in the external resolver interface structure, |
| 11166 | but nowhere does it seem to describe how they are used or what you might want |
| 11167 | to set in them. |
| 11168 | |
| 11169 | .conf dns@_retry integer 0 |
| 11170 | See \dns@_retrans\ above. |
| 11171 | |
| 11172 | .conf drop@_cr boolean false |
| 11173 | This is an obsolete option that is now a no-op. It used to affect the way Exim |
| 11174 | handled CR and LF characters in incoming messages. What happens now is |
| 11175 | described in section ~~SECTlineendings. |
| 11176 | |
| 11177 | .conf envelope@_to@_remove boolean true |
| 11178 | .index ::Envelope-to:: header line |
| 11179 | Exim's transports have an option for adding an ::Envelope-to:: header to a |
| 11180 | message when it is delivered -- in exactly the same way as ::Return-path:: is |
| 11181 | handled. ::Envelope-to:: records the original recipient address from the |
| 11182 | messages's envelope that caused the delivery to happen. Such headers should not |
| 11183 | be present in incoming messages, and this option causes them to be removed at |
| 11184 | the time the message is received, to avoid any problems that might occur when a |
| 11185 | delivered message is subsequently sent on to some other recipient. |
| 11186 | |
| 11187 | .conf errors@_copy "string list$**$" unset |
| 11188 | .index bounce message||copy to other address |
| 11189 | .index copy of bounce message |
| 11190 | Setting this option causes Exim to send bcc copies of bounce messages that it |
| 11191 | generates to other addresses. \**Note**\: this does not apply to bounce messages |
| 11192 | coming from elsewhere. The value of the option is a colon-separated list of |
| 11193 | items. Each item consists of a pattern, terminated by white space, followed by |
| 11194 | a comma-separated list of email addresses. If a pattern contains spaces, it |
| 11195 | must be enclosed in double quotes. |
| 11196 | |
| 11197 | Each pattern is processed in the same way as a single item in an address list |
| 11198 | (see section ~~SECTaddresslist). When a pattern matches the recipient of the |
| 11199 | bounce message, the message is copied to the addresses on the list. The items |
| 11200 | are scanned in order, and once a matching one is found, no further items are |
| 11201 | examined. For example: |
| 11202 | .display asis |
| 11203 | errors_copy = spqr@mydomain postmaster@mydomain.example :\ |
| 11204 | rqps@mydomain hostmaster@mydomain.example,\ |
| 11205 | postmaster@mydomain.example |
| 11206 | .endd |
| 11207 | The address list is expanded before use. The expansion variables |
| 11208 | \$local@_part$\ and \$domain$\ are set from the original recipient of the error |
| 11209 | message, and if there was any wildcard matching in the pattern, the expansion |
| 11210 | .index numerical variables (\$1$\, \$2$\, etc)||in \errors@_copy\ |
| 11211 | variables \$0$\, \$1$\, etc. are set in the normal way. |
| 11212 | |
| 11213 | .conf errors@_reply@_to string unset |
| 11214 | .index bounce message||::Reply-to:: in |
| 11215 | Exim's bounce and delivery warning messages contain the header line |
| 11216 | .display |
| 11217 | From: Mail Delivery System @<Mailer-Daemon@@<<qualify-domain>>@> |
| 11218 | .endd |
| 11219 | where <<qualify-domain>> is the value of the \qualify@_domain\ option. |
| 11220 | Experience shows that people reply to bounce messages. If the |
| 11221 | \errors@_reply@_to\ option is set, a ::Reply-To:: header is added to bounce and |
| 11222 | warning messages. For example: |
| 11223 | .display asis |
| 11224 | errors_reply_to = postmaster@my.domain.example |
| 11225 | .endd |
| 11226 | The value of the option is not expanded. It must specify a valid RFC 2822 |
| 11227 | address. |
| 11228 | |
| 11229 | .conf exim@_group string "compile-time configured" |
| 11230 | .index gid (group id)||Exim's own |
| 11231 | .index Exim group |
| 11232 | This option changes the gid under which Exim runs when it gives up root |
| 11233 | privilege. The default value is compiled into the binary. The value of this |
| 11234 | option is used only when \exim@_user\ is also set. Unless it consists entirely |
| 11235 | of digits, the string is looked up using \*getgrnam()*\, and failure causes a |
| 11236 | configuration error. See chapter ~~CHAPsecurity for a discussion of security |
| 11237 | issues. |
| 11238 | |
| 11239 | .conf exim@_path string "see below" |
| 11240 | .index Exim binary, path name |
| 11241 | This option specifies the path name of the Exim binary, which is used when Exim |
| 11242 | needs to re-exec itself. The default is set up to point to the file \*exim*\ in |
| 11243 | the directory configured at compile time by the \\BIN@_DIRECTORY\\ setting. It |
| 11244 | is necessary to change \exim@_path\ if, exceptionally, Exim is run from some |
| 11245 | other place. |
| 11246 | \**Warning**\: Do not use a macro to define the value of this option, because |
| 11247 | you will break those Exim utilities that scan the configuration file to find |
| 11248 | where the binary is. (They then use the \-bP-\ option to extract option |
| 11249 | settings such as the value of \spool@_directory\.) |
| 11250 | |
| 11251 | .conf exim@_user string "compile-time configured" |
| 11252 | .index uid (user id)||Exim's own |
| 11253 | .index Exim user |
| 11254 | This option changes the uid under which Exim runs when it gives up root |
| 11255 | privilege. The default value is compiled into the binary. Ownership of the run |
| 11256 | time configuration file and the use of the \-C-\ and \-D-\ command line options |
| 11257 | is checked against the values in the binary, not what is set here. |
| 11258 | |
| 11259 | Unless it consists entirely of digits, the string is looked up using |
| 11260 | \*getpwnam()*\, and failure causes a configuration error. If \exim@_group\ is |
| 11261 | not also supplied, the gid is taken from the result of \*getpwnam()*\ if it is |
| 11262 | used. See chapter ~~CHAPsecurity for a discussion of security issues. |
| 11263 | |
| 11264 | .conf extra@_local@_interfaces "string list" unset |
| 11265 | .index |
| 11266 | This option defines network interfaces that are to be considered local when |
| 11267 | routing, but which are not used for listening by the daemon. See section |
| 11268 | ~~SECTreclocipadd for details. |
| 11269 | |
| 11270 | .conf extract@_addresses@_remove@_arguments boolean true |
| 11271 | .index \-t-\ option |
| 11272 | .index command line||addresses with \-t-\ |
| 11273 | .index Sendmail compatibility||\-t-\ option |
| 11274 | According to some Sendmail documentation (Sun, IRIX, HP-UX), if any addresses |
| 11275 | are present on the command line when the \-t-\ option is used to build an |
| 11276 | envelope from a message's ::To::, ::Cc:: and ::Bcc:: headers, the command line |
| 11277 | addresses are removed from the recipients list. This is also how Smail behaves. |
| 11278 | However, other Sendmail documentation (the O'Reilly book) states that command |
| 11279 | line addresses are added to those obtained from the header lines. When |
| 11280 | \extract@_addresses@_remove@_arguments\ is true (the default), Exim subtracts |
| 11281 | argument headers. If it is set false, Exim adds rather than removes argument |
| 11282 | addresses. |
| 11283 | |
| 11284 | .conf finduser@_retries integer 0 |
| 11285 | .index NIS, looking up users, retrying |
| 11286 | On systems running NIS or other schemes in which user and group information is |
| 11287 | distributed from a remote system, there can be times when \*getpwnam()*\ and |
| 11288 | related functions fail, even when given valid data, because things time out. |
| 11289 | Unfortunately these failures cannot be distinguished from genuine `not found' |
| 11290 | errors. If \finduser@_retries\ is set greater than zero, Exim will try that |
| 11291 | many extra times to find a user or a group, waiting for one second between |
| 11292 | retries. |
| 11293 | |
| 11294 | .conf freeze@_tell "string list, comma separated" unset |
| 11295 | .index freezing messages||sending a message when freezing |
| 11296 | On encountering certain errors, or when configured to do so in a system filter, |
| 11297 | or in an ACL, |
| 11298 | Exim freezes a message. This means that no further delivery attempts take place |
| 11299 | until an administrator (or the \auto@_thaw\ feature) thaws the message. If |
| 11300 | \freeze@_tell\ is set, Exim generates a warning message whenever it freezes |
| 11301 | something, unless the message it is freezing is a |
| 11302 | locally-generated |
| 11303 | bounce message. (Without this exception there is the possibility of looping.) |
| 11304 | The warning message is sent to the addresses supplied as the comma-separated |
| 11305 | value of this option. If several of the message's addresses cause freezing, |
| 11306 | only a single message is sent. |
| 11307 | If the freezing was automatic, the reason(s) for freezing can be found in the |
| 11308 | message log. If you configure freezing in a filter or ACL, you must arrange for |
| 11309 | any logging that you require. |
| 11310 | |
| 11311 | .conf gecos@_name string$**$ unset |
| 11312 | .index HP-UX |
| 11313 | .index `gecos' field, parsing |
| 11314 | Some operating systems, notably HP-UX, use the `gecos' field in the system |
| 11315 | password file to hold other information in addition to users' real names. Exim |
| 11316 | looks up this field for use when it is creating ::Sender:: or ::From:: headers. |
| 11317 | If either \gecos@_pattern\ or \gecos@_name\ are unset, the contents of the |
| 11318 | field are used unchanged, except that, if an ampersand is encountered, it is |
| 11319 | replaced by the user's login name with the first character forced to |
| 11320 | upper case, since this is a convention that is observed on many systems. |
| 11321 | |
| 11322 | When these options are set, \gecos@_pattern\ is treated as a regular expression |
| 11323 | that is to be applied to the field (again with & replaced by the login name), |
| 11324 | and if it matches, \gecos@_name\ is expanded and used as the user's name. |
| 11325 | .index numerical variables (\$1$\, \$2$\, etc)||in \gecos@_name\ |
| 11326 | Numeric variables such as \$1$\, \$2$\, etc. can be used in the expansion to |
| 11327 | pick up sub-fields that were matched by the pattern. In HP-UX, where the user's |
| 11328 | name terminates at the first comma, the following can be used: |
| 11329 | .display asis |
| 11330 | gecos_pattern = ([^,]*) |
| 11331 | gecos_name = $1 |
| 11332 | .endd |
| 11333 | |
| 11334 | .conf gecos@_pattern string unset |
| 11335 | See \gecos@_name\ above. |
| 11336 | |
| 11337 | .conf headers@_charset string "see below" |
| 11338 | This option sets a default character set for translating from encoded MIME |
| 11339 | `words' in header lines, when referenced by an \$h@_xxx$\ expansion item. The |
| 11340 | default is the value of \\HEADERS@_CHARSET\\ in \(Local/Makefile)\. The |
| 11341 | ultimate default is ISO-8859-1. For more details see the description of header |
| 11342 | insertions in section ~~SECTexpansionitems. |
| 11343 | |
| 11344 | |
| 11345 | .conf header@_maxsize integer "see below" |
| 11346 | .index header section||maximum size of |
| 11347 | .index limit||size of message header section |
| 11348 | This option controls the overall maximum size of a message's header |
| 11349 | section. The default is the value of \\HEADER@_MAXSIZE\\ in |
| 11350 | \(Local/Makefile)\; the default for that is 1M. Messages with larger header |
| 11351 | sections are rejected. |
| 11352 | |
| 11353 | .conf header@_line@_maxsize integer 0 |
| 11354 | .index header lines||maximum size of |
| 11355 | .index limit||size of one header line |
| 11356 | This option limits the length of any individual header line in a message, after |
| 11357 | all the continuations have been joined together. Messages with individual |
| 11358 | header lines that are longer than the limit are rejected. The default value of |
| 11359 | zero means `no limit'. |
| 11360 | |
| 11361 | |
| 11362 | |
| 11363 | .conf helo@_accept@_junk@_hosts "host list$**$" unset |
| 11364 | .index \\HELO\\||accepting junk data |
| 11365 | .index \\EHLO\\||accepting junk data |
| 11366 | Exim checks the syntax of \\HELO\\ and \\EHLO\\ commands for incoming SMTP |
| 11367 | mail, and gives an error response for invalid data. Unfortunately, there are |
| 11368 | some SMTP clients that send syntactic junk. They can be accommodated by setting |
| 11369 | this option. Note that this is a syntax check only. See \helo@_verify@_hosts\ |
| 11370 | if you want to do semantic checking. |
| 11371 | See also \helo@_allow@_chars\ for a way of extending the permitted character |
| 11372 | set. |
| 11373 | |
| 11374 | .conf helo@_allow@_chars string unset |
| 11375 | .index \\HELO\\||underscores in |
| 11376 | .index \\EHLO\\||underscores in |
| 11377 | .index underscore in \\EHLO\\/\\HELO\\ |
| 11378 | This option can be set to a string of rogue characters that are permitted in |
| 11379 | all \\EHLO\\ and \\HELO\\ names in addition to the standard letters, digits, |
| 11380 | hyphens, and dots. If you really must allow underscores, you can set |
| 11381 | .display asis |
| 11382 | helo_allow_chars = _ |
| 11383 | .endd |
| 11384 | Note that the value is one string, not a list. |
| 11385 | |
| 11386 | .conf helo@_lookup@_domains "domain list$**$" "$tt{@@:@@[]}" |
| 11387 | .index \\HELO\\||forcing reverse lookup |
| 11388 | .index \\EHLO\\||forcing reverse lookup |
| 11389 | If the domain given by a client in a \\HELO\\ or \\EHLO\\ command matches this |
| 11390 | list, a reverse lookup is done in order to establish the host's true name. The |
| 11391 | default forces a lookup if the client host gives the server's name or any of |
| 11392 | its IP addresses (in brackets), something that broken clients have been seen to |
| 11393 | do. |
| 11394 | |
| 11395 | .conf helo@_try@_verify@_hosts "host list$**$" unset |
| 11396 | .index \\HELO\\||verifying, optional |
| 11397 | .index \\EHLO\\||verifying, optional |
| 11398 | The RFCs mandate that a server must not reject a message because it doesn't |
| 11399 | like the \\HELO\\ or \\EHLO\\ command. By default, Exim just checks the syntax |
| 11400 | of these commands (see \helo__accept__junk__hosts\ and \helo@_allow@_chars\ |
| 11401 | above). However, some sites like to be stricter. If the calling host matches |
| 11402 | \helo@_try@_verify@_hosts\, Exim checks that the host name given in the \\HELO\\ |
| 11403 | or \\EHLO\\ command either: |
| 11404 | .numberpars $. |
| 11405 | is an IP literal matching the calling address of the host (the RFCs |
| 11406 | specifically allow this), or |
| 11407 | .nextp |
| 11408 | .index DNS||reverse lookup |
| 11409 | .index reverse DNS lookup |
| 11410 | matches the host name that Exim obtains by doing a reverse lookup of the |
| 11411 | calling host address, or |
| 11412 | .nextp |
| 11413 | when looked up using \*gethostbyname()*\ (or \*getipnodebyname()*\ when |
| 11414 | available) yields the calling host address. |
| 11415 | .endp |
| 11416 | However, the \\EHLO\\ or \\HELO\\ command is not rejected if any of the checks |
| 11417 | fail. Processing continues, but the result of the check is remembered, and can |
| 11418 | be detected later in an ACL by the \"verify = helo"\ condition. If you want |
| 11419 | verification failure to cause rejection of \\EHLO\\ or \\HELO\\, use |
| 11420 | \helo@_verify@_hosts\ instead. |
| 11421 | |
| 11422 | |
| 11423 | .conf helo@_verify@_hosts "host list$**$" unset |
| 11424 | .index \\HELO\\||verifying, mandatory |
| 11425 | .index \\EHLO\\||verifying, mandatory |
| 11426 | For hosts that match this option, Exim checks the host name given in the |
| 11427 | \\HELO\\ or \\EHLO\\ in the same way as for \helo@_try@_verify@_hosts\. If the |
| 11428 | check fails, the \\HELO\\ or \\EHLO\\ command is rejected with a 550 error, and |
| 11429 | entries are written to the main and reject logs. If a \\MAIL\\ command is |
| 11430 | received before \\EHLO\\ or \\HELO\\, it is rejected with a |
| 11431 | 503 |
| 11432 | error. |
| 11433 | |
| 11434 | .conf hold@_domains "domain list$**$" unset |
| 11435 | .index domain||delaying delivery |
| 11436 | .index delivery||delaying certain domains |
| 11437 | This option allows mail for particular domains to be held on the queue |
| 11438 | manually. The option is overridden if a message delivery is forced with the |
| 11439 | \-M-\, \-qf-\, \-Rf-\ or \-Sf-\ options, and also while testing or verifying |
| 11440 | addresses using \-bt-\ or \-bv-\. Otherwise, if a domain matches an item in |
| 11441 | \hold@_domains\, no routing or delivery for that address is done, and it is |
| 11442 | deferred every time the message is looked at. |
| 11443 | |
| 11444 | This option is intended as a temporary operational measure for delaying the |
| 11445 | delivery of mail while some problem is being sorted out, or some new |
| 11446 | configuration tested. If you just want to delay the processing of some |
| 11447 | domains until a queue run occurs, you should use \queue@_domains\ or |
| 11448 | \queue@_smtp@_domains\, not \hold@_domains\. |
| 11449 | |
| 11450 | A setting of \hold@_domains\ does not override Exim's code for removing |
| 11451 | messages from the queue if they have been there longer than the longest retry |
| 11452 | time in any retry rule. If you want to hold messages for longer than the normal |
| 11453 | retry times, insert a dummy retry rule with a long retry time. |
| 11454 | |
| 11455 | .conf host@_lookup "host list$**$" unset |
| 11456 | .index host||name lookup, forcing |
| 11457 | Exim does not look up the name of a calling host from its IP address unless it |
| 11458 | is required to compare against some host list, or the host matches |
| 11459 | \helo@_try@_verify@_hosts\ or \helo@_verify@_hosts\, or the host matches this |
| 11460 | option (which normally contains IP addresses rather than host names). The |
| 11461 | default configuration file contains |
| 11462 | .display asis |
| 11463 | host_lookup = * |
| 11464 | .endd |
| 11465 | which causes a lookup to happen for all hosts. If the expense of these lookups |
| 11466 | is felt to be too great, the setting can be changed or removed. |
| 11467 | |
| 11468 | After a successful reverse lookup, Exim does a forward lookup on the name it |
| 11469 | has obtained, to verify that it yields the IP address that it started with. If |
| 11470 | this check fails, Exim behaves as if the name lookup failed. |
| 11471 | |
| 11472 | After any kind of failure, the host name (in \$sender@_host@_name$\) remains |
| 11473 | unset, and \$host@_lookup@_failed$\ is set to the string `1'. See also |
| 11474 | \dns@_again@_means@_nonexist\, \helo__lookup__domains\, and \"verify = |
| 11475 | reverse@_host@_lookup"\ in ACLs. |
| 11476 | |
| 11477 | .conf host@_lookup@_order "string list" $tt{bydns:byaddr} |
| 11478 | This option specifies the order of different lookup methods when Exim is trying |
| 11479 | to find a host name from an IP address. The default is to do a DNS lookup |
| 11480 | first, and then to try a local lookup (using \*gethostbyaddr()*\ or equivalent) |
| 11481 | if that fails. You can change the order of these lookups, or omit one entirely, |
| 11482 | if you want. |
| 11483 | |
| 11484 | \**Warning**\: the `byaddr' method does not always yield aliases when there are |
| 11485 | multiple PTR records in the DNS and the IP address is not listed in |
| 11486 | \(/etc/hosts)\. Different operating systems give different results in this |
| 11487 | case. That is why the default tries a DNS lookup first. |
| 11488 | |
| 11489 | |
| 11490 | .conf host@_reject@_connection "host list$**$" unset |
| 11491 | .index host||rejecting connections from |
| 11492 | If this option is set, incoming SMTP calls from the hosts listed are rejected |
| 11493 | as soon as the connection is made. |
| 11494 | This option is obsolete, and retained only for backward compatibility, because |
| 11495 | nowadays the ACL specified by \acl@_smtp@_connect\ can also reject incoming |
| 11496 | connections immediately. |
| 11497 | |
| 11498 | The ability to give an immediate rejection (either by this option or using an |
| 11499 | ACL) is provided for use in unusual cases. Many hosts will just try again, |
| 11500 | sometimes without much delay. Normally, it is better to use an ACL to reject |
| 11501 | incoming messages at a later stage, such as after \\RCPT\\ commands. See |
| 11502 | chapter ~~CHAPACL. |
| 11503 | |
| 11504 | .conf hosts@_treat@_as@_local "domain list$**$" unset |
| 11505 | .index local host||domains treated as |
| 11506 | .index host||treated as local |
| 11507 | If this option is set, any host names that match the domain list are treated as |
| 11508 | if they were the local host when Exim is scanning host lists obtained from MX |
| 11509 | records |
| 11510 | or other sources. Note that the value of this option is a domain list, not a |
| 11511 | host list, because it is always used to check host names, not IP addresses. |
| 11512 | |
| 11513 | This option also applies when Exim is matching the special items |
| 11514 | \"@@mx@_any"\, \"@@mx@_primary"\, and \"@@mx@_secondary"\ in a domain list (see |
| 11515 | section ~~SECTdomainlist), and when checking the \hosts\ option in the \%smtp%\ |
| 11516 | transport for the local host (see the \allow@_localhost\ option in that |
| 11517 | transport). |
| 11518 | See also \local@_interfaces\, \extra@_local@_interfaces\, and chapter |
| 11519 | ~~CHAPinterfaces, which contains a discussion about local network interfaces |
| 11520 | and recognising the local host. |
| 11521 | |
| 11522 | .conf ignore@_bounce@_errors@_after time 10w |
| 11523 | .index bounce message||discarding |
| 11524 | .index discarding bounce message |
| 11525 | This option affects the processing of bounce messages that cannot be delivered, |
| 11526 | that is, those that suffer a permanent delivery failure. (Bounce messages that |
| 11527 | suffer temporary delivery failures are of course retried in the usual way.) |
| 11528 | |
| 11529 | After a permanent delivery failure, bounce messages are frozen, |
| 11530 | because there is no sender to whom they can be returned. When a frozen bounce |
| 11531 | message has been on the queue for more than the given time, it is unfrozen at |
| 11532 | the next queue run, and a further delivery is attempted. If delivery fails |
| 11533 | again, the bounce message is discarded. This makes it possible to keep failed |
| 11534 | bounce messages around for a shorter time than the normal maximum retry time |
| 11535 | for frozen messages. For example, |
| 11536 | .display asis |
| 11537 | ignore_bounce_errors_after = 12h |
| 11538 | .endd |
| 11539 | retries failed bounce message deliveries after 12 hours, discarding any further |
| 11540 | failures. If the value of this option is set to a zero time period, bounce |
| 11541 | failures are discarded immediately. Setting a very long time (as in the default |
| 11542 | value) has the effect of disabling this option. For ways of automatically |
| 11543 | dealing with other kinds of frozen message, see \auto@_thaw\ and |
| 11544 | \timeout@_frozen@_after\. |
| 11545 | |
| 11546 | .conf ignore@_fromline@_hosts "host list$**$" unset |
| 11547 | .index `From' line |
| 11548 | .index UUCP||`From' line |
| 11549 | Some broken SMTP clients insist on sending a UUCP-like `From' line before the |
| 11550 | headers of a message. By default this is treated as the start of the message's |
| 11551 | body, which means that any following headers are not recognized as such. Exim |
| 11552 | can be made to ignore it by setting \ignore@_fromline@_hosts\ to match those |
| 11553 | hosts that insist on sending it. If the sender is actually a local process |
| 11554 | rather than a remote host, and is using \-bs-\ to inject the messages, |
| 11555 | \ignore__fromline__local\ must be set to achieve this effect. |
| 11556 | |
| 11557 | .conf ignore@_fromline@_local boolean false |
| 11558 | See \ignore@_fromline@_hosts\ above. |
| 11559 | |
| 11560 | .conf keep@_malformed time 4d |
| 11561 | This option specifies the length of time to keep messages whose spool files |
| 11562 | have been corrupted in some way. This should, of course, never happen. At the |
| 11563 | next attempt to deliver such a message, it gets removed. The incident is |
| 11564 | logged. |
| 11565 | |
| 11566 | .conf ldap@_default@_servers "string list" unset |
| 11567 | .index LDAP||default servers |
| 11568 | This option provides a list of LDAP servers which are tried in turn when an |
| 11569 | LDAP query does not contain a server. See section ~~SECTforldaque for details |
| 11570 | of LDAP queries. This option is available only when Exim has been built with |
| 11571 | LDAP support. |
| 11572 | |
| 11573 | .conf ldap@_version integer unset |
| 11574 | .index LDAP||protocol version, forcing |
| 11575 | This option can be used to force Exim to set a specific protocol version for |
| 11576 | LDAP. If it option is unset, it is shown by the \-bP-\ command line option as |
| 11577 | -1. When this is the case, the default is 3 if \\LDAP@_VERSION3\\ is defined in |
| 11578 | the LDAP headers; otherwise it is 2. This option is available only when Exim |
| 11579 | has been built with LDAP support. |
| 11580 | |
| 11581 | |
| 11582 | .conf local@_from@_check boolean true |
| 11583 | .index ::Sender:: header line||disabling addition of |
| 11584 | .index ::From:: header line||disabling checking of |
| 11585 | When a message is submitted locally (that is, not over a TCP/IP connection) by |
| 11586 | an untrusted user, Exim removes any existing ::Sender:: header line, and checks |
| 11587 | that the ::From:: header line matches the login of the calling user. You can |
| 11588 | use \local@_from@_prefix\ and \local@_from@_suffix\ to permit affixes on the |
| 11589 | local part. If the ::From:: header line does not match, Exim adds a ::Sender:: |
| 11590 | header with an address constructed from the calling user's login and the |
| 11591 | default qualify domain. |
| 11592 | |
| 11593 | If \local@_from@_check\ is set false, the ::From:: header check is disabled, |
| 11594 | and no ::Sender:: header is ever added. If, in addition, you want to retain |
| 11595 | ::Sender:: header lines supplied by untrusted users, you must also set |
| 11596 | \local@_sender@_retain\ to be true. |
| 11597 | |
| 11598 | .index envelope sender |
| 11599 | These options affect only the header lines in the message. The envelope sender |
| 11600 | is still forced to be the login id at the qualify domain unless |
| 11601 | \untrusted@_set@_sender\ permits the user to supply an envelope sender. |
| 11602 | Section ~~SECTthesenhea has more details about ::Sender:: processing. |
| 11603 | |
| 11604 | |
| 11605 | .conf local@_from@_prefix string unset |
| 11606 | When Exim checks the ::From:: header line of locally submitted messages for |
| 11607 | matching the login id (see \local@_from@_check\ above), it can be configured to |
| 11608 | ignore certain prefixes and suffixes in the local part of the address. This is |
| 11609 | done by setting \local@_from@_prefix\ and/or \local@_from@_suffix\ to |
| 11610 | appropriate lists, in the same form as the \local@_part@_prefix\ and |
| 11611 | \local@_part@_suffix\ router options (see chapter ~~CHAProutergeneric). For |
| 11612 | example, if |
| 11613 | .display asis |
| 11614 | local_from_prefix = *- |
| 11615 | .endd |
| 11616 | is set, a ::From:: line containing |
| 11617 | .display asis |
| 11618 | From: anything-user@your.domain.example |
| 11619 | .endd |
| 11620 | will not cause a ::Sender:: header to be added if \*user@@your.domain.example*\ |
| 11621 | matches the actual sender address that is constructed from the login name and |
| 11622 | qualify domain. |
| 11623 | |
| 11624 | .conf local@_from@_suffix string unset |
| 11625 | See \local@_from@_prefix\ above. |
| 11626 | |
| 11627 | .conf local@_interfaces "string list" "see below" |
| 11628 | This option controls which network interfaces are used by the daemon for |
| 11629 | listening; they are also used to identify the local host when routing. Chapter |
| 11630 | ~~CHAPinterfaces contains a full description of this option and the related |
| 11631 | options \extra@_local@_interfaces\ and \hosts@_treat@_as@_local\. The default |
| 11632 | value for \local@_interfaces\ is |
| 11633 | .display asis |
| 11634 | local_interfaces = 0.0.0.0 |
| 11635 | .endd |
| 11636 | when Exim is built without IPv6 support; otherwise it is |
| 11637 | .display asis |
| 11638 | local_interfaces = <; ::0 ; 0.0.0.0 |
| 11639 | .endd |
| 11640 | |
| 11641 | .conf local@_scan@_timeout time 5m |
| 11642 | .index timeout||for \*local@_scan()*\ function |
| 11643 | .index \*local@_scan()*\ function||timeout |
| 11644 | This timeout applies to the \*local@_scan()*\ function (see chapter |
| 11645 | ~~CHAPlocalscan). Zero means `no timeout'. If the timeout is exceeded, the |
| 11646 | incoming message is rejected with a temporary error if it is an SMTP message. |
| 11647 | For a non-SMTP message, the message is dropped and Exim ends with a non-zero |
| 11648 | code. The incident is logged on the main and reject logs. |
| 11649 | |
| 11650 | |
| 11651 | .conf local@_sender@_retain boolean false |
| 11652 | .index ::Sender:: header line||retaining from local submission |
| 11653 | When a message is submitted locally (that is, not over a TCP/IP connection) by |
| 11654 | an untrusted user, Exim removes any existing ::Sender:: header line. If you |
| 11655 | do not want this to happen, you must set \local@_sender@_retain\, and you must |
| 11656 | also set \local@_from@_check\ to be false (Exim will complain if you do not). |
| 11657 | Section ~~SECTthesenhea has more details about ::Sender:: processing. |
| 11658 | |
| 11659 | |
| 11660 | |
| 11661 | .conf localhost@_number string$**$ unset |
| 11662 | .index host||locally unique number for |
| 11663 | .index message||ids, with multiple hosts |
| 11664 | Exim's message ids are normally unique only within the local host. If |
| 11665 | uniqueness among a set of hosts is required, each host must set a different |
| 11666 | value for the \localhost@_number\ option. The string is expanded immediately |
| 11667 | after reading the configuration file (so that a number can be computed from the |
| 11668 | host name, for example) and the result of the expansion must be a number in the |
| 11669 | range 0--16 (or 0--10 on operating systems with case-insensitive file systems). |
| 11670 | This is available in subsequent string expansions via the variable |
| 11671 | \$localhost@_number$\. When \localhost@_number is set\, the final two |
| 11672 | characters of the message id, instead of just being a fractional part of the |
| 11673 | time, are computed from the time and the local host number as described in |
| 11674 | section ~~SECTmessiden. |
| 11675 | |
| 11676 | |
| 11677 | .conf log@_file@_path "string list$**$" "set at compile time" |
| 11678 | .index log||file path for |
| 11679 | This option sets the path which is used to determine the names of Exim's log |
| 11680 | files, or indicates that logging is to be to syslog, or both. It is expanded |
| 11681 | when Exim is entered, so it can, for example, contain a reference to the host |
| 11682 | name. If no specific path is set for the log files at compile or run time, they |
| 11683 | are written in a sub-directory called \(log)\ in Exim's spool directory. |
| 11684 | Chapter ~~CHAPlog contains further details about Exim's logging, and section |
| 11685 | ~~SECTwhelogwri describes how the contents of \log@_file@_path\ are used. If |
| 11686 | this string is fixed at your installation (contains no expansion variables) it |
| 11687 | is recommended that you do not set this option in the configuration file, but |
| 11688 | instead supply the path using \\LOG@_FILE@_PATH\\ in \(Local/Makefile)\ so that |
| 11689 | it is available to Exim for logging errors detected early on -- in particular, |
| 11690 | failure to read the configuration file. |
| 11691 | |
| 11692 | .conf log@_selector string unset |
| 11693 | .index log||selectors |
| 11694 | This option can be used to reduce or increase the number of things that Exim |
| 11695 | writes to its log files. Its argument is made up of names preceded by plus or |
| 11696 | minus characters. For example: |
| 11697 | .display asis |
| 11698 | log_selector = +arguments -retry_defer |
| 11699 | .endd |
| 11700 | A list of possible names and what they control is given in the chapter on |
| 11701 | logging, in section ~~SECTlogselector. |
| 11702 | |
| 11703 | .conf log@_timezone boolean false |
| 11704 | .index log||timezone for entries |
| 11705 | By default, the timestamps on log lines are in local time without the |
| 11706 | timezone. This means that if your timezone changes twice a year, the timestamps |
| 11707 | in log lines are ambiguous for an hour when the clocks go back. One way of |
| 11708 | avoiding this problem is to set the timezone to UTC. An alternative is to set |
| 11709 | \log@_timezone\ true. This turns on the addition of the timezone offset to |
| 11710 | timestamps in log lines. Turning on this option can add quite a lot to the size |
| 11711 | of log files because each line is extended by 6 characters. Note that the |
| 11712 | \$tod@_log$\ variable contains the log timestamp without the zone, but there is |
| 11713 | another variable called \$tod@_zone$\ that contains just the timezone offset. |
| 11714 | |
| 11715 | .conf lookup@_open@_max integer 25 |
| 11716 | .index too many open files |
| 11717 | .index open files, too many |
| 11718 | .index file||too many open |
| 11719 | .index lookup||maximum open files |
| 11720 | .index limit||open files for lookups |
| 11721 | This option limits the number of simultaneously open files for single-key |
| 11722 | lookups that use regular files (that is, \%lsearch%\, \%dbm%\, and \%cdb%\). Exim |
| 11723 | normally keeps these files open during routing, because often the same file is |
| 11724 | required several times. If the limit is reached, Exim closes the least recently |
| 11725 | used file. Note that if you are using the \*ndbm*\ library, it actually opens |
| 11726 | two files for each logical DBM database, though it still counts as one for the |
| 11727 | purposes of \lookup@_open@_max\. If you are getting `too many open files' |
| 11728 | errors with NDBM, you need to reduce the value of \lookup@_open@_max\. |
| 11729 | |
| 11730 | .conf max@_username@_length integer 0 |
| 11731 | .index length of login name |
| 11732 | .index user name||maximum length |
| 11733 | .index limit||user name length |
| 11734 | Some operating systems are broken in that they truncate long arguments to |
| 11735 | \*getpwnam()*\ to eight characters, instead of returning `no such user'. If |
| 11736 | this option is set greater than zero, any attempt to call \*getpwnam()*\ with |
| 11737 | an argument that is longer behaves as if \*getpwnam()*\ failed. |
| 11738 | |
| 11739 | |
| 11740 | .conf message@_body@_visible integer 500 |
| 11741 | .index body of message||visible size |
| 11742 | .index message||body, visible size |
| 11743 | This option specifies how much of a message's body is to be included in the |
| 11744 | \$message@_body$\ and \$message@_body@_end$\ expansion variables. |
| 11745 | |
| 11746 | .conf message@_id@_header@_domain string$**$ unset |
| 11747 | .index ::Message-ID:: header line |
| 11748 | If this option is set, the string is expanded and used as the right hand side |
| 11749 | (domain) of the ::Message-ID:: header that Exim creates if a |
| 11750 | locally-originated incoming message does not have one. `Locally-originated' |
| 11751 | means `not received over TCP/IP.' |
| 11752 | Otherwise, the primary host name is used. |
| 11753 | Only letters, digits, dot and hyphen are accepted; any other characters are |
| 11754 | replaced by hyphens. If the expansion is forced to fail, or if the result is an |
| 11755 | empty string, the option is ignored. |
| 11756 | |
| 11757 | .conf message@_id@_header@_text string$**$ unset |
| 11758 | If this variable is set, the string is expanded and used to augment the text of |
| 11759 | the ::Message-id:: header that Exim creates if a |
| 11760 | locally-originated |
| 11761 | incoming message does not have one. The text of this header is required by RFC |
| 11762 | 2822 to take the form of an address. By default, Exim uses its internal message |
| 11763 | id as the local part, and the primary host name as the domain. If this option |
| 11764 | is set, it is expanded, and provided the expansion is not forced to fail, and |
| 11765 | does not yield an empty string, the result is inserted into the header |
| 11766 | immediately before the @@, separated from the internal message id by a dot. Any |
| 11767 | characters that are illegal in an address are automatically converted into |
| 11768 | hyphens. This means that variables such as \$tod@_log$\ can be used, because |
| 11769 | the spaces and colons will become hyphens. |
| 11770 | |
| 11771 | .conf message@_logs boolean true |
| 11772 | .index message||log, disabling |
| 11773 | .index log||message log, disabling |
| 11774 | If this option is turned off, per-message log files are not created in the |
| 11775 | \(msglog)\ spool sub-directory. This reduces the amount of disk I/O required by |
| 11776 | Exim, by reducing the number of files involved in handling a message from a |
| 11777 | minimum of four (header spool file, body spool file, delivery journal, and |
| 11778 | per-message log) to three. The other major I/O activity is Exim's main log, |
| 11779 | which is not affected by this option. |
| 11780 | |
| 11781 | .conf message@_size@_limit string$**$ 50M |
| 11782 | .index message||size limit |
| 11783 | .index limit||message size |
| 11784 | .index size||of message, limit |
| 11785 | This option limits the maximum size of message that Exim will process. The |
| 11786 | value is expanded for each incoming |
| 11787 | connection so, for example, it can be made to depend on the IP address of the |
| 11788 | remote host for messages arriving via TCP/IP. \**Note**\: This limit cannot be |
| 11789 | made to depend on a message's sender or any other properties of an individual |
| 11790 | message, because it has to be advertised in the server's response to \\EHLO\\. |
| 11791 | String expansion failure causes a temporary error. A value of zero means no |
| 11792 | limit, but its use is not recommended. See also \bounce@_return@_size@_limit\. |
| 11793 | |
| 11794 | Incoming SMTP messages are failed with a 552 error if the limit is |
| 11795 | exceeded; locally-generated messages either get a stderr message or a delivery |
| 11796 | failure message to the sender, depending on the \-oe-\ setting. Rejection of an |
| 11797 | oversized message is logged in both the main and the reject logs. See also the |
| 11798 | generic transport option \message@_size@_limit\, which limits the size of |
| 11799 | message that an individual transport can process. |
| 11800 | |
| 11801 | .conf move@_frozen@_messages boolean false |
| 11802 | .index frozen messages||moving |
| 11803 | This option, which is available only if Exim has been built with the setting |
| 11804 | .display asis |
| 11805 | SUPPORT_MOVE_FROZEN_MESSAGES=yes |
| 11806 | .endd |
| 11807 | in \(Local/Makefile)\, causes frozen messages and their message logs to be |
| 11808 | moved from the \(input)\ and \(msglog)\ directories on the spool to \(Finput)\ |
| 11809 | and \(Fmsglog)\, respectively. There is currently no support in Exim or the |
| 11810 | standard utilities for handling such moved messages, and they do not show up in |
| 11811 | lists generated by \-bp-\ or by the Exim monitor. |
| 11812 | |
| 11813 | .conf mysql@_servers "string list" unset |
| 11814 | .index MySQL||server list |
| 11815 | This option provides a list of MySQL servers and associated connection data, to |
| 11816 | be used in conjunction with \%mysql%\ lookups (see section ~~SECTsql). The |
| 11817 | option is available only if Exim has been built with MySQL support. |
| 11818 | |
| 11819 | .conf never@_users "string list" unset |
| 11820 | Local message deliveries are normally run in processes that are setuid to the |
| 11821 | recipient, and remote deliveries are normally run under Exim's own uid and gid. |
| 11822 | It is usually desirable to prevent any deliveries from running as root, as a |
| 11823 | safety precaution. |
| 11824 | |
| 11825 | When Exim is built, an option called \\FIXED@_NEVER@_USERS\\ can be set to a |
| 11826 | list of users that must not be used for local deliveries. This list is fixed in |
| 11827 | the binary and cannot be overridden by the configuration file. By default, it |
| 11828 | contains just the single user name `root'. The \never@_users\ runtime option |
| 11829 | can be used to add more users to the fixed list. |
| 11830 | |
| 11831 | If a message is to be delivered as one of the users on the fixed list or the |
| 11832 | \never@_users\ list, an error occurs, and delivery is deferred. A common |
| 11833 | example is |
| 11834 | .display |
| 11835 | never@_users = root:daemon:bin |
| 11836 | .endd |
| 11837 | Including root is redundant if it is also on the fixed list, but it does no |
| 11838 | harm. |
| 11839 | This option overrides the \pipe@_as@_creator\ option of the \%pipe%\ transport |
| 11840 | driver. |
| 11841 | |
| 11842 | .conf oracle@_servers "string list" unset |
| 11843 | .index Oracle||server list |
| 11844 | This option provides a list of Oracle servers and associated connection data, |
| 11845 | to be used in conjunction with \%oracle%\ lookups (see section ~~SECTsql). The |
| 11846 | option is available only if Exim has been built with Oracle support. |
| 11847 | |
| 11848 | .conf percent@_hack@_domains "domain list$**$" unset |
| 11849 | .index `percent hack' |
| 11850 | .index source routing||in email address |
| 11851 | .index address||source-routed |
| 11852 | The `percent hack' is the convention whereby a local part containing a percent |
| 11853 | sign is re-interpreted as a new email address, with the percent replaced by @@. |
| 11854 | This is sometimes called `source routing', though that term is also applied to |
| 11855 | RFC 2822 addresses that begin with an @@ character. If this option is set, Exim |
| 11856 | implements the percent facility for those domains listed, but no others. This |
| 11857 | happens before an incoming SMTP address is tested against an ACL. |
| 11858 | |
| 11859 | \**Warning**\: The `percent hack' has often been abused by people who are |
| 11860 | trying to get round relaying restrictions. For this reason, it is best avoided |
| 11861 | if at all possible. Unfortunately, a number of less security-conscious MTAs |
| 11862 | implement it unconditionally. If you are running Exim on a gateway host, and |
| 11863 | routing mail through to internal MTAs without processing the local parts, it is |
| 11864 | a good idea to reject recipient addresses with percent characters in their |
| 11865 | local parts. Exim's default configuration does this. |
| 11866 | |
| 11867 | .conf perl@_at@_start boolean false |
| 11868 | This option is available only when Exim is built with an embedded Perl |
| 11869 | interpreter. See chapter ~~CHAPperl for details of its use. |
| 11870 | |
| 11871 | .conf perl@_startup string unset |
| 11872 | This option is available only when Exim is built with an embedded Perl |
| 11873 | interpreter. See chapter ~~CHAPperl for details of its use. |
| 11874 | |
| 11875 | .conf pgsql@_servers "string list" unset |
| 11876 | .index PostgreSQL lookup type||server list |
| 11877 | This option provides a list of PostgreSQL servers and associated connection |
| 11878 | data, to be used in conjunction with \%pgsql%\ lookups (see section ~~SECTsql). |
| 11879 | The option is available only if Exim has been built with PostgreSQL support. |
| 11880 | |
| 11881 | .conf pid@_file@_path string$**$ "set at compile time" |
| 11882 | .index daemon||pid file path |
| 11883 | .index pid file, path for |
| 11884 | This option sets the name of the file to which the Exim daemon writes its |
| 11885 | process id. The string is expanded, so it can contain, for example, references |
| 11886 | to the host name: |
| 11887 | .display asis |
| 11888 | pid_file_path = /var/log/$primary_hostname/exim.pid |
| 11889 | .endd |
| 11890 | If no path is set, the pid is written to the file \(exim-daemon.pid)\ in Exim's |
| 11891 | spool directory. |
| 11892 | The value set by the option can be overridden by the \-oP-\ command line |
| 11893 | option. A pid file is not written if a `non-standard' daemon is run by means of |
| 11894 | the \-oX-\ option, unless a path is explicitly supplied by \-oP-\. |
| 11895 | |
| 11896 | .conf pipelining@_advertise@_hosts "host list$**$" $*$ |
| 11897 | .index \\PIPELINING\\||advertising, suppressing |
| 11898 | This option can be used to suppress the advertisement of the SMTP |
| 11899 | \\PIPELINING\\ extension to specific hosts. When \\PIPELINING\\ is not |
| 11900 | advertised and \smtp@_enforce@_sync\ is true, an Exim server enforces strict |
| 11901 | synchronization for each SMTP command and response. |
| 11902 | When \\PIPELINING\\ is advertised, Exim assumes that clients will use it; `out |
| 11903 | of order' commands that are `expected' do not count as protocol errors (see |
| 11904 | \smtp@_max@_synprot@_errors\). |
| 11905 | |
| 11906 | .conf preserve@_message@_logs boolean false |
| 11907 | .index message logs, preserving |
| 11908 | If this option is set, message log files are not deleted when messages are |
| 11909 | completed. Instead, they are moved to a sub-directory of the spool directory |
| 11910 | called \(msglog.OLD)\, where they remain available for statistical or debugging |
| 11911 | purposes. This is a dangerous option to set on systems with any appreciable |
| 11912 | volume of mail. Use with care! |
| 11913 | |
| 11914 | .conf primary@_hostname string "see below" |
| 11915 | .index name||of local host |
| 11916 | .index host||name of local |
| 11917 | .index local host||name of |
| 11918 | This specifies the name of the current host. It is used in the default \\EHLO\\ |
| 11919 | or \\HELO\\ command for outgoing SMTP messages (changeable via the \helo@_data\ |
| 11920 | option in the \%smtp%\ transport), |
| 11921 | and as the default for \qualify@_domain\. If it is not set, Exim calls |
| 11922 | \*uname()*\ to find it. If this fails, Exim panics and dies. If the name |
| 11923 | returned by \*uname()*\ contains only one component, Exim passes it to |
| 11924 | \*gethostbyname()*\ (or \*getipnodebyname()*\ when available) in order to |
| 11925 | obtain the fully qualified version. |
| 11926 | |
| 11927 | The value of \$primary@_hostname$\ is also used by default in some SMTP |
| 11928 | response messages from an Exim server. This can be changed dynamically by |
| 11929 | setting \smtp@_active@_hostname\. |
| 11930 | |
| 11931 | .conf print@_topbitchars boolean false |
| 11932 | .index printing characters |
| 11933 | .index 8-bit characters |
| 11934 | By default, Exim considers only those characters whose codes lie in the range |
| 11935 | 32--126 to be printing characters. In a number of circumstances (for example, |
| 11936 | when writing log entries) non-printing characters are converted into escape |
| 11937 | sequences, primarily to avoid messing up the layout. If \print@_topbitchars\ is |
| 11938 | set, code values of 128 and above are also considered to be printing |
| 11939 | characters. |
| 11940 | |
| 11941 | .conf process@_log@_path string unset |
| 11942 | .index process log path |
| 11943 | .index log||process log |
| 11944 | .index \*exiwhat*\ |
| 11945 | This option sets the name of the file to which an Exim process writes its |
| 11946 | `process log' when sent a USR1 signal. This is used by the \*exiwhat*\ utility |
| 11947 | script. If this option is unset, the file called \(exim-process.info)\ in |
| 11948 | Exim's spool directory is used. The ability to specify the name explicitly can |
| 11949 | be useful in environments where two different Exims are running, using |
| 11950 | different spool directories. |
| 11951 | |
| 11952 | .conf prod@_requires@_admin boolean true |
| 11953 | .index \-M-\ option |
| 11954 | .index \-R-\ option |
| 11955 | .index \-q-\ option |
| 11956 | The \-M-\, \-R-\, and \-q-\ command-line options require the caller to be an |
| 11957 | admin user unless \prod@_requires@_admin\ is set false. See also |
| 11958 | \queue@_list@_requires@_admin\. |
| 11959 | |
| 11960 | .conf qualify@_domain string "see below" |
| 11961 | .index domain||for qualifying addresses |
| 11962 | .index address||qualification |
| 11963 | This option specifies the domain name that is added to any sender addresses |
| 11964 | that do not have a domain qualification. It also applies to recipient addresses |
| 11965 | if \qualify@_recipient\ is not set. Such addresses are accepted by default only |
| 11966 | for locally-generated messages. Messages from external sources must always |
| 11967 | contain fully qualified addresses, unless the sending host matches |
| 11968 | \sender@_unqualified@_hosts\ or \recipient@_unqualified@_hosts\ (as |
| 11969 | appropriate), in which case incoming addresses are qualified with |
| 11970 | \qualify@_domain\ or \qualify@_recipient\ as necessary. Internally, Exim always |
| 11971 | works with fully qualified addresses. |
| 11972 | If \qualify@_domain\ is not set, it defaults to the \primary@_hostname\ value. |
| 11973 | |
| 11974 | .conf qualify@_recipient string "see below" |
| 11975 | This specifies the domain name that is added to any recipient addresses that do |
| 11976 | not have a domain qualification. Such addresses are accepted by default only |
| 11977 | for locally-generated messages. Messages from external sources must always |
| 11978 | contain fully qualified recipient addresses, unless the sending host matches |
| 11979 | \recipient@_unqualified@_hosts\, |
| 11980 | in which case incoming recipient addresses are qualified with |
| 11981 | \qualify@_recipient\. |
| 11982 | If \qualify@_recipient\ is not set, it defaults to the \qualify@_domain\ value. |
| 11983 | |
| 11984 | .conf queue@_domains "domain list$**$" unset |
| 11985 | .index domain||specifying non-immediate delivery |
| 11986 | .index queueing incoming messages |
| 11987 | .index message||queueing certain domains |
| 11988 | This option lists domains for which immediate delivery is not required. |
| 11989 | A delivery process is started whenever a message is received, but only those |
| 11990 | domains that do not match are processed. All other deliveries wait until the |
| 11991 | next queue run. See also \hold@_domains\ and \queue@_smtp@_domains\. |
| 11992 | |
| 11993 | .conf queue@_list@_requires@_admin boolean true |
| 11994 | .index \-bp-\ option |
| 11995 | The \-bp-\ command-line option, which lists the messages that are on the queue, |
| 11996 | requires the caller to be an admin user unless \queue__list__requires__admin\ |
| 11997 | is set false. See also \prod@_requires@_admin\. |
| 11998 | |
| 11999 | .conf queue@_only boolean false |
| 12000 | .index queueing incoming messages |
| 12001 | .index message||queueing unconditionally |
| 12002 | If \queue@_only\ is set, a delivery process is not automatically started |
| 12003 | whenever a message is received. Instead, the message waits on the queue for the |
| 12004 | next queue run. Even if \queue@_only\ is false, incoming messages may not get |
| 12005 | delivered immediately when certain conditions (such as heavy load) occur. |
| 12006 | |
| 12007 | The \-odq-\ command line has the same effect as \queue@_only\. The \-odb-\ and |
| 12008 | \-odi-\ command line options override \queue@_only\ unless |
| 12009 | \queue@_only@_override\ is set false. See also \queue@_only@_file\, |
| 12010 | \queue@_only@_load\, and \smtp@_accept@_queue\. |
| 12011 | |
| 12012 | .conf queue@_only@_file string unset |
| 12013 | .index queueing incoming messages |
| 12014 | .index message||queueing by file existence |
| 12015 | This option can be set to a colon-separated list of absolute path names, each |
| 12016 | one optionally preceded by `smtp'. When Exim is receiving a message, |
| 12017 | it tests for the existence of each listed path using a call to \*stat()*\. For |
| 12018 | each path that exists, the corresponding queuing option is set. |
| 12019 | For paths with no prefix, \queue@_only\ is set; for paths prefixed by `smtp', |
| 12020 | \queue@_smtp@_domains\ is set to match all domains. So, for example, |
| 12021 | .display asis |
| 12022 | queue_only_file = smtp/some/file |
| 12023 | .endd |
| 12024 | causes Exim to behave as if \queue@_smtp@_domains\ were set to `$*$' whenever |
| 12025 | \(/some/file)\ exists. |
| 12026 | |
| 12027 | .conf queue@_only@_load fixed-point unset |
| 12028 | .index load average |
| 12029 | .index queueing incoming messages |
| 12030 | .index message||queueing by load |
| 12031 | If the system load average is higher than this value, incoming messages from |
| 12032 | all sources are queued, and no automatic deliveries are started. If this |
| 12033 | happens during local or remote SMTP input, all subsequent messages on the same |
| 12034 | connection are queued. Deliveries will subsequently be performed by queue |
| 12035 | runner processes. This option has no effect on ancient operating systems on |
| 12036 | which Exim cannot determine the load average. See also |
| 12037 | \deliver@_queue@_load@_max\ and \smtp@_load@_reserve\. |
| 12038 | |
| 12039 | .conf queue@_only@_override boolean true |
| 12040 | .index queueing incoming messages |
| 12041 | When this option is true, the \-od\*x*\-\ command line options override the |
| 12042 | setting of \queue@_only\ or \queue@_only@_file\ in the configuration file. If |
| 12043 | \queue@_only@_override\ is set false, the \-od\*x*\-\ options cannot be used to |
| 12044 | override; they are accepted, but ignored. |
| 12045 | |
| 12046 | .conf queue@_run@_in@_order boolean false |
| 12047 | .index queue runner||processing messages in order |
| 12048 | If this option is set, queue runs happen in order of message arrival instead of |
| 12049 | in an arbitrary order. For this to happen, a complete list of the entire queue |
| 12050 | must be set up before the deliveries start. When the queue is all in a single |
| 12051 | directory (the default), this happens anyway, but if \split@_spool@_directory\ |
| 12052 | is set it does not -- for delivery in random order, the sub-directories are |
| 12053 | processed one at a time (in random order), to avoid setting up one huge list. |
| 12054 | Thus, setting \queue@_run@_in@_order\ with \split@_spool@_directory\ may |
| 12055 | degrade performance when the queue is large. In most situations, |
| 12056 | \queue@_run@_in@_order\ should not be set. |
| 12057 | |
| 12058 | .conf queue@_run@_max integer 5 |
| 12059 | .index queue runner||maximum number of |
| 12060 | This controls the maximum number of queue runner processes that an Exim daemon |
| 12061 | can run simultaneously. This does not mean that it starts them all at once, |
| 12062 | but rather that if the maximum number are still running when the time comes to |
| 12063 | start another one, it refrains from starting another one. This can happen with |
| 12064 | very large queues and/or very sluggish deliveries. This option does not, |
| 12065 | however, interlock with other processes, so additional queue runners can be |
| 12066 | started by other means, or by killing and restarting the daemon. |
| 12067 | |
| 12068 | .conf queue@_smtp@_domains "domain list$**$" unset |
| 12069 | .index queueing incoming messages |
| 12070 | .index message||queueing remote deliveries |
| 12071 | When this option is set, a delivery process is started whenever a message is |
| 12072 | received, routing is performed, and local deliveries take place. |
| 12073 | However, if any SMTP deliveries are required for domains that match |
| 12074 | \queue@_smtp@_domains\, they are not immediately delivered, but instead the |
| 12075 | message waits on the queue for the next queue run. Since routing of the message |
| 12076 | has taken place, Exim knows to which remote hosts it must be delivered, and so |
| 12077 | when the queue run happens, multiple messages for the same host are delivered |
| 12078 | over a single SMTP connection. The \-odqs-\ command line option causes all SMTP |
| 12079 | deliveries to be queued in this way, and is equivalent to setting |
| 12080 | \queue@_smtp@_domains\ to `$*$'. See also \hold@_domains\ and \queue@_domains\. |
| 12081 | |
| 12082 | .conf receive@_timeout time 0s |
| 12083 | .index timeout||for non-SMTP input |
| 12084 | This option sets the timeout for accepting a non-SMTP message, that is, the |
| 12085 | maximum time that Exim waits when reading a message on the standard input. If |
| 12086 | the value is zero, it will wait for ever. This setting is overridden by the |
| 12087 | \-or-\ command line option. The timeout for incoming SMTP messages is |
| 12088 | controlled by \smtp@_receive@_timeout\. |
| 12089 | |
| 12090 | .index customizing|| ::Received:: header |
| 12091 | .index ::Received:: header line||customizing |
| 12092 | .conf received@_header@_text string$**$ "see below" |
| 12093 | This string defines the contents of the ::Received:: message header that is |
| 12094 | added to each message, except for the timestamp, which is automatically added |
| 12095 | on at the end (preceded by a semicolon). The string is expanded each time it is |
| 12096 | used. If the expansion yields an empty string, no ::Received:: header line is |
| 12097 | added to the message. Otherwise, the string should start with the text |
| 12098 | `Received:' and conform to the RFC 2822 specification for ::Received:: header |
| 12099 | lines. The default setting is: |
| 12100 | .display asis |
| 12101 | received_header_text = Received: \ |
| 12102 | ${if def:sender_rcvhost {from $sender_rcvhost\n\t}\ |
| 12103 | {${if def:sender_ident {from $sender_ident }}\ |
| 12104 | ${if def:sender_helo_name {(helo=$sender_helo_name)\n\t}}}}\ |
| 12105 | by $primary_hostname \ |
| 12106 | ${if def:received_protocol {with $received_protocol}} \ |
| 12107 | ${if def:tls_cipher {($tls_cipher)\n\t}}\ |
| 12108 | (Exim $version_number)\n\t\ |
| 12109 | id $message_id\ |
| 12110 | ${if def:received_for {\n\tfor $received_for}} |
| 12111 | .endd |
| 12112 | Note the use of quotes, to allow the sequences \"@\n"\ and \"@\t"\ to be used |
| 12113 | for newlines and tabs, respectively. The reference to the TLS cipher is omitted |
| 12114 | when Exim is built without TLS support. The use of conditional expansions |
| 12115 | ensures that this works for both locally generated messages and messages |
| 12116 | received from remote hosts, giving header lines such as the following: |
| 12117 | .display asis |
| 12118 | Received: from scrooge.carol.example ([192.168.12.25] ident=root) |
| 12119 | by marley.carol.example with esmtp (Exim 4.00) |
| 12120 | id 16IOWa-00019l-00 |
| 12121 | for chas@dickens.example; Tue, 25 Dec 2001 14:43:44 +0000 |
| 12122 | Received: by scrooge.carol.example with local (Exim 4.00) |
| 12123 | id 16IOWW-000083-00; Tue, 25 Dec 2001 14:43:41 +0000 |
| 12124 | .endd |
| 12125 | Until the body of the message has been received, the timestamp is the time when |
| 12126 | the message started to be received. Once the body has arrived, and all policy |
| 12127 | checks have taken place, the timestamp is updated to the time at which the |
| 12128 | message was accepted. |
| 12129 | |
| 12130 | .conf received@_headers@_max integer 30 |
| 12131 | .index loop||prevention |
| 12132 | .index mail loop prevention |
| 12133 | .index ::Received:: header line||counting |
| 12134 | When a message is to be delivered, the number of ::Received:: headers is |
| 12135 | counted, and if it is greater than this parameter, a mail loop is assumed to |
| 12136 | have occurred, the delivery is abandoned, and an error message is generated. |
| 12137 | This applies to both local and remote deliveries. |
| 12138 | |
| 12139 | .conf recipient@_unqualified@_hosts "host list$**$" unset |
| 12140 | .index unqualified addresses |
| 12141 | .index host||unqualified addresses from |
| 12142 | This option lists those hosts from which Exim is prepared to accept unqualified |
| 12143 | recipient addresses in message envelopes. The addresses are made fully |
| 12144 | qualified by the addition of the \qualify@_recipient\ value. This option also |
| 12145 | affects message header lines. Exim does not reject unqualified recipient |
| 12146 | addresses in headers, but it qualifies them only if the message came from a |
| 12147 | host that matches \recipient@_unqualified@_hosts\, |
| 12148 | or if the message was submitted locally (not using TCP/IP), and the \-bnq-\ |
| 12149 | option was not set. |
| 12150 | |
| 12151 | .conf recipients@_max integer 0 |
| 12152 | .index limit||number of recipients |
| 12153 | .index recipient||maximum number |
| 12154 | If this option is set greater than zero, it specifies the maximum number of |
| 12155 | original recipients for any message. Additional recipients that are generated |
| 12156 | by aliasing or forwarding do not count. SMTP messages get a 452 response for |
| 12157 | all recipients over the limit; earlier recipients are delivered as normal. |
| 12158 | Non-SMTP messages with too many recipients are failed, and no deliveries are |
| 12159 | done. |
| 12160 | .index \\RCPT\\||maximum number of incoming |
| 12161 | Note that the RFCs specify that an SMTP server should accept at least 100 |
| 12162 | \\RCPT\\ commands in a single message. |
| 12163 | |
| 12164 | .conf recipients@_max@_reject boolean false |
| 12165 | If this option is set true, Exim rejects SMTP messages containing too many |
| 12166 | recipients by giving 552 errors to the surplus \\RCPT\\ commands, and a 554 |
| 12167 | error to the eventual \\DATA\\ command. Otherwise (the default) it gives a 452 |
| 12168 | error to the surplus \\RCPT\\ commands and accepts the message on behalf of the |
| 12169 | initial set of recipients. The remote server should then re-send the message |
| 12170 | for the remaining recipients at a later time. |
| 12171 | |
| 12172 | .conf remote@_max@_parallel integer 2 |
| 12173 | .index delivery||parallelism for remote |
| 12174 | This option controls parallel delivery of one message to a number of remote |
| 12175 | hosts. If the value is less than 2, parallel delivery is disabled, and Exim |
| 12176 | does all the remote deliveries for a message one by one. Otherwise, if a single |
| 12177 | message has to be delivered to more than one remote host, or if several copies |
| 12178 | have to be sent to the same remote host, up to \remote@_max@_parallel\ |
| 12179 | deliveries are done simultaneously. If more than \remote@_max@_parallel\ |
| 12180 | deliveries are required, the maximum number of processes are started, and as |
| 12181 | each one finishes, another is begun. The order of starting processes is the |
| 12182 | same as if sequential delivery were being done, and can be controlled by the |
| 12183 | \remote@_sort@_domains\ option. If parallel delivery takes place while running |
| 12184 | with debugging turned on, the debugging output from each delivery process is |
| 12185 | tagged with its process id. |
| 12186 | |
| 12187 | This option controls only the maximum number of parallel deliveries for one |
| 12188 | message in one Exim delivery process. Because Exim has no central queue |
| 12189 | manager, there is no way of controlling the total number of simultaneous |
| 12190 | deliveries if the configuration allows a delivery attempt as soon as a message |
| 12191 | is received. |
| 12192 | .index number of deliveries |
| 12193 | .index delivery||maximum number of |
| 12194 | If you want to control the total number of deliveries on the system, you |
| 12195 | need to set the \queue@_only\ option. This ensures that all incoming messages |
| 12196 | are added to the queue without starting a delivery process. Then set up an Exim |
| 12197 | daemon to start queue runner processes at appropriate intervals (probably |
| 12198 | fairly often, for example, every minute), and limit the total number of queue |
| 12199 | runners by setting the \queue__run__max\ parameter. Because each queue runner |
| 12200 | delivers only one message at a time, the maximum number of deliveries that can |
| 12201 | then take place at once is \queue@_run@_max\ multiplied by |
| 12202 | \remote@_max@_parallel\. |
| 12203 | |
| 12204 | If it is purely remote deliveries you want to control, use \queue@_smtp\ |
| 12205 | instead of \queue@_only\. This has the added benefit of doing the SMTP routing |
| 12206 | before queuing, so that several messages for the same host will eventually get |
| 12207 | delivered down the same connection. |
| 12208 | |
| 12209 | .conf remote@_sort@_domains "domain list$**$" unset |
| 12210 | .index sorting remote deliveries |
| 12211 | .index delivery||sorting remote |
| 12212 | When there are a number of remote deliveries for a message, they are sorted by |
| 12213 | domain into the order given by this list. For example, |
| 12214 | .display asis |
| 12215 | remote_sort_domains = *.cam.ac.uk:*.uk |
| 12216 | .endd |
| 12217 | would attempt to deliver to all addresses in the \*cam.ac.uk*\ domain first, then |
| 12218 | to those in the \uk\ domain, then to any others. |
| 12219 | |
| 12220 | .conf retry@_data@_expire time 7d |
| 12221 | .index hints database||data expiry |
| 12222 | This option sets a `use before' time on retry information in Exim's hints |
| 12223 | database. Any older retry data is ignored. This means that, for example, once a |
| 12224 | host has not been tried for 7 days, Exim behaves as if it has no knowledge of |
| 12225 | past failures. |
| 12226 | |
| 12227 | .conf retry@_interval@_max time 24h |
| 12228 | .index retry||limit on interval |
| 12229 | .index limit||on retry interval |
| 12230 | Chapter ~~CHAPretry describes Exim's mechanisms for controlling the intervals |
| 12231 | between delivery attempts for messages that cannot be delivered straight away. |
| 12232 | This option sets an overall limit to the length of time between retries. |
| 12233 | |
| 12234 | .conf return@_path@_remove boolean true |
| 12235 | .index ::Return-path:: header line||removing |
| 12236 | RFC 2821, section 4.4, states that an SMTP server must insert a ::Return-path:: |
| 12237 | header line into a message when it makes a `final delivery'. The ::Return-path:: |
| 12238 | header preserves the sender address as received in the \\MAIL\\ command. This |
| 12239 | description implies that this header should not be present in an incoming |
| 12240 | message. If \return@_path@_remove\ is true, any existing ::Return-path:: |
| 12241 | headers are removed from messages at the time they are received. Exim's |
| 12242 | transports have options for adding ::Return-path:: headers at the time of |
| 12243 | delivery. They are normally used only for final local deliveries. |
| 12244 | |
| 12245 | .conf return@_size@_limit integer 100K |
| 12246 | This option is an obsolete synonym for \bounce@_return@_size@_limit\. |
| 12247 | |
| 12248 | .conf rfc1413@_hosts "host list$**$" $*$ |
| 12249 | .index RFC 1413 |
| 12250 | .index host||for RFC 1413 calls |
| 12251 | RFC 1413 identification calls are made to any client host which matches an item |
| 12252 | in the list. |
| 12253 | |
| 12254 | .conf rfc1413@_query@_timeout time 30s |
| 12255 | .index RFC 1413||query timeout |
| 12256 | .index timeout||for RFC 1413 call |
| 12257 | This sets the timeout on RFC 1413 identification calls. If it is set to zero, |
| 12258 | no RFC 1413 calls are ever made. |
| 12259 | |
| 12260 | .conf sender@_unqualified@_hosts "host list$**$" unset |
| 12261 | .index unqualified addresses |
| 12262 | .index host||unqualified addresses from |
| 12263 | This option lists those hosts from which Exim is prepared to accept unqualified |
| 12264 | sender addresses. The addresses are made fully qualified by the addition of |
| 12265 | \qualify@_domain\. This option also affects message header lines. Exim does not |
| 12266 | reject unqualified addresses in headers that contain sender addresses, but it |
| 12267 | qualifies them only if the message came from a host that matches |
| 12268 | \sender@_unqualified@_hosts\, |
| 12269 | or if the message was submitted locally (not using TCP/IP), and the \-bnq-\ |
| 12270 | option was not set. |
| 12271 | |
| 12272 | .conf smtp@_accept@_keepalive boolean true |
| 12273 | .index keepalive||on incoming connection |
| 12274 | This option controls the setting of the \\SO@_KEEPALIVE\\ option on incoming |
| 12275 | TCP/IP socket connections. When set, it causes the kernel to probe idle |
| 12276 | connections periodically, by sending packets with `old' sequence numbers. The |
| 12277 | other end of the connection should send an acknowledgement if the connection is |
| 12278 | still okay or a reset if the connection has been aborted. The reason for doing |
| 12279 | this is that it has the beneficial effect of freeing up certain types of |
| 12280 | connection that can get stuck when the remote host is disconnected without |
| 12281 | tidying up the TCP/IP call properly. The keepalive mechanism takes several |
| 12282 | hours to detect unreachable hosts. |
| 12283 | |
| 12284 | |
| 12285 | .conf smtp@_accept@_max integer 20 |
| 12286 | .index limit||incoming SMTP connections |
| 12287 | .index SMTP||incoming connection count |
| 12288 | .index inetd |
| 12289 | This option specifies the maximum number of simultaneous incoming SMTP calls |
| 12290 | that Exim will accept. It applies only to the listening daemon; there is no |
| 12291 | control (in Exim) when incoming SMTP is being handled by \*inetd*\. If the value |
| 12292 | is set to zero, no limit is applied. However, it is required to be non-zero if |
| 12293 | either \smtp@_accept@_max@_per@_host\ or \smtp@_accept@_queue\ is set. See also |
| 12294 | \smtp@_accept@_reserve\. |
| 12295 | |
| 12296 | |
| 12297 | .conf smtp@_accept@_max@_nonmail integer 10 |
| 12298 | .index limit||non-mail SMTP commands |
| 12299 | .index SMTP||limiting non-mail commands |
| 12300 | Exim counts the number of `non-mail' commands in an SMTP session, and drops the |
| 12301 | connection if there are too many. This option defines `too many'. The check |
| 12302 | catches some denial-of-service attacks, repeated failing \\AUTH\\s, or a mad |
| 12303 | client looping sending \\EHLO\\, for example. The check is applied only if the |
| 12304 | client host matches \smtp@_accept@_max@_nonmail@_hosts\. |
| 12305 | |
| 12306 | When a new message is expected, one occurrence of \\RSET\\ is not counted. This |
| 12307 | allows a client to send one \\RSET\\ between messages (this is not necessary, |
| 12308 | but some clients do it). Exim also allows one uncounted occurence of \\HELO\\ |
| 12309 | or \\EHLO\\, and one occurrence of \\STARTTLS\\ between messages. After |
| 12310 | starting up a TLS session, another \\EHLO\\ is expected, and so it too is not |
| 12311 | counted. The first occurrence of \\AUTH\\ in a connection, or immediately |
| 12312 | following \\STARTTLS\\ is not counted. Otherwise, all commands other than |
| 12313 | \\MAIL\\, \\RCPT\\, \\DATA\\, and \\QUIT\\ are counted. |
| 12314 | |
| 12315 | .conf smtp@_accept@_max@_nonmail@_hosts "host list$**$" $*$ |
| 12316 | You can control which hosts are subject to the \smtp@_accept@_max@_nonmail\ |
| 12317 | check by setting this option. The default value makes it apply to all hosts. By |
| 12318 | changing the value, you can exclude any badly-behaved hosts that you have to |
| 12319 | live with. |
| 12320 | |
| 12321 | |
| 12322 | .conf smtp@_accept@_max@_per@_connection integer 1000 |
| 12323 | .index SMTP||incoming message count, limiting |
| 12324 | .index limit||messages per SMTP connection |
| 12325 | The value of this option limits the number of \\MAIL\\ commands that Exim is |
| 12326 | prepared to accept over a single SMTP connection, whether or not each command |
| 12327 | results in the transfer of a message. After the limit is reached, a 421 |
| 12328 | response is given to subsequent \\MAIL\\ commands. This limit is a safety |
| 12329 | precaution against a client that goes mad (incidents of this type have been |
| 12330 | seen). |
| 12331 | |
| 12332 | .conf smtp@_accept@_max@_per@_host string$**$ unset |
| 12333 | .index limit||SMTP connections from one host |
| 12334 | .index host||limiting SMTP connections from |
| 12335 | This option restricts the number of simultaneous IP connections from a single |
| 12336 | host (strictly, from a single IP address) to the Exim daemon. The option is |
| 12337 | expanded, to enable different limits to be applied to different hosts by |
| 12338 | reference to \$sender@_host@_address$\. Once the limit is reached, additional |
| 12339 | connection attempts from the same host are rejected with error code 421. The |
| 12340 | default value of zero imposes no limit. If this option is set, it is required |
| 12341 | that \smtp@_accept@_max\ be non-zero. |
| 12342 | |
| 12343 | \**Warning**\: When setting this option you should not use any expansion |
| 12344 | constructions that take an appreciable amount of time. The expansion and test |
| 12345 | happen in the main daemon loop, in order to reject additional connections |
| 12346 | without forking additional processes (otherwise a denial-of-service attack |
| 12347 | could cause a vast number or processes to be created). While the daemon is |
| 12348 | doing this processing, it cannot accept any other incoming connections. |
| 12349 | |
| 12350 | |
| 12351 | .conf smtp@_accept@_queue integer 0 |
| 12352 | .index SMTP||incoming connection count |
| 12353 | .index queueing incoming messages |
| 12354 | .index message||queueing by SMTP connection count |
| 12355 | If the number of simultaneous incoming SMTP calls handled via the listening |
| 12356 | daemon exceeds this value, messages received by SMTP are just placed on the |
| 12357 | queue; no delivery processes are started automatically. A value of zero implies |
| 12358 | no limit, and clearly any non-zero value is useful only if it is less than the |
| 12359 | \smtp@_accept@_max\ value (unless that is zero). See also \queue@_only\, |
| 12360 | \queue@_only@_load\, \queue@_smtp@_domains\, and the various \-od-\ command |
| 12361 | line options. |
| 12362 | |
| 12363 | .conf smtp@_accept@_queue@_per@_connection integer 10 |
| 12364 | .index queueing incoming messages |
| 12365 | .index message||queueing by message count |
| 12366 | This option limits the number of delivery processes that Exim starts |
| 12367 | automatically when receiving messages via SMTP, whether via the daemon or by |
| 12368 | the use of \-bs-\ or \-bS-\. If the value of the option is greater than zero, |
| 12369 | and the number of messages received in a single SMTP session exceeds this |
| 12370 | number, subsequent messages are placed on the queue, but no delivery processes |
| 12371 | are started. This helps to limit the number of Exim processes when a server |
| 12372 | restarts after downtime and there is a lot of mail waiting for it on other |
| 12373 | systems. On large systems, the default should probably be increased, and on |
| 12374 | dial-in client systems it should probably be set to zero (that is, disabled). |
| 12375 | |
| 12376 | .conf smtp@_accept@_reserve integer 0 |
| 12377 | .index SMTP||incoming call count |
| 12378 | .index host||reserved |
| 12379 | When \smtp@_accept@_max\ is set greater than zero, this option specifies a |
| 12380 | number of SMTP connections that are reserved for connections from the hosts |
| 12381 | that are specified in \smtp@_reserve@_hosts\. The value set in |
| 12382 | \smtp@_accept@_max\ includes this reserve pool. The specified hosts are not |
| 12383 | restricted to this number of connections; the option specifies a minimum number |
| 12384 | of connection slots for them, not a maximum. It is a guarantee that that group |
| 12385 | of hosts can always get at least \smtp@_accept@_reserve\ connections. |
| 12386 | |
| 12387 | For example, if \smtp@_accept@_max\ is set to 50 and \smtp@_accept@_reserve\ is |
| 12388 | set to 5, once there are 45 active connections (from any hosts), new |
| 12389 | connections are accepted only from hosts listed in \smtp@_reserve@_hosts\. |
| 12390 | See also \smtp@_accept@_max@_per@_host\. |
| 12391 | |
| 12392 | .conf smtp@_active@_hostname string$**$ unset |
| 12393 | .index host||name in SMTP responses |
| 12394 | .index SMTP||host name in responses |
| 12395 | This option is provided for multi-homed servers that want to masquerade as |
| 12396 | several different hosts. At the start of an SMTP connection, its value is |
| 12397 | expanded and used instead of the value of \$primary@_hostname$\ in SMTP |
| 12398 | responses. For example, it is used as domain name in the response to an |
| 12399 | incoming \\HELO\\ or \\EHLO\\ command. If this option is unset, or if its |
| 12400 | expansion is forced to fail, or if the expansion results in an empty string, |
| 12401 | the value of \$primary@_hostname$\ is used. Other expansion failures cause a |
| 12402 | message to be written to the main and panic logs, and the SMTP command receives |
| 12403 | a temporary error. Typically, the value of \smtp@_active@_hostname\ depends on |
| 12404 | the incoming interface address. For example: |
| 12405 | .display asis |
| 12406 | smtp_active_hostname = ${if eq{$interface_address}{10.0.0.1}\ |
| 12407 | {cox.mydomain}{box.mydomain}} |
| 12408 | .endd |
| 12409 | If you set \smtp@_active@_hostname\, you probably also want to set |
| 12410 | \smtp@_banner\, since its default value references \$primary@_hostname$\. |
| 12411 | |
| 12412 | .conf smtp@_banner string$**$ "see below" |
| 12413 | .index SMTP||welcome banner |
| 12414 | .index banner for SMTP |
| 12415 | .index welcome banner for SMTP |
| 12416 | .index customizing||SMTP banner |
| 12417 | This string, which is expanded every time it is used, is output as the initial |
| 12418 | positive response to an SMTP connection. The default setting is: |
| 12419 | .display asis |
| 12420 | smtp_banner = $primary_hostname ESMTP Exim $version_number \ |
| 12421 | $tod_full |
| 12422 | .endd |
| 12423 | Failure to expand the string causes a panic error. If you want to create a |
| 12424 | multiline response to the initial SMTP connection, use `@\n' in the string at |
| 12425 | appropriate points, but not at the end. Note that the 220 code is not included |
| 12426 | in this string. Exim adds it automatically (several times in the case of a |
| 12427 | multiline response). |
| 12428 | |
| 12429 | .conf smtp@_check@_spool@_space boolean true |
| 12430 | .index checking disk space |
| 12431 | .index disk space, checking |
| 12432 | .index spool directory||checking space |
| 12433 | When this option is set, if an incoming SMTP session encounters the \\SIZE\\ |
| 12434 | option on a \\MAIL\\ command, it checks that there is enough space in the |
| 12435 | spool directory's partition to accept a message of that size, while still |
| 12436 | leaving free the amount specified by \check@_spool@_space\ (even if that value |
| 12437 | is zero). If there isn't enough space, a temporary error code is returned. |
| 12438 | |
| 12439 | .conf smtp@_connect@_backlog integer 20 |
| 12440 | .index connection backlog |
| 12441 | .index SMTP||connection backlog |
| 12442 | .index backlog of connections |
| 12443 | This option specifies a maximum number of waiting SMTP connections. Exim passes |
| 12444 | this value to the TCP/IP system when it sets up its listener. Once this number |
| 12445 | of connections are waiting for the daemon's attention, subsequent connection |
| 12446 | attempts are refused at the TCP/IP level. At least, that is what the manuals |
| 12447 | say; in some circumstances such connection attempts have been observed to time |
| 12448 | out instead. For large systems it is probably a good idea to increase the |
| 12449 | value (to 50, say). It also gives some protection against denial-of-service |
| 12450 | attacks by SYN flooding. |
| 12451 | |
| 12452 | .conf smtp@_enforce@_sync boolean true |
| 12453 | .index SMTP||synchronization checking |
| 12454 | .index synchronization checking in SMTP |
| 12455 | The SMTP protocol specification requires the client to wait for a response from |
| 12456 | the server at certain points in the dialogue. Without \\PIPELINING\\ these |
| 12457 | synchronization points are after every command; with \\PIPELINING\\ they are |
| 12458 | fewer, but they still exist. Some spamming sites send out a complete set of |
| 12459 | SMTP commands without waiting for any response. Exim protects against this by |
| 12460 | rejecting a message if the client has sent further input when it should not |
| 12461 | have. The error response `554 SMTP synchronization error' is sent, and the |
| 12462 | connection is dropped. Testing for this error cannot be perfect because of |
| 12463 | transmission delays (unexpected input may be on its way but not yet received |
| 12464 | when Exim checks). However, it does detect many instances. The check can be |
| 12465 | disabled by setting \smtp@_enforce@_sync\ false. |
| 12466 | See also \pipelining@_advertise@_hosts\. |
| 12467 | |
| 12468 | .conf smtp@_etrn@_command string$**$ unset |
| 12469 | .index \\ETRN\\||command to be run |
| 12470 | If this option is set, the given command is run whenever an SMTP \\ETRN\\ |
| 12471 | command is received from a host that is permitted to issue such commands (see |
| 12472 | chapter ~~CHAPACL). The string is split up into separate arguments which are |
| 12473 | independently expanded. The expansion variable \$domain$\ is set to the |
| 12474 | argument of the \\ETRN\\ command, and no syntax checking is done on it. For |
| 12475 | example: |
| 12476 | .display asis |
| 12477 | smtp_etrn_command = /etc/etrn_command $domain $sender_host_address |
| 12478 | .endd |
| 12479 | A new process is created to run the command, but Exim does not wait for it to |
| 12480 | complete. Consequently, its status cannot be checked. If the command cannot be |
| 12481 | run, a line is written to the panic log, but the \\ETRN\\ caller still receives |
| 12482 | a 250 success response. Exim is normally running under its own uid when |
| 12483 | receiving SMTP, so it is not possible for it to change the uid before running |
| 12484 | the command. |
| 12485 | |
| 12486 | .conf smtp@_etrn@_serialize boolean true |
| 12487 | .index \\ETRN\\||serializing |
| 12488 | When this option is set, it prevents the simultaneous execution of more than |
| 12489 | one identical command as a result of \\ETRN\\ in an SMTP connection. See |
| 12490 | section ~~SECTETRN for details. |
| 12491 | |
| 12492 | .conf smtp@_load@_reserve fixed-point unset |
| 12493 | .index load average |
| 12494 | If the system load average ever gets higher than this, incoming SMTP calls are |
| 12495 | accepted only from those hosts that match an entry in \smtp@_reserve@_hosts\. |
| 12496 | If \smtp@_reserve@_hosts\ is not set, no incoming SMTP calls are accepted when |
| 12497 | the load is over the limit. The option has no effect on ancient operating |
| 12498 | systems on which Exim cannot determine the load average. See also |
| 12499 | \deliver@_queue@_load@_max\ and \queue@_only@_load\. |
| 12500 | |
| 12501 | |
| 12502 | .conf smtp@_max@_synprot@_errors integer 3 |
| 12503 | .index SMTP||limiting syntax and protocol errors |
| 12504 | .index limit||SMTP syntax and protocol errors |
| 12505 | Exim rejects SMTP commands that contain syntax or protocol errors. In |
| 12506 | particular, a syntactically invalid email address, as in this command: |
| 12507 | .display asis |
| 12508 | RCPT TO:<abc xyz@a.b.c> |
| 12509 | .endd |
| 12510 | causes immediate rejection of the command, before any other tests are done. |
| 12511 | (The ACL cannot be run if there is no valid address to set up for it.) An |
| 12512 | example of a protocol error is receiving \\RCPT\\ before \\MAIL\\. If there are |
| 12513 | too many syntax or protocol errors in one SMTP session, the connection is |
| 12514 | dropped. The limit is set by this option. |
| 12515 | |
| 12516 | .index \\PIPELINING\\||expected errors |
| 12517 | When the \\PIPELINING\\ extension to SMTP is in use, some protocol errors are |
| 12518 | `expected', for instance, a \\RCPT\\ command after a rejected \\MAIL\\ command. |
| 12519 | Exim assumes that \\PIPELINING\\ will be used if it advertises it (see |
| 12520 | \pipelining@_advertise@_hosts\), and in this situation, `expected' errors do |
| 12521 | not count towards the limit. |
| 12522 | |
| 12523 | |
| 12524 | .conf smtp@_max@_unknown@_commands integer 3 |
| 12525 | .index SMTP||limiting unknown commands |
| 12526 | .index limit||unknown SMTP commands |
| 12527 | If there are too many unrecognized commands in an incoming SMTP session, an |
| 12528 | Exim server drops the connection. This is a defence against some kinds of abuse |
| 12529 | that subvert web |
| 12530 | clients |
| 12531 | into making connections to SMTP ports; in these circumstances, a number of |
| 12532 | non-SMTP command lines are sent first. |
| 12533 | |
| 12534 | |
| 12535 | .conf smtp@_ratelimit@_hosts "host list$**$" unset |
| 12536 | .index SMTP||rate limiting |
| 12537 | .index limit||rate of message arrival |
| 12538 | .index \\RCPT\\||rate limiting |
| 12539 | Some sites find it helpful to be able to limit the rate at which certain hosts |
| 12540 | can send them messages, and the rate at which an individual message can specify |
| 12541 | recipients. When a host matches \smtp@_ratelimit@_hosts\, the values of |
| 12542 | \smtp@_ratelimit@_mail\ and \smtp@_ratelimit@_rcpt\ are used to control the |
| 12543 | rate of acceptance of \\MAIL\\ and \\RCPT\\ commands in a single SMTP session, |
| 12544 | respectively. Each option, if set, must contain a set of four comma-separated |
| 12545 | values: |
| 12546 | .numberpars $. |
| 12547 | A threshold, before which there is no rate limiting. |
| 12548 | .nextp |
| 12549 | An initial time delay. Unlike other times in Exim, numbers with decimal |
| 12550 | fractional parts are allowed here. |
| 12551 | .nextp |
| 12552 | A factor by which to increase the delay each time. |
| 12553 | .nextp |
| 12554 | A maximum value for the delay. This should normally be less than 5 minutes, |
| 12555 | because after that time, the client is liable to timeout the SMTP command. |
| 12556 | .endp |
| 12557 | For example, these settings have been used successfully at the site which |
| 12558 | first suggested this feature, for controlling mail from their customers: |
| 12559 | .display asis |
| 12560 | smtp_ratelimit_mail = 2,0.5s,1.05,4m |
| 12561 | smtp_ratelimit_rcpt = 4,0.25s,1.015,4m |
| 12562 | .endd |
| 12563 | The first setting specifies delays that are applied to \\MAIL\\ commands after |
| 12564 | two have been received over a single connection. The initial delay is 0.5 |
| 12565 | seconds, increasing by a factor of 1.05 each time. The second setting applies |
| 12566 | delays to \\RCPT\\ commands when more than four occur in a single message. |
| 12567 | |
| 12568 | It is also possible to configure delays explicitly in ACLs. See section |
| 12569 | ~~SECTACLmodi for details. |
| 12570 | |
| 12571 | |
| 12572 | .conf smtp@_ratelimit@_mail string unset |
| 12573 | See \smtp@_ratelimit@_hosts\ above. |
| 12574 | |
| 12575 | .conf smtp@_ratelimit@_rcpt string unset |
| 12576 | See \smtp@_ratelimit@_hosts\ above. |
| 12577 | |
| 12578 | .conf smtp@_receive@_timeout time 5m |
| 12579 | .index timeout||for SMTP input |
| 12580 | .index SMTP||timeout, input |
| 12581 | This sets a timeout value for SMTP reception. It applies to all forms of SMTP |
| 12582 | input, including batch SMTP. If a line of input (either an SMTP command or a |
| 12583 | data line) is not received within this time, the SMTP connection is dropped and |
| 12584 | the message is abandoned. |
| 12585 | A line is written to the log containing one of the following messages: |
| 12586 | .display asis |
| 12587 | SMTP command timeout on connection from... |
| 12588 | SMTP data timeout on connection from... |
| 12589 | .endd |
| 12590 | The former means that Exim was expecting to read an SMTP command; the latter |
| 12591 | means that it was in the \\DATA\\ phase, reading the contents of a message. |
| 12592 | |
| 12593 | |
| 12594 | .index \-os-\ option |
| 12595 | The value set by this option can be overridden by the |
| 12596 | \-os-\ command-line option. A setting of zero time disables the timeout, but |
| 12597 | this should never be used for SMTP over TCP/IP. (It can be useful in some cases |
| 12598 | of local input using \-bs-\ or \-bS-\.) For non-SMTP input, the reception |
| 12599 | timeout is controlled by \receive@_timeout\ and \-or-\. |
| 12600 | |
| 12601 | .conf smtp@_reserve@_hosts "host list$**$" unset |
| 12602 | This option defines hosts for which SMTP connections are reserved; see |
| 12603 | \smtp@_accept@_reserve\ and \smtp@_load@_reserve\ above. |
| 12604 | |
| 12605 | .conf smtp@_return@_error@_details boolean false |
| 12606 | .index SMTP||details policy failures |
| 12607 | .index policy control||rejection, returning details |
| 12608 | In the default state, Exim uses bland messages such as |
| 12609 | `Administrative prohibition' when it rejects SMTP commands for policy |
| 12610 | reasons. Many sysadmins like this because it gives away little information |
| 12611 | to spammers. However, some other syadmins who are applying strict checking |
| 12612 | policies want to give out much fuller information about failures. Setting |
| 12613 | \smtp@_return@_error@_details\ true causes Exim to be more forthcoming. For |
| 12614 | example, instead of `Administrative prohibition', it might give: |
| 12615 | .display asis |
| 12616 | 550-Rejected after DATA: '>' missing at end of address: |
| 12617 | 550 failing address in "From" header is: <user@dom.ain |
| 12618 | .endd |
| 12619 | |
| 12620 | .conf split@_spool@_directory boolean false |
| 12621 | .index multiple spool directories |
| 12622 | .index spool directory||split |
| 12623 | .index directories, multiple |
| 12624 | If this option is set, it causes Exim to split its input directory into 62 |
| 12625 | subdirectories, each with a single alphanumeric character as its name. The |
| 12626 | sixth character of the message id is used to allocate messages to |
| 12627 | subdirectories; this is the least significant base-62 digit of the time of |
| 12628 | arrival of the message. |
| 12629 | |
| 12630 | Splitting up the spool in this way may provide better performance on systems |
| 12631 | where there are long mail queues, by reducing the number of files in any one |
| 12632 | directory. The msglog directory is also split up in a similar way to the input |
| 12633 | directory; however, if \preserve@_message@_logs\ is set, all old msglog files |
| 12634 | are still placed in the single directory \(msglog.OLD)\. |
| 12635 | |
| 12636 | It is not necessary to take any special action for existing messages when |
| 12637 | changing \split@_spool@_directory\. Exim notices messages that are in the |
| 12638 | `wrong' place, and continues to process them. If the option is turned off after |
| 12639 | a period of being on, the subdirectories will eventually empty and be |
| 12640 | automatically deleted. |
| 12641 | |
| 12642 | When \split@_spool@_directory\ is set, the behaviour of queue runner processes |
| 12643 | changes. Instead of creating a list of all messages in the queue, and then |
| 12644 | trying to deliver each one in turn, it constructs a list of those in one |
| 12645 | sub-directory and tries to deliver them, before moving on to the next |
| 12646 | sub-directory. The sub-directories are processed in a random order. This |
| 12647 | spreads out the scanning of the input directories, and uses less memory. It is |
| 12648 | particularly beneficial when there are lots of messages on the queue. However, |
| 12649 | if \queue@_run@_in@_order\ is set, none of this new processing happens. The |
| 12650 | entire queue has to be scanned and sorted before any deliveries can start. |
| 12651 | |
| 12652 | .conf spool@_directory string$**$ "set at compile time" |
| 12653 | .index spool directory||path to |
| 12654 | This defines the directory in which Exim keeps its spool, that is, the messages |
| 12655 | it is waiting to deliver. The default value is taken from the compile-time |
| 12656 | configuration setting, if there is one. If not, this option must be set. The |
| 12657 | string is expanded, so it can contain, for example, a reference to |
| 12658 | \$primary@_hostname$\. |
| 12659 | |
| 12660 | If the spool directory name is fixed on your installation, it is recommended |
| 12661 | that you set it at build time rather than from this option, particularly if the |
| 12662 | log files are being written to the spool directory (see \log@_file@_path\). |
| 12663 | Otherwise log files cannot be used for errors that are detected early on, such |
| 12664 | as failures in the configuration file. |
| 12665 | |
| 12666 | By using this option to override the compiled-in path, it is possible to run |
| 12667 | tests of Exim without using the standard spool. |
| 12668 | |
| 12669 | .conf strip@_excess@_angle@_brackets boolean false |
| 12670 | .index angle brackets, excess |
| 12671 | If this option is set, redundant pairs of angle brackets round `route-addr' |
| 12672 | items in addresses are stripped. For example, \*@<@<xxx@@a.b.c.d@>@>*\ is treated |
| 12673 | as \*@<xxx@@a.b.c.d@>*\. If this is in the envelope and the message is passed on |
| 12674 | to another MTA, the excess angle brackets are not passed on. If this option is |
| 12675 | not set, multiple pairs of angle brackets cause a syntax error. |
| 12676 | |
| 12677 | .conf strip@_trailing@_dot boolean false |
| 12678 | .index trailing dot on domain |
| 12679 | .index dot||trailing on domain |
| 12680 | If this option is set, a trailing dot at the end of a domain in an address is |
| 12681 | ignored. If this is in the envelope and the message is passed on to another |
| 12682 | MTA, the dot is not passed on. If this option is not set, a dot at the end of a |
| 12683 | domain causes a syntax error. |
| 12684 | However, addresses in header lines are checked only when an ACL requests header |
| 12685 | syntax checking. |
| 12686 | |
| 12687 | .conf syslog@_duplication boolean true |
| 12688 | .index syslog||duplicate log lines, suppressing |
| 12689 | When Exim is logging to syslog, it writes the log lines for its three |
| 12690 | separate logs at different syslog priorities so that they can in principle |
| 12691 | be separated on the logging hosts. Some installations do not require this |
| 12692 | separation, and in those cases, the duplication of certain log lines is a |
| 12693 | nuisance. If \syslog@_duplication\ is set false, only one copy of any |
| 12694 | particular log line is written to syslog. For lines that normally go to |
| 12695 | both the main log and the reject log, the reject log version (possibly |
| 12696 | containing message header lines) is written, at \\LOG@_NOTICE\\ priority. |
| 12697 | Lines that normally go to both the main and the panic log are written at |
| 12698 | the \\LOG@_ALERT\\ priority. |
| 12699 | |
| 12700 | .conf syslog@_facility string unset |
| 12701 | .index syslog||facility, setting |
| 12702 | This option sets the syslog `facility' name, used when Exim is logging to |
| 12703 | syslog. The value must be one of the strings `mail', `user', `news', `uucp', |
| 12704 | `daemon', or `local\*x*\' where \*x*\ is a digit between 0 and 7. If this |
| 12705 | option is unset, `mail' is used. See chapter ~~CHAPlog for details of Exim's |
| 12706 | logging. |
| 12707 | |
| 12708 | |
| 12709 | .conf syslog@_processname string "$tt{exim}" |
| 12710 | .index syslog||process name, setting |
| 12711 | This option sets the syslog `ident' name, used when Exim is logging to syslog. |
| 12712 | The value must be no longer than 32 characters. See chapter ~~CHAPlog for |
| 12713 | details of Exim's logging. |
| 12714 | |
| 12715 | |
| 12716 | .conf syslog@_timestamp boolean true |
| 12717 | .index syslog||timestamps |
| 12718 | If \syslog@_timestamp\ is set false, the timestamps on Exim's log lines are |
| 12719 | omitted when these lines are sent to syslog. See chapter ~~CHAPlog for |
| 12720 | details of Exim's logging. |
| 12721 | |
| 12722 | .conf system@_filter string$**$ unset |
| 12723 | .index filter||system filter |
| 12724 | .index system filter||specifying |
| 12725 | .index Sieve filter||not available for system filter |
| 12726 | This option specifies an Exim filter file that is applied to all messages at |
| 12727 | the start of each delivery attempt, before any routing is done. System filters |
| 12728 | must be Exim filters; they cannot be Sieve filters. If the system filter |
| 12729 | generates any deliveries to files or pipes, or any new mail messages, the |
| 12730 | appropriate \system@_filter@_...@_transport\ option(s) must be set, to define |
| 12731 | which transports are to be used. Details of this facility are given in chapter |
| 12732 | ~~CHAPsystemfilter. |
| 12733 | |
| 12734 | .conf system@_filter@_directory@_transport string$**$ unset |
| 12735 | This sets the name of the transport driver that is to be used when the |
| 12736 | \save\ command in a system message filter specifies a path ending in `/', |
| 12737 | implying delivery of each message into a separate file in some directory. |
| 12738 | During the delivery, the variable \$address@_file$\ contains the path name. |
| 12739 | |
| 12740 | .conf system@_filter@_file@_transport string$**$ unset |
| 12741 | .index file||transport for system filter |
| 12742 | This sets the name of the transport driver that is to be used when the \save\ |
| 12743 | command in a system message filter specifies a path not ending in `/'. During |
| 12744 | the delivery, the variable \$address@_file$\ contains the path name. |
| 12745 | |
| 12746 | .index gid (group id)||system filter |
| 12747 | .conf system@_filter@_group string unset |
| 12748 | This option is used only when \system@_filter@_user\ is also set. It sets the |
| 12749 | gid under which the system filter is run, overriding any gid that is associated |
| 12750 | with the user. The value may be numerical or symbolic. |
| 12751 | |
| 12752 | .conf system@_filter@_pipe@_transport string$**$ unset 7 |
| 12753 | .index \%pipe%\ transport||for system filter |
| 12754 | This specifies the transport driver that is to be used when a \pipe\ command is |
| 12755 | used in a system filter. During the delivery, the variable \$address@_pipe$\ |
| 12756 | contains the pipe command. |
| 12757 | |
| 12758 | .conf system@_filter@_reply@_transport string$**$ unset |
| 12759 | .index \%autoreply%\ transport||for system filter |
| 12760 | This specifies the transport driver that is to be used when a \mail\ command is |
| 12761 | used in a system filter. |
| 12762 | |
| 12763 | .index uid (user id)||system filter |
| 12764 | .conf system@_filter@_user string unset |
| 12765 | If this option is not set, the system filter is run in the main Exim delivery |
| 12766 | process, as root. When the option is set, the system filter runs in a separate |
| 12767 | process, as the given user. Unless the string consists entirely of digits, it |
| 12768 | is looked up in the password data. Failure to find the named user causes a |
| 12769 | configuration error. The gid is either taken from the password data, or |
| 12770 | specified by \system@_filter@_group\. When the uid is specified numerically, |
| 12771 | \system@_filter@_group\ is required to be set. |
| 12772 | |
| 12773 | If the system filter generates any pipe, file, or reply deliveries, the uid |
| 12774 | under which the filter is run is used when transporting them, unless a |
| 12775 | transport option overrides. |
| 12776 | Normally you should set \system@_filter@_user\ if your system filter generates |
| 12777 | these kinds of delivery. |
| 12778 | |
| 12779 | .conf tcp@_nodelay boolean true |
| 12780 | .index daemon||\\TCP@_NODELAY\\ on sockets |
| 12781 | .index Nagle algorithm |
| 12782 | .index \\TCP@_NODELAY\\ on listening sockets |
| 12783 | If this option is set false, it stops the Exim daemon setting the |
| 12784 | \\TCP@_NODELAY\\ option on its listening sockets. Setting \\TCP@_NODELAY\\ |
| 12785 | turns off the `Nagle algorithm', which is a way of improving network |
| 12786 | performance in interactive (character-by-character) situations. Turning it off |
| 12787 | should improve Exim's performance a bit, so that is what happens by default. |
| 12788 | However, it appears that some broken clients cannot cope, and time out. Hence |
| 12789 | this option. It affects only those sockets that are set up for listening by the |
| 12790 | daemon. Sockets created by the smtp transport for delivering mail always set |
| 12791 | \\TCP@_NODELAY\\. |
| 12792 | |
| 12793 | .conf timeout@_frozen@_after time 0s |
| 12794 | .index frozen messages||timing out |
| 12795 | .index timeout||frozen messages |
| 12796 | If \timeout@_frozen@_after\ is set to a time greater than zero, a frozen |
| 12797 | message of any kind that has been on the queue for longer than the given |
| 12798 | time is automatically cancelled at the next queue run. If it is a bounce |
| 12799 | message, it is just discarded; otherwise, a bounce is sent to the sender, in a |
| 12800 | similar manner to cancellation by the \-Mg-\ command line option. If you want |
| 12801 | to timeout frozen bounce messages earlier than other kinds of frozen message, |
| 12802 | see \ignore@_bounce@_errors@_after\. |
| 12803 | |
| 12804 | .conf timezone string unset |
| 12805 | .index timezone, setting |
| 12806 | The value of \timezone\ is used to set the environment variable \\TZ\\ while |
| 12807 | running Exim (if it is different on entry). This ensures that all timestamps |
| 12808 | created by Exim are in the required timezone. If you want all your timestamps |
| 12809 | to be in UTC (aka GMT) you should set |
| 12810 | .display asis |
| 12811 | timezone = UTC |
| 12812 | .endd |
| 12813 | The default value is taken from \\TIMEZONE@_DEFAULT\\ in \(Local/Makefile)\, |
| 12814 | or, if that is not set, from the value of the TZ environment variable when Exim |
| 12815 | is built. If \timezone\ is set to the empty string, either at build or run |
| 12816 | time, any existing \\TZ\\ variable is removed from the environment when Exim |
| 12817 | runs. This is appropriate behaviour for obtaining wall-clock time on some, but |
| 12818 | unfortunately not all, operating systems. |
| 12819 | |
| 12820 | .conf tls@_advertise@_hosts "host list$**$" unset |
| 12821 | .index TLS||advertising |
| 12822 | .index encryption||on SMTP connection |
| 12823 | .index SMTP||encrypted connection |
| 12824 | When Exim is built with support for TLS encrypted connections, the availability |
| 12825 | of the \\STARTTLS\\ command to set up an encrypted session is advertised in |
| 12826 | response to \\EHLO\\ only to those client hosts that match this option. See |
| 12827 | chapter ~~CHAPTLS for details of Exim's support for TLS. |
| 12828 | |
| 12829 | .conf tls@_certificate string$**$ unset |
| 12830 | .index TLS||server certificate, location of |
| 12831 | .index certificate||for server, location of |
| 12832 | The value of this option is expanded, and must then be the absolute path to a |
| 12833 | file which contains the server's certificates. The server's private key is also |
| 12834 | assumed to be in this file if \tls@_privatekey\ is unset. See chapter ~~CHAPTLS |
| 12835 | for further details. |
| 12836 | |
| 12837 | \**Note**\: The certificates defined by this option are used only when Exim is |
| 12838 | receiving incoming messages as a server. If you want to supply certificates for |
| 12839 | use when sending messages as a client, you must set the \tls@_certificate\ |
| 12840 | option in the relevant \%smtp%\ transport. |
| 12841 | |
| 12842 | .conf tls@_crl string$**$ unset |
| 12843 | .index TLS||server certificate revocation list |
| 12844 | .index certificate||revocation list for server |
| 12845 | This option specifies a certificate revocation list. The expanded value must |
| 12846 | be the name of a file that contains a CRL in PEM format. |
| 12847 | |
| 12848 | .conf tls@_dhparam string$**$ unset |
| 12849 | .index TLS||D-H parameters for server |
| 12850 | The value of this option is expanded, and must then be the absolute path to |
| 12851 | a file which contains the server's DH parameter values. |
| 12852 | This is used only for OpenSSL. When Exim is linked with GnuTLS, this option is |
| 12853 | ignored. See section ~~SECTopenvsgnu for further details. |
| 12854 | |
| 12855 | .conf tls@_privatekey string$**$ unset |
| 12856 | .index TLS||server private key, location of |
| 12857 | The value of this option is expanded, and must then be the absolute path to |
| 12858 | a file which contains the server's private key. |
| 12859 | If this option is unset, the private key is assumed to be in the same file as |
| 12860 | the server's certificates. See chapter ~~CHAPTLS for further details. |
| 12861 | |
| 12862 | .conf tls@_remember@_esmtp boolean false |
| 12863 | .index TLS||esmtp state, remembering |
| 12864 | .index TLS||broken clients |
| 12865 | If this option is set true, Exim violates the RFCs by remembering that it is in |
| 12866 | `esmtp' state after successfully negotiating a TLS session. This provides |
| 12867 | support for broken clients that fail to send a new \\EHLO\\ after starting a |
| 12868 | TLS session. |
| 12869 | |
| 12870 | .conf tls@_require@_ciphers string$**$ unset |
| 12871 | .index TLS||requiring specific ciphers |
| 12872 | .index cipher||requiring specific |
| 12873 | This option controls which ciphers can be used for incoming TLS connections. |
| 12874 | (The \%smtp%\ transport has an option of the same name for controlling outgoing |
| 12875 | connections.) This option is expanded for each connection, so can be varied for |
| 12876 | different clients if required. The value of this option must be a list of |
| 12877 | permitted cipher suites. The OpenSSL and GnuTLS libraries handle cipher control |
| 12878 | in somewhat different ways. Details are given in section ~~SECTreqciphsslgnu. |
| 12879 | |
| 12880 | .conf tls@_try@_verify@_hosts "host list$**$" unset |
| 12881 | .index TLS||client certificate verification |
| 12882 | .index certificate||verification of client |
| 12883 | See \tls@_verify@_hosts\ below. |
| 12884 | |
| 12885 | .conf tls@_verify@_certificates string$**$ unset |
| 12886 | .index TLS||client certificate verification |
| 12887 | .index certificate||verification of client |
| 12888 | The value of this option is expanded, and must then be the absolute path to |
| 12889 | a file containing permitted certificates for clients that |
| 12890 | match \tls@_verify@_hosts\ or \tls@_try@_verify@_hosts\. Alternatively, if you |
| 12891 | are using OpenSSL, you can set \tls@_verify@_certificates\ to the name of a |
| 12892 | directory containing certificate files. This does not work with GnuTLS; the |
| 12893 | option must be set to the name of a single file if you are using GnuTLS. |
| 12894 | |
| 12895 | .conf tls@_verify@_hosts "host list$**$" unset |
| 12896 | .index TLS||client certificate verification |
| 12897 | .index certificate||verification of client |
| 12898 | This option, along with \tls@_try@_verify@_hosts\, controls the checking of |
| 12899 | certificates from clients. |
| 12900 | The expected certificates are defined by \tls@_verify@_certificates\, which |
| 12901 | must be set. A configuration error occurs if either \tls@_verify@_hosts\ or |
| 12902 | \tls@_try@_verify@_hosts\ is set and \tls@_verify@_certificates\ is not set. |
| 12903 | |
| 12904 | Any client that matches \tls@_verify@_hosts\ is constrained by |
| 12905 | \tls@_verify@_certificates\. The client must present one of the listed |
| 12906 | certificates. If it does not, the connection is aborted. |
| 12907 | |
| 12908 | A weaker form of checking is provided by \tls@_try@_verify@_hosts\. If a client |
| 12909 | matches this option (but not \tls@_verify@_hosts\), Exim requests a |
| 12910 | certificate and checks it against \tls@_verify@_certificates\, but does not |
| 12911 | abort the connection if there is no certificate or if it does not match. This |
| 12912 | state can be detected in an ACL, which makes it possible to implement policies |
| 12913 | such as `accept for relay only if a verified certificate has been received, but |
| 12914 | accept for local delivery if encrypted, even without a verified certificate'. |
| 12915 | |
| 12916 | Client hosts that match neither of these lists are not asked to present |
| 12917 | certificates. |
| 12918 | |
| 12919 | .conf trusted@_groups "string list" unset |
| 12920 | .index trusted group |
| 12921 | .index group||trusted |
| 12922 | If this option is set, any process that is running in one of the listed groups, |
| 12923 | or which has one of them as a supplementary group, is trusted. |
| 12924 | The groups can be specified numerically or by name. |
| 12925 | See section ~~SECTtrustedadmin for details of what trusted callers are |
| 12926 | permitted to do. If neither \trusted@_groups\ nor \trusted@_users\ is set, only |
| 12927 | root and the Exim user are trusted. |
| 12928 | |
| 12929 | .conf trusted@_users "string list" unset |
| 12930 | .index trusted user |
| 12931 | .index user||trusted |
| 12932 | If this option is set, any process that is running as one of the listed users |
| 12933 | is trusted. |
| 12934 | The users can be specified numerically or by name. |
| 12935 | See section ~~SECTtrustedadmin for details of what trusted callers are |
| 12936 | permitted to do. If neither \trusted@_groups\ nor \trusted@_users\ is set, only |
| 12937 | root and the Exim user are trusted. |
| 12938 | |
| 12939 | .index uid (user id)||unknown caller |
| 12940 | .conf unknown@_login string$**$ unset |
| 12941 | This is a specialized feature for use in unusual configurations. By default, if |
| 12942 | the uid of the caller of Exim cannot be looked up using \*getpwuid()*\, Exim |
| 12943 | gives up. The \unknown@_login\ option can be used to set a login name to be |
| 12944 | used in this circumstance. It is expanded, so values like \user@$caller@_uid\ |
| 12945 | can be set. When \unknown@_login\ is used, the value of \unknown@_username\ is |
| 12946 | used for the user's real name (gecos field), unless this has been set by the |
| 12947 | \-F-\ option. |
| 12948 | |
| 12949 | .conf unknown@_username string unset |
| 12950 | See \unknown@_login\. |
| 12951 | |
| 12952 | .conf untrusted@_set@_sender "address list$**$" unset |
| 12953 | .index trusted user |
| 12954 | .index sender||setting by untrusted user |
| 12955 | .index untrusted user, setting sender |
| 12956 | .index user||untrusted setting sender |
| 12957 | .index envelope sender |
| 12958 | When an untrusted user submits a message to Exim using the standard input, Exim |
| 12959 | normally creates an envelope sender address from the user's login and the |
| 12960 | default qualification domain. Data from the \-f-\ option (for setting envelope |
| 12961 | senders on non-SMTP messages) or the SMTP \\MAIL\\ command (if \-bs-\ or \-bS-\ |
| 12962 | is used) is ignored. |
| 12963 | |
| 12964 | However, untrusted users are permitted to set an empty envelope sender address, |
| 12965 | to declare that a message should never generate any bounces. For example: |
| 12966 | .display asis |
| 12967 | exim -f '<>' user@domain.example |
| 12968 | .endd |
| 12969 | The \untrusted@_set@_sender\ option allows you to permit untrusted users to set |
| 12970 | other envelope sender addresses in a controlled way. When it is set, untrusted |
| 12971 | users are allowed to set envelope sender addresses that match any of the |
| 12972 | patterns in the list. Like all address lists, the string is expanded. The |
| 12973 | identity of the user is in \$sender@_ident$\, so you can, for example, restrict |
| 12974 | users to setting senders that start with their login ids |
| 12975 | followed by a hyphen |
| 12976 | by a setting like this: |
| 12977 | .display asis |
| 12978 | untrusted_set_sender = ^$sender_ident- |
| 12979 | .endd |
| 12980 | If you want to allow untrusted users to set envelope sender addresses without |
| 12981 | restriction, you can use |
| 12982 | .display asis |
| 12983 | untrusted_set_sender = * |
| 12984 | .endd |
| 12985 | The \untrusted@_set@_sender\ option applies to all forms of local input, but |
| 12986 | only to the setting of the envelope sender. It does not permit untrusted users |
| 12987 | to use the other options which trusted user can use to override message |
| 12988 | parameters. Furthermore, it does not stop Exim from removing an existing |
| 12989 | ::Sender:: header in the message, or from adding a ::Sender:: header if |
| 12990 | necessary. See \local__sender__retain\ and \local@_from@_check\ for ways of |
| 12991 | overriding these actions. The handling of the ::Sender:: header is also |
| 12992 | described in section ~~SECTthesenhea. |
| 12993 | |
| 12994 | The log line for a message's arrival shows the envelope sender following `<='. |
| 12995 | For local messages, the user's login always follows, after `U='. In \-bp-\ |
| 12996 | displays, and in the Exim monitor, if an untrusted user sets an envelope sender |
| 12997 | address, the user's login is shown in parentheses after the sender address. |
| 12998 | |
| 12999 | .conf uucp@_from@_pattern string "see below" |
| 13000 | .index `From' line |
| 13001 | .index UUCP||`From' line |
| 13002 | Some applications that pass messages to an MTA via a command line interface use |
| 13003 | an initial line starting with `From' to pass the envelope sender. In |
| 13004 | particular, this is used by UUCP software. Exim recognizes such a line by means |
| 13005 | of a regular expression that is set in \uucp@_from@_pattern\. When the pattern |
| 13006 | matches, the sender address is constructed by expanding the contents of |
| 13007 | \uucp@_from@_sender\, provided that the caller of Exim is a trusted user. The |
| 13008 | default pattern recognizes lines in the following two forms: |
| 13009 | .display asis |
| 13010 | From ph10 Fri Jan 5 12:35 GMT 1996 |
| 13011 | From ph10 Fri, 7 Jan 97 14:00:00 GMT |
| 13012 | .endd |
| 13013 | The pattern can be seen by running |
| 13014 | .display asis |
| 13015 | exim -bP uucp_from_pattern |
| 13016 | .endd |
| 13017 | It checks only up to the hours and minutes, and allows for a 2-digit or 4-digit |
| 13018 | year in the second case. The first word after `From' is matched in the regular |
| 13019 | expression by a parenthesized subpattern. The default value for |
| 13020 | \uucp@_from@_sender\ is `$1', which therefore just uses this first word (`ph10' |
| 13021 | in the example above) as the message's sender. See also |
| 13022 | \ignore@_fromline@_hosts\. |
| 13023 | |
| 13024 | .conf uucp@_from@_sender string$**$ "$tt{@$1}" |
| 13025 | See \uucp@_from@_pattern\ above. |
| 13026 | |
| 13027 | .conf warn@_message@_file string unset |
| 13028 | .index warning of delay||customizing the message |
| 13029 | .index customizing||warning message |
| 13030 | This option defines a template file containing paragraphs of text to be used |
| 13031 | for constructing the warning message which is sent by Exim when a message has |
| 13032 | been on the queue for a specified amount of time, as specified by |
| 13033 | \delay@_warning\. Details of the file's contents are given in chapter |
| 13034 | ~~CHAPemsgcust. See also \bounce@_message@_file\. |
| 13035 | |
| 13036 | .conf write@_rejectlog boolean true |
| 13037 | .index reject log||disabling |
| 13038 | If this option is set false, Exim no longer writes anything to the reject log. |
| 13039 | See chapter ~~CHAPlog for details of what Exim writes to its logs. |
| 13040 | |
| 13041 | .endconf |
| 13042 | |
| 13043 | |
| 13044 | |
| 13045 | . |
| 13046 | . |
| 13047 | . |
| 13048 | . |
| 13049 | . ============================================================================ |
| 13050 | .chapter Generic options for routers |
| 13051 | .rset CHAProutergeneric "~~chapter" |
| 13052 | .set runningfoot "generic router options" |
| 13053 | .index options||generic, for routers |
| 13054 | .index generic options||router |
| 13055 | |
| 13056 | This chapter describes the generic options that apply to all routers, |
| 13057 | identifying those that are preconditions. For a general description of how a |
| 13058 | router operates, see sections ~~SECTrunindrou and ~~SECTrouprecon. The second |
| 13059 | of these sections specifies the order in which the preconditions are tested. |
| 13060 | The order of expansion of the options that provide data for a transport is: |
| 13061 | \errors@_to\, \headers@_add\, \headers@_remove\, \transport\. |
| 13062 | |
| 13063 | .startconf |
| 13064 | |
| 13065 | .conf address@_data string$**$ unset |
| 13066 | .index router||data attached to address |
| 13067 | The string is expanded just before the router is run, that is, after all the |
| 13068 | precondition tests have succeeded. If the expansion is forced to fail, the |
| 13069 | router declines. Other expansion failures cause delivery of the address to be |
| 13070 | deferred. |
| 13071 | |
| 13072 | When the expansion succeeds, the value is retained with the address, and can be |
| 13073 | accessed using the variable \$address@_data$\ in the current router, subsequent |
| 13074 | routers, and the eventual transport. |
| 13075 | |
| 13076 | \**Warning**\: if the current or any subsequent router is a \%redirect%\ router |
| 13077 | that runs a user's filter file, the contents of \$address@_data$\ are |
| 13078 | accessible in the filter. This is not normally a problem, because such data is |
| 13079 | usually either not confidential or it `belongs' to the current user, but if you |
| 13080 | do put confidential data into \$address@_data$\ you need to remember this |
| 13081 | point. |
| 13082 | |
| 13083 | Even if the router declines or passes, the value of \$address@_data$\ remains |
| 13084 | with the address, though it can be changed by another \address@_data\ setting |
| 13085 | on a subsequent router. If a router generates child addresses, the value of |
| 13086 | \$address@_data$\ propagates to them. This also applies to the special kind of |
| 13087 | `child' that is generated by a router with the \unseen\ option. |
| 13088 | |
| 13089 | The idea of \address@_data\ is that you can use it to look up a lot of data for |
| 13090 | the address once, and then pick out parts of the data later. For example, you |
| 13091 | could use a single LDAP lookup to return a string of the form |
| 13092 | .display asis |
| 13093 | uid=1234 gid=5678 mailbox=/mail/xyz forward=/home/xyz/.forward |
| 13094 | .endd |
| 13095 | In the transport you could pick out the mailbox by a setting such as |
| 13096 | .display asis |
| 13097 | file = ${extract{mailbox}{$address_data}} |
| 13098 | .endd |
| 13099 | This makes the configuration file less messy, and also reduces the number of |
| 13100 | lookups. (Exim does cache the most recent lookup, but there may be several |
| 13101 | addresses in a message which cause lookups to occur.) |
| 13102 | |
| 13103 | The \address@_data\ facility is also useful as a means of passing information |
| 13104 | from one router to another, |
| 13105 | and from a router to a transport. In addition, if \address@_data\ is set by a |
| 13106 | router when verifying an address from an ACL, its value is available for use in |
| 13107 | the rest of the ACL statement. |
| 13108 | |
| 13109 | |
| 13110 | .conf address@_test "boolean (precondition)" true |
| 13111 | .index \-bt-\ option |
| 13112 | .index router||skipping when address testing |
| 13113 | If this option is set false, the router is skipped when routing is being tested |
| 13114 | by means of the \-bt-\ command line option. This can be a convenience when your |
| 13115 | first router sends messages to an external scanner, because it saves you |
| 13116 | having to set the `already scanned' indicator when testing real address |
| 13117 | routing. |
| 13118 | |
| 13119 | |
| 13120 | .conf cannot@_route@_message string$**$ unset |
| 13121 | .index router||customizing `cannot route' message |
| 13122 | .index customizing||`cannot route' message |
| 13123 | This option specifies a text message that is used when an address cannot be |
| 13124 | routed because Exim has run out of routers. The default message is `Unrouteable |
| 13125 | address'. This option is useful only on routers that have \more\ set false, or |
| 13126 | on the very last router in a configuration, because the value that is used is |
| 13127 | taken from the last router that inspects an address. For example, using the |
| 13128 | default configuration, you could put: |
| 13129 | .display asis |
| 13130 | cannot_route_message = Remote domain not found in DNS |
| 13131 | .endd |
| 13132 | on the first (\%dnslookup%\) router, and |
| 13133 | .display asis |
| 13134 | cannot_route_message = Unknown local user |
| 13135 | .endd |
| 13136 | on the final router that checks for local users. If string expansion fails, the |
| 13137 | default message is used. |
| 13138 | Unless the expansion failure was explicitly forced, a message about the failure |
| 13139 | is written to the main and panic logs, in addition to the normal message about |
| 13140 | the routing failure. |
| 13141 | |
| 13142 | .conf caseful@_local@_part boolean false |
| 13143 | .index case of local parts |
| 13144 | .index router||case of local parts |
| 13145 | By default, routers handle the local parts of addresses in a case-insensitive |
| 13146 | manner, though the actual case is preserved for transmission with the message. |
| 13147 | If you want the case of letters to be significant in a router, you must set |
| 13148 | this option true. For individual router options that contain address or local |
| 13149 | part lists (for example, \local@_parts\), case-sensitive matching can be turned |
| 13150 | on by `+caseful' as a list item. See section ~~SECTcasletadd for more details. |
| 13151 | |
| 13152 | |
| 13153 | .conf check@_local@_user "boolean (precondition)" false |
| 13154 | .index local user, checking in router |
| 13155 | .index router||checking for local user |
| 13156 | When this option is true, Exim checks that the local part of the recipient |
| 13157 | address (with affixes removed if relevant) is the name of an account on the |
| 13158 | local system. The check is done by calling the \*getpwnam()*\ function rather |
| 13159 | than trying to read \(/etc/passwd)\ directly. This means that other methods of |
| 13160 | holding password data (such as NIS) are supported. If the local part is a local |
| 13161 | user, \$home$\ is set from the password data, and can be tested in other |
| 13162 | preconditions that are evaluated after this one |
| 13163 | (the order of evaluation is given in section ~~SECTrouprecon). However, the |
| 13164 | value of \$home$\ can be overridden by \router@_home@_directory\. |
| 13165 | If the local part is not a local user, the router is skipped. |
| 13166 | |
| 13167 | If you want to check that the local part is either the name of a local user |
| 13168 | or matches something else, you cannot combine \check@_local@_user\ with a |
| 13169 | setting of \local@_parts\, because that specifies the logical \*and*\ of the |
| 13170 | two conditions. However, you can use a \%passwd%\ lookup in a \local@_parts\ |
| 13171 | setting to achieve this. For example: |
| 13172 | .display asis |
| 13173 | local_parts = passwd;$local_part : lsearch;/etc/other/users |
| 13174 | .endd |
| 13175 | Note, however, that the side effects of \check@_local@_user\ (such as setting |
| 13176 | up a home directory) do not occur when a \%passwd%\ lookup is used in a |
| 13177 | \local@_parts\ (or any other) precondition. |
| 13178 | |
| 13179 | .conf condition "string$**$ (precondition)" unset |
| 13180 | .index router||customized precondition |
| 13181 | This option specifies a general precondition test that has to succeed for the |
| 13182 | router to be called. The string is expanded, and if the result is a forced |
| 13183 | failure or an empty string or one of the strings `0' or `no' or `false' |
| 13184 | (checked without regard to the case of the letters), the router is skipped, and |
| 13185 | the address is offered to the next one. This provides a means of applying |
| 13186 | special-purpose conditions to the running of routers. |
| 13187 | |
| 13188 | If the expansion fails (other than forced failure) delivery is deferred. Some |
| 13189 | of the other options below are common special cases that could in fact be |
| 13190 | specified using \condition\. |
| 13191 | Note that \condition\ is the last precondition to be evaluated (see |
| 13192 | section ~~SECTrouprecon). |
| 13193 | |
| 13194 | |
| 13195 | .conf debug@_print string$**$ unset |
| 13196 | .index testing||variables in drivers |
| 13197 | If this option is set and debugging is enabled (see the \-d-\ command line |
| 13198 | option), the string is expanded and included in the debugging output. |
| 13199 | If expansion of the string fails, the error message is written to the debugging |
| 13200 | output, and Exim carries on processing. |
| 13201 | This option is provided to help with checking out the values of variables and |
| 13202 | so on when debugging router configurations. For example, if a \condition\ |
| 13203 | option appears not to be working, \debug@_print\ can be used to output the |
| 13204 | variables it references. The output happens after checks for \domains\, |
| 13205 | \local@_parts\, and \check@_local@_user\ but before any other preconditions are |
| 13206 | tested. A newline is added to the text if it does not end with one. |
| 13207 | |
| 13208 | |
| 13209 | .conf disable@_logging boolean false |
| 13210 | If this option is set true, nothing is logged for any routing errors |
| 13211 | or for any deliveries caused by this router. You should not set this option |
| 13212 | unless you really, really know what you are doing. See also the generic |
| 13213 | transport option of the same name. |
| 13214 | |
| 13215 | .conf domains "domain list$**$ (precondition)" unset |
| 13216 | .index router||restricting to specific domains |
| 13217 | If this option is set, the router is skipped unless the current domain matches |
| 13218 | the list. If the match is achieved by means of a file lookup, the data that the |
| 13219 | lookup returned for the domain is placed in \$domain@_data$\ for use in string |
| 13220 | expansions of the driver's private options. |
| 13221 | See section ~~SECTrouprecon for a list of the order in which preconditions |
| 13222 | are evaluated. |
| 13223 | |
| 13224 | |
| 13225 | .conf driver string unset |
| 13226 | This option must always be set. It specifies which of the available routers is |
| 13227 | to be used. |
| 13228 | |
| 13229 | |
| 13230 | .conf errors@_to string$**$ unset |
| 13231 | .index envelope sender |
| 13232 | .index router||changing address for errors |
| 13233 | If a router successfully handles an address, it may queue the address for |
| 13234 | delivery or it may generate child addresses. In both cases, if there is a |
| 13235 | delivery problem during later processing, the resulting bounce message is sent |
| 13236 | to the address that results from expanding this string, provided that the |
| 13237 | address verifies successfully. |
| 13238 | \errors@_to\ is expanded before \headers@_add\, \headers@_remove\, and |
| 13239 | \transport\. |
| 13240 | |
| 13241 | If the option is unset, or the expansion is forced to fail, or the result of |
| 13242 | the expansion fails to verify, the errors address associated with the incoming |
| 13243 | address is used. At top level, this is the envelope sender. A non-forced |
| 13244 | expansion failure causes delivery to be deferred. |
| 13245 | |
| 13246 | If an address for which \errors@_to\ has been set ends up being delivered over |
| 13247 | SMTP, the envelope sender for that delivery is the \errors@_to\ value, so that |
| 13248 | any bounces that are generated by other MTAs on the delivery route are also |
| 13249 | sent there. The most common use of \errors@_to\ is probably to direct mailing |
| 13250 | list bounces to the manager of the list, as described in section |
| 13251 | ~~SECTmailinglists. |
| 13252 | |
| 13253 | The \errors@_to\ setting associated with an address can be overridden if it |
| 13254 | subsequently passes through other routers that have their own \errors@_to\ |
| 13255 | settings, |
| 13256 | or if it is delivered by a transport with a \return@_path\ setting. |
| 13257 | |
| 13258 | You can set \errors@_to\ to the empty string by either of these settings: |
| 13259 | .display asis |
| 13260 | errors_to = |
| 13261 | errors_to = "" |
| 13262 | .endd |
| 13263 | An expansion item that yields an empty string has the same effect. If you do |
| 13264 | this, a locally detected delivery error for addresses processed by this router |
| 13265 | no longer gives rise to a bounce message; the error is discarded. If the |
| 13266 | address is delivered to a remote host, the return path is set to \"<>"\, unless |
| 13267 | overridden by the \return@_path\ option on the transport. |
| 13268 | |
| 13269 | If for some reason you want to discard local errors, but use a non-empty |
| 13270 | \\MAIL\\ command for remote delivery, you can preserve the original return |
| 13271 | path in \$address@_data$\ in the router, and reinstate it in the transport by |
| 13272 | setting \return@_path\. |
| 13273 | |
| 13274 | |
| 13275 | .conf expn "boolean (precondition)" true |
| 13276 | .index address||testing |
| 13277 | .index testing||addresses |
| 13278 | .index \\EXPN\\||router skipping |
| 13279 | .index router||skipping for \\EXPN\\ |
| 13280 | If this option is turned off, the router is skipped when testing an address |
| 13281 | as a result of processing an SMTP \\EXPN\\ command. You might, for example, |
| 13282 | want to turn it off on a router for users' \(.forward)\ files, while leaving it |
| 13283 | on for the system alias file. |
| 13284 | See section ~~SECTrouprecon for a list of the order in which preconditions |
| 13285 | are evaluated. |
| 13286 | |
| 13287 | The use of the SMTP \\EXPN\\ command is controlled by an ACL (see chapter |
| 13288 | ~~CHAPACL). When Exim is running an \\EXPN\\ command, it is similar to testing |
| 13289 | an address with \-bt-\. Compare \\VRFY\\, whose counterpart is \-bv-\. |
| 13290 | |
| 13291 | |
| 13292 | .conf fail@_verify boolean false |
| 13293 | .index router||forcing verification failure |
| 13294 | Setting this option has the effect of setting both \fail@_verify@_sender\ and |
| 13295 | \fail@_verify@_recipient\ to the same value. |
| 13296 | |
| 13297 | |
| 13298 | .conf fail@_verify@_recipient boolean false |
| 13299 | If this option is true and an address is accepted by this router when |
| 13300 | verifying a recipient, verification fails. |
| 13301 | |
| 13302 | |
| 13303 | .conf fail@_verify@_sender boolean false |
| 13304 | If this option is true and an address is accepted by this router when |
| 13305 | verifying a sender, verification fails. |
| 13306 | |
| 13307 | |
| 13308 | .conf fallback@_hosts "string list" unset |
| 13309 | .index router||fallback hosts |
| 13310 | .index fallback||hosts specified on router |
| 13311 | String expansion is not applied to this option. The argument must be a |
| 13312 | colon-separated list of host names or IP addresses. If a router queues an |
| 13313 | address for a remote transport, this host list is associated with the address, |
| 13314 | and used instead of the transport's fallback host list. If \hosts@_randomize\ |
| 13315 | is set on the transport, the order of the list is randomized for each use. See |
| 13316 | the \fallback@_hosts\ option of the \%smtp%\ transport for further details. |
| 13317 | |
| 13318 | .conf group string$**$ "see below" |
| 13319 | .index gid (group id)||local delivery |
| 13320 | .index local transports||uid and gid |
| 13321 | .index transport||local |
| 13322 | .index router||setting group |
| 13323 | When a router queues an address for a transport, and the transport does not |
| 13324 | specify a group, the group given here is used when running the delivery |
| 13325 | process. |
| 13326 | The group may be specified numerically or by name. If expansion fails, the |
| 13327 | error is logged and delivery is deferred. |
| 13328 | The default is unset, unless \check@_local@_user\ is set, when the default |
| 13329 | is taken from the password information. See also \initgroups\ and \user\ and |
| 13330 | the discussion in chapter ~~CHAPenvironment. |
| 13331 | |
| 13332 | |
| 13333 | .conf headers@_add string$**$ unset |
| 13334 | .index header lines||adding |
| 13335 | .index router||adding header lines |
| 13336 | This option specifies a string of text that is expanded at routing time, and |
| 13337 | associated with any addresses that are processed by the router |
| 13338 | when delivering a message. This option has no effect when an address is just |
| 13339 | being verified. |
| 13340 | |
| 13341 | The \headers@_add\ option is expanded after \errors@_to\, but before |
| 13342 | \headers@_remove\ and \transport\. |
| 13343 | If the expanded string is empty, or if the expansion is forced to fail, the |
| 13344 | option has no effect. Other expansion failures are treated as configuration |
| 13345 | errors. The expanded string must be in the form of one or more RFC 2822 header |
| 13346 | lines, separated by newlines (coded as `@\n'). For example: |
| 13347 | .display asis |
| 13348 | headers_add = X-added-header: added by $primary_hostname\n\ |
| 13349 | X-added-second: another added header line |
| 13350 | .endd |
| 13351 | Exim does not check the syntax of these added header lines. If an address |
| 13352 | passes through several routers as a result of aliasing or forwarding |
| 13353 | operations, any \headers@_add\ or \headers@_remove\ specifications are |
| 13354 | cumulative. This does not apply for multiple routers that result from the use |
| 13355 | of `unseen'. |
| 13356 | |
| 13357 | At transport time, all the original headers listed in \headers__remove\ are |
| 13358 | removed. If there are multiple instances of any listed header, they are all |
| 13359 | removed. |
| 13360 | Then the new headers specified by \headers@_add\ are added, in the order in |
| 13361 | which they were attached to the address. Finally, any additional headers |
| 13362 | specified by the transport are added. It is not possible to remove headers |
| 13363 | added to an address by \headers@_add\. |
| 13364 | |
| 13365 | Because the addition does not happen until transport time, header lines that |
| 13366 | are added by \headers@_add\ are not accessible by means of the \$header@_xxx$\ |
| 13367 | expansion syntax. Conversely, header lines that are removed by |
| 13368 | \headers@_remove\ remain visible. |
| 13369 | |
| 13370 | Addresses with different \headers@_add\ or \headers@_remove\ settings cannot be |
| 13371 | delivered together in a batch. The \headers@_add\ option cannot be used for a |
| 13372 | \%redirect%\ router that has the \one@_time\ option set. |
| 13373 | |
| 13374 | |
| 13375 | .conf headers@_remove string$**$ unset |
| 13376 | .index header lines||removing |
| 13377 | .index router||removing header lines |
| 13378 | The string is expanded at routing time and is then associated with any |
| 13379 | addresses that are processed by the router when delivering a message. This |
| 13380 | option has no effect when an address is being verified. The \headers@_remove\ |
| 13381 | option is expanded after \errors@_to\ and \headers@_add\, but before |
| 13382 | \transport\. If the expansion is forced to fail, the option has no effect. |
| 13383 | Other expansion failures are treated as configuration errors. |
| 13384 | |
| 13385 | After expansion, the string must consist of a colon-separated list of header |
| 13386 | names. This is confusing, because header names themselves are often terminated |
| 13387 | by colons. In this case, the colons are the list separators, not part of the |
| 13388 | names. |
| 13389 | For example: |
| 13390 | .display asis |
| 13391 | headers_remove = return-receipt-to:acknowledge-to |
| 13392 | .endd |
| 13393 | The list is used at transport time as described under \headers@_add\ above. The |
| 13394 | \headers@_remove\ option cannot be used for a \%redirect%\ router that has the |
| 13395 | \one@_time\ option set. |
| 13396 | |
| 13397 | .conf ignore@_target@_hosts "host list$**$" unset |
| 13398 | .index IP address||discarding |
| 13399 | .index router||discarding IP addresses |
| 13400 | Although this option is a host list, it should normally contain IP address |
| 13401 | entries rather than names. If any host that is looked up by the router has an |
| 13402 | IP address that matches an item in this list, Exim behaves as if that IP |
| 13403 | address did not exist. This option allows you to cope with rogue DNS entries |
| 13404 | like |
| 13405 | .display asis |
| 13406 | remote.domain.example. A 127.0.0.1 |
| 13407 | .endd |
| 13408 | by setting |
| 13409 | .display asis |
| 13410 | ignore_target_hosts = 127.0.0.1 |
| 13411 | .endd |
| 13412 | on the relevant router. |
| 13413 | If all the hosts found by a \%dnslookup%\ router are discarded in this way, the |
| 13414 | router declines. In a conventional configuration, an attempt to mail to such a |
| 13415 | domain would then normally provoke the `unrouteable domain' error, and an |
| 13416 | attempt to verify an address in the domain would fail. |
| 13417 | |
| 13418 | Similarly, if \ignore@_target@_hosts\ is set on an \%ipliteral%\ router, the |
| 13419 | router declines if presented with one of the listed addresses. |
| 13420 | |
| 13421 | This option may also be useful for ignoring link-local and site-local IPv6 |
| 13422 | addresses. Because, like all host lists, the value of \ignore@_target@_hosts\ |
| 13423 | is expanded before use as a list, it is possible to make it dependent on the |
| 13424 | domain that is being routed. |
| 13425 | |
| 13426 | |
| 13427 | |
| 13428 | .index additional groups |
| 13429 | .index groups, additional |
| 13430 | .index local transports||uid and gid |
| 13431 | .index transport||local |
| 13432 | .conf initgroups boolean false |
| 13433 | If the router queues an address for a transport, and this option is true, and |
| 13434 | the uid supplied by the router is not overridden by the transport, the |
| 13435 | \*initgroups()*\ function is called when running the transport to ensure that |
| 13436 | any additional groups associated with the uid are set up. See also \group\ and |
| 13437 | \user\ and the discussion in chapter ~~CHAPenvironment. |
| 13438 | |
| 13439 | |
| 13440 | .conf local@_part@_prefix "string list (precondition)" unset |
| 13441 | .index router||prefix for local part |
| 13442 | .index prefix||for local part, used in router |
| 13443 | If this option is set, the router is skipped unless the local part |
| 13444 | starts with one of the given strings, or \local@_part@_prefix@_optional\ is |
| 13445 | true. |
| 13446 | See section ~~SECTrouprecon for a list of the order in which preconditions |
| 13447 | are evaluated. |
| 13448 | |
| 13449 | The list is scanned from left to right, and the first prefix that matches is |
| 13450 | used. A limited form of wildcard is available; if the prefix begins with an |
| 13451 | asterisk, it matches the longest possible sequence of arbitrary characters at |
| 13452 | the start of the local part. An asterisk should therefore always be followed by |
| 13453 | some character that does not occur in normal local parts. |
| 13454 | .index multiple mailboxes |
| 13455 | .index mailbox||multiple |
| 13456 | Wildcarding can be used to set up multiple user mailboxes, as described in |
| 13457 | section ~~SECTmulbox. |
| 13458 | |
| 13459 | During the testing of the \local@_parts\ option, and while the router is |
| 13460 | running, the prefix is removed from the local part, and is available in the |
| 13461 | expansion variable \$local@_part@_prefix$\. If the router accepts the address, |
| 13462 | this remains true during subsequent delivery. |
| 13463 | In particular, the local part that is transmitted in the \\RCPT\\ command |
| 13464 | for LMTP, SMTP, and BSMTP deliveries has the prefix removed by default. This |
| 13465 | behaviour can be overridden by setting \rcpt@_include@_affixes\ true on the |
| 13466 | relevant transport. |
| 13467 | |
| 13468 | The prefix facility is commonly used to handle local parts of the form |
| 13469 | \owner-something\. Another common use is to support local parts of the form |
| 13470 | \real-username\ to bypass a user's \(.forward)\ file -- helpful when trying to |
| 13471 | tell a user their forwarding is broken -- by placing a router like this one |
| 13472 | immediately before the router that handles \(.forward)\ files: |
| 13473 | .display asis |
| 13474 | real_localuser: |
| 13475 | driver = accept |
| 13476 | local_part_prefix = real- |
| 13477 | check_local_user |
| 13478 | transport = local_delivery |
| 13479 | .endd |
| 13480 | If both \local@_part@_prefix\ and \local@_part@_suffix\ are set for a router, |
| 13481 | both conditions must be met if not optional. Care must be taken if wildcards |
| 13482 | are used in both a prefix and a suffix on the same router. Different |
| 13483 | separator characters must be used to avoid ambiguity. |
| 13484 | |
| 13485 | .conf local@_part@_prefix@_optional boolean false |
| 13486 | See \local@_part@_prefix\ above. |
| 13487 | |
| 13488 | |
| 13489 | .conf local@_part@_suffix "string list (precondition)" unset |
| 13490 | .index router||suffix for local part |
| 13491 | .index suffix for local part, used in router |
| 13492 | This option operates in the same way as \local@_part@_prefix\, except that the |
| 13493 | local part must end (rather than start) with the given string, the |
| 13494 | \local@_part@_suffix@_optional\ option determines whether the suffix is |
| 13495 | mandatory, and the wildcard $*$ character, if present, must be the last |
| 13496 | character of the suffix. This option facility is commonly used to handle local |
| 13497 | parts of the form \something-request\ and multiple user mailboxes of the form |
| 13498 | \username-foo\. |
| 13499 | |
| 13500 | .conf local@_part@_suffix@_optional boolean false |
| 13501 | See \local@_part@_suffix\ above. |
| 13502 | |
| 13503 | |
| 13504 | .conf local@_parts "local part list$**$ (precondition)" unset |
| 13505 | .index router||restricting to specific local parts |
| 13506 | .index local part||checking in router |
| 13507 | The router is run only if the local part of the address matches the list. |
| 13508 | See section ~~SECTrouprecon for a list of the order in which preconditions |
| 13509 | are evaluated, and |
| 13510 | section ~~SECTlocparlis for a discussion of local part lists. Because the |
| 13511 | string is expanded, it is possible to make it depend on the domain, for |
| 13512 | example: |
| 13513 | .display asis |
| 13514 | local_parts = dbm;/usr/local/specials/$domain |
| 13515 | .endd |
| 13516 | If the match is achieved by a lookup, the data that the lookup returned |
| 13517 | for the local part is placed in the variable \$local@_part@_data$\ for use in |
| 13518 | expansions of the router's private options. You might use this option, for |
| 13519 | example, if you have a large number of local virtual domains, and you want to |
| 13520 | send all postmaster mail to the same place without having to set up an alias in |
| 13521 | each virtual domain: |
| 13522 | .display asis |
| 13523 | postmaster: |
| 13524 | driver = redirect |
| 13525 | local_parts = postmaster |
| 13526 | data = postmaster@real.domain.example |
| 13527 | .endd |
| 13528 | |
| 13529 | |
| 13530 | .conf log@_as@_local boolean "see below" |
| 13531 | .index log||delivery line |
| 13532 | .index delivery||log line format |
| 13533 | Exim has two logging styles for delivery, the idea being to make local |
| 13534 | deliveries stand out more visibly from remote ones. In the `local' style, the |
| 13535 | recipient address is given just as the local part, without a domain. The use of |
| 13536 | this style is controlled by this option. It defaults to true for the \%accept%\ |
| 13537 | router, and false for all the others. |
| 13538 | |
| 13539 | |
| 13540 | .conf more boolean$**$ true |
| 13541 | The result of string expansion for this option must be a valid boolean value, |
| 13542 | that is, one of the strings `yes', `no', `true', or `false'. Any other result |
| 13543 | causes an error, and delivery is deferred. If the expansion is forced to fail, |
| 13544 | the default value for the option (true) is used. Other failures cause delivery |
| 13545 | to be deferred. |
| 13546 | |
| 13547 | If this option is set false, and the router is run, but declines to handle the |
| 13548 | address, no further routers are tried, routing fails, and the address is |
| 13549 | bounced. |
| 13550 | .index \self\ option |
| 13551 | However, if the router explicitly passes an address to the following router by |
| 13552 | means of the setting |
| 13553 | .display asis |
| 13554 | self = pass |
| 13555 | .endd |
| 13556 | or otherwise, the setting of \more\ is ignored. Also, the setting of \more\ |
| 13557 | does not affect the behaviour if one of the precondition tests fails. In that |
| 13558 | case, the address is always passed to the next router. |
| 13559 | |
| 13560 | |
| 13561 | .conf pass@_on@_timeout boolean false |
| 13562 | .index timeout||of router |
| 13563 | .index router||timeout |
| 13564 | If a router times out during a host lookup, it normally causes deferral of the |
| 13565 | address. If \pass@_on@_timeout\ is set, the address is passed on to the next |
| 13566 | router, overriding \no@_more\. This may be helpful for systems that are |
| 13567 | intermittently connected to the Internet, or those that want to pass to a smart |
| 13568 | host any messages that cannot immediately be delivered. |
| 13569 | |
| 13570 | There are occasional other temporary errors that can occur while doing DNS |
| 13571 | lookups. They are treated in the same way as a timeout, and this option |
| 13572 | applies to all of them. |
| 13573 | |
| 13574 | |
| 13575 | .conf pass@_router string unset |
| 13576 | .index router||go to after `pass' |
| 13577 | When a router returns `pass', the address is normally handed on to the next |
| 13578 | router in sequence. This can be changed by setting \pass@_router\ to the name |
| 13579 | of another router. However (unlike \redirect@_router\) the named router must be |
| 13580 | below the current router, to avoid loops. Note that this option applies only to |
| 13581 | the special case of `pass'. It does not apply when a router returns `decline'. |
| 13582 | |
| 13583 | |
| 13584 | .conf redirect@_router string unset |
| 13585 | .index router||start at after redirection |
| 13586 | Sometimes an administrator knows that it is pointless to reprocess addresses |
| 13587 | generated from alias or forward files with the same router again. For |
| 13588 | example, if an alias file translates real names into login ids there is no |
| 13589 | point searching the alias file a second time, especially if it is a large file. |
| 13590 | |
| 13591 | The \redirect@_router\ option can be set to the name of any router instance. It |
| 13592 | causes the routing of any generated addresses to start at the named router |
| 13593 | instead of at the first router. This option has no effect if the router in |
| 13594 | which it is set does not generate new addresses. |
| 13595 | |
| 13596 | |
| 13597 | .conf require@_files "string list$**$ (precondition)" unset |
| 13598 | .index file||requiring for router |
| 13599 | .index router||requiring file existence |
| 13600 | This option provides a general mechanism for predicating the running of a |
| 13601 | router on the existence or non-existence of certain files or directories. |
| 13602 | Before running a router, as one of its precondition tests, Exim works its way |
| 13603 | through the \require@_files\ list, expanding each item separately. |
| 13604 | |
| 13605 | Because the list is split before expansion, any colons in expansion items must |
| 13606 | be doubled, or the facility for using a different list separator must be used. |
| 13607 | If any expansion is forced to fail, the item is ignored. Other expansion |
| 13608 | failures cause routing of the address to be deferred. |
| 13609 | |
| 13610 | If any expanded string is empty, it is ignored. Otherwise, except as described |
| 13611 | below, each string must be a fully qualified file path, optionally preceded by |
| 13612 | `!'. The paths are passed to the \*stat()*\ function to test for the existence |
| 13613 | of the files or directories. The router is skipped if any paths not preceded by |
| 13614 | `!' do not exist, or if any paths preceded by `!' do exist. |
| 13615 | |
| 13616 | .index NFS |
| 13617 | If \*stat()*\ cannot determine whether a file exists or not, delivery of |
| 13618 | the message is deferred. This can happen when NFS-mounted filesystems are |
| 13619 | unavailable. |
| 13620 | |
| 13621 | This option is checked after the \domains\, \local@_parts\, and \senders\ |
| 13622 | options, so you cannot use it to check for the existence of a file in which to |
| 13623 | look up a domain, local part, or sender. (See section ~~SECTrouprecon for a |
| 13624 | full list of the order in which preconditions are evaluated.) However, as |
| 13625 | these options are all expanded, you can use the \exists\ expansion condition to |
| 13626 | make such tests. The \require@_files\ option is intended for checking files |
| 13627 | that the router may be going to use internally, or which are needed by a |
| 13628 | transport (for example \(.procmailrc)\). |
| 13629 | |
| 13630 | During delivery, the \*stat()*\ function is run as root, but there is a |
| 13631 | facility for some checking of the accessibility of a file by another user. |
| 13632 | This is not a proper permissions check, but just a `rough' check that |
| 13633 | operates as follows: |
| 13634 | |
| 13635 | If an item in a \require@_files\ list does not contain any forward slash |
| 13636 | characters, it is taken to be the user (and optional group, separated by a |
| 13637 | comma) to be checked for subsequent files in the list. If no group is specified |
| 13638 | but the user is specified symbolically, the gid associated with the uid is |
| 13639 | used. For example: |
| 13640 | .display asis |
| 13641 | require_files = mail:/some/file |
| 13642 | require_files = $local_part:$home/.procmailrc |
| 13643 | .endd |
| 13644 | If a user or group name in a \require@_files\ list does not exist, the |
| 13645 | \require@_files\ condition fails. |
| 13646 | |
| 13647 | Exim performs the check by scanning along the components of the file path, and |
| 13648 | checking the access for the given uid and gid. It checks for `x' access on |
| 13649 | directories, and `r' access on the final file. Note that this means that file |
| 13650 | access control lists, if the operating system has them, are ignored. |
| 13651 | |
| 13652 | \**Warning 1**\: When the router is being run to verify addresses for an |
| 13653 | incoming SMTP message, Exim is not running as root, but under its own uid. This |
| 13654 | may affect the result of a \require@_files\ check. In particular, \*stat()*\ |
| 13655 | may yield the error \\EACCES\\ (`Permission denied'). This means that the Exim |
| 13656 | user is not permitted to read one of the directories on the file's path. |
| 13657 | |
| 13658 | \**Warning 2**\: Even when Exim is running as root while delivering a message, |
| 13659 | \*stat()*\ can yield \\EACCES\\ for a file on an NFS directory that is mounted |
| 13660 | without root access. |
| 13661 | |
| 13662 | In both cases, |
| 13663 | the default action is to consider this a configuration error, and routing is |
| 13664 | deferred because the existence or non-existence of the file cannot be |
| 13665 | determined. However, in some circumstances it may be desirable to treat this |
| 13666 | condition as if the file did not exist. If the file name (or the exclamation |
| 13667 | mark that precedes the file name for non-existence) is preceded by a plus sign, |
| 13668 | the \\EACCES\\ error is treated as if the file did not exist. For example: |
| 13669 | .display asis |
| 13670 | require_files = +/some/file |
| 13671 | .endd |
| 13672 | If the router is not an essential part of verification (for example, it |
| 13673 | handles users' \(.forward)\ files), another solution is to set the \verify\ |
| 13674 | option false so that the router is skipped when verifying. |
| 13675 | |
| 13676 | |
| 13677 | .conf retry@_use@_local@_part boolean "see below" |
| 13678 | .index hints database||retry keys |
| 13679 | .index local part||in retry keys |
| 13680 | When a delivery suffers a temporary routing failure, a retry record is created |
| 13681 | in Exim's hints database. For addresses whose routing depends only on the |
| 13682 | domain, the key for the retry record should not involve the local part, but for |
| 13683 | other addresses, both the domain and the local part should be included. |
| 13684 | Usually, remote routing is of the former kind, and local routing is of the |
| 13685 | latter kind. |
| 13686 | |
| 13687 | This option controls whether the local part is used to form the key for retry |
| 13688 | hints for addresses that suffer temporary errors while being handled by this |
| 13689 | router. The default value is true for any router that has \check@_local@_user\ |
| 13690 | set, and false otherwise. Note that this option does not apply to hints keys |
| 13691 | for transport delays; they are controlled by a generic transport option of the |
| 13692 | same name. |
| 13693 | |
| 13694 | The setting of \retry@_use@_local@_part\ applies only to the router on which it |
| 13695 | appears. If the router generates child addresses, they are routed |
| 13696 | independently; this setting does not become attached to them. |
| 13697 | |
| 13698 | |
| 13699 | .conf router@_home@_directory string$**$ unset |
| 13700 | .index router||home directory for |
| 13701 | .index home directory||for router |
| 13702 | This option sets a home directory for use while the router is running. (Compare |
| 13703 | \transport__home@_directory\, which sets a home directory for later |
| 13704 | transporting.) In particular, if used on a \%redirect%\ router, this option |
| 13705 | sets a value for \$home$\ while a filter is running. The value is expanded; |
| 13706 | forced expansion failure causes the option to be ignored -- other failures |
| 13707 | cause the router to defer. |
| 13708 | |
| 13709 | Expansion of \router@_home@_directory\ happens immediately after the |
| 13710 | \check@_local@_user\ test (if configured), before any further expansions take |
| 13711 | place. |
| 13712 | (See section ~~SECTrouprecon for a list of the order in which preconditions |
| 13713 | are evaluated.) |
| 13714 | While the router is running, \router__home@_directory\ overrides the value of |
| 13715 | \$home$\ that came from \check@_local@_user\. |
| 13716 | |
| 13717 | When a router accepts an address and routes it to a transport (including the |
| 13718 | cases when a redirect router generates a pipe, file, or autoreply delivery), |
| 13719 | the home directory setting for the transport is taken from the first of these |
| 13720 | values that is set: |
| 13721 | .numberpars $. |
| 13722 | The \home@_directory\ option on the transport; |
| 13723 | .nextp |
| 13724 | The \transport@_home@_directory\ option on the router; |
| 13725 | .nextp |
| 13726 | The password data if \check@_local@_user\ is set on the router; |
| 13727 | .nextp |
| 13728 | The \router@_home@_directory\ option on the router. |
| 13729 | .endp |
| 13730 | In other words, \router@_home@_directory\ overrides the password data for the |
| 13731 | router, but not for the transport. |
| 13732 | |
| 13733 | |
| 13734 | .conf self string "freeze" |
| 13735 | .index MX record||pointing to local host |
| 13736 | .index local host||MX pointing to |
| 13737 | This option applies to those routers that use a recipient address to find a |
| 13738 | list of remote hosts. Currently, these are the \%dnslookup%\, \%ipliteral%\, |
| 13739 | and \%manualroute%\ routers. |
| 13740 | Certain configurations of the \%queryprogram%\ router can also specify a list |
| 13741 | of remote hosts. |
| 13742 | Usually such routers are configured to send the message to a remote host via an |
| 13743 | \%smtp%\ transport. The \self\ option specifies what happens when the first |
| 13744 | host on the list turns out to be the local host. |
| 13745 | The way in which Exim checks for the local host is described in section |
| 13746 | ~~SECTreclocipadd. |
| 13747 | |
| 13748 | Normally this situation indicates either an error in Exim's configuration (for |
| 13749 | example, the router should be configured not to process this domain), or an |
| 13750 | error in the DNS (for example, the MX should not point to this host). For this |
| 13751 | reason, the default action is to log the incident, defer the address, and |
| 13752 | freeze the message. The following alternatives are provided for use in special |
| 13753 | cases: |
| 13754 | .numberpars $. |
| 13755 | \defer\ |
| 13756 | .newline |
| 13757 | Delivery of the message is tried again later, but the message is not frozen. |
| 13758 | .nextp |
| 13759 | \reroute: <<domain>>\ |
| 13760 | .newline |
| 13761 | The domain is changed to the given domain, and the address is passed back to |
| 13762 | be reprocessed by the routers. No rewriting of headers takes place. This |
| 13763 | behaviour is essentially a redirection. |
| 13764 | .nextp |
| 13765 | \reroute: rewrite: <<domain>>\ |
| 13766 | .newline |
| 13767 | The domain is changed to the given domain, and the address is passed back to be |
| 13768 | reprocessed by the routers. Any headers that contain the original domain are |
| 13769 | rewritten. |
| 13770 | .nextp |
| 13771 | \pass\ |
| 13772 | .newline |
| 13773 | The router passes the address to the next router, or to the router named in the |
| 13774 | \pass@_router\ option if it is set. |
| 13775 | .index \more\ option |
| 13776 | This overrides \no@_more\. |
| 13777 | |
| 13778 | During subsequent routing and delivery, the variable |
| 13779 | \$self@_hostname$\ contains the name of the local host that the router |
| 13780 | encountered. This can be used to distinguish between different cases for hosts |
| 13781 | with multiple names. The combination |
| 13782 | .display asis |
| 13783 | self = pass |
| 13784 | no_more |
| 13785 | .endd |
| 13786 | ensures that only those addresses that routed to the local host are passed on. |
| 13787 | Without \no@_more\, addresses that were declined for other reasons would also |
| 13788 | be passed to the next router. |
| 13789 | .nextp |
| 13790 | \fail\ |
| 13791 | .newline |
| 13792 | Delivery fails and an error report is generated. |
| 13793 | .nextp |
| 13794 | \send\ |
| 13795 | .newline |
| 13796 | .index local host||sending to |
| 13797 | The anomaly is ignored and the address is queued for the transport. This |
| 13798 | setting should be used with extreme caution. For an \%smtp%\ transport, it makes |
| 13799 | sense only in cases where the program that is listening on the SMTP port is not |
| 13800 | this version of Exim. That is, it must be some other MTA, or Exim with a |
| 13801 | different configuration file that handles the domain in another way. |
| 13802 | .endp |
| 13803 | |
| 13804 | .conf senders "address list$**$ (precondition)" unset |
| 13805 | .index router||checking senders |
| 13806 | If this option is set, the router is skipped unless the message's sender |
| 13807 | address matches something on the list. |
| 13808 | See section ~~SECTrouprecon for a list of the order in which preconditions |
| 13809 | are evaluated. |
| 13810 | |
| 13811 | There are issues concerning verification when the running of routers is |
| 13812 | dependent on the sender. When Exim is verifying the address in an \errors@_to\ |
| 13813 | setting, it sets the sender to the null string. When using the \-bt-\ option to |
| 13814 | check a configuration file, it is necessary also to use the \-f-\ option to set |
| 13815 | an appropriate sender. For incoming mail, the sender is unset when verifying |
| 13816 | the sender, but is available when verifying any recipients. If the SMTP |
| 13817 | \\VRFY\\ command is enabled, it must be used after \\MAIL\\ if the sender |
| 13818 | address matters. |
| 13819 | |
| 13820 | .conf translate@_ip@_address string$**$ unset |
| 13821 | .index IP address||translating |
| 13822 | .index packet radio |
| 13823 | .index router||IP address translation |
| 13824 | There exist some rare networking situations (for example, packet radio) where |
| 13825 | it is helpful to be able to translate IP addresses generated by normal routing |
| 13826 | mechanisms into other IP addresses, thus performing a kind of manual IP |
| 13827 | routing. This should be done only if the normal IP routing of the TCP/IP stack |
| 13828 | is inadequate or broken. Because this is an extremely uncommon requirement, the |
| 13829 | code to support this option is not included in the Exim binary unless |
| 13830 | \\SUPPORT__TRANSLATE__IP__ADDRESS\\=yes is set in \(Local/Makefile)\. |
| 13831 | |
| 13832 | The \translate@_ip@_address\ string is expanded for every IP address generated |
| 13833 | by the router, with the generated address set in \$host@_address$\. If the |
| 13834 | expansion is forced to fail, no action is taken. |
| 13835 | For any other expansion error, delivery of the message is deferred. |
| 13836 | If the result of the expansion is an IP address, that replaces the original |
| 13837 | address; otherwise the result is assumed to be a host name -- this is looked up |
| 13838 | using \*gethostbyname()*\ (or \*getipnodebyname()*\ when available) to produce |
| 13839 | one or more replacement IP addresses. For example, to subvert all IP addresses |
| 13840 | in some specific networks, this could be added to a router: |
| 13841 | .display |
| 13842 | $smc{translate@_ip@_address = @\ |
| 13843 | @$@{lookup@{@$@{mask:@$host@_address/26@}@}lsearch@{/some/file@}@{@$value@}fail@}} |
| 13844 | .endd |
| 13845 | The file would contain lines like |
| 13846 | .display asis |
| 13847 | 10.2.3.128/26 some.host |
| 13848 | 10.8.4.34/26 10.44.8.15 |
| 13849 | .endd |
| 13850 | You should not make use of this facility unless you really understand what you |
| 13851 | are doing. |
| 13852 | |
| 13853 | |
| 13854 | .conf transport string$**$ unset |
| 13855 | This option specifies the transport to be used when a router accepts an address |
| 13856 | and sets it up for delivery. A transport is never needed if a router is used |
| 13857 | only for verification. The value of the option is expanded at routing time, |
| 13858 | after the expansion of \errors@_to\, |
| 13859 | \headers@_add\, and \headers@_remove\, |
| 13860 | and result must be the name of one of the configured transports. If it is |
| 13861 | not, delivery is deferred. |
| 13862 | |
| 13863 | The \transport\ option is not used by the \%redirect%\ router, but it does have |
| 13864 | some private options that set up transports for pipe and file deliveries (see |
| 13865 | chapter ~~CHAPredirect). |
| 13866 | |
| 13867 | |
| 13868 | .conf transport@_current@_directory string$**$ unset |
| 13869 | .index current directory for local transport |
| 13870 | This option associates a current directory with any address that is routed |
| 13871 | to a local transport. This can happen either because a transport is |
| 13872 | explicitly configured for the router, or because it generates a delivery to a |
| 13873 | file or a pipe. During the delivery process (that is, at transport time), this |
| 13874 | option string is expanded and is set as the current directory, unless |
| 13875 | overridden by a setting on the transport. |
| 13876 | If the expansion fails for any reason, including forced failure, an error is |
| 13877 | logged, and delivery is deferred. |
| 13878 | See chapter ~~CHAPenvironment for details of the local delivery environment. |
| 13879 | |
| 13880 | |
| 13881 | |
| 13882 | .conf transport@_home@_directory string$**$ "see below" |
| 13883 | .index home directory||for local transport |
| 13884 | This option associates a home directory with any address that is routed to a |
| 13885 | local transport. This can happen either because a transport is explicitly |
| 13886 | configured for the router, or because it generates a delivery to a file or a |
| 13887 | pipe. During the delivery process (that is, at transport time), the option |
| 13888 | string is expanded and is set as the home directory, unless overridden by a |
| 13889 | setting of \home@_directory\ on the transport. |
| 13890 | If the expansion fails for any reason, including forced failure, an error is |
| 13891 | logged, and delivery is deferred. |
| 13892 | |
| 13893 | If the transport does not specify a home directory, and |
| 13894 | \transport@_home@_directory\ is not set for the router, the home directory for |
| 13895 | the tranport is taken from the password data if \check@_local@_user\ is set for |
| 13896 | the router. Otherwise it is taken from \router@_home@_directory\ if that option |
| 13897 | is set; if not, no home directory is set for the transport. |
| 13898 | |
| 13899 | See chapter ~~CHAPenvironment for further details of the local delivery |
| 13900 | environment. |
| 13901 | |
| 13902 | |
| 13903 | |
| 13904 | .conf unseen boolean$**$ false |
| 13905 | .index router||carrying on after success |
| 13906 | The result of string expansion for this option must be a valid boolean value, |
| 13907 | that is, one of the strings `yes', `no', `true', or `false'. Any other result |
| 13908 | causes an error, and delivery is deferred. If the expansion is forced to fail, |
| 13909 | the default value for the option (false) is used. Other failures cause delivery |
| 13910 | to be deferred. |
| 13911 | |
| 13912 | When this option is set true, routing does not cease if the router accepts the |
| 13913 | address. Instead, a copy of the incoming address is passed to the next router, |
| 13914 | overriding a false setting of \more\. There is little point in setting \more\ |
| 13915 | false if \unseen\ is always true, but it may be useful in cases when the value |
| 13916 | of \unseen\ contains expansion items (and therefore, presumably, is sometimes |
| 13917 | true and sometimes false). |
| 13918 | |
| 13919 | The \unseen\ option can be used to cause |
| 13920 | .index copy of message (\unseen\ option) |
| 13921 | copies of messages to be delivered to some other destination, while also |
| 13922 | carrying out a normal delivery. In effect, the current address is made into a |
| 13923 | `parent' that has two children -- one that is delivered as specified by this |
| 13924 | router, and a clone that goes on to be routed further. |
| 13925 | |
| 13926 | Header lines added to the address (or specified for removal) by this router or |
| 13927 | by previous routers affect the `unseen' copy of the message only. The clone |
| 13928 | that continues to be processed by further routers starts with no added headers |
| 13929 | and none specified for removal. |
| 13930 | |
| 13931 | However, any data that was set by the \address@_data\ option in the current or |
| 13932 | previous routers is passed on. Setting this option has a similar effect to the |
| 13933 | \unseen\ command qualifier in filter files. |
| 13934 | |
| 13935 | |
| 13936 | .conf user string$**$ "see below" |
| 13937 | .index uid (user id)||local delivery |
| 13938 | .index local transports||uid and gid |
| 13939 | .index transport||local |
| 13940 | .index router||user for filter processing |
| 13941 | .index filter||user for processing |
| 13942 | When a router queues an address for a transport, and the transport does not |
| 13943 | specify a user, the user given here is used when running the delivery process. |
| 13944 | The user may be specified numerically or by name. If expansion fails, the |
| 13945 | error is logged and delivery is deferred. |
| 13946 | This user is also used by the \%redirect%\ router when running a filter file. |
| 13947 | The default is unset, except when \check@_local@_user\ is set. In this case, |
| 13948 | the default is taken from the password information. If the user is specified as |
| 13949 | a name, and \group\ is not set, the group associated with the user is used. See |
| 13950 | also \initgroups\ and \group\ and the discussion in chapter ~~CHAPenvironment. |
| 13951 | |
| 13952 | |
| 13953 | .conf verify "boolean (precondition)" true |
| 13954 | Setting this option has the effect of setting \verify@_sender\ and |
| 13955 | \verify@_recipient\ to the same value. |
| 13956 | |
| 13957 | .conf verify@_only "boolean (precondition)" false |
| 13958 | .index \\EXPN\\||with \verify@_only\ |
| 13959 | .index \-bv-\ option |
| 13960 | .index router||used only when verifying |
| 13961 | If this option is set, the router is used only when verifying an address or |
| 13962 | testing with the \-bv-\ option, not when actually doing a delivery, testing |
| 13963 | with the \-bt-\ option, or running the SMTP \\EXPN\\ command. It can be further |
| 13964 | restricted to verifying only senders or recipients by means of \verify@_sender\ |
| 13965 | and \verify@_recipient\. |
| 13966 | |
| 13967 | \**Warning**\: When the router is being run to verify addresses for an incoming |
| 13968 | SMTP message, Exim is not running as root, but under its own uid. If the router |
| 13969 | accesses any files, you need to make sure that they are accessible to the Exim |
| 13970 | user or group. |
| 13971 | |
| 13972 | .conf verify@_recipient "boolean (precondition)" true |
| 13973 | If this option is false, the router is skipped when verifying recipient |
| 13974 | addresses |
| 13975 | or testing recipient verification using \-bv-\. |
| 13976 | See section ~~SECTrouprecon for a list of the order in which preconditions |
| 13977 | are evaluated. |
| 13978 | |
| 13979 | .conf verify@_sender "boolean (precondition)" true |
| 13980 | If this option is false, the router is skipped when verifying sender addresses |
| 13981 | or testing sender verification using \-bvs-\. |
| 13982 | See section ~~SECTrouprecon for a list of the order in which preconditions |
| 13983 | are evaluated. |
| 13984 | |
| 13985 | .endconf |
| 13986 | |
| 13987 | |
| 13988 | |
| 13989 | |
| 13990 | |
| 13991 | . |
| 13992 | . |
| 13993 | . |
| 13994 | . |
| 13995 | . ============================================================================ |
| 13996 | .chapter The accept router |
| 13997 | .set runningfoot "accept router" |
| 13998 | .index \%accept%\ router |
| 13999 | .index routers||\%accept%\ |
| 14000 | The \%accept%\ router has no private options of its own. Unless it is being used |
| 14001 | purely for verification (see \verify@_only\) a transport is required to be |
| 14002 | defined by the generic \transport\ option. If the preconditions that are |
| 14003 | specified by generic options are met, the router accepts the address and queues |
| 14004 | it for the given transport. The most common use of this router is for setting |
| 14005 | up deliveries to local mailboxes. For example: |
| 14006 | .display asis |
| 14007 | localusers: |
| 14008 | driver = accept |
| 14009 | domains = mydomain.example |
| 14010 | check_local_user |
| 14011 | transport = local_delivery |
| 14012 | .endd |
| 14013 | The \domains\ condition in this example checks the domain of the address, and |
| 14014 | \check@_local@_user\ checks that the local part is the login of a local user. |
| 14015 | When both preconditions are met, the \%accept%\ router runs, and queues the |
| 14016 | address for the \%local@_delivery%\ transport. |
| 14017 | |
| 14018 | |
| 14019 | |
| 14020 | |
| 14021 | |
| 14022 | |
| 14023 | . |
| 14024 | . |
| 14025 | . |
| 14026 | . |
| 14027 | . ============================================================================ |
| 14028 | .chapter The dnslookup router |
| 14029 | .rset CHAPdnslookup "~~chapter" |
| 14030 | .set runningfoot "dnslookup router" |
| 14031 | .index \%dnslookup%\ router |
| 14032 | .index routers||\%dnslookup%\ |
| 14033 | The \%dnslookup%\ router looks up the hosts that handle mail for the given |
| 14034 | domain in the DNS. A transport must always be set for this router, unless |
| 14035 | \verify@_only\ is set. |
| 14036 | |
| 14037 | If SRV support is configured (see \check@_srv\ below), Exim first searches for |
| 14038 | SRV records. If none are found, or if SRV support is not configured, |
| 14039 | MX records are looked up. If no MX records exist, address records are sought. |
| 14040 | However, \mx@_domains\ can be set to disable the direct use of address records. |
| 14041 | |
| 14042 | MX records of equal priority are sorted by Exim into a random order. Exim then |
| 14043 | looks for address records for the host names obtained from MX or SRV records. |
| 14044 | When a host has more than one IP address, they are sorted into a random order, |
| 14045 | except that IPv6 addresses are always sorted before IPv4 addresses. If all the |
| 14046 | IP addresses found are discarded by a setting of the \ignore@_target@_hosts\ |
| 14047 | generic option, the router declines. |
| 14048 | |
| 14049 | Unless they have the highest priority (lowest MX value), MX records that point |
| 14050 | to the local host, or to any host name that matches \hosts__treat__as__local\, |
| 14051 | are discarded, together with any other MX records of equal or lower priority. |
| 14052 | |
| 14053 | .index MX record||pointing to local host |
| 14054 | .index local host||MX pointing to |
| 14055 | .index \self\ option||in \%dnslookup%\ router |
| 14056 | If the host pointed to by the highest priority MX record, or looked up as an |
| 14057 | address record, is the local host, or matches \hosts__treat__as__local\, what |
| 14058 | happens is controlled by the generic \self\ option. |
| 14059 | |
| 14060 | There are a number of private options that can be used to vary the way the DNS |
| 14061 | lookup is handled. |
| 14062 | |
| 14063 | |
| 14064 | .startconf |
| 14065 | .index options||\%dnslookup%\ router |
| 14066 | .conf check@_secondary@_mx boolean false |
| 14067 | .index MX record||checking for secondary |
| 14068 | If this option is set, the router declines unless the local host is found in |
| 14069 | (and removed from) the list of hosts obtained by MX lookup. This can be used to |
| 14070 | process domains for which the local host is a secondary mail exchanger |
| 14071 | differently to other domains. The way in which Exim decides whether a host is |
| 14072 | the local host is described in section ~~SECTreclocipadd. |
| 14073 | |
| 14074 | .conf check@_srv string$**$ unset |
| 14075 | .index SRV record||enabling use of |
| 14076 | The dnslookup router supports the use of SRV records (see RFC 2782) in |
| 14077 | addition to MX and address records. The support is disabled by default. To |
| 14078 | enable SRV support, set the \check@_srv\ option to the name of the service |
| 14079 | required. For example, |
| 14080 | .display asis |
| 14081 | check_srv = smtp |
| 14082 | .endd |
| 14083 | looks for SRV records that refer to the normal smtp service. The option is |
| 14084 | expanded, so the service name can vary from message to message or address |
| 14085 | to address. This might be helpful if SRV records are being used for a |
| 14086 | submission service. If the expansion is forced to fail, the \check@_srv\ |
| 14087 | option is ignored, and the router proceeds to look for MX records in the |
| 14088 | normal way. |
| 14089 | |
| 14090 | When the expansion succeeds, the router searches first for SRV records for |
| 14091 | the given service (it assumes TCP protocol). A single SRV record with the |
| 14092 | host name \"."\ indicates `no such service for this domain'; if this is |
| 14093 | encountered, the router declines. If other kinds of SRV record are found, |
| 14094 | they are used to construct a host list for delivery according to the rules |
| 14095 | of RFC 2782. MX records are not sought in this case. |
| 14096 | |
| 14097 | However, when no SRV records are found, MX records (and address records) |
| 14098 | are sought in the traditional way. In other words, SRV records take |
| 14099 | precedence over MX records, just as MX records take precedence over address |
| 14100 | records. Note that this behaviour is not sanctioned by RFC 2782, though a |
| 14101 | previous draft RFC defined it. It is apparently believed that MX records |
| 14102 | are sufficient for email and that SRV records should not be used for this |
| 14103 | purpose. However, SRV records have an additional `weight' feature which |
| 14104 | some people might find useful when trying to split an SMTP load between |
| 14105 | hosts of different power. |
| 14106 | |
| 14107 | .conf mx@_domains "domain list$**$" unset |
| 14108 | .index MX record||required to exist |
| 14109 | .index SRV record||required to exist |
| 14110 | A domain that matches \mx@_domains\ is required to have either an MX or an SRV |
| 14111 | record in order to be recognised. (The name of this option could be improved.) |
| 14112 | For example, if all the mail hosts in \*fict.example*\ are known to have MX |
| 14113 | records, except for those in \*discworld.fict.example*\, you could use this |
| 14114 | setting: |
| 14115 | .display asis |
| 14116 | mx_domains = ! *.discworld.fict.example : *.fict.example |
| 14117 | .endd |
| 14118 | This specifies that messages addressed to a domain that matches the list but |
| 14119 | has no MX record should be bounced immediately instead of being routed using |
| 14120 | the address record. |
| 14121 | |
| 14122 | .conf qualify@_single boolean true |
| 14123 | .index DNS||resolver options |
| 14124 | .index DNS||qualifying single-component names |
| 14125 | When this option is true, the resolver option \\RES@_DEFNAMES\\ is set for DNS |
| 14126 | lookups. Typically, but not standardly, this causes the resolver to qualify |
| 14127 | single-component names with the default domain. For example, on a machine |
| 14128 | called \*dictionary.ref.example*\, the domain \*thesaurus*\ would be changed to |
| 14129 | \*thesaurus.ref.example*\ inside the resolver. For details of what your resolver |
| 14130 | actually does, consult your man pages for \*resolver*\ and \*resolv.conf*\. |
| 14131 | |
| 14132 | |
| 14133 | .conf rewrite@_headers boolean true |
| 14134 | .index rewriting||header lines |
| 14135 | .index header lines||rewriting |
| 14136 | If the domain name in the address that is being processed is not fully |
| 14137 | qualified, it may be expanded to its full form by a DNS lookup. For example, if |
| 14138 | an address is specified as \*dormouse@@teaparty*\, the domain might be |
| 14139 | expanded to \*teaparty.wonderland.fict.example*\. Domain expansion can also |
| 14140 | occur as a result of setting the \widen@_domains\ option. If \rewrite@_headers\ |
| 14141 | is true, all occurrences of the abbreviated domain name in any ::Bcc::, ::Cc::, |
| 14142 | ::From::, ::Reply-to::, ::Sender::, and ::To:: header lines of the message are |
| 14143 | rewritten with the full domain name. |
| 14144 | |
| 14145 | This option should be turned off only when it is known that no message is |
| 14146 | ever going to be sent outside an environment where the abbreviation makes |
| 14147 | sense. |
| 14148 | |
| 14149 | When an MX record is looked up in the DNS and matches a wildcard record, name |
| 14150 | servers normally return a record containing the name that has been looked up, |
| 14151 | making it impossible to detect whether a wildcard was present or not. However, |
| 14152 | some name servers have recently been seen to return the wildcard entry. If the |
| 14153 | name returned by a DNS lookup begins with an asterisk, it is not used for |
| 14154 | header rewriting. |
| 14155 | |
| 14156 | .conf same@_domain@_copy@_routing boolean false |
| 14157 | .index address||copying routing |
| 14158 | Addresses with the same domain are normally routed by the \%dnslookup%\ router |
| 14159 | to the same list of hosts. However, this cannot be presumed, because the router |
| 14160 | options and preconditions may refer to the local part of the address. By |
| 14161 | default, therefore, Exim routes each address in a message independently. DNS |
| 14162 | servers run caches, so repeated DNS lookups are not normally expensive, and in |
| 14163 | any case, personal messages rarely have more than a few recipients. |
| 14164 | |
| 14165 | If you are running mailing lists with large numbers of subscribers at the same |
| 14166 | domain, and you are using a \%dnslookup%\ router which is independent of the |
| 14167 | local part, you can set \same__domain__copy@_routing\ to bypass repeated DNS |
| 14168 | lookups for identical domains in one message. In this case, when \%dnslookup%\ |
| 14169 | routes an address to a remote transport, any other unrouted addresses in the |
| 14170 | message that have the same domain are automatically given the same routing |
| 14171 | without processing them independently, |
| 14172 | provided the following conditions are met: |
| 14173 | .numberpars $. |
| 14174 | No router that processed the address specified \headers@_add\ or |
| 14175 | \headers@_remove\. |
| 14176 | .nextp |
| 14177 | The router did not change the address in any way, for example, by `widening' |
| 14178 | the domain. |
| 14179 | .endp |
| 14180 | |
| 14181 | |
| 14182 | .conf search@_parents boolean false |
| 14183 | .index DNS||resolver options |
| 14184 | When this option is true, the resolver option \\RES@_DNSRCH\\ is set for DNS |
| 14185 | lookups. This is different from the \qualify@_single\ option in that it applies |
| 14186 | to domains containing dots. Typically, but not standardly, it causes the |
| 14187 | resolver to search for the name in the current domain and in parent domains. |
| 14188 | For example, on a machine in the \*fict.example*\ domain, if looking up |
| 14189 | \*teaparty.wonderland*\ failed, the resolver would try |
| 14190 | \*teaparty.wonderland.fict.example*\. For details of what your resolver |
| 14191 | actually does, consult your man pages for \*resolver*\ and \*resolv.conf*\. |
| 14192 | |
| 14193 | Setting this option true can cause problems in domains that have a wildcard MX |
| 14194 | record, because any domain that does not have its own MX record matches the |
| 14195 | local wildcard. |
| 14196 | |
| 14197 | .conf widen@_domains "string list" unset |
| 14198 | .index domain||partial, widening |
| 14199 | If a DNS lookup fails and this option is set, each of its strings in turn is |
| 14200 | added onto the end of the domain, and the lookup is tried again. For example, |
| 14201 | if |
| 14202 | .display asis |
| 14203 | widen_domains = fict.example:ref.example |
| 14204 | .endd |
| 14205 | is set and a lookup of \*klingon.dictionary*\ fails, |
| 14206 | \*klingon.dictionary.fict.example*\ is looked up, and if this fails, |
| 14207 | \*klingon.dictionary.ref.example*\ is tried. Note that the \qualify@_single\ |
| 14208 | and \search@_parents\ options can cause some widening to be undertaken inside |
| 14209 | the DNS resolver. |
| 14210 | |
| 14211 | .endconf |
| 14212 | |
| 14213 | .section Effect of qualify@_single and search@_parents |
| 14214 | When a domain from an envelope recipient is changed by the resolver as a result |
| 14215 | of the \qualify@_single\ or \search@_parents\ options, Exim rewrites the |
| 14216 | corresponding address in the message's header lines unless \rewrite@_headers\ |
| 14217 | is set false. Exim then re-routes the address, using the full domain. |
| 14218 | |
| 14219 | These two options affect only the DNS lookup that takes place inside the router |
| 14220 | for the domain of the address that is being routed. They do not affect lookups |
| 14221 | such as that implied by |
| 14222 | .display asis |
| 14223 | domains = @mx_any |
| 14224 | .endd |
| 14225 | that may happen while processing a router precondition before the router is |
| 14226 | entered. No widening ever takes place for these lookups. |
| 14227 | |
| 14228 | |
| 14229 | |
| 14230 | |
| 14231 | |
| 14232 | |
| 14233 | |
| 14234 | |
| 14235 | |
| 14236 | . |
| 14237 | . |
| 14238 | . |
| 14239 | . |
| 14240 | . ============================================================================ |
| 14241 | .chapter The ipliteral router |
| 14242 | .set runningfoot "ipliteral router" |
| 14243 | .index \%ipliteral%\ router |
| 14244 | .index domain literal||routing |
| 14245 | .index routers||\%ipliteral%\ |
| 14246 | This router has no private options. Unless it is being used purely for |
| 14247 | verification (see \verify@_only\) a transport is required to be defined by the |
| 14248 | generic \transport\ option. The router accepts the address if its domain part |
| 14249 | takes the form of an RFC 2822 domain literal, that is, an IP address enclosed |
| 14250 | in square brackets. For example, this router handles the address |
| 14251 | .display asis |
| 14252 | root@[192.168.1.1] |
| 14253 | .endd |
| 14254 | by setting up delivery to the host with that IP address. |
| 14255 | |
| 14256 | If the IP address matches something in \ignore@_target@_hosts\, the router |
| 14257 | declines. |
| 14258 | .index \self\ option||in \%ipliteral%\ router |
| 14259 | If an IP literal turns out to refer to the local host, the generic \self\ |
| 14260 | option determines what happens. |
| 14261 | |
| 14262 | The RFCs require support for domain literals; however, their use is |
| 14263 | controversial in today's Internet. If you want to use this router, you must |
| 14264 | also set the main configuration option \allow@_domain@_literals\. Otherwise, |
| 14265 | Exim will not recognize the domain literal syntax in addresses. |
| 14266 | |
| 14267 | |
| 14268 | |
| 14269 | . |
| 14270 | . |
| 14271 | . |
| 14272 | . |
| 14273 | . ============================================================================ |
| 14274 | .chapter The iplookup router |
| 14275 | .set runningfoot "iplookup router" |
| 14276 | .index \%iplookup%\ router |
| 14277 | .index routers||\%iplookup%\ |
| 14278 | The \%iplookup%\ router was written to fulfil a specific requirement in |
| 14279 | Cambridge University. For this reason, it is not included in the binary of Exim |
| 14280 | by default. If you want to include it, you must set |
| 14281 | .display asis |
| 14282 | ROUTER_IPLOOKUP=yes |
| 14283 | .endd |
| 14284 | in your \(Local/Makefile)\ configuration file. |
| 14285 | |
| 14286 | The \%iplookup%\ router routes an address by sending it over a TCP or UDP |
| 14287 | connection to one or more specific hosts. The host can then return the same or |
| 14288 | a different address -- in effect rewriting the recipient address in the |
| 14289 | message's envelope. The new address is then passed on to subsequent routers. |
| 14290 | |
| 14291 | |
| 14292 | If this process fails, the address can be passed on to |
| 14293 | other routers, or delivery can be deferred. |
| 14294 | |
| 14295 | Background, for those that are interested: We have an Oracle database of all |
| 14296 | Cambridge users, and one of the items of data it maintains for each user is |
| 14297 | where to send mail addressed to \*user@@cam.ac.uk*\. The MX records for |
| 14298 | \*cam.ac.uk*\ point to a central machine that has a large alias list that is |
| 14299 | abstracted from the database. Mail from outside is switched by this system, and |
| 14300 | originally internal mail was also done this way. However, this resulted in a |
| 14301 | fair number of messages travelling from some of our larger systems to the |
| 14302 | switch and back again. The Oracle machine now runs a UDP service that can be |
| 14303 | called by the \%iplookup%\ router in Exim to find out where \*user@@cam.ac.uk*\ |
| 14304 | addresses really have to go; this saves passing through the central switch, and |
| 14305 | in many cases saves doing any remote delivery at all. |
| 14306 | |
| 14307 | Since \%iplookup%\ is just a rewriting router, a transport must not be |
| 14308 | specified for it. |
| 14309 | |
| 14310 | .startconf |
| 14311 | .index options||\%iplookup%\ router |
| 14312 | |
| 14313 | .conf hosts string unset |
| 14314 | This option must be supplied. Its value is a colon-separated list of host |
| 14315 | names. The hosts are looked up using \*gethostbyname()*\ |
| 14316 | (or \*getipnodebyname()*\ when available) |
| 14317 | and are tried in order until one responds to the query. If none respond, what |
| 14318 | happens is controlled by \optional\. |
| 14319 | |
| 14320 | .conf optional boolean false |
| 14321 | If \optional\ is true, if no response is obtained from any host, the address is |
| 14322 | passed to the next router, overriding \no@_more\. If \optional\ is false, |
| 14323 | delivery to the address is deferred. |
| 14324 | |
| 14325 | .conf port integer 0 |
| 14326 | .index port||\%iplookup%\ router |
| 14327 | This option must be supplied. It specifies the port number for the TCP or UDP |
| 14328 | call. |
| 14329 | |
| 14330 | .conf protocol string "udp" |
| 14331 | This option can be set to `udp' or `tcp' to specify which of the two protocols |
| 14332 | is to be used. |
| 14333 | |
| 14334 | .conf query string$**$ "$tt{@$local@_part@@@$domain @$local@_part@@@$domain}" |
| 14335 | This defines the content of the query that is sent to the remote hosts. The |
| 14336 | repetition serves as a way of checking that a response is to the correct query |
| 14337 | in the default case (see \response@_pattern\ below). |
| 14338 | |
| 14339 | .conf reroute string$**$ unset |
| 14340 | If this option is not set, the rerouted address is precisely the byte string |
| 14341 | returned by the remote host, up to the first white space, if any. If set, the |
| 14342 | string is expanded to form the rerouted address. It can include parts matched |
| 14343 | in the response by \response@_pattern\ by means of numeric variables such as |
| 14344 | \$1$\, \$2$\, etc. The variable \$0$\ refers to the entire input string, |
| 14345 | whether or not a pattern is in use. In all cases, the rerouted address must end |
| 14346 | up in the form \*local@_part@@domain*\. |
| 14347 | |
| 14348 | .conf response@_pattern string unset |
| 14349 | This option can be set to a regular expression that is applied to the string |
| 14350 | returned from the remote host. If the pattern does not match the response, the |
| 14351 | router declines. If \response@_pattern\ is not set, no checking of the response |
| 14352 | is done, unless the query was defaulted, in which case there is a check that |
| 14353 | the text returned after the first white space is the original address. This |
| 14354 | checks that the answer that has been received is in response to the correct |
| 14355 | question. For example, if the response is just a new domain, the following |
| 14356 | could be used: |
| 14357 | .display asis |
| 14358 | response_pattern = ^([^@]+)$ |
| 14359 | reroute = $local_part@$1 |
| 14360 | .endd |
| 14361 | |
| 14362 | .conf timeout time 5s |
| 14363 | This specifies the amount of time to wait for a response from the remote |
| 14364 | machine. The same timeout is used for the \*connect()*\ function for a TCP |
| 14365 | call. It does not apply to UDP. |
| 14366 | |
| 14367 | .endconf |
| 14368 | |
| 14369 | |
| 14370 | |
| 14371 | |
| 14372 | . |
| 14373 | . |
| 14374 | . |
| 14375 | . |
| 14376 | . ============================================================================ |
| 14377 | .chapter The manualroute router |
| 14378 | .set runningfoot "manualroute router" |
| 14379 | .index \%manualroute%\ router |
| 14380 | .index routers||\%manualroute%\ |
| 14381 | .index domain||manually routing |
| 14382 | The \%manualroute%\ router is so-called because it provides a way of manually |
| 14383 | routing an address according to its domain. It is mainly used when you want to |
| 14384 | route addresses to remote hosts according to your own rules, bypassing the |
| 14385 | normal DNS routing that looks up MX records. However, \%manualroute%\ can also |
| 14386 | route to local transports, a facility that may be useful if you want to save |
| 14387 | messages for dial-in hosts in local files. |
| 14388 | |
| 14389 | The \%manualroute%\ router compares a list of domain patterns with the domain it |
| 14390 | is trying to route. If there is no match, the router declines. Each pattern has |
| 14391 | associated with it a list of hosts and some other optional data, which may |
| 14392 | include a transport. The combination of a pattern and its data is called a |
| 14393 | `routing rule'. For patterns that do not have an associated transport, the |
| 14394 | generic \transport\ option must specify a transport, unless the router is being |
| 14395 | used purely for verification (see \verify@_only\). |
| 14396 | |
| 14397 | In the case of verification, matching the domain pattern is sufficient for the |
| 14398 | router to accept the address. When actually routing an address for delivery, |
| 14399 | an address that matches a domain pattern is queued for the associated |
| 14400 | transport. If the transport is not a local one, a host list must be associated |
| 14401 | with the pattern; IP addresses are looked up for the hosts, and these are |
| 14402 | passed to the transport along with the mail address. For local transports, a |
| 14403 | host list is optional. If it is present, it is passed in \$host$\ as a single |
| 14404 | text string. |
| 14405 | |
| 14406 | The list of routing rules can be provided as an inline string in \route@_list\, |
| 14407 | or the data can be obtained by looking up the domain in a file or database by |
| 14408 | setting \route@_data\. Only one of these settings may appear in any one |
| 14409 | instance of \%manualroute%\. The format of routing rules is described below, |
| 14410 | following the list of private options. |
| 14411 | |
| 14412 | .section Private options for manualroute |
| 14413 | .rset SECTprioptman "~~chapter.~~section" |
| 14414 | |
| 14415 | The private options for the \%manualroute%\ router are as follows: |
| 14416 | |
| 14417 | .startconf |
| 14418 | .index options||\%manualroute%\ router |
| 14419 | |
| 14420 | .conf host@_find@_failed string "freeze" |
| 14421 | This option controls what happens when \%manualroute%\ tries to find an IP |
| 14422 | address for a host, and the host does not exist. The option can be set to one |
| 14423 | of |
| 14424 | .display asis |
| 14425 | decline |
| 14426 | defer |
| 14427 | fail |
| 14428 | freeze |
| 14429 | pass |
| 14430 | .endd |
| 14431 | The default assumes that this state is a serious configuration error. The |
| 14432 | difference between `pass' and `decline' is that the former forces the address |
| 14433 | to be passed to the next router (or the router defined by \pass@_router\), |
| 14434 | .index \more\ option |
| 14435 | overriding \no@_more\, whereas the latter passes the address to the next router |
| 14436 | only if \more\ is true. |
| 14437 | |
| 14438 | This option applies only to a definite `does not exist' state; if a host lookup |
| 14439 | gets a temporary error, delivery is deferred unless the generic |
| 14440 | \pass@_on@_timeout\ option is set. |
| 14441 | |
| 14442 | .conf hosts@_randomize boolean false |
| 14443 | .index randomized host list |
| 14444 | .index host||list of, randomized |
| 14445 | If this option is set, the order of the items in a host list in a routing rule |
| 14446 | is randomized each time the list is used, unless an option in the routing rule |
| 14447 | overrides (see below). Randomizing the order of a host list can be used to do |
| 14448 | crude load sharing. However, if more than one mail address is routed by the |
| 14449 | same router to the same host list, the host lists are considered to be the same |
| 14450 | (even though they may be randomized into different orders) for the purpose of |
| 14451 | deciding whether to batch the deliveries into a single SMTP transaction. |
| 14452 | |
| 14453 | When \hosts@_randomize\ is true, a host list may be split |
| 14454 | into groups whose order is separately randomized. This makes it possible to |
| 14455 | set up MX-like behaviour. The boundaries between groups are indicated by an |
| 14456 | item that is just \"+"\ in the host list. For example: |
| 14457 | .display asis |
| 14458 | route_list = * host1:host2:host3:+:host4:host5 |
| 14459 | .endd |
| 14460 | The order of the first three hosts and the order of the last two hosts is |
| 14461 | randomized for each use, but the first three always end up before the last two. |
| 14462 | If \hosts@_randomize\ is not set, a \"+"\ item in the list is ignored. If a |
| 14463 | randomized host list is passed to an \%smtp%\ transport that also has |
| 14464 | \hosts@_randomize set\, the list is not re-randomized. |
| 14465 | |
| 14466 | .conf route@_data string$**$ unset |
| 14467 | If this option is set, it must expand to yield the data part of a routing rule. |
| 14468 | Typically, the expansion string includes a lookup based on the domain. For |
| 14469 | example: |
| 14470 | .display asis |
| 14471 | route_data = ${lookup{$domain}dbm{/etc/routes}} |
| 14472 | .endd |
| 14473 | If the expansion is forced to fail, or the result is an empty string, the |
| 14474 | router declines. Other kinds of expansion failure cause delivery to be |
| 14475 | deferred. |
| 14476 | |
| 14477 | .conf route@_list "string list, semicolon-separated" unset |
| 14478 | This string is a list of routing rules, in the form defined below. Note that, |
| 14479 | unlike most string lists, the items are separated by semicolons. This is so |
| 14480 | that they may contain colon-separated host lists. |
| 14481 | |
| 14482 | .conf same@_domain@_copy@_routing boolean false |
| 14483 | .index address||copying routing |
| 14484 | Addresses with the same domain are normally routed by the \%manualroute%\ router |
| 14485 | to the same list of hosts. However, this cannot be presumed, because the router |
| 14486 | options and preconditions may refer to the local part of the address. By |
| 14487 | default, therefore, Exim routes each address in a message independently. DNS |
| 14488 | servers run caches, so repeated DNS lookups are not normally expensive, and in |
| 14489 | any case, personal messages rarely have more than a few recipients. |
| 14490 | |
| 14491 | If you are running mailing lists with large numbers of subscribers at the same |
| 14492 | domain, and you are using a \%manualroute%\ router which is independent of the |
| 14493 | local part, you can set \same@_domain@_copy@_routing\ to bypass repeated DNS |
| 14494 | lookups for identical domains in one message. In this case, when \%manualroute%\ |
| 14495 | routes an address to a remote transport, any other unrouted addresses in the |
| 14496 | message that have the same domain are automatically given the same routing |
| 14497 | without processing them independently. However, this is only done if |
| 14498 | \headers@_add\ and \headers@_remove\ are unset. |
| 14499 | |
| 14500 | .endconf |
| 14501 | |
| 14502 | |
| 14503 | .section Routing rules in route@_list |
| 14504 | The value of \route@_list\ is a string consisting of a sequence of routing |
| 14505 | rules, separated by semicolons. If a semicolon is needed in a rule, it can be |
| 14506 | entered as two semicolons. Empty rules are ignored. The format of each rule is |
| 14507 | .display |
| 14508 | <<domain pattern>> <<list of hosts>> <<options>> |
| 14509 | .endd |
| 14510 | The following example contains two rules, each with a simple domain pattern and |
| 14511 | no options: |
| 14512 | .display asis |
| 14513 | route_list = \ |
| 14514 | dict.ref.example mail-1.ref.example:mail-2.ref.example ; \ |
| 14515 | thes.ref.example mail-3.ref.example:mail-4.ref.example |
| 14516 | .endd |
| 14517 | The three parts of a rule are separated by white space. The pattern and the |
| 14518 | list of hosts can be enclosed in quotes if necessary, and if they are, the |
| 14519 | usual quoting rules apply. Each rule in a \route@_list\ must start with a |
| 14520 | single domain pattern, which is the only mandatory item in the rule. The |
| 14521 | pattern is in the same format as one item in a domain list (see section |
| 14522 | ~~SECTdomainlist), |
| 14523 | except that it may not be the name of an interpolated file. |
| 14524 | That is, it may be wildcarded, or a regular expression, or a file or database |
| 14525 | lookup (with semicolons doubled, because of the use of semicolon as a separator |
| 14526 | in a \route@_list\). |
| 14527 | |
| 14528 | The rules in \route@_list\ are searched in order until one of the patterns |
| 14529 | matches the domain that is being routed. The list of hosts and then options are |
| 14530 | then used as described below. If there is no match, the router declines. When |
| 14531 | \route@_list\ is set, \route@_data\ must not be set. |
| 14532 | |
| 14533 | |
| 14534 | .section Routing rules in route@_data |
| 14535 | The use of \route@_list\ is convenient when there are only a small number of |
| 14536 | routing rules. For larger numbers, it is easier to use a file or database to |
| 14537 | hold the routing information, and use the \route@_data\ option instead. |
| 14538 | The value of \route@_data\ is a list of hosts, followed by (optional) options. |
| 14539 | Most commonly, \route@_data\ is set as a string that contains an |
| 14540 | expansion lookup. For example, suppose we place two routing rules in a file |
| 14541 | like this: |
| 14542 | .display asis |
| 14543 | dict.ref.example: mail-1.ref.example:mail-2.ref.example |
| 14544 | thes.ref.example: mail-3.ref.example:mail-4.ref.example |
| 14545 | .endd |
| 14546 | This data can be accessed by setting |
| 14547 | .display asis |
| 14548 | route_data = ${lookup{$domain}lsearch{/the/file/name}} |
| 14549 | .endd |
| 14550 | Failure of the lookup results in an empty string, causing the router to |
| 14551 | decline. However, you do not have to use a lookup in \route@_data\. The only |
| 14552 | requirement is that the result of expanding the string is a list of hosts, |
| 14553 | possibly followed by options, separated by white space. The list of hosts must |
| 14554 | be enclosed in quotes if it contains white space. |
| 14555 | |
| 14556 | |
| 14557 | |
| 14558 | .section Format of the list of hosts |
| 14559 | A list of hosts, whether obtained via \route@_data\ or \route@_list\, is always |
| 14560 | separately expanded before use. If the expansion fails, the router declines. |
| 14561 | The result of the expansion must be a colon-separated list of names and/or |
| 14562 | IP addresses. IP addresses are not enclosed in brackets. |
| 14563 | |
| 14564 | If the list of hosts was obtained from a \route@_list\ item, the following |
| 14565 | variables are set during its expansion: |
| 14566 | .index numerical variables (\$1$\, \$2$\, etc)||in \%manualroute%\ router |
| 14567 | .numberpars $. |
| 14568 | If the domain was matched against a regular expression, the numeric variables |
| 14569 | \$1$\, \$2$\, etc. may be set. |
| 14570 | .nextp |
| 14571 | \$0$\ is always set to the entire domain. |
| 14572 | .nextp |
| 14573 | \$1$\ is also set when partial matching is done in a file lookup. |
| 14574 | .nextp |
| 14575 | .index \$value$\ |
| 14576 | If the pattern that matched the domain was a lookup item, the data that was |
| 14577 | looked up is available in the expansion variable \$value$\. |
| 14578 | .endp |
| 14579 | |
| 14580 | |
| 14581 | .section How the list of hosts is used |
| 14582 | When an address is routed to an \%smtp%\ transport by \%manualroute%\, each of |
| 14583 | the hosts is tried, in the order specified, when carrying out the SMTP |
| 14584 | delivery. However, the order can be changed by setting the \hosts@_randomize\ |
| 14585 | option, either on the router (see section ~~SECTprioptman above), or on the |
| 14586 | transport. |
| 14587 | |
| 14588 | Hosts may be listed by name or by IP address. An unadorned name in the list of |
| 14589 | hosts is interpreted as a host name. A name that is followed by \"/MX"\ is |
| 14590 | interpreted as an indirection to a sublist of hosts obtained by looking up MX |
| 14591 | records in the DNS. For example: |
| 14592 | .display asis |
| 14593 | route_list = * x.y.z:p.q.r/MX:e.f.g |
| 14594 | .endd |
| 14595 | If the \hosts@_randomize\ option is set, the order of the items in the list is |
| 14596 | randomized before any lookups are done. Exim then scans the list; for any name |
| 14597 | that is not followed by \"/MX"\ it looks up an IP address. If this turns out to |
| 14598 | be an interface on the local host and the item is not the first in the list, |
| 14599 | Exim discards it and any subsequent items. If it is the first item, what |
| 14600 | happens is controlled by the |
| 14601 | .index \self\ option||in \%manualroute%\ router |
| 14602 | \self\ option of the router. |
| 14603 | |
| 14604 | A name on the list that is followed by \"/MX"\ is replaced with the list of |
| 14605 | hosts obtained by looking up MX records for the name. This is always a DNS |
| 14606 | lookup; the \bydns\ and \byname\ options (see section ~~SECThowoptused below) |
| 14607 | are not relevant here. The order of these hosts is determined by the preference |
| 14608 | values in the MX records, according to the usual rules. Because randomizing |
| 14609 | happens before the MX lookup, it does not affect the order that is defined by |
| 14610 | MX preferences. |
| 14611 | |
| 14612 | If the local host is present in the sublist obtained from MX records, but is |
| 14613 | not the most preferred host in that list, it and any equally or less |
| 14614 | preferred hosts are removed before the sublist is inserted into the main list. |
| 14615 | |
| 14616 | If the local host is the most preferred host in the MX list, what happens |
| 14617 | depends on where in the original list of hosts the \"/MX"\ item appears. If it |
| 14618 | is not the first item (that is, there are previous hosts in the main list), |
| 14619 | Exim discards this name and any subsequent items in the main list. |
| 14620 | |
| 14621 | If the MX item is first in the list of hosts, and the local host is the |
| 14622 | most preferred host, what happens is controlled by the \self\ option of the |
| 14623 | router. |
| 14624 | |
| 14625 | DNS failures when lookup up the MX records are treated in the same way as DNS |
| 14626 | failures when looking up IP addresses: \pass@_on@_timeout\ and |
| 14627 | \host@_find@_failed\ are used when relevant. |
| 14628 | |
| 14629 | The generic \ignore@_target@_hosts\ option applies to all hosts in the list, |
| 14630 | whether obtained from an MX lookup or not. |
| 14631 | |
| 14632 | |
| 14633 | .section How the options are used |
| 14634 | .rset SECThowoptused "~~chapter.~~section" |
| 14635 | The options are a sequence of words; in practice no more than three are ever |
| 14636 | present. One of the words can be the name of a transport; this overrides the |
| 14637 | \transport\ option on the router for this particular routing rule only. The |
| 14638 | other words (if present) control randomization of the list of hosts on a |
| 14639 | per-rule basis, and how the IP addresses of the hosts are to be found when |
| 14640 | routing to a remote transport. These options are as follows: |
| 14641 | .numberpars $. |
| 14642 | \randomize\: randomize the order of the hosts in this list, overriding the |
| 14643 | setting of \hosts@_randomize\ for this routing rule only. |
| 14644 | .nextp |
| 14645 | \no@_randomize\: do not randomize the order of the hosts in this list, |
| 14646 | overriding the setting of \hosts@_randomize\ for this routing rule only. |
| 14647 | .nextp |
| 14648 | \byname\: use \*getipnodebyname()*\ (\*gethostbyname()*\ on older systems) to |
| 14649 | find IP addresses. This function may ultimately cause a DNS lookup, but it may |
| 14650 | also look in \(/etc/hosts)\ or other sources of information. |
| 14651 | .nextp |
| 14652 | \bydns\: look up address records for the hosts directly in the DNS; fail if |
| 14653 | no address records are found. If there is a temporary DNS error (such as a |
| 14654 | timeout), delivery is deferred. |
| 14655 | .endp |
| 14656 | For example: |
| 14657 | .display asis |
| 14658 | route_list = domain1 host1:host2:host3 randomize bydns;\ |
| 14659 | domain2 host4:host5 |
| 14660 | .endd |
| 14661 | If neither \byname\ nor \bydns\ is given, Exim behaves as follows: First, a DNS |
| 14662 | lookup is done. If this yields anything other than \\HOST@_NOT@_FOUND\\, that |
| 14663 | result is used. Otherwise, Exim goes on to try a call to \*getipnodebyname()*\ |
| 14664 | or \*gethostbyname()*\, and the result of the lookup is the result of that |
| 14665 | call. |
| 14666 | |
| 14667 | \**Warning**\: It has been discovered that on some systems, if a DNS lookup |
| 14668 | called via \*getipnodebyname()*\ times out, \\HOST@_NOT@_FOUND\\ is returned |
| 14669 | instead of \\TRY@_AGAIN\\. That is why the default action is to try a DNS |
| 14670 | lookup first. Only if that gives a definite `no such host' is the local |
| 14671 | function called. |
| 14672 | |
| 14673 | |
| 14674 | |
| 14675 | If no IP address for a host can be found, what happens is controlled by the |
| 14676 | \host@_find@_failed\ option. |
| 14677 | |
| 14678 | When an address is routed to a local transport, IP addresses are not looked up. |
| 14679 | The host list is passed to the transport in the \$host$\ variable. |
| 14680 | |
| 14681 | |
| 14682 | .section Manualroute examples |
| 14683 | In some of the examples that follow, the presence of the \remote@_smtp\ |
| 14684 | transport, as defined in the default configuration file, is assumed: |
| 14685 | |
| 14686 | .numberpars $. |
| 14687 | .index smart host||example router |
| 14688 | The \%manualroute%\ router can be used to forward all external mail to a |
| 14689 | \*smart host*\. If you have set up, in the main part of the configuration, a |
| 14690 | named domain list that contains your local domains, for example, |
| 14691 | .display asis |
| 14692 | domainlist local_domains = my.domain.example |
| 14693 | .endd |
| 14694 | you can arrange for all other domains to be routed to a smart host by making |
| 14695 | your first router something like this: |
| 14696 | .display asis |
| 14697 | smart_route: |
| 14698 | driver = manualroute |
| 14699 | domains = !+local_domains |
| 14700 | transport = remote_smtp |
| 14701 | route_list = * smarthost.ref.example |
| 14702 | .endd |
| 14703 | This causes all non-local addresses to be sent to the single host |
| 14704 | \*smarthost.ref.example*\. If a colon-separated list of smart hosts is given, |
| 14705 | they are tried in order |
| 14706 | (but you can use \hosts@_randomize\ to vary the order each time). |
| 14707 | Another way of configuring the same thing is this: |
| 14708 | .display asis |
| 14709 | smart_route: |
| 14710 | driver = manualroute |
| 14711 | transport = remote_smtp |
| 14712 | route_list = !+local_domains smarthost.ref.example |
| 14713 | .endd |
| 14714 | There is no difference in behaviour between these two routers as they stand. |
| 14715 | However, they behave differently if \no@_more\ is added to them. In the first |
| 14716 | example, the router is skipped if the domain does not match the \domains\ |
| 14717 | precondition; the following router is always tried. If the router runs, it |
| 14718 | always matches the domain and so can never decline. Therefore, \no@_more\ would |
| 14719 | have no effect. In the second case, the router is never skipped; it always |
| 14720 | runs. However, if it doesn't match the domain, it declines. In this case |
| 14721 | \no@_more\ would prevent subsequent routers from running. |
| 14722 | |
| 14723 | .nextp |
| 14724 | .index mail hub example |
| 14725 | A \*mail hub*\ is a host which receives mail for a number of domains via MX |
| 14726 | records in the DNS and delivers it via its own private routing mechanism. Often |
| 14727 | the final destinations are behind a firewall, with the mail hub being the one |
| 14728 | machine that can connect to machines both inside and outside the firewall. The |
| 14729 | \%manualroute%\ router is usually used on a mail hub to route incoming messages |
| 14730 | to the correct hosts. For a small number of domains, the routing can be inline, |
| 14731 | using the \route@_list\ option, but for a larger number a file or database |
| 14732 | lookup is easier to manage. |
| 14733 | |
| 14734 | If the domain names are in fact the names of the machines to which the mail is |
| 14735 | to be sent by the mail hub, the configuration can be quite simple. For |
| 14736 | example, |
| 14737 | .display asis |
| 14738 | hub_route: |
| 14739 | driver = manualroute |
| 14740 | transport = remote_smtp |
| 14741 | route_list = *.rhodes.tvs.example $domain |
| 14742 | .endd |
| 14743 | This configuration routes domains that match \"*.rhodes.tvs.example"\ to hosts |
| 14744 | whose names are the same as the mail domains. A similar approach can be taken |
| 14745 | if the host name can be obtained from the domain name by a string manipulation |
| 14746 | that the expansion facilities can handle. Otherwise, a lookup based on the |
| 14747 | domain can be used to find the host: |
| 14748 | .display asis |
| 14749 | through_firewall: |
| 14750 | driver = manualroute |
| 14751 | transport = remote_smtp |
| 14752 | route_data = ${lookup {$domain} cdb {/internal/host/routes}} |
| 14753 | .endd |
| 14754 | The result of the lookup must be the name or IP address of the host (or |
| 14755 | hosts) to which the address is to be routed. If the lookup fails, the route |
| 14756 | data is empty, causing the router to decline. The address then passes to the |
| 14757 | next router. |
| 14758 | |
| 14759 | .nextp |
| 14760 | .index batched SMTP output example |
| 14761 | .index SMTP||batched outgoing, example |
| 14762 | You can use \%manualroute%\ to deliver messages to pipes or files in batched |
| 14763 | SMTP format for onward transportation by some other means. This is one way of |
| 14764 | storing mail for a dial-up host when it is not connected. The route list entry |
| 14765 | can be as simple as a single domain name in a configuration like this: |
| 14766 | .display asis |
| 14767 | save_in_file: |
| 14768 | driver = manualroute |
| 14769 | transport = batchsmtp_appendfile |
| 14770 | route_list = saved.domain.example |
| 14771 | .endd |
| 14772 | though often a pattern is used to pick up more than one domain. If there are |
| 14773 | several domains or groups of domains with different transport requirements, |
| 14774 | different transports can be listed in the routing information: |
| 14775 | .display asis |
| 14776 | save_in_file: |
| 14777 | driver = manualroute |
| 14778 | route_list = \ |
| 14779 | *.saved.domain1.example $domain batch_appendfile; \ |
| 14780 | *.saved.domain2.example \ |
| 14781 | ${lookup{$domain}dbm{/domain2/hosts}{$value}fail} \ |
| 14782 | batch_pipe |
| 14783 | .endd |
| 14784 | The first of these just passes the domain in the \$host$\ variable, which |
| 14785 | doesn't achieve much (since it is also in \$domain$\), but the second does a |
| 14786 | file lookup to find a value to pass, causing the router to decline to handle |
| 14787 | the address if the lookup fails. |
| 14788 | .nextp |
| 14789 | .index UUCP||example of router for |
| 14790 | Routing mail directly to UUCP software is a specific case of the use of |
| 14791 | \%manualroute%\ in a gateway to another mail environment. This is an example of |
| 14792 | one way it can be done: |
| 14793 | .display asis |
| 14794 | # Transport |
| 14795 | uucp: |
| 14796 | driver = pipe |
| 14797 | user = nobody |
| 14798 | command = /usr/local/bin/uux -r - \ |
| 14799 | ${substr_-5:$host}!rmail ${local_part} |
| 14800 | return_fail_output = true |
| 14801 | .endd |
| 14802 | .display asis |
| 14803 | # Router |
| 14804 | uucphost: |
| 14805 | transport = uucp |
| 14806 | driver = manualroute |
| 14807 | route_data = \ |
| 14808 | ${lookup{$domain}lsearch{/usr/local/exim/uucphosts}} |
| 14809 | .endd |
| 14810 | The file \(/usr/local/exim/uucphosts)\ contains entries like |
| 14811 | .display asis |
| 14812 | darksite.ethereal.example: darksite.UUCP |
| 14813 | .endd |
| 14814 | It can be set up more simply without adding and removing `.UUCP' but this way |
| 14815 | makes clear the distinction between the domain name |
| 14816 | \*darksite.ethereal.example*\ and the UUCP host name \*darksite*\. |
| 14817 | .endp |
| 14818 | |
| 14819 | |
| 14820 | |
| 14821 | |
| 14822 | |
| 14823 | |
| 14824 | . |
| 14825 | . |
| 14826 | . |
| 14827 | . |
| 14828 | . ============================================================================ |
| 14829 | .chapter The queryprogram router |
| 14830 | .set runningfoot "queryprogram router" |
| 14831 | .rset CHAPdriverlast "~~chapter" |
| 14832 | .index \%queryprogram%\ router |
| 14833 | .index routers||\%queryprogram%\ |
| 14834 | .index routing||by external program |
| 14835 | The \%queryprogram%\ router routes an address by running an external command and |
| 14836 | acting on its output. This is an expensive way to route, and is intended mainly |
| 14837 | for use in lightly-loaded systems, or for performing experiments. However, if |
| 14838 | it is possible to use the precondition options (\domains\, \local@_parts\, |
| 14839 | etc) to skip this router for most addresses, it could sensibly be used in |
| 14840 | special cases, even on a busy host. There are the following private options: |
| 14841 | |
| 14842 | .startconf |
| 14843 | .index options||\%queryprogram%\ router |
| 14844 | .conf command string$**$ unset |
| 14845 | This option must be set. It specifies the command that is to be run. The |
| 14846 | command is split up into a command name and arguments, and then each is |
| 14847 | expanded separately (exactly as for a \%pipe%\ transport, described in chapter |
| 14848 | ~~CHAPpipetransport). |
| 14849 | |
| 14850 | .conf command@_group string unset |
| 14851 | .index gid (group id)||in \%queryprogram%\ router |
| 14852 | This option specifies a gid to be set when running the command. It must be set |
| 14853 | if \command@_user\ specifies a numerical uid. If it begins with a digit, it is |
| 14854 | interpreted as the numerical value of the gid. Otherwise it is looked up using |
| 14855 | \*getgrnam()*\. |
| 14856 | |
| 14857 | .conf command@_user string unset |
| 14858 | .index uid (user id)||for \%queryprogram%\ |
| 14859 | This option must be set. It specifies the uid which is set when running the |
| 14860 | command. If it begins with a digit it is interpreted as the numerical value of |
| 14861 | the uid. Otherwise, it is looked up using \*getpwnam()*\ to obtain a value for |
| 14862 | the uid and, if \command@_group\ is not set, a value for the gid also. |
| 14863 | |
| 14864 | .conf current@_directory string / |
| 14865 | This option specifies an absolute path which is made the current directory |
| 14866 | before running the command. |
| 14867 | |
| 14868 | .conf timeout time 1h |
| 14869 | If the command does not complete within the timeout period, its process group |
| 14870 | is killed and the message is frozen. A value of zero time specifies no |
| 14871 | timeout. |
| 14872 | |
| 14873 | .endconf |
| 14874 | |
| 14875 | The standard output of the command is connected to a pipe, which is read when |
| 14876 | the command terminates. It should consist of a single line of output, |
| 14877 | containing up to five fields, separated by white space. The first field is one |
| 14878 | of the following words (case-insensitive): |
| 14879 | .numberpars $. |
| 14880 | \*Accept*\: routing succeeded; the remaining fields specify what to do (see |
| 14881 | below). |
| 14882 | .nextp |
| 14883 | \*Decline*\: the router declines; pass the address to the next router, unless |
| 14884 | \no@_more\ is set. |
| 14885 | .nextp |
| 14886 | \*Fail*\: routing failed; do not pass the address to any more routers. Any |
| 14887 | subsequent text on the line is an error message. If the router is run as part |
| 14888 | of address verification during an incoming SMTP message, the message is |
| 14889 | included in the SMTP response. |
| 14890 | .nextp |
| 14891 | \*Defer*\: routing could not be completed at this time; try again later. Any |
| 14892 | subsequent text on the line is an error message which is logged. It is not |
| 14893 | included in any SMTP response. |
| 14894 | .nextp |
| 14895 | \*Freeze*\: the same as \*defer*\, except that the message is frozen. |
| 14896 | .nextp |
| 14897 | \*Pass*\: pass the address to the next router (or the router specified by |
| 14898 | \pass@_router\), overriding \no@_more\. |
| 14899 | .nextp |
| 14900 | \*Redirect*\: the message is redirected. The remainder of the line is a list of |
| 14901 | new addresses, which are routed independently, starting with the first router, |
| 14902 | or the router specified by \redirect@_router\, if set. |
| 14903 | .endp |
| 14904 | When the first word is \*accept*\, the remainder of the line consists of a |
| 14905 | number of keyed data values, as follows (split into two lines here, to fit on |
| 14906 | the page): |
| 14907 | .display |
| 14908 | ACCEPT TRANSPORT=<<transport>> HOSTS=<<list of hosts>> |
| 14909 | LOOKUP=byname|bydns DATA=<<text>> |
| 14910 | .endd |
| 14911 | The data items can be given in any order, and all are optional. If no transport |
| 14912 | is included, the transport specified by the generic \transport\ option is used. |
| 14913 | The list of hosts and the lookup type are needed only if the transport is an |
| 14914 | \%smtp%\ transport that does not itself supply a list of hosts. |
| 14915 | |
| 14916 | The format of the list of hosts is the same as for the \%manualroute%\ router. |
| 14917 | As well as host names and IP addresses, it may contain names followed by |
| 14918 | \"/MX"\ to specify sublists of hosts that are obtained by looking up MX |
| 14919 | records. |
| 14920 | |
| 14921 | If the lookup type is not specified, Exim behaves as follows when trying to |
| 14922 | find an IP address for each host: First, a DNS lookup is done. If this yields |
| 14923 | anything other than \\HOST@_NOT@_FOUND\\, that result is used. Otherwise, Exim |
| 14924 | goes on to try a call to \*getipnodebyname()*\ or \*gethostbyname()*\, and the |
| 14925 | result of the lookup is the result of that call. |
| 14926 | |
| 14927 | If the DATA field is set, its value is placed in the \$address@_data$\ |
| 14928 | variable. For example, this return line |
| 14929 | .display asis |
| 14930 | accept hosts=x1.y.example:x2.y.example data="rule1" |
| 14931 | .endd |
| 14932 | routes the address to the default transport, with a host list containing two |
| 14933 | hosts. When the transport runs, the string `rule1' is in \$address@_data$\. |
| 14934 | |
| 14935 | |
| 14936 | |
| 14937 | . |
| 14938 | . |
| 14939 | . |
| 14940 | . |
| 14941 | . ============================================================================ |
| 14942 | .chapter The redirect router |
| 14943 | .set runningfoot "redirect router" |
| 14944 | .rset CHAPredirect "~~chapter" |
| 14945 | .index \%redirect%\ router |
| 14946 | .index routers||\%redirect%\ |
| 14947 | .index alias file||in a \%redirect%\ router |
| 14948 | .index address redirection||\%redirect%\ router |
| 14949 | The \%redirect%\ router handles several kinds of address redirection. Its most |
| 14950 | common uses are for resolving local part aliases from a central alias file |
| 14951 | (usually called \(/etc/aliases)\) and for handling users' personal \(.forward)\ |
| 14952 | files, but it has many other potential uses. The incoming address can be |
| 14953 | redirected in several different ways: |
| 14954 | .numberpars $. |
| 14955 | It can be replaced by one or more new addresses which are themselves routed |
| 14956 | independently. |
| 14957 | .nextp |
| 14958 | It can be routed to be delivered to a given file or directory. |
| 14959 | .nextp |
| 14960 | It can be routed to be delivered to a specified pipe command. |
| 14961 | .nextp |
| 14962 | It can cause an automatic reply to be generated. |
| 14963 | .nextp |
| 14964 | It can be forced to fail, with a custom error message. |
| 14965 | .nextp |
| 14966 | It can be temporarily deferred. |
| 14967 | .nextp |
| 14968 | It can be discarded. |
| 14969 | .endp |
| 14970 | The generic \transport\ option must not be set for \%redirect%\ routers. |
| 14971 | However, there are some private options which define transports for delivery to |
| 14972 | files and pipes, and for generating autoreplies. See the \file@_transport\, |
| 14973 | \pipe@_transport\ and \reply@_transport\ descriptions below. |
| 14974 | |
| 14975 | |
| 14976 | .section Redirection data |
| 14977 | The router operates by interpreting a text string which it obtains either by |
| 14978 | expanding the contents of the \data\ option, or by reading the entire contents |
| 14979 | of a file whose name is given in the \file\ option. These two options are |
| 14980 | mutually exclusive. The first is commonly used for handling system aliases, in |
| 14981 | a configuration like this: |
| 14982 | .display asis |
| 14983 | system_aliases: |
| 14984 | driver = redirect |
| 14985 | data = ${lookup{$local_part}lsearch{/etc/aliases}} |
| 14986 | .endd |
| 14987 | If the lookup fails, the expanded string in this example is empty. When the |
| 14988 | expansion of \data\ results in an empty string, the router declines. A forced |
| 14989 | expansion failure also causes the router to decline; other expansion failures |
| 14990 | cause delivery to be deferred. |
| 14991 | |
| 14992 | A configuration using \file\ is commonly used for handling users' \(.forward)\ |
| 14993 | files, like this: |
| 14994 | .display asis |
| 14995 | userforward: |
| 14996 | driver = redirect |
| 14997 | check_local_user |
| 14998 | file = $home/.forward |
| 14999 | no_verify |
| 15000 | .endd |
| 15001 | If the file does not exist, or causes no action to be taken (for example, it is |
| 15002 | empty or consists only of comments), the router declines. \**Warning**\: This |
| 15003 | is not the case when the file contains syntactically valid items that happen to |
| 15004 | yield empty addresses, for example, items containing only RFC 2822 address |
| 15005 | comments. |
| 15006 | |
| 15007 | |
| 15008 | .section Forward files and address verification |
| 15009 | .index address redirection||while verifying |
| 15010 | It is usual to set \no@_verify\ on \%redirect%\ routers which handle users' |
| 15011 | \(.forward)\ files, as in the example above. There are two reasons for this: |
| 15012 | .numberpars $. |
| 15013 | When Exim is receiving an incoming SMTP message from a remote host, it is |
| 15014 | running under the Exim uid, not as root. |
| 15015 | No additional groups are set up, even if the Exim uid is a member of other |
| 15016 | groups (that is, the \*initgroups()*\ function is not run). |
| 15017 | Exim is unable to change uid to read the file as the user, and it may not be |
| 15018 | able to read it as the Exim user. So in practice the router may not be able to |
| 15019 | operate. |
| 15020 | .nextp |
| 15021 | However, even when the router can operate, the existence of a \(.forward)\ file |
| 15022 | is unimportant when verifying an address. What should be checked is whether the |
| 15023 | local part is a valid user name or not. Cutting out the redirection processing |
| 15024 | saves some resources. |
| 15025 | .endp |
| 15026 | |
| 15027 | |
| 15028 | |
| 15029 | |
| 15030 | .section Interpreting redirection data |
| 15031 | .index Sieve filter||specifying in redirection data |
| 15032 | .index filter||specifying in redirection data |
| 15033 | The contents of the data string, whether obtained from \data\ or \file\, can be |
| 15034 | interpreted in two different ways: |
| 15035 | .numberpars $. |
| 15036 | If the \allow@_filter\ option is set true, and the data begins with the text |
| 15037 | `@#Exim filter' or `@#Sieve filter', it is interpreted as a list of |
| 15038 | \*filtering*\ instructions in the form of an Exim or Sieve filter file, |
| 15039 | respectively. Details of the syntax and semantics of filter files are described |
| 15040 | in a separate document entitled \*Exim's interfaces to mail filtering*\; this |
| 15041 | document is intended for use by end users. |
| 15042 | .nextp |
| 15043 | Otherwise, the data must be a comma-separated list of redirection items, as |
| 15044 | described in the next section. |
| 15045 | .endp |
| 15046 | When a message is redirected to a file (a `mail folder'), the file name given |
| 15047 | in a non-filter redirection list must always be an absolute path. A filter may |
| 15048 | generate a relative path -- how this is handled depends on the transport's |
| 15049 | configuration. See section ~~SECTfildiropt for a discussion of this issue for |
| 15050 | the \%appendfile%\ transport. |
| 15051 | |
| 15052 | |
| 15053 | .section Items in a non-filter redirection list |
| 15054 | .rset SECTitenonfilred "~~chapter.~~section" |
| 15055 | .index address redirection||non-filter list items |
| 15056 | When the redirection data is not an Exim or Sieve filter, for example, if it |
| 15057 | comes from a conventional alias or forward file, it consists of a list of |
| 15058 | addresses, file names, pipe commands, or certain special items (see section |
| 15059 | ~~SECTspecitredli below). The special items can be individually enabled or |
| 15060 | disabled by means of options whose names begin with \allow@_\ or \forbid@_\, |
| 15061 | depending on their default values. The items in the list are separated by |
| 15062 | commas or newlines. |
| 15063 | If a comma is required in an item, the entire item must be enclosed in double |
| 15064 | quotes. |
| 15065 | |
| 15066 | Lines starting with a @# character are comments, and are ignored, and @# may |
| 15067 | also appear following a comma, in which case everything between the @# and the |
| 15068 | next newline character is ignored. |
| 15069 | |
| 15070 | If an item is entirely enclosed in double quotes, these are removed. Otherwise |
| 15071 | double quotes are retained because some forms of mail address require their use |
| 15072 | (but never to enclose the entire address). In the following description, `item' |
| 15073 | refers to what remains after any surrounding double quotes have been removed. |
| 15074 | |
| 15075 | \**Warning**\: If you use an Exim expansion to construct a redirection address, |
| 15076 | and the expansion contains a reference to \$local@_part$\, you should make use |
| 15077 | of the \quote\ expansion operator, in case the local part contains special |
| 15078 | characters. For example, to redirect all mail for the domain |
| 15079 | \*obsolete.example*\, retaining the existing local part, you could use this |
| 15080 | setting: |
| 15081 | .display asis |
| 15082 | data = ${quote:$local_part}@newdomain.example |
| 15083 | .endd |
| 15084 | |
| 15085 | |
| 15086 | .section Redirecting to a local mailbox |
| 15087 | .rset SECTredlocmai "~~chapter.~~section" |
| 15088 | .index routing||loops in |
| 15089 | .index loop||while routing, avoidance of |
| 15090 | .index address redirection||to local mailbox |
| 15091 | A redirection item may safely be the same as the address currently under |
| 15092 | consideration. This does not cause a routing loop, because a router is |
| 15093 | automatically skipped if any ancestor of the address that is being processed |
| 15094 | is the same as the current address and was processed by the current router. |
| 15095 | Such an address is therefore passed to the following routers, so it is handled |
| 15096 | as if there were no redirection. When making this loop-avoidance test, the |
| 15097 | complete local part, including any prefix or suffix, is used. |
| 15098 | |
| 15099 | .index address redirection||local part without domain |
| 15100 | Specifying the same local part without a domain is a common usage in personal |
| 15101 | filter files when the user wants to have messages delivered to the local |
| 15102 | mailbox and also forwarded elsewhere. For example, the user whose login is |
| 15103 | \*cleo*\ might have a \(.forward)\ file containing this: |
| 15104 | .display asis |
| 15105 | cleo, cleopatra@egypt.example |
| 15106 | .endd |
| 15107 | .index backslash in alias file |
| 15108 | .index alias file||backslash in |
| 15109 | For compatibility with other MTAs, such unqualified local parts may be |
| 15110 | preceeded by `@\', but this is not a requirement for loop prevention. However, |
| 15111 | it does make a difference if more than one domain is being handled |
| 15112 | synonymously. |
| 15113 | |
| 15114 | If an item begins with `@\' and the rest of the item parses as a valid RFC 2822 |
| 15115 | address that does not include a domain, the item is qualified using the domain |
| 15116 | of the incoming address. In the absence of a leading `@\', unqualified |
| 15117 | addresses are qualified using the value in \qualify@_recipient\, but you can |
| 15118 | force the incoming domain to be used by setting \qualify__preserve@_domain\. |
| 15119 | |
| 15120 | Care must be taken if there are alias names for local users. |
| 15121 | Consider an MTA handling a single local domain where the system alias file |
| 15122 | contains: |
| 15123 | .display asis |
| 15124 | Sam.Reman: spqr |
| 15125 | .endd |
| 15126 | Now suppose that Sam (whose login id is \*spqr*\) wants to save copies of |
| 15127 | messages in the local mailbox, and also forward copies elsewhere. He creates |
| 15128 | this forward file: |
| 15129 | .display asis |
| 15130 | Sam.Reman, spqr@reme.elsewhere.example |
| 15131 | .endd |
| 15132 | With these settings, an incoming message addressed to \*Sam.Reman*\ fails. The |
| 15133 | \%redirect%\ router for system aliases does not process \*Sam.Reman*\ the |
| 15134 | second time round, because it has previously routed it, |
| 15135 | and the following routers presumably cannot handle the alias. The forward file |
| 15136 | should really contain |
| 15137 | .display asis |
| 15138 | spqr, spqr@reme.elsewhere.example |
| 15139 | .endd |
| 15140 | but because this is such a common error, the \check@_ancestor\ option (see |
| 15141 | below) exists to provide a way to get round it. This is normally set on a |
| 15142 | \%redirect%\ router that is handling users' \(.forward)\ files. |
| 15143 | |
| 15144 | |
| 15145 | .section Special items in redirection lists |
| 15146 | .rset SECTspecitredli "~~chapter.~~section" |
| 15147 | In addition to addresses, the following types of item may appear in redirection |
| 15148 | lists (that is, in non-filter redirection data): |
| 15149 | |
| 15150 | .numberpars $. |
| 15151 | .index pipe||in redirection list |
| 15152 | .index address redirection||to pipe |
| 15153 | An item is treated as a pipe command if it begins with `|' and does not parse |
| 15154 | as a valid RFC 2822 address that includes a domain. A transport for running the |
| 15155 | command must be specified by the \pipe@_transport\ option. |
| 15156 | Normally, either the router or the transport specifies a user and a group under |
| 15157 | which to run the delivery. The default is to use the Exim user and group. |
| 15158 | |
| 15159 | Single or double quotes can be used for enclosing the individual arguments of |
| 15160 | the pipe command; no interpretation of escapes is done for single quotes. If |
| 15161 | the command contains a comma character, it is necessary to put the whole item |
| 15162 | in double quotes, for example: |
| 15163 | .display asis |
| 15164 | "|/some/command ready,steady,go" |
| 15165 | .endd |
| 15166 | since items in redirection lists are terminated by commas. Do not, however, |
| 15167 | quote just the command. An item such as |
| 15168 | .display asis |
| 15169 | |"/some/command ready,steady,go" |
| 15170 | .endd |
| 15171 | is interpreted as a pipe with a rather strange command name, and no arguments. |
| 15172 | .nextp |
| 15173 | .index file||in redirection list |
| 15174 | .index address redirection||to file |
| 15175 | An item is interpreted as a path name if it begins with `/' and does not parse |
| 15176 | as a valid RFC 2822 address that includes a domain. For example, |
| 15177 | .display asis |
| 15178 | /home/world/minbari |
| 15179 | .endd |
| 15180 | is treated as a file name, but |
| 15181 | .display asis |
| 15182 | /s=molari/o=babylon/@x400gate.way |
| 15183 | .endd |
| 15184 | is treated as an address. For a file name, a transport must be specified using |
| 15185 | the \file@_transport\ option. However, if the generated path name ends with a |
| 15186 | forward slash character, it is interpreted as a directory name rather than a |
| 15187 | file name, and \directory@_transport\ is used instead. |
| 15188 | |
| 15189 | Normally, either the router or the transport specifies a user and a group under |
| 15190 | which to run the delivery. The default is to use the Exim user and group. |
| 15191 | .index \(/dev/null)\ |
| 15192 | However, if a redirection item is the path \(/dev/null)\, delivery to it is |
| 15193 | bypassed at a high level, and the log entry shows `$*$$*$bypassed$*$$*$' |
| 15194 | instead of a transport name. In this case the user and group are not used. |
| 15195 | .nextp |
| 15196 | .index included address list |
| 15197 | .index address redirection||included external list |
| 15198 | If an item is of the form |
| 15199 | .display |
| 15200 | :include:<<path name>> |
| 15201 | .endd |
| 15202 | a list of further items is taken from the given file and included at that |
| 15203 | point. |
| 15204 | \**Note**\: such a file can not be a filter file; it is just an out-of-line |
| 15205 | addition to the list. |
| 15206 | The items in the included list are separated by commas or newlines and are not |
| 15207 | subject to expansion. If this is the first item in an alias list in an |
| 15208 | \%lsearch%\ file, a colon must be used to terminate the alias name. This |
| 15209 | example is incorrect: |
| 15210 | .display asis |
| 15211 | list1 :include:/opt/lists/list1 |
| 15212 | .endd |
| 15213 | It must be given as |
| 15214 | .display asis |
| 15215 | list1: :include:/opt/lists/list1 |
| 15216 | .endd |
| 15217 | .nextp |
| 15218 | .index address redirection||to black hole |
| 15219 | Sometimes you want to throw away mail to a particular local part. Making the |
| 15220 | \data\ option expand to an empty string does not work, because that causes the |
| 15221 | router to decline. Instead, the alias item |
| 15222 | .index black hole |
| 15223 | .index abandoning mail |
| 15224 | .display |
| 15225 | :blackhole: |
| 15226 | .endd |
| 15227 | can be used. It does what its name implies. No delivery is done, and no error |
| 15228 | message is generated. This has the same effect as specifing \(/dev/null)\, but |
| 15229 | can be independently disabled. |
| 15230 | |
| 15231 | \**Warning**\: If \":blackhole:"\ appears anywhere in a redirection list, no |
| 15232 | delivery is done for the original local part, even if other redirection items |
| 15233 | are present. If you are generating a multi-item list (for example, by reading a |
| 15234 | database) and need the ability to provide a no-op item, you must use |
| 15235 | \(/dev/null)\. |
| 15236 | |
| 15237 | .nextp |
| 15238 | .index delivery||forcing failure |
| 15239 | .index delivery||forcing deferral |
| 15240 | .index failing delivery||forcing |
| 15241 | .index deferred delivery, forcing |
| 15242 | .index customizing||failure message |
| 15243 | An attempt to deliver a particular address can be deferred or forced to fail by |
| 15244 | redirection items of the form |
| 15245 | .display |
| 15246 | :defer: |
| 15247 | $rm{or} |
| 15248 | :fail: |
| 15249 | .endd |
| 15250 | respectively. When a redirection list contains such an item, it applies to the |
| 15251 | entire redirection; any other items in the list are ignored (:::blackhole:: is |
| 15252 | different). Any text following :::fail:: or :::defer:: is placed in the error |
| 15253 | text associated with the failure. For example, an alias file might contain: |
| 15254 | .display asis |
| 15255 | X.Employee: :fail: Gone away, no forwarding address |
| 15256 | .endd |
| 15257 | In the case of an address that is being verified from an ACL or as the subject |
| 15258 | of a \\VRFY\\ command, the text is included in the SMTP error response by |
| 15259 | default. In an ACL, an explicitly provided message overrides the default, but |
| 15260 | the default message is available in the variable \$acl@_verify@_message$\ and |
| 15261 | can therefore be included in a custom message if this is desired. Exim sends a |
| 15262 | 451 SMTP code for a :::defer::, and 550 for :::fail::. In non-SMTP cases the |
| 15263 | text is included in the error message that Exim generates. |
| 15264 | |
| 15265 | |
| 15266 | |
| 15267 | Normally the error text is the rest of the redirection list -- a comma does not |
| 15268 | terminate it -- but a newline does act as a terminator. Newlines are not |
| 15269 | normally present in alias expansions. In \%lsearch%\ lookups they are removed as |
| 15270 | part of the continuation process, but they may exist in other kinds of lookup |
| 15271 | and in :::include:: files. |
| 15272 | |
| 15273 | During routing for message delivery (as opposed to verification), a redirection |
| 15274 | containing :::fail:: causes an immediate failure of the incoming address, |
| 15275 | whereas :::defer:: causes the message to remain on the queue so that a |
| 15276 | subsequent delivery attempt can happen at a later time. If an address is |
| 15277 | deferred for too long, it will ultimately fail, because the normal retry |
| 15278 | rules still apply. |
| 15279 | .nextp |
| 15280 | .index alias file||exception to default |
| 15281 | Sometimes it is useful to use a single-key search type with a default (see |
| 15282 | chapter ~~CHAPfdlookup) to look up aliases. However, there may be a need for |
| 15283 | exceptions to the default. These can be handled by aliasing them to |
| 15284 | .display asis |
| 15285 | :unknown: |
| 15286 | .endd |
| 15287 | This differs from :::fail:: in that it causes the \%redirect%\ router to decline, |
| 15288 | whereas :::fail:: forces routing to fail. A lookup which results in an empty |
| 15289 | redirection list has the same effect. |
| 15290 | .endp |
| 15291 | |
| 15292 | .section Duplicate addresses |
| 15293 | .index duplicate addresses |
| 15294 | .index address||duplicate, discarding |
| 15295 | .index pipe||duplicated |
| 15296 | Exim removes duplicate addresses from the list to which it is delivering, so as |
| 15297 | to deliver just one copy to each address. This does not apply to deliveries |
| 15298 | routed to pipes by different immediate parent addresses, but an indirect |
| 15299 | aliasing scheme of the type |
| 15300 | .display asis |
| 15301 | pipe: |/some/command $local_part |
| 15302 | localpart1: pipe |
| 15303 | localpart2: pipe |
| 15304 | .endd |
| 15305 | does not work with a message that is addressed to both local parts, because |
| 15306 | when the second is aliased to the intermediate local part `pipe' it gets |
| 15307 | discarded as being the same as a previously handled address. However, a scheme |
| 15308 | such as |
| 15309 | .display asis |
| 15310 | localpart1: |/some/command $local_part |
| 15311 | localpart2: |/some/command $local_part |
| 15312 | .endd |
| 15313 | does result in two different pipe deliveries, because the immediate parents of |
| 15314 | the pipes are distinct. |
| 15315 | |
| 15316 | |
| 15317 | .section Repeated redirection expansion |
| 15318 | .index repeated redirection expansion |
| 15319 | .index address redirection||repeated for each delivery attempt |
| 15320 | When a message cannot be delivered to all of its recipients immediately, |
| 15321 | leading to two or more delivery attempts, redirection expansion is carried out |
| 15322 | afresh each time for those addresses whose children were not all previously |
| 15323 | delivered. If redirection is being used as a mailing list, this can lead to new |
| 15324 | members of the list receiving copies of old messages. The \one@_time\ option |
| 15325 | can be used to avoid this. |
| 15326 | |
| 15327 | .section Errors in redirection lists |
| 15328 | .index address redirection||errors |
| 15329 | If \skip@_syntax@_errors\ is set, a malformed address that causes a parsing |
| 15330 | error is skipped, and an entry is written to the main log. This may be useful |
| 15331 | for mailing lists that are automatically managed. Otherwise, if an error is |
| 15332 | detected while generating the list of new addresses, the original address is |
| 15333 | deferred. See also \syntax@_errors@_to\. |
| 15334 | |
| 15335 | |
| 15336 | .section Private options for the redirect router |
| 15337 | |
| 15338 | The private options for the \%redirect%\ router are as follows: |
| 15339 | |
| 15340 | .startconf |
| 15341 | .index options||\%redirect%\ router |
| 15342 | |
| 15343 | .conf allow@_defer boolean false |
| 15344 | Setting this option allows the use of :::defer:: in non-filter redirection |
| 15345 | data, |
| 15346 | or the \defer\ command in an Exim filter file. |
| 15347 | |
| 15348 | .conf allow@_fail boolean false |
| 15349 | .index failing delivery||from filter |
| 15350 | If this option is true, the :::fail:: item can be used in a redirection list, |
| 15351 | and the \fail\ command may be used in a filter file. |
| 15352 | |
| 15353 | .conf allow@_filter boolean false |
| 15354 | .index filter||enabling use of |
| 15355 | .index Sieve filter||enabling use of |
| 15356 | Setting this option allows Exim to interpret redirection data that starts with |
| 15357 | `@#Exim filter' or `@#Sieve filter' as a set of filtering instructions. There |
| 15358 | are some features of Exim filter files that some administrators may wish to |
| 15359 | lock out; see the \forbid@_filter@_xxx\ options below. The filter is run using |
| 15360 | the uid and gid set by the generic \user\ and \group\ options. These take their |
| 15361 | defaults from the password data if \check@_local@_user\ is set, so in the |
| 15362 | normal case of users' personal filter files, the filter is run as the relevant |
| 15363 | user. When \allow@_filter\ is set true, Exim insists that either |
| 15364 | \check@_local@_user\ or \user\ is set. |
| 15365 | |
| 15366 | |
| 15367 | .conf allow@_freeze boolean false |
| 15368 | .index freezing messages||allowing in filter |
| 15369 | Setting this option allows the use of the \freeze\ command in an Exim filter. |
| 15370 | This command is more normally encountered in system filters, and is disabled by |
| 15371 | default for redirection filters because it isn't something you usually want to |
| 15372 | let ordinary users do. |
| 15373 | |
| 15374 | |
| 15375 | .conf check@_ancestor boolean false |
| 15376 | This option is concerned with handling generated addresses that are the same |
| 15377 | as some address in the list of redirection ancestors of the current address. |
| 15378 | Although it is turned off by default in the code, it is set in the default |
| 15379 | configuration file for handling users' \(.forward)\ files. It is recommended |
| 15380 | for this use of the \%redirect%\ router. |
| 15381 | |
| 15382 | When \check@_ancestor\ is set, if a generated address (including the domain) is |
| 15383 | the same as any ancestor of the current address, it is replaced by a copy of |
| 15384 | the current address. This helps in the case where local part A is aliased to B, |
| 15385 | and B has a \(.forward)\ file pointing back to A. For example, within a single |
| 15386 | domain, the local part `Joe.Bloggs' is aliased to `jb' and \(@~jb/.forward)\ |
| 15387 | contains: |
| 15388 | .display |
| 15389 | @\Joe.Bloggs, <<other item(s)>> |
| 15390 | .endd |
| 15391 | Without the \check@_ancestor\ setting, either local part (`jb' or `joe.bloggs') |
| 15392 | gets processed once by each router and so ends up as it was originally. If `jb' |
| 15393 | is the real mailbox name, mail to `jb' gets delivered (having been turned into |
| 15394 | `joe.bloggs' by the \(.forward)\ file and back to `jb' by the alias), but mail |
| 15395 | to `joe.bloggs' fails. Setting \check@_ancestor\ on the \%redirect%\ router that |
| 15396 | handles the \(.forward)\ file prevents it from turning `jb' back into |
| 15397 | `joe.bloggs' when that was the original address. See also the \repeat@_use\ |
| 15398 | option below. |
| 15399 | |
| 15400 | .conf check@_group boolean "see below" |
| 15401 | When the \file\ option is used, the group owner of the file is checked only |
| 15402 | when this option is set. The permitted groups are those listed in the |
| 15403 | \owngroups\ option, together with the user's default group if |
| 15404 | \check@_local@_user\ is set. If the file has the wrong group, routing is |
| 15405 | deferred. The default setting for this option is true if \check@_local@_user\ |
| 15406 | is set and the \modemask\ option permits the group write bit, or if the |
| 15407 | \owngroups\ option is set. Otherwise it is false, and no group check occurs. |
| 15408 | |
| 15409 | |
| 15410 | .conf check@_owner boolean "see below" |
| 15411 | When the \file\ option is used, the owner of the file is checked only when this |
| 15412 | option is set. If \check@_local@_user\ is set, the local user is permitted; |
| 15413 | otherwise the owner must be one of those listed in the \owners\ option. The |
| 15414 | default value for this option is true if \check@_local@_user\ or \owners\ is |
| 15415 | set. Otherwise the default is false, and no owner check occurs. |
| 15416 | |
| 15417 | .conf data string$**$ unset |
| 15418 | This option is mutually exclusive with \file\. One or other of them must be |
| 15419 | set, but not both. The contents of \data\ are expanded, and then used as the |
| 15420 | list of forwarding items, or as a set of filtering instructions. If the |
| 15421 | expansion is forced to fail, or the result is an empty string or a string that |
| 15422 | has no effect (consists entirely of comments), the router declines. |
| 15423 | |
| 15424 | When filtering instructions are used, the string must begin with `@#Exim |
| 15425 | filter', and all comments in the string, including this initial one, must be |
| 15426 | terminated with newline characters. For example: |
| 15427 | .display asis |
| 15428 | data = #Exim filter\n\ |
| 15429 | if $h_to: contains Exim then save $home/mail/exim endif |
| 15430 | .endd |
| 15431 | If you are reading the data from a database where newlines cannot be included, |
| 15432 | you can use the \$@{sg@}$\ expansion item to turn the escape string of your |
| 15433 | choice into a newline. |
| 15434 | |
| 15435 | .conf directory@_transport string$**$ unset |
| 15436 | A \%redirect%\ router sets up a direct delivery to a directory when a path name |
| 15437 | ending with a slash is specified as a new `address'. The transport used is |
| 15438 | specified by this option, which, after expansion, must be the name of a |
| 15439 | configured transport. This should normally be an \%appendfile%\ transport. |
| 15440 | |
| 15441 | .conf file string$**$ unset |
| 15442 | This option specifies the name of a file that contains the redirection data. It |
| 15443 | is mutually exclusive with the \data\ option. The string is expanded before |
| 15444 | use; if the expansion is forced to fail, the router declines. Other expansion |
| 15445 | failures cause delivery to be deferred. The result of a successful expansion |
| 15446 | must be an absolute path. The entire file is read and used as the redirection |
| 15447 | data. If the data is an empty string or a string that has no effect (consists |
| 15448 | entirely of comments), the router declines. |
| 15449 | |
| 15450 | .index NFS||checking for file existence |
| 15451 | If the attempt to open the file fails with a `does not exist' error, Exim |
| 15452 | runs a check on the containing directory, |
| 15453 | unless \ignore@_enotdir\ is true (see below). |
| 15454 | If the directory does not appear to exist, delivery is deferred. This can |
| 15455 | happen when users' \(.forward)\ files are in NFS-mounted directories, and there |
| 15456 | is a mount problem. If the containing directory does exist, but the file does |
| 15457 | not, the router declines. |
| 15458 | |
| 15459 | .conf file@_transport string$**$ unset |
| 15460 | A \%redirect%\ router sets up a direct delivery to a file when a path name not |
| 15461 | ending in a slash is specified as a new `address'. The transport used is |
| 15462 | specified by this option, which, after expansion, must be the name of a |
| 15463 | configured transport. |
| 15464 | This should normally be an \%appendfile%\ transport. |
| 15465 | When it is running, the file name is in \$address@_file$\. |
| 15466 | |
| 15467 | .conf forbid@_blackhole boolean false |
| 15468 | If this option is true, the :::blackhole:: item may not appear in a redirection |
| 15469 | list. |
| 15470 | |
| 15471 | .conf forbid@_file boolean false |
| 15472 | .index delivery||to file, forbidding |
| 15473 | .index Sieve filter||forbidding delivery to a file |
| 15474 | .index Sieve filter||`keep' facility, disabling |
| 15475 | If this option is true, this router may not generate a new address that |
| 15476 | specifies delivery to a local file or directory, either from a filter or from a |
| 15477 | conventional forward file. This option is forced to be true if \one@_time\ is |
| 15478 | set. It applies to Sieve filters as well as to Exim filters, but if true, it |
| 15479 | locks out the Sieve's `keep' facility. |
| 15480 | |
| 15481 | .conf forbid@_filter@_existstest boolean false |
| 15482 | .index filter||locking out certain features |
| 15483 | If this option is true, string expansions in Exim filters are not allowed to |
| 15484 | make use of the \exists\ condition. |
| 15485 | |
| 15486 | .conf forbid@_filter@_logwrite boolean false |
| 15487 | If this option is true, use of the logging facility in Exim filters is not |
| 15488 | permitted. Logging is in any case available only if the filter is being run |
| 15489 | under some unprivileged uid (which is normally the case for ordinary users' |
| 15490 | \(.forward)\ files). |
| 15491 | |
| 15492 | .conf forbid@_filter@_lookup boolean false |
| 15493 | If this option is true, string expansions in Exim filter files are not allowed |
| 15494 | to make use of \lookup\ items. |
| 15495 | |
| 15496 | .conf forbid@_filter@_perl boolean false |
| 15497 | This option is available only if Exim is built with embedded Perl support. If |
| 15498 | it is true, string expansions in Exim filter files are not allowed to make use |
| 15499 | of the embedded Perl support. |
| 15500 | |
| 15501 | .conf forbid@_filter@_readfile boolean false |
| 15502 | If this option is true, string expansions in Exim filter files are not allowed |
| 15503 | to make use of \readfile\ items. |
| 15504 | |
| 15505 | .conf forbid@_filter@_readsocket boolean false |
| 15506 | If this option is true, string expansions in Exim filter files are not allowed |
| 15507 | to make use of \readsocket\ items. |
| 15508 | |
| 15509 | .conf forbid@_filter@_reply boolean false |
| 15510 | If this option is true, this router may not generate an automatic reply |
| 15511 | message. Automatic replies can be generated only from Exim filter files, not |
| 15512 | from traditional forward files or Sieve filters. This option is forced to be |
| 15513 | true if \one@_time\ is set. |
| 15514 | |
| 15515 | .conf forbid@_filter@_run boolean false |
| 15516 | If this option is true, string expansions in Exim filter files are not allowed |
| 15517 | to make use of \run\ items. |
| 15518 | |
| 15519 | .conf forbid@_include boolean false |
| 15520 | If this option is true, items of the form |
| 15521 | .display |
| 15522 | :include:<<path name>> |
| 15523 | .endd |
| 15524 | are not permitted in non-filter redirection lists. |
| 15525 | |
| 15526 | .conf forbid@_pipe boolean false |
| 15527 | .index delivery||to pipe, forbidding |
| 15528 | If this option is true, this router may not generate a new address which |
| 15529 | specifies delivery to a pipe, either from an Exim filter or from a conventional |
| 15530 | forward file. This option is forced to be true if \one@_time\ is set. |
| 15531 | |
| 15532 | .conf hide@_child@_in@_errmsg boolean false |
| 15533 | .index bounce message||redirection details, suppressing |
| 15534 | If this option is true, it prevents Exim from quoting a child address if it |
| 15535 | generates a bounce or delay message for it. Instead it says `an address |
| 15536 | generated from <<the top level address>>'. Of course, this applies only to |
| 15537 | bounces generated locally. If a message is forwarded to another host, $it{its} |
| 15538 | bounce may well quote the generated address. |
| 15539 | |
| 15540 | .conf ignore@_eacces boolean false |
| 15541 | .index \\EACCES\\ |
| 15542 | If this option is set and an attempt to open a redirection file yields the |
| 15543 | \\EACCES\\ error (permission denied), the \%redirect%\ router behaves as if the |
| 15544 | file did not exist. |
| 15545 | |
| 15546 | .conf ignore@_enotdir boolean false |
| 15547 | .index \\ENOTDIR\\ |
| 15548 | If this option is set and an attempt to open a redirection file yields the |
| 15549 | \\ENOTDIR\\ error (something on the path is not a directory), the \%redirect%\ |
| 15550 | router behaves as if the file did not exist. |
| 15551 | |
| 15552 | Setting \ignore@_enotdir\ has another effect as well: When a \%redirect%\ |
| 15553 | router that has the \file\ option set discovers that the file does not exist |
| 15554 | (the \\ENOENT\\ error), it tries to \*stat()*\ the parent directory, as a check |
| 15555 | against unmounted NFS directories. If the parent can not be statted, delivery |
| 15556 | is deferred. However, it seems wrong to do this check when \ignore@_enotdir\ is |
| 15557 | set, because that option tells Exim to ignore `something on the path is not a |
| 15558 | directory' (the \\ENOTDIR\\ error). This is a confusing area, because it seems |
| 15559 | that some operating systems give \\ENOENT\\ where others give \\ENOTDIR\\. |
| 15560 | |
| 15561 | |
| 15562 | .conf include@_directory string unset |
| 15563 | If this option is set, the path names of any :::include:: items in a redirection |
| 15564 | list must start with this directory. |
| 15565 | |
| 15566 | .conf modemask "octal integer" 022 |
| 15567 | This specifies mode bits which must not be set for a file specified by the |
| 15568 | \file\ option. If any of the forbidden bits are set, delivery is deferred. |
| 15569 | |
| 15570 | .conf one@_time boolean false |
| 15571 | .index one-time aliasing/forwarding expansion |
| 15572 | .index alias file||one-time expansion |
| 15573 | .index forward file||one-time expansion |
| 15574 | .index mailing lists||one-time expansion |
| 15575 | .index address redirection||one-time expansion |
| 15576 | Sometimes the fact that Exim re-evaluates aliases and reprocesses redirection |
| 15577 | files each time it tries to deliver a message causes a problem |
| 15578 | when one or more of the generated addresses fails be delivered at the first |
| 15579 | attempt. The problem is not one of duplicate delivery -- Exim is clever enough |
| 15580 | to handle that -- but of what happens when the redirection list changes during |
| 15581 | the time that the message is on Exim's queue. This is particularly true in the |
| 15582 | case of mailing lists, where new subscribers might receive copies of messages |
| 15583 | that were posted before they subscribed. |
| 15584 | |
| 15585 | If \one@_time\ is set and any addresses generated by the router fail to |
| 15586 | deliver at the first attempt, the failing addresses are added to the message as |
| 15587 | `top level' addresses, and the parent address that generated them is marked |
| 15588 | `delivered'. Thus, redirection does not happen again at the next |
| 15589 | delivery attempt. |
| 15590 | |
| 15591 | \**Warning 1**\: This means that any header line addition or removal that is |
| 15592 | specified by this router would be lost if delivery did not succeed at the |
| 15593 | first attempt. For this reason, the \headers@_add\ and \headers@_remove\ |
| 15594 | generic options are not permitted when \one@_time\ is set. |
| 15595 | |
| 15596 | \**Warning 2**\: To ensure that the router generates only addresses (as opposed |
| 15597 | to pipe or file deliveries or auto-replies) \forbid@_file\, \forbid@_pipe\, |
| 15598 | and \forbid@_filter@_reply\ are forced to be true when \one@_time\ is set. |
| 15599 | |
| 15600 | The original top-level address is remembered with each of the generated |
| 15601 | addresses, and is output in any log messages. However, any intermediate parent |
| 15602 | addresses are not recorded. This makes a difference to the log only if |
| 15603 | \all__parents\ log selector is set. It is expected that \one@_time\ will |
| 15604 | typically be used for mailing lists, where there is normally just one level of |
| 15605 | expansion. |
| 15606 | |
| 15607 | .conf owners "string list" unset |
| 15608 | .index ownership||alias file |
| 15609 | .index ownership||forward file |
| 15610 | .index alias file||ownership |
| 15611 | .index forward file||ownership |
| 15612 | This specifies a list of permitted owners for the file specified by \file\. |
| 15613 | This list is in addition to the local user when \check@_local@_user\ is set. |
| 15614 | See \check@_owner\ above. |
| 15615 | |
| 15616 | .conf owngroups "string list" unset |
| 15617 | This specifies a list of permitted groups for the file specified by \file\. The |
| 15618 | list is in addition to the local user's primary group when \check@_local@_user\ |
| 15619 | is set. See \check@_group\ above. |
| 15620 | |
| 15621 | .conf qualify@_domain string$**$ unset |
| 15622 | If this option is set and an unqualified address (one without a domain) is |
| 15623 | generated, it is qualified with the domain specified by expanding this string, |
| 15624 | instead of the global setting in \qualify@_recipient\. If the expansion fails, |
| 15625 | the router declines. If you want to revert to the default, you can have the |
| 15626 | expansion generate \$qualify@_recipient$\. |
| 15627 | |
| 15628 | .conf pipe@_transport string$**$ unset |
| 15629 | A \%redirect%\ router sets up a direct delivery to a pipe when a string starting |
| 15630 | with a vertical bar character is specified as a new `address'. The transport |
| 15631 | used is specified by this option, which, after expansion, must be the name of a |
| 15632 | configured transport. |
| 15633 | This should normally be a \%pipe%\ transport. |
| 15634 | When the transport is run, the pipe command is in \$address@_pipe$\. |
| 15635 | |
| 15636 | .conf qualify@_preserve@_domain boolean false |
| 15637 | .index domain||in redirection, preserving |
| 15638 | .index preserving domain in redirection |
| 15639 | .index address redirection||domain, preserving |
| 15640 | If this is set and an unqualified address (one without a domain) is generated, |
| 15641 | it is qualified with the domain of the |
| 15642 | parent address (the immediately preceding ancestor) instead of the local |
| 15643 | \qualify@_domain\ or global \qualify@_recipient\ value. |
| 15644 | |
| 15645 | .conf repeat@_use boolean true |
| 15646 | If this option is set false, the router is skipped for a child address that has |
| 15647 | any ancestor that was routed by this router. This test happens before any of |
| 15648 | the other preconditions are tested. Exim's default anti-looping rules skip |
| 15649 | only when the ancestor is the same as the current address. See also |
| 15650 | \check@_ancestor\ above and the generic \redirect@_router\ option. |
| 15651 | |
| 15652 | .conf reply@_transport string$**$ unset |
| 15653 | A \%redirect%\ router sets up an automatic reply when a \mail\ or \vacation\ |
| 15654 | command is used in a filter file. The transport used is specified by this |
| 15655 | option, which, after expansion, must be the name of a configured transport. |
| 15656 | This should normally be an \%autoreply%\ transport. Other transports are |
| 15657 | unlikely to do anything sensible or useful. |
| 15658 | |
| 15659 | .conf rewrite boolean true |
| 15660 | .index address redirection||disabling rewriting |
| 15661 | If this option is set false, addresses generated by the router are not |
| 15662 | subject to address rewriting. Otherwise, they are treated like new addresses |
| 15663 | and are rewritten according to the global rewriting rules. |
| 15664 | |
| 15665 | .conf skip@_syntax@_errors boolean false |
| 15666 | .index forward file||broken |
| 15667 | .index address redirection||broken files |
| 15668 | .index alias file||broken |
| 15669 | .index broken alias or forward files |
| 15670 | .index ignoring faulty addresses |
| 15671 | .index skipping faulty addresses |
| 15672 | .index error||skipping bad syntax |
| 15673 | If \skip@_syntax@_errors\ is set, syntactically malformed addresses in |
| 15674 | non-filter redirection data are skipped, and each failing address is logged. If |
| 15675 | \syntax@_errors@_to\ is set, a message is sent to the address it defines, |
| 15676 | giving details of the failures. If \syntax@_errors@_text\ is set, its contents |
| 15677 | are expanded and placed at the head of the error message generated by |
| 15678 | \syntax@_errors@_to\. Usually it is appropriate to set \syntax@_errors@_to\ to |
| 15679 | be the same address as the generic \errors@_to\ option. The |
| 15680 | \skip@_syntax@_errors\ option is often used when handling mailing lists. |
| 15681 | |
| 15682 | If all the addresses in a redirection list are skipped because of syntax |
| 15683 | errors, the router declines to handle the original address, and it is passed to |
| 15684 | the following routers. |
| 15685 | |
| 15686 | If \skip@_syntax@_errors\ is set when an Exim filter is interpreted, any syntax |
| 15687 | error in the filter causes filtering to be abandoned without any action being |
| 15688 | taken. The incident is logged, and the router declines to handle the address, |
| 15689 | so it is passed to the following routers. |
| 15690 | |
| 15691 | .index Sieve filter||syntax errors in |
| 15692 | Currently, any syntax errors in a Sieve filter file cause the `keep' action to |
| 15693 | occur. The values of \skip@_syntax@_errors\, \syntax@_errors@_to\, and |
| 15694 | \syntax@_errors@_text\ are not used. |
| 15695 | |
| 15696 | \skip@_syntax@_errors\ can be used to specify that errors in users' forward |
| 15697 | lists or filter files should not prevent delivery. The \syntax@_errors@_to\ |
| 15698 | option, used with an address that does not get redirected, can be used to |
| 15699 | notify users of these errors, by means of a router like this: |
| 15700 | .display flow asis |
| 15701 | userforward: |
| 15702 | driver = redirect |
| 15703 | allow_filter |
| 15704 | check_local_user |
| 15705 | file = $home/.forward |
| 15706 | file_transport = address_file |
| 15707 | pipe_transport = address_pipe |
| 15708 | reply_transport = address_reply |
| 15709 | no_verify |
| 15710 | skip_syntax_errors |
| 15711 | syntax_errors_to = real-$local_part@$domain |
| 15712 | syntax_errors_text = \ |
| 15713 | This is an automatically generated message. An error has\n\ |
| 15714 | been found in your .forward file. Details of the error are\n\ |
| 15715 | reported below. While this error persists, you will receive\n\ |
| 15716 | a copy of this message for every message that is addressed\n\ |
| 15717 | to you. If your .forward file is a filter file, or if it is\n\ |
| 15718 | a non-filter file containing no valid forwarding addresses,\n\ |
| 15719 | a copy of each incoming message will be put in your normal\n\ |
| 15720 | mailbox. If a non-filter file contains at least one valid\n\ |
| 15721 | forwarding address, forwarding to the valid addresses will\n\ |
| 15722 | happen, and those will be the only deliveries that occur. |
| 15723 | .endd |
| 15724 | You also need a router to ensure that local addresses that are prefixed by |
| 15725 | \"real-"\ are recognized, but not forwarded or filtered. For example, you could |
| 15726 | put this immediately before the \%userforward%\ router: |
| 15727 | .display asis |
| 15728 | real_localuser: |
| 15729 | driver = accept |
| 15730 | check_local_user |
| 15731 | local_part_prefix = real- |
| 15732 | transport = local_delivery |
| 15733 | .endd |
| 15734 | |
| 15735 | .conf syntax@_errors@_text string$**$ unset |
| 15736 | See \skip@_syntax@_errors\ above. |
| 15737 | |
| 15738 | .conf syntax@_errors@_to string unset |
| 15739 | See \skip@_syntax@_errors\ above. |
| 15740 | |
| 15741 | .endconf |
| 15742 | |
| 15743 | |
| 15744 | |
| 15745 | |
| 15746 | |
| 15747 | . |
| 15748 | . |
| 15749 | . |
| 15750 | . ============================================================================ |
| 15751 | .chapter Environment for running local transports |
| 15752 | .rset CHAPenvironment "~~chapter" |
| 15753 | .set runningfoot "local transport environment" |
| 15754 | .index local transports||environment for |
| 15755 | .index environment for local transports |
| 15756 | .index transport||local, environment for |
| 15757 | Local transports handle deliveries to files and pipes. (The \%autoreply%\ |
| 15758 | transport can be thought of as similar to a pipe.) Exim always runs transports |
| 15759 | in subprocesses, under specified uids and gids. Typical deliveries to local |
| 15760 | mailboxes run under the uid and gid of the local user. |
| 15761 | |
| 15762 | Exim also sets a specific current directory while running the transport; for |
| 15763 | some transports a home directory setting is also relevant. The \%pipe%\ |
| 15764 | transport is the only one which sets up environment variables; see section |
| 15765 | ~~SECTpipeenv for details. |
| 15766 | |
| 15767 | The values used for the uid, gid, and the directories may come from several |
| 15768 | different places. In many cases, the router that handles the address associates |
| 15769 | settings with that address as a result of its \check@_local@_user\, \group\, or |
| 15770 | \user\ options. However, values may also be given in the transport's own |
| 15771 | configuration, and these override anything that comes from the router. |
| 15772 | |
| 15773 | .section Uids and gids |
| 15774 | .rset SECTenvuidgid "~~chapter.~~section" |
| 15775 | .index local transports||uid and gid |
| 15776 | .index transport||local, uid and gid |
| 15777 | All transports have the options \group\ and \user\. If \group\ is set, it |
| 15778 | overrides any group that the router set in the address, even if \user\ is not |
| 15779 | set for the transport. This makes it possible, for example, to run local mail |
| 15780 | delivery under the uid of the recipient (set by the router), but in a special |
| 15781 | group (set by the transport). For example: |
| 15782 | .display asis |
| 15783 | # Routers ... |
| 15784 | # User/group are set by check_local_user in this router |
| 15785 | local_users: |
| 15786 | driver = accept |
| 15787 | check_local_user |
| 15788 | transport = group_delivery |
| 15789 | |
| 15790 | # Transports ... |
| 15791 | # This transport overrides the group |
| 15792 | group_delivery: |
| 15793 | driver = appendfile |
| 15794 | file = /var/spool/mail/$local_part |
| 15795 | group = mail |
| 15796 | .endd |
| 15797 | If \user\ is set for a transport, its value overrides what is set in the |
| 15798 | address. If \user\ is non-numeric and \group\ is not set, the gid associated |
| 15799 | with the user is used. If \user\ is numeric, \group\ must be set. |
| 15800 | |
| 15801 | .index \initgroups\ option |
| 15802 | When the uid is taken from the transport's configuration, the \*initgroups()*\ |
| 15803 | function is called for the groups associated with that uid if the \initgroups\ |
| 15804 | option is set for the transport. When the uid is not specified by the |
| 15805 | transport, but is associated with the address by a router, the option for |
| 15806 | calling \*initgroups()*\ is taken from the router configuration. |
| 15807 | |
| 15808 | .index \%pipe%\ transport||uid for |
| 15809 | The \%pipe%\ transport contains the special option \pipe@_as@_creator\. If this |
| 15810 | is set and \user\ is not set, the uid of the process that called Exim to |
| 15811 | receive the message is used, and if \group\ is not set, the corresponding |
| 15812 | original gid is also used. |
| 15813 | |
| 15814 | |
| 15815 | .section Current and home directories |
| 15816 | .index current directory for local transport |
| 15817 | .index home directory||for local transport |
| 15818 | .index transport||local, home directory for |
| 15819 | .index transport||local, current directory for |
| 15820 | Routers may set current and home directories for local transports by means of |
| 15821 | the \transport__current@_directory\ and \transport@_home@_directory\ options. |
| 15822 | However, if the transport's \current__directory\ or \home@_directory\ options |
| 15823 | are set, they override the router's values. In detail, the home directory |
| 15824 | for a local transport is taken from the first of these values that is set: |
| 15825 | .numberpars $. |
| 15826 | The \home@_directory\ option on the transport; |
| 15827 | .nextp |
| 15828 | The \transport@_home@_directory\ option on the router; |
| 15829 | .nextp |
| 15830 | The password data if \check@_local@_user\ is set on the router; |
| 15831 | .nextp |
| 15832 | The \router@_home@_directory\ option on the router. |
| 15833 | .endp |
| 15834 | The current directory is taken from the first of these values that is set: |
| 15835 | .numberpars $. |
| 15836 | The \current@_directory\ option on the transport; |
| 15837 | .nextp |
| 15838 | The \transport@_current@_directory\ option on the router. |
| 15839 | .endp |
| 15840 | |
| 15841 | If neither the router nor the transport sets a current directory, Exim uses the |
| 15842 | value of the home directory, if it is set. Otherwise it sets the current |
| 15843 | directory to \(/)\ before running a local transport. |
| 15844 | |
| 15845 | |
| 15846 | .section Expansion variables derived from the address |
| 15847 | Normally a local delivery is handling a single address, and in that case the |
| 15848 | variables such as \$domain$\ and \$local@_part$\ are set during local |
| 15849 | deliveries. However, in some circumstances more than one address may be handled |
| 15850 | at once (for example, while writing batch SMTP for onward transmission by some |
| 15851 | other means). In this case, the variables associated with the local part are |
| 15852 | never set, \$domain$\ is set only if all the addresses have the same |
| 15853 | domain, and \$original@_domain$\ is never set. |
| 15854 | |
| 15855 | |
| 15856 | |
| 15857 | |
| 15858 | |
| 15859 | |
| 15860 | |
| 15861 | . |
| 15862 | . |
| 15863 | . |
| 15864 | . ============================================================================ |
| 15865 | .chapter Generic options for transports |
| 15866 | .rset CHAPtransportgeneric "~~chapter" |
| 15867 | .set runningfoot "generic transport options" |
| 15868 | |
| 15869 | .index generic options||transport |
| 15870 | .index options||generic, for transports |
| 15871 | .index transport||generic options for |
| 15872 | The following generic options apply to all transports: |
| 15873 | |
| 15874 | .startconf |
| 15875 | .conf body@_only boolean false |
| 15876 | .index transport||body only |
| 15877 | .index message||transporting body only |
| 15878 | .index body of message||transporting |
| 15879 | If this option is set, the message's headers are not transported. It is |
| 15880 | mutually exclusive with \headers@_only\. If it is used with the \%appendfile%\ or |
| 15881 | \%pipe%\ transports, the settings of \message@_prefix\ and \message@_suffix\ |
| 15882 | should be checked, because this option does not automatically suppress them. |
| 15883 | |
| 15884 | .conf current@_directory string$**$ unset |
| 15885 | .index transport||current directory for |
| 15886 | This specifies the current directory that is to be set while running the |
| 15887 | transport, overriding any value that may have been set by the router. |
| 15888 | If the expansion fails for any reason, including forced failure, an error is |
| 15889 | logged, and delivery is deferred. |
| 15890 | |
| 15891 | .conf disable@_logging boolean false |
| 15892 | If this option is set true, nothing is logged for any |
| 15893 | deliveries by the transport or for any |
| 15894 | transport errors. You should not set this option unless you really, really know |
| 15895 | what you are doing. |
| 15896 | |
| 15897 | .conf debug@_print string$**$ unset |
| 15898 | .index testing||variables in drivers |
| 15899 | If this option is set and debugging is enabled (see the \-d-\ command line |
| 15900 | option), the string is expanded and included in the debugging output when the |
| 15901 | transport is run. |
| 15902 | If expansion of the string fails, the error message is written to the debugging |
| 15903 | output, and Exim carries on processing. |
| 15904 | This facility is provided to help with checking out the values of variables and |
| 15905 | so on when debugging driver configurations. For example, if a \headers@_add\ |
| 15906 | option is not working properly, \debug@_print\ could be used to output the |
| 15907 | variables it references. A newline is added to the text if it does not end with |
| 15908 | one. |
| 15909 | |
| 15910 | .conf delivery@_date@_add boolean false |
| 15911 | .index ::Delivery-date:: header line |
| 15912 | If this option is true, a ::Delivery-date:: header is added to the message. This |
| 15913 | gives the actual time the delivery was made. As this is not a standard header, |
| 15914 | Exim has a configuration option (\delivery@_date@_remove\) which requests its |
| 15915 | removal from incoming messages, so that delivered messages can safely be resent |
| 15916 | to other recipients. |
| 15917 | |
| 15918 | .conf driver string unset |
| 15919 | This specifies which of the available transport drivers is to be used. |
| 15920 | There is no default, and this option must be set for every transport. |
| 15921 | |
| 15922 | .conf envelope@_to@_add boolean false |
| 15923 | .index ::Envelope-to:: header line |
| 15924 | If this option is true, an ::Envelope-to:: header is added to the message. This |
| 15925 | gives the original address(es) in the incoming envelope that caused this |
| 15926 | delivery to happen. More than one address may be present if the transport is |
| 15927 | configured to handle several addresses at once, or if more than one original |
| 15928 | address was redirected to the same final address. As this is not a standard |
| 15929 | header, Exim has a configuration option (\envelope@_to@_remove\) which requests |
| 15930 | its removal from incoming messages, so that delivered messages can safely be |
| 15931 | resent to other recipients. |
| 15932 | |
| 15933 | .conf group string$**$ "Exim group" |
| 15934 | .index transport||group, specifying |
| 15935 | This option specifies a gid for running the transport process, overriding any |
| 15936 | value that the router supplies, and also overriding any value associated with |
| 15937 | \user\ (see below). |
| 15938 | |
| 15939 | .conf headers@_add string$**$ unset |
| 15940 | .index header lines||adding in transport |
| 15941 | .index transport||header lines, adding |
| 15942 | This option specifies a string of text which is expanded and added to the |
| 15943 | header portion of a message as it is transported. If the result of the |
| 15944 | expansion is an empty string, or if the expansion is forced to fail, no action |
| 15945 | is taken. Other expansion failures are treated as errors and cause the delivery |
| 15946 | to be deferred. The expanded string should be in the form of one or more RFC |
| 15947 | 2822 header lines, separated by newlines (coded as `@\n'), for example: |
| 15948 | .display asis |
| 15949 | headers_add = X-added: this is a header added at $tod_log\n\ |
| 15950 | X-added: this is another |
| 15951 | .endd |
| 15952 | Exim does not check the syntax of these added header lines. They are added at |
| 15953 | the end of the existing header lines. If you include a blank line within the |
| 15954 | string, you can subvert this facility into adding text at the start of the |
| 15955 | message's body. This is not recommended. Additional header lines can also be |
| 15956 | specified by routers. See chapter ~~CHAProutergeneric and section |
| 15957 | ~~SECTheadersaddrem. |
| 15958 | |
| 15959 | .conf headers@_only boolean false |
| 15960 | .index transport||header lines only |
| 15961 | .index message||transporting headers only |
| 15962 | .index header lines||transporting |
| 15963 | If this option is set, the message's body is not transported. It is mutually |
| 15964 | exclusive with \body@_only\. If it is used with the \%appendfile%\ or \%pipe%\ |
| 15965 | transports, the settings of \message@_prefix\ and \message__suffix\ should be |
| 15966 | checked, since this option does not automatically suppress them. |
| 15967 | |
| 15968 | .conf headers@_remove string$**$ unset |
| 15969 | .index header lines||removing |
| 15970 | .index transport||header lines, removing |
| 15971 | This option is expanded; the result must consist of a colon-separated list of |
| 15972 | header names, not including the terminating colon, for example: |
| 15973 | .display asis |
| 15974 | headers_remove = return-receipt-to:acknowledge-to |
| 15975 | .endd |
| 15976 | Any existing headers matching those names are not included in any message that |
| 15977 | is transmitted by the transport. |
| 15978 | If the result of the expansion is an empty string, or if the expansion is |
| 15979 | forced to fail, no action is taken. Other expansion failures are treated as |
| 15980 | errors and cause the delivery to be deferred. |
| 15981 | |
| 15982 | If there are multiple instances of a header, they are all removed. However, |
| 15983 | added headers may have these names. Thus it is possible to replace a header by |
| 15984 | specifying it in \headers@_remove\ and supplying the replacement in |
| 15985 | \headers@_add\. Headers to be removed can also be specified by routers. See |
| 15986 | chapter ~~CHAProutergeneric and section ~~SECTheadersaddrem. |
| 15987 | |
| 15988 | .conf headers@_rewrite string unset |
| 15989 | .index transport||header lines, rewriting |
| 15990 | .index rewriting||at transport time |
| 15991 | This option allows addresses in header lines to be rewritten at transport time, |
| 15992 | that is, as the message is being copied to its destination. The contents of the |
| 15993 | option are a colon-separated list of rewriting rules. Each rule is in exactly |
| 15994 | the same form as one of the general rewriting rules that are applied when a |
| 15995 | message is received. These are described in chapter ~~CHAPrewrite. For example, |
| 15996 | .display asis |
| 15997 | headers_rewrite = a@b c@d f : \ |
| 15998 | x@y w@z |
| 15999 | .endd |
| 16000 | changes \a@@b\ into \c@@d\ in ::From:: header lines, and \x@@y\ into \w@@z\ in |
| 16001 | all address-bearing header lines. The rules are applied to the header lines |
| 16002 | just before they are written out at transport time, so they affect only those |
| 16003 | copies of the message that pass through the transport. However, only the |
| 16004 | message's original header lines, and any that were added by a system filter, |
| 16005 | are rewritten. If a router or transport adds header lines, they are |
| 16006 | not affected by this option. These rewriting rules are $it{not} applied to the |
| 16007 | envelope. You can change the return path using \return@_path\, but you cannot |
| 16008 | change envelope recipients at this time. |
| 16009 | |
| 16010 | .conf home@_directory string$**$ unset |
| 16011 | .index transport||home directory for |
| 16012 | This option specifies a home directory setting for the transport, overriding |
| 16013 | any value that may be set by the router. The home directory is placed in |
| 16014 | \$home$\ while expanding the transport's private options. It is also used as |
| 16015 | the current directory if no current directory is set by the |
| 16016 | \current__directory\ option on the transport or the |
| 16017 | \transport__current__directory\ option on the router. |
| 16018 | If the expansion fails for any reason, including forced failure, an error is |
| 16019 | logged, and delivery is deferred. |
| 16020 | |
| 16021 | |
| 16022 | .index additional groups |
| 16023 | .index groups, additional |
| 16024 | .index transport||group, additional |
| 16025 | .conf initgroups boolean false |
| 16026 | If this option is true and the uid for the delivery process is provided by the |
| 16027 | transport, the \*initgroups()*\ function is called when running the transport |
| 16028 | to ensure that any additional groups associated with the uid are set up. |
| 16029 | |
| 16030 | .conf message@_size@_limit string$**$ 0 |
| 16031 | .index limit||message size per transport |
| 16032 | .index size||of message, limit |
| 16033 | .index transport||message size, limiting |
| 16034 | This option controls the size of messages passed through the transport. It is |
| 16035 | expanded before use; the result of the expansion must be a sequence of digits, |
| 16036 | optionally followed by K or M. |
| 16037 | If the expansion fails for any reason, including forced failure, or if the |
| 16038 | result is not of the required form, delivery is deferred. |
| 16039 | If the value is greater than zero and the size of a message exceeds this |
| 16040 | limit, the address is failed. If there is any chance that the resulting bounce |
| 16041 | message could be routed to the same transport, you should ensure that |
| 16042 | \return@_size@_limit\ is less than the transport's \message@_size@_limit\, as |
| 16043 | otherwise the bounce message will fail to get delivered. |
| 16044 | |
| 16045 | |
| 16046 | .conf rcpt@_include@_affixes boolean false |
| 16047 | .index prefix||for local part, including in envelope |
| 16048 | .index suffix||for local part, including in envelope |
| 16049 | .index local part||prefix |
| 16050 | .index local part||suffix |
| 16051 | When this option is false (the default), and an address that has had any |
| 16052 | affixes (prefixes or suffixes) removed from the local part is delivered by any |
| 16053 | form of SMTP or LMTP, the affixes are not included. For example, if a router |
| 16054 | that contains |
| 16055 | .display asis |
| 16056 | local_part_prefix = *- |
| 16057 | .endd |
| 16058 | routes the address \*abc-xyz@@some.domain*\ to an SMTP transport, the envelope |
| 16059 | is delivered with |
| 16060 | .display asis |
| 16061 | RCPT TO:<xyz@some.domain> |
| 16062 | .endd |
| 16063 | If \rcpt@_include@_affixes\ is set true, the whole local part is included in |
| 16064 | the \\RCPT\\ command. This option applies to BSMTP deliveries by the |
| 16065 | \%appendfile%\ and \%pipe%\ transports as well as to the \%lmtp%\ and \%smtp%\ |
| 16066 | transports. |
| 16067 | |
| 16068 | .conf retry@_use@_local@_part boolean "see below" |
| 16069 | .index hints database||retry keys |
| 16070 | When a delivery suffers a temporary failure, a retry record is created |
| 16071 | in Exim's hints database. For remote deliveries, the key for the retry record |
| 16072 | is based on the name and/or IP address of the failing remote host. For local |
| 16073 | deliveries, the key is normally the entire address, including both the local |
| 16074 | part and the domain. This is suitable for most common cases of local delivery |
| 16075 | temporary failure -- for example, exceeding a mailbox quota should delay only |
| 16076 | deliveries to that mailbox, not to the whole domain. |
| 16077 | |
| 16078 | However, in some special cases you may want to treat a temporary local delivery |
| 16079 | as a failure associated with the domain, and not with a particular local part. |
| 16080 | (For example, if you are storing all mail for some domain in files.) You can do |
| 16081 | this by setting \retry@_use@_local@_part\ false. |
| 16082 | |
| 16083 | For all the local transports, its default value is true. For remote transports, |
| 16084 | the default value is false for tidiness, but changing the value has no effect |
| 16085 | on a remote transport in the current implementation. |
| 16086 | |
| 16087 | .conf return@_path string$**$ unset |
| 16088 | .index envelope sender |
| 16089 | .index transport||return path, changing |
| 16090 | .index return path||changing in transport |
| 16091 | If this option is set, the string is expanded at transport time and replaces |
| 16092 | the existing return path (envelope sender) value in the copy of the message |
| 16093 | that is being delivered. An empty return path is permitted. This feature is |
| 16094 | designed for remote deliveries, where the value of this option is used in the |
| 16095 | SMTP \\MAIL\\ command. If you set \return@_path\ for a local transport, the |
| 16096 | only effect is to change the address that is placed in the ::Return-path:: |
| 16097 | header line, if one is added to the message (see the next option). |
| 16098 | |
| 16099 | The expansion can refer to the existing value via \$return@_path$\. This is |
| 16100 | either the message's envelope sender, or an address set by the |
| 16101 | \errors@_to\ option on a router. If the expansion is forced to fail, no |
| 16102 | replacement occurs; if it fails for another reason, delivery is deferred. This |
| 16103 | option can be used to support VERP (Variable Envelope Return Paths) -- see |
| 16104 | chapter ~~CHAPSMTP. |
| 16105 | |
| 16106 | \**Note**\: If a delivery error is detected locally, |
| 16107 | including the case when a remote server rejects a message at SMTP time, |
| 16108 | the bounce message is not sent to the value of this option, but to the |
| 16109 | previously set errors address (which defaults to the incoming sender address). |
| 16110 | |
| 16111 | |
| 16112 | .conf return@_path@_add boolean false |
| 16113 | .index ::Return-path:: header line |
| 16114 | If this option is true, a ::Return-path:: header is added to the message. |
| 16115 | Although the return path is normally available in the prefix line of BSD |
| 16116 | mailboxes, this is commonly not displayed by MUAs, and so the user does not |
| 16117 | have easy access to it. |
| 16118 | |
| 16119 | RFC 2821 states that the ::Return-path:: header is added to a message `when the |
| 16120 | delivery SMTP server makes the final delivery'. This implies that this header |
| 16121 | should not be present in incoming messages. Exim has a configuration option, |
| 16122 | \return@_path@_remove\, which requests removal of this header from incoming |
| 16123 | messages, so that delivered messages can safely be resent to other recipients. |
| 16124 | |
| 16125 | .conf shadow@_condition string$**$ unset |
| 16126 | See \shadow@_transport\ below. |
| 16127 | |
| 16128 | .conf shadow@_transport string unset |
| 16129 | .index shadow transport |
| 16130 | .index transport||shadow |
| 16131 | A local transport may set the \shadow@_transport\ option to the name of another |
| 16132 | local transport. Shadow remote transports are not supported. |
| 16133 | |
| 16134 | Whenever a delivery to the main transport succeeds, and either |
| 16135 | \shadow@_condition\ is unset, or its expansion does not result in the empty |
| 16136 | string or one of the strings `0' or `no' or `false', the message is also passed |
| 16137 | to the shadow transport, with the same delivery address or addresses. |
| 16138 | If expansion fails, no action is taken except that non-forced expansion |
| 16139 | failures cause a log line to be written. |
| 16140 | |
| 16141 | The result of the shadow transport is discarded and does not affect the |
| 16142 | subsequent processing of the message. Only a single level of shadowing is |
| 16143 | provided; the \shadow@_transport\ option is ignored on any transport when it is |
| 16144 | running as a shadow. Options concerned with output from pipes are also ignored. |
| 16145 | |
| 16146 | The log line for the successful delivery has an item added on the end, of the |
| 16147 | form |
| 16148 | .display |
| 16149 | ST=<<shadow transport name>> |
| 16150 | .endd |
| 16151 | If the shadow transport did not succeed, the error message is put in |
| 16152 | parentheses afterwards. |
| 16153 | |
| 16154 | Shadow transports can be used for a number of different purposes, including |
| 16155 | keeping more detailed log information than Exim normally provides, and |
| 16156 | implementing automatic acknowledgement policies based on message headers that |
| 16157 | some sites insist on. |
| 16158 | |
| 16159 | .conf transport@_filter string$**$ unset |
| 16160 | .index transport||filter |
| 16161 | .index filter||transport filter |
| 16162 | This option sets up a filtering (in the Unix shell sense) process for messages |
| 16163 | at transport time. It should not be confused with mail filtering as set up by |
| 16164 | individual users or via a system filter. |
| 16165 | |
| 16166 | When the message is about to be written out, the command specified by |
| 16167 | \transport@_filter\ is started up in a separate process, and the entire |
| 16168 | message, including the header lines, is passed to it on its standard input |
| 16169 | (this in fact is done from a third process, to avoid deadlock). |
| 16170 | The command must be specified as an absolute path. |
| 16171 | |
| 16172 | The message is passed to the filter before any SMTP-specific processing, such |
| 16173 | as turning `@\n' into `@\r@\n' and escaping lines beginning with a dot, and |
| 16174 | also before any processing implied by the settings of \check@_string\ and |
| 16175 | \escape@_string\ in the \%appendfile%\ or \%pipe%\ transports. |
| 16176 | |
| 16177 | The filter's standard output is read and written to the message's destination. |
| 16178 | The filter can perform any transformations it likes, but of course should take |
| 16179 | care not to break RFC 2822 syntax. A demonstration Perl script is provided in |
| 16180 | \(util/transport-filter.pl)\; this makes a few arbitrary modifications just to |
| 16181 | show the possibilities. Exim does not check the result, except to test for a |
| 16182 | final newline when SMTP is in use. All messages transmitted over SMTP must end |
| 16183 | with a newline, so Exim supplies one if it is missing. |
| 16184 | |
| 16185 | .index SMTP||\\SIZE\\ |
| 16186 | A problem might arise if the filter increases the size of a message that is |
| 16187 | being sent down an SMTP connection. If the receiving SMTP server has indicated |
| 16188 | support for the \\SIZE\\ parameter, Exim will have sent the size of the message |
| 16189 | at the start of the SMTP session. If what is actually sent is substantially |
| 16190 | more, the server might reject the message. This can be worked round by setting |
| 16191 | the \size@_addition\ option on the \%smtp%\ transport, either to allow for |
| 16192 | additions to the message, or to disable the use of \\SIZE\\ altogether. |
| 16193 | |
| 16194 | The value of the option is the command string for starting up the filter, which |
| 16195 | is run directly from Exim, not under a shell. The string is parsed by Exim in |
| 16196 | the same way as a command string for the \%pipe%\ transport: Exim breaks it up |
| 16197 | into arguments and then expands each argument separately. The special argument |
| 16198 | \$pipe@_addresses$\ is replaced by a number of arguments, one for each address |
| 16199 | that applies to this delivery. (This isn't an ideal name for this feature here, |
| 16200 | but as it was already implemented for the \%pipe%\ transport, it seemed sensible |
| 16201 | not to change it.) |
| 16202 | |
| 16203 | .index \$host$\ |
| 16204 | .index \$host@_address$\ |
| 16205 | The expansion variables \$host$\ and \$host@_address$\ are available when the |
| 16206 | transport is a remote one. They contain the name and IP address of the host to |
| 16207 | which the message is being sent. For example: |
| 16208 | .display asis |
| 16209 | transport_filter = /some/directory/transport-filter.pl \ |
| 16210 | $host $host_address $sender_address $pipe_addresses |
| 16211 | .endd |
| 16212 | The filter process is run under the same uid and gid as the normal delivery. |
| 16213 | For remote deliveries this is the Exim uid/gid by default. |
| 16214 | |
| 16215 | If a transport filter is set on an autoreply transport, the original message is |
| 16216 | passed through the filter as it is being copied into the newly generated |
| 16217 | message, which happens if the \return@_message\ option is set. |
| 16218 | |
| 16219 | .conf transport@_filter@_timeout time 5m |
| 16220 | .index transport||filter, timeout |
| 16221 | When Exim is reading the output of a transport filter, it a applies a timeout |
| 16222 | that can be set by this option. Exceeding the timeout is treated as a |
| 16223 | temporary delivery failure. |
| 16224 | |
| 16225 | |
| 16226 | .conf user string$**$ "Exim user" |
| 16227 | .index uid (user id)||local delivery |
| 16228 | .index transport||user, specifying |
| 16229 | This option specifies the user under whose uid the delivery process is to be |
| 16230 | run, overriding any uid that may have been set by the router. If the user is |
| 16231 | given as a name, the uid is looked up from the password data, and the |
| 16232 | associated group is taken as the value of the gid to be used if the \group\ |
| 16233 | option is not set. |
| 16234 | |
| 16235 | For deliveries that use local transports, a user and group are normally |
| 16236 | specified explicitly or implicitly (for example, as a result of |
| 16237 | \check@_local@_user\) by the router or transport. |
| 16238 | |
| 16239 | .index hints database||access by remote transport |
| 16240 | For remote transports, you should leave this option unset unless you really are |
| 16241 | sure you know what you are doing. When a remote transport is running, it needs |
| 16242 | to be able to access Exim's hints databases, because each host may have its own |
| 16243 | retry data. |
| 16244 | |
| 16245 | .endconf |
| 16246 | |
| 16247 | |
| 16248 | |
| 16249 | |
| 16250 | |
| 16251 | . |
| 16252 | . |
| 16253 | . |
| 16254 | . ============================================================================ |
| 16255 | .chapter Address batching in local transports |
| 16256 | .set runningfoot "address batching" |
| 16257 | .rset CHAPbatching ~~chapter |
| 16258 | .index transport||local, address batching in |
| 16259 | The only remote transport (\%smtp%\) is normally configured to handle more than |
| 16260 | one address at a time, so that when several addresses are routed to the same |
| 16261 | remote host, just one copy of the message is sent. Local transports, however, |
| 16262 | normally handle one address at a time. That is, a separate instance of the |
| 16263 | transport is run for each address that is routed to the transport. A separate |
| 16264 | copy of the message is delivered each time. |
| 16265 | |
| 16266 | .index batched local delivery |
| 16267 | .index \batch@_max\ |
| 16268 | .index \batch@_id\ |
| 16269 | In special cases, it may be desirable to handle several addresses at once in a |
| 16270 | local transport, for example: |
| 16271 | .numberpars $. |
| 16272 | In an \%appendfile%\ transport, when storing messages in files for later |
| 16273 | delivery by some other means, a single copy of the message with multiple |
| 16274 | recipients saves space. |
| 16275 | .nextp |
| 16276 | In an \%lmtp%\ transport, when delivering over `local SMTP' to some process, |
| 16277 | a single copy saves time, and is the normal way LMTP is expected to work. |
| 16278 | .nextp |
| 16279 | In a \%pipe%\ transport, when passing the message |
| 16280 | to a scanner program or |
| 16281 | to some other delivery mechanism such as UUCP, multiple recipients may be |
| 16282 | acceptable. |
| 16283 | .endp |
| 16284 | The three local transports (\%appendfile%\, \%lmtp%\, and \%pipe%\) all have |
| 16285 | the same options for controlling multiple (`batched') deliveries, namely |
| 16286 | \batch@_max\ and \batch@_id\. To save repeating the information for each |
| 16287 | transport, these options are described here. |
| 16288 | |
| 16289 | The \batch@_max\ option specifies the maximum number of addresses that can be |
| 16290 | delivered together in a single run of the transport. Its default value is one. |
| 16291 | When more than one address is routed to a transport that has a \batch@_max\ |
| 16292 | value greater than one, the addresses are delivered in a batch (that is, in a |
| 16293 | single run of the transport), subject to certain conditions: |
| 16294 | .numberpars $. |
| 16295 | If any of the transport's options contain a reference to \$local@_part$\, no |
| 16296 | batching is possible. |
| 16297 | .nextp |
| 16298 | If any of the transport's options contain a reference to \$domain$\, only |
| 16299 | addresses with the same domain are batched. |
| 16300 | .nextp |
| 16301 | .index customizing||batching condition |
| 16302 | If \batch@_id\ is set, it is expanded for each address, and only those |
| 16303 | addresses with the same expanded value are batched. This allows you to specify |
| 16304 | customized batching conditions. |
| 16305 | Failure of the expansion for any reason, including forced failure, disables |
| 16306 | batching, but it does not stop the delivery from taking place. |
| 16307 | .nextp |
| 16308 | Batched addresses must also have the same errors address (where to send |
| 16309 | delivery errors), the same header additions and removals, the same user and |
| 16310 | group for the transport, and if a host list is present, the first host must |
| 16311 | be the same. |
| 16312 | .endp |
| 16313 | .index ::Envelope-to:: header line |
| 16314 | If the generic \envelope@_to@_add\ option is set for the transport, the |
| 16315 | ::Envelope-to:: header that is added to the message contains all the addresses |
| 16316 | that are batched together. |
| 16317 | |
| 16318 | The \%appendfile%\ and \%pipe%\ transports have an option called \use@_bsmtp\, |
| 16319 | which causes them to deliver the message in `batched SMTP' format, with the |
| 16320 | envelope represented as SMTP commands. The \check@_string\ and \escape@_string\ |
| 16321 | options are forced to the values |
| 16322 | .display asis |
| 16323 | check_string = "." |
| 16324 | escape_string = ".." |
| 16325 | .endd |
| 16326 | when batched SMTP is in use. A full description of the batch SMTP mechanism is |
| 16327 | given in section ~~SECTbatchSMTP. The \%lmtp%\ transport does not have a |
| 16328 | \use@_bsmtp\ option, because it always delivers using the SMTP protocol. |
| 16329 | |
| 16330 | .index \%pipe%\ transport||with multiple addresses |
| 16331 | If you are not using BSMTP, but are using a \%pipe%\ transport, you can include |
| 16332 | \$pipe@_addresses$\ as part of the command. This is not a true variable; it is |
| 16333 | a bit of magic that causes each of the recipient addresses to be inserted into |
| 16334 | the command as a separate argument. This provides a way of accessing all the |
| 16335 | addresses that are being delivered in the batch. |
| 16336 | |
| 16337 | If you are using a batching \%appendfile%\ transport without \use@_bsmtp\, the |
| 16338 | only way to preserve the recipient addresses is to set the \envelope@_to@_add\ |
| 16339 | option. This causes an ::Envelope-to:: header line to be added to the message, |
| 16340 | containing all the recipients. |
| 16341 | |
| 16342 | |
| 16343 | |
| 16344 | . |
| 16345 | . |
| 16346 | . |
| 16347 | . ============================================================================ |
| 16348 | .chapter The appendfile transport |
| 16349 | .set runningfoot "appendfile transport" |
| 16350 | .rset CHAPappendfile ~~chapter |
| 16351 | .index \%appendfile%\ transport |
| 16352 | .index transports||\%appendfile%\ |
| 16353 | .index directory creation |
| 16354 | .index creating directories |
| 16355 | The \%appendfile%\ transport delivers a message by appending it to an existing |
| 16356 | file, or by creating an entirely new file in a specified directory. Single |
| 16357 | files to which messages are appended can be in the traditional Unix mailbox |
| 16358 | format, or optionally in the MBX format supported by the Pine MUA and |
| 16359 | University of Washington IMAP daemon, $it{inter alia}. When each message is |
| 16360 | being delivered as a separate file, `maildir' format can optionally be used to |
| 16361 | give added protection against failures that happen part-way through the |
| 16362 | delivery. A third form of separate-file delivery known as `mailstore' is also |
| 16363 | supported. For all file formats, Exim attempts to create as many levels of |
| 16364 | directory as necessary, provided that \create@_directory\ is set. |
| 16365 | |
| 16366 | The code for the optional formats is not included in the Exim binary by |
| 16367 | default. It is necessary to set \\SUPPORT@_MBX\\, \\SUPPORT@_MAILDIR\\ and/or |
| 16368 | \\SUPPORT@_MAILSTORE\\ in \(Local/Makefile)\ to have the appropriate code |
| 16369 | included. |
| 16370 | |
| 16371 | .index quota||system |
| 16372 | Exim recognises system quota errors, and generates an appropriate message. Exim |
| 16373 | also supports its own quota control within the transport, for use when the |
| 16374 | system facility is unavailable or cannot be used for some reason. |
| 16375 | |
| 16376 | If there is an error while appending to a file (for example, quota exceeded or |
| 16377 | partition filled), Exim attempts to reset the file's length and last |
| 16378 | modification time back to what they were before. If there is an error while |
| 16379 | creating an entirely new file, the new file is removed. |
| 16380 | |
| 16381 | Before appending to a file, a number of security checks are made, and the |
| 16382 | file is locked. A detailed description is given below, after the list of |
| 16383 | private options. |
| 16384 | |
| 16385 | \%appendfile%\ is most commonly used for local deliveries to users' mailboxes. |
| 16386 | However, it can also be used as a pseudo-remote transport for putting messages |
| 16387 | into files for remote delivery by some means other than Exim. `Batch SMTP' |
| 16388 | format is often used in this case (see the \use@_bsmtp\ option). |
| 16389 | |
| 16390 | |
| 16391 | .section The file and directory options |
| 16392 | .rset SECTfildiropt "~~chapter.~~section" |
| 16393 | The \file\ option specifies a single file, to which the message is appended; |
| 16394 | the \directory\ option specifies a directory, in which a new file containing |
| 16395 | the message is created. Only one of these two options can be set, and for |
| 16396 | normal deliveries to mailboxes, one of them \*must*\ be set. |
| 16397 | |
| 16398 | However, \%appendfile%\ is also used for delivering messages to files or |
| 16399 | directories whose names (or parts of names) are obtained from alias, |
| 16400 | forwarding, or filtering operations (for example, a \save\ command in a user's |
| 16401 | Exim filter). When such a transport is running, \$local@_part$\ contains the |
| 16402 | local part that was aliased or forwarded, and \$address@_file$\ contains the |
| 16403 | name (or partial name) of the file or directory generated by the redirection |
| 16404 | operation. There are two cases: |
| 16405 | .numberpars $. |
| 16406 | If neither \file\ nor \directory\ is set, the redirection operation |
| 16407 | must specify an absolute path (one that begins with \"/"\). This is the most |
| 16408 | common case when users with local accounts use filtering to sort mail into |
| 16409 | different folders. See for example, the \%address@_file%\ transport in the |
| 16410 | default configuration. If the path ends with a slash, it is assumed to be the |
| 16411 | name of a directory. A delivery to a directory can also be forced by setting |
| 16412 | \maildir@_format\ or \mailstore@_format\. |
| 16413 | .nextp |
| 16414 | If \file\ or \directory\ is set for a delivery from a redirection, it is used |
| 16415 | to determine the file or directory name for the delivery. Normally, the |
| 16416 | contents of \$address@_file$\ are used in some way in the string expansion. |
| 16417 | .endp |
| 16418 | |
| 16419 | .index Sieve filter||configuring \%appendfile%\ |
| 16420 | .index Sieve filter||relative mailbox path handling |
| 16421 | As an example of the second case, consider an environment where users do not |
| 16422 | have home directories. They may be permitted to use Exim filter commands of the |
| 16423 | form: |
| 16424 | .display asis |
| 16425 | save folder23 |
| 16426 | .endd |
| 16427 | or Sieve filter commands of the form: |
| 16428 | .display asis |
| 16429 | require "fileinto"; |
| 16430 | fileinto "folder23"; |
| 16431 | .endd |
| 16432 | In this situation, the expansion of \file\ or \directory\ in the transport must |
| 16433 | transform the relative path into an appropriate absolute file name. In the case |
| 16434 | of Sieve filters, the name \*inbox*\ must be handled. It is the name that is |
| 16435 | used as a result of a `keep' action in the filter. This example shows one way |
| 16436 | of handling this requirement: |
| 16437 | .display asis |
| 16438 | file = ${if eq{$address_file}{inbox} \ |
| 16439 | {/var/mail/$local_part} \ |
| 16440 | {${if eq{${substr_0_1:$address_file}}{/} \ |
| 16441 | {$address_file} \ |
| 16442 | {$home/mail/$address_file} \ |
| 16443 | }} \ |
| 16444 | } |
| 16445 | .endd |
| 16446 | With this setting of \file\, \*inbox*\ refers to the standard mailbox location, |
| 16447 | absolute paths are used without change, and other folders are in the \(mail)\ |
| 16448 | directory within the home directory. |
| 16449 | |
| 16450 | \**Note 1**\: While processing an Exim filter, a relative path such as |
| 16451 | \(folder23)\ is turned into an absolute path if a home directory is known to |
| 16452 | the router. In particular, this is the case if \check@_local@_user\ is set. If |
| 16453 | you want to prevent this happening at routing time, you can set |
| 16454 | \router@_home@_directory\ empty. This forces the router to pass the relative |
| 16455 | path to the transport. |
| 16456 | |
| 16457 | \**Note 2**\: An absolute path in \$address@_file$\ is not treated specially; |
| 16458 | the \file\ or \directory\ option is still used if it is set. |
| 16459 | |
| 16460 | |
| 16461 | |
| 16462 | .section Private options for appendfile |
| 16463 | .index options||\%appendfile%\ transport |
| 16464 | |
| 16465 | .startconf |
| 16466 | |
| 16467 | .conf allow@_fifo boolean false |
| 16468 | .index fifo (named pipe) |
| 16469 | .index named pipe (fifo) |
| 16470 | .index pipe||named (fifo) |
| 16471 | Setting this option permits delivery to named pipes (FIFOs) as well as to |
| 16472 | regular files. If no process is reading the named pipe at delivery time, the |
| 16473 | delivery is deferred. |
| 16474 | |
| 16475 | .conf allow@_symlink boolean false |
| 16476 | .index symbolic link||to mailbox |
| 16477 | .index mailbox||symbolic link |
| 16478 | By default, \%appendfile%\ will not deliver if the path name for the file is |
| 16479 | that of a symbolic link. Setting this option relaxes that constraint, but there |
| 16480 | are security issues involved in the use of symbolic links. Be sure you know |
| 16481 | what you are doing if you set this. Details of exactly what this option affects |
| 16482 | are included in the discussion which follows this list of options. |
| 16483 | |
| 16484 | .conf batch@_id string$**$ unset |
| 16485 | See the description of local delivery batching in chapter ~~CHAPbatching. |
| 16486 | However, batching is automatically disabled for \%appendfile%\ deliveries that |
| 16487 | happen as a result of forwarding or aliasing or other redirection directly to a |
| 16488 | file. |
| 16489 | |
| 16490 | .conf batch@_max integer 1 |
| 16491 | See the description of local delivery batching in chapter ~~CHAPbatching. |
| 16492 | |
| 16493 | .conf check@_group boolean false |
| 16494 | When this option is set, the group owner of the file defined by the \file\ |
| 16495 | option is checked to see that it is the same as the group under which the |
| 16496 | delivery process is running. The default setting is false because the default |
| 16497 | file mode is 0600, which means that the group is irrelevant. |
| 16498 | |
| 16499 | .conf check@_owner boolean true |
| 16500 | When this option is set, the owner of the file defined by the \file\ option is |
| 16501 | checked to ensure that it is the same as the user under which the delivery |
| 16502 | process is running. |
| 16503 | |
| 16504 | .conf check@_string string "see below" |
| 16505 | .index `From' line |
| 16506 | As \%appendfile%\ writes the message, the start of each line is tested for |
| 16507 | matching \check@_string\, and if it does, the initial matching characters are |
| 16508 | replaced by the contents of \escape@_string\. The value of \check@_string\ is a |
| 16509 | literal string, not a regular expression, and the case of any letters it |
| 16510 | contains is significant. |
| 16511 | |
| 16512 | If \use@_bsmtp\ is set the values of \check@_string\ and \escape@_string\ are |
| 16513 | forced to `.' and `..' respectively, and any settings in the configuration are |
| 16514 | ignored. Otherwise, they default to `From ' and `>From ' when the \file\ option |
| 16515 | is set, and unset when |
| 16516 | any of the \directory\, \maildir\, or \mailstore\ options are set. |
| 16517 | |
| 16518 | The default settings, along with \message@_prefix\ and \message@_suffix\, are |
| 16519 | suitable for traditional `BSD' mailboxes, where a line beginning with `From ' |
| 16520 | indicates the start of a new message. All four options need changing if another |
| 16521 | format is used. For example, to deliver to mailboxes in MMDF format: |
| 16522 | .index MMDF format mailbox |
| 16523 | .index mailbox||MMDF format |
| 16524 | .display asis |
| 16525 | check_string = "\1\1\1\1\n" |
| 16526 | escape_string = "\1\1\1\1 \n" |
| 16527 | message_prefix = "\1\1\1\1\n" |
| 16528 | message_suffix = "\1\1\1\1\n" |
| 16529 | .endd |
| 16530 | |
| 16531 | .index directory creation |
| 16532 | .conf create@_directory boolean true |
| 16533 | When this option is true, Exim attempts to create any missing superior |
| 16534 | directories for the file that it is about to write. A created directory's mode |
| 16535 | is given by the \directory@_mode\ option. |
| 16536 | |
| 16537 | .conf create@_file string "anywhere" |
| 16538 | This option constrains the location of files and directories that are created |
| 16539 | by this transport. It applies to files defined by the \file\ option and |
| 16540 | directories defined by the \directory\ option. In the case of maildir delivery, |
| 16541 | it applies to the top level directory, not the maildir directories beneath. |
| 16542 | |
| 16543 | The option must be set to one of the words `anywhere', `inhome', or |
| 16544 | `belowhome'. In the second and third cases, a home directory must have been set |
| 16545 | for the transport. This option is not useful when an explicit file name is |
| 16546 | given for normal mailbox deliveries. It is intended for the case when file |
| 16547 | names are generated from users' \(.forward)\ files. These are usually handled |
| 16548 | by an \%appendfile%\ transport called \address@_file\. See also |
| 16549 | \file@_must@_exist\. |
| 16550 | |
| 16551 | .conf directory string$**$ unset |
| 16552 | This option is mutually exclusive with the \file\ option, but one of \file\ or |
| 16553 | \directory\ must be set, unless the delivery is the direct result of a |
| 16554 | redirection (see section ~~SECTfildiropt). |
| 16555 | |
| 16556 | When \directory\ is set, the string is expanded, and the message is delivered |
| 16557 | into a new file or files in or below the given directory, instead of being |
| 16558 | appended to a single mailbox file. A number of different formats are provided |
| 16559 | (see \maildir@_format\ and \mailstore@_format\), and see section ~~SECTopdir |
| 16560 | for further details of this form of delivery. |
| 16561 | |
| 16562 | .conf directory@_file string$**$ "$tt{q@$@{base62:@$tod@_epoch@}-@$inode}" |
| 16563 | .index base62 |
| 16564 | When \directory\ is set, but neither \maildir@_format\ nor \mailstore@_format\ |
| 16565 | is set, \%appendfile%\ delivers each message into a file whose name is obtained |
| 16566 | by expanding this string. The default value generates a unique name from the |
| 16567 | current time, in base 62 form, and the inode of the file. The variable |
| 16568 | \$inode$\ is available only when expanding this option. |
| 16569 | |
| 16570 | .conf directory@_mode "octal integer" 0700 |
| 16571 | If \%appendfile%\ creates any directories as a result of the \create@_directory\ |
| 16572 | option, their mode is specified by this option. |
| 16573 | |
| 16574 | .conf escape@_string string "see description" |
| 16575 | See \check@_string\ above. |
| 16576 | |
| 16577 | .conf file string$**$ unset |
| 16578 | This option is mutually exclusive with the \directory\ option, but one of |
| 16579 | \file\ or \directory\ must be set, unless the delivery is the direct result of |
| 16580 | a redirection (see section ~~SECTfildiropt). The \file\ option specifies a |
| 16581 | single file, to which the message is appended. One or more of |
| 16582 | \use@_fcntl@_lock\, \use@_flock@_lock\, or \use@_lockfile\ must be set with |
| 16583 | \file\. |
| 16584 | .index NFS||lock file |
| 16585 | .index locking files |
| 16586 | .index lock files |
| 16587 | If you are using more than one host to deliver over NFS into the same |
| 16588 | mailboxes, you should always use lock files. |
| 16589 | |
| 16590 | The string value is expanded for each delivery, and must yield an absolute |
| 16591 | path. The most common settings of this option are variations on one of these |
| 16592 | examples: |
| 16593 | .display asis |
| 16594 | file = /var/spool/mail/$local_part |
| 16595 | file = /home/$local_part/inbox |
| 16596 | file = $home/inbox |
| 16597 | .endd |
| 16598 | .index `sticky' bit |
| 16599 | In the first example, all deliveries are done into the same directory. If Exim |
| 16600 | is configured to use lock files (see \use@_lockfile\ below) it must be able to |
| 16601 | create a file in the directory, so the `sticky' bit must be turned on for |
| 16602 | deliveries to be possible, or alternatively the \group\ option can be used to |
| 16603 | run the delivery under a group id which has write access to the directory. |
| 16604 | |
| 16605 | |
| 16606 | .conf file@_format string unset |
| 16607 | .index file||mailbox, checking existing format |
| 16608 | This option requests the transport to check the format of an existing file |
| 16609 | before adding to it. The check consists of matching a specific string at the |
| 16610 | start of the file. The value of the option consists of an even number of |
| 16611 | colon-separated strings. The first of each pair is the test string, and the |
| 16612 | second is the name of a transport. If the transport associated with a matched |
| 16613 | string is not the current transport, control is passed over to the other |
| 16614 | transport. For example, suppose the standard \%local@_delivery%\ transport has |
| 16615 | this added to it: |
| 16616 | .display asis |
| 16617 | file_format = "From : local_delivery :\ |
| 16618 | \1\1\1\1\n : local_mmdf_delivery" |
| 16619 | .endd |
| 16620 | Mailboxes that begin with `From' are still handled by this transport, but if a |
| 16621 | mailbox begins with four binary ones followed by a newline, control is passed |
| 16622 | to a transport called \local__mmdf__delivery\, which presumably is configured |
| 16623 | to do the delivery in MMDF format. If a mailbox does not exist or is empty, it |
| 16624 | is assumed to match the current transport. If the start of a mailbox doesn't |
| 16625 | match any string, or if the transport named for a given string is not defined, |
| 16626 | delivery is deferred. |
| 16627 | |
| 16628 | .conf file@_must@_exist boolean false |
| 16629 | If this option is true, the file specified by the \file\ option must exist, and |
| 16630 | an error occurs if it does not. Otherwise, it is created if it does not exist. |
| 16631 | |
| 16632 | .conf lock@_fcntl@_timeout time 0s |
| 16633 | .index timeout||mailbox locking |
| 16634 | .index mailbox locking||blocking and non-blocking |
| 16635 | .index locking files |
| 16636 | By default, the \%appendfile%\ transport uses non-blocking calls to \*fcntl()*\ |
| 16637 | when locking an open mailbox file. If the call fails, the delivery process |
| 16638 | sleeps for \lock@_interval\ and tries again, up to \lock@_retries\ times. |
| 16639 | Non-blocking calls are used so that the file is not kept open during the wait |
| 16640 | for the lock; the reason for this is to make it as safe as possible for |
| 16641 | deliveries over NFS in the case when processes might be accessing an NFS |
| 16642 | mailbox without using a lock file. This should not be done, but |
| 16643 | misunderstandings and hence misconfigurations are not unknown. |
| 16644 | |
| 16645 | On a busy system, however, the performance of a non-blocking lock approach is |
| 16646 | not as good as using a blocking lock with a timeout. In this case, the waiting |
| 16647 | is done inside the system call, and Exim's delivery process acquires the lock |
| 16648 | and can proceed as soon as the previous lock holder releases it. |
| 16649 | |
| 16650 | If \lock@_fcntl@_timeout\ is set to a non-zero time, blocking locks, with that |
| 16651 | timeout, are used. There may still be some retrying: the maximum number of |
| 16652 | retries is |
| 16653 | .display asis |
| 16654 | (lock_retries * lock_interval) / lock_fcntl_timeout |
| 16655 | .endd |
| 16656 | rounded up to the next whole number. In other words, the total time during |
| 16657 | which \%appendfile%\ is trying to get a lock is roughly the same, unless |
| 16658 | \lock@_fcntl@_timeout\ is set very large. |
| 16659 | |
| 16660 | You should consider setting this option if you are getting a lot of delayed |
| 16661 | local deliveries because of errors of the form |
| 16662 | .display asis |
| 16663 | failed to lock mailbox /some/file (fcntl) |
| 16664 | .endd |
| 16665 | |
| 16666 | .conf lock@_flock@_timeout time 0s |
| 16667 | This timeout applies to file locking when using \*flock()*\ (see \use@_flock\); |
| 16668 | the timeout operates in a similar manner to \lock@_fcntl@_timeout\. |
| 16669 | |
| 16670 | .conf lock@_interval time 3s |
| 16671 | This specifies the time to wait between attempts to lock the file. See below |
| 16672 | for details of locking. |
| 16673 | |
| 16674 | .conf lock@_retries integer 10 |
| 16675 | This specifies the maximum number of attempts to lock the file. A value of zero |
| 16676 | is treated as 1. See below for details of locking. |
| 16677 | |
| 16678 | .conf lockfile@_mode "octal integer" 0600 |
| 16679 | This specifies the mode of the created lock file, when a lock file is being |
| 16680 | used (see \use@_lockfile\). |
| 16681 | |
| 16682 | .conf lockfile@_timeout time 30m |
| 16683 | .index timeout||mailbox locking |
| 16684 | When a lock file is being used (see \use@_lockfile\), if a lock file already |
| 16685 | exists and is older than this value, it is assumed to have been left behind by |
| 16686 | accident, and Exim attempts to remove it. |
| 16687 | |
| 16688 | .conf maildir@_format boolean false |
| 16689 | .index maildir format||specifying |
| 16690 | If this option is set with the \directory\ option, the delivery is into a new |
| 16691 | file, in the `maildir' format that is used by other mail software. When the |
| 16692 | transport is activated directly from a \%redirect%\ router (for example, the |
| 16693 | \%address@_file%\ transport in the default configuration), setting |
| 16694 | \maildir@_format\ causes the path received from the router to be treated as a |
| 16695 | directory, whether or not it ends with \"/"\. This option is available only if |
| 16696 | \\SUPPORT@_MAILDIR\\ is present in \(Local/Makefile)\. See section |
| 16697 | ~~SECTmaildirdelivery below for further details. |
| 16698 | |
| 16699 | .conf maildir@_quota@_directory@_regex string "See below" |
| 16700 | .index maildir format||quota, directories included in |
| 16701 | .index quota||maildir, directories included in |
| 16702 | This option is relevant only when \maildir@_use@_size@_file\ is set. It defines |
| 16703 | a regular expression for specifying directories that should be included in the |
| 16704 | quota calculation. The default value is |
| 16705 | .display asis |
| 16706 | maildir_quota_directory_regex = ^(?:cur|new|\..*)$ |
| 16707 | .endd |
| 16708 | which includes the \(cur)\ and \(new)\ directories, and any maildir++ folders |
| 16709 | (directories whose names begin with a dot). If you want to exclude the |
| 16710 | \(Trash)\ |
| 16711 | folder from the count (as some sites do), you need to change this setting to |
| 16712 | .display asis |
| 16713 | maildir_quota_directory_regex = ^(?:cur|new|\.(?!Trash).*)$ |
| 16714 | .endd |
| 16715 | This uses a negative lookahead in the regular expression to exclude the |
| 16716 | directory whose name is \(.Trash)\. |
| 16717 | |
| 16718 | .conf maildir@_retries integer 10 |
| 16719 | This option specifies the number of times to retry when writing a file in |
| 16720 | `maildir' format. See section ~~SECTmaildirdelivery below. |
| 16721 | |
| 16722 | .conf maildir@_tag string$**$ unset |
| 16723 | This option applies only to deliveries in maildir format, and is described in |
| 16724 | section ~~SECTmaildirdelivery below. |
| 16725 | |
| 16726 | .conf maildir@_use@_size@_file boolean false |
| 16727 | .index maildir format||\(maildirsize)\ file |
| 16728 | Setting this option true enables support for \(maildirsize)\ files. Exim |
| 16729 | creates a \(maildirsize)\ file in a maildir if one does not exist, taking the |
| 16730 | quota from the \quota\ option of the transport. If \quota\ is unset, the value |
| 16731 | is zero. See section ~~SECTmaildirdelivery below for further details. |
| 16732 | |
| 16733 | .conf mailstore@_format boolean false |
| 16734 | .index mailstore format||specifying |
| 16735 | If this option is set with the \directory\ option, the delivery is into two new |
| 16736 | files in `mailstore' format. The option is available only if |
| 16737 | \\SUPPORT@_MAILSTORE\\ is present in \(Local/Makefile)\. See section |
| 16738 | ~~SECTopdir below for further details. |
| 16739 | |
| 16740 | .conf mailstore@_prefix string$**$ unset |
| 16741 | This option applies only to deliveries in mailstore format, and is described in |
| 16742 | section ~~SECTopdir below. |
| 16743 | |
| 16744 | .conf mailstore@_suffix string$**$ unset |
| 16745 | This option applies only to deliveries in mailstore format, and is described in |
| 16746 | section ~~SECTopdir below. |
| 16747 | |
| 16748 | .conf mbx@_format boolean false |
| 16749 | .index locking files |
| 16750 | .index file||locking |
| 16751 | .index file||MBX format |
| 16752 | .index MBX format, specifying |
| 16753 | This option is available only if Exim has been compiled with \\SUPPORT@_MBX\\ |
| 16754 | set in \(Local/Makefile)\. If \mbx@_format\ is set with the \file\ option, |
| 16755 | the message is appended to the mailbox file in MBX format instead of |
| 16756 | traditional Unix format. This format is supported by Pine4 and its associated |
| 16757 | IMAP and POP daemons, by means of the \*c-client*\ library that they all use. |
| 16758 | |
| 16759 | \**Note**\: The \message@_prefix\ and \message@_suffix\ options are not |
| 16760 | automatically changed by the use of \mbx@_format\. They should normally be set |
| 16761 | empty when using MBX format, so this option almost always appears in this |
| 16762 | combination: |
| 16763 | .display asis |
| 16764 | mbx_format = true |
| 16765 | message_prefix = |
| 16766 | message_suffix = |
| 16767 | .endd |
| 16768 | |
| 16769 | If none of the locking options are mentioned in the configuration, |
| 16770 | \use@_mbx@_lock\ is assumed and the other locking options default to false. It |
| 16771 | is possible to specify the other kinds of locking with \mbx@_format\, but |
| 16772 | \use@_fcntl@_lock\ and \use@_mbx@_lock\ are mutually exclusive. MBX locking |
| 16773 | interworks with \*c-client*\, providing for shared access to the mailbox. It |
| 16774 | should not be used if any program that does not use this form of locking is |
| 16775 | going to access the mailbox, nor should it be used if the mailbox file is NFS |
| 16776 | mounted, because it works only when the mailbox is accessed from a single host. |
| 16777 | |
| 16778 | If you set \use@_fcntl@_lock\ with an MBX-format mailbox, you cannot use |
| 16779 | the standard version of \*c-client*\, because as long as it has a mailbox open |
| 16780 | (this means for the whole of a Pine or IMAP session), Exim will not be able to |
| 16781 | append messages to it. |
| 16782 | |
| 16783 | .conf message@_prefix string$**$ "see below" |
| 16784 | .index `From' line |
| 16785 | The string specified here is expanded and output at the start of every message. |
| 16786 | The default is unset unless \file\ is specified and \use@_bsmtp\ is not set, in |
| 16787 | which case it is: |
| 16788 | .display asis |
| 16789 | message_prefix = "From ${if def:return_path{$return_path}\ |
| 16790 | {MAILER-DAEMON}} $tod_bsdinbox\n" |
| 16791 | .endd |
| 16792 | |
| 16793 | .conf message@_suffix string$**$ "see below" |
| 16794 | The string specified here is expanded and output at the end of every message. |
| 16795 | The default is unset unless \file\ is specified and \use@_bsmtp\ is not set, in |
| 16796 | which case it is a single newline character. The suffix can be suppressed by |
| 16797 | setting |
| 16798 | .display asis |
| 16799 | message_suffix = |
| 16800 | .endd |
| 16801 | |
| 16802 | .conf mode "octal integer" 0600 |
| 16803 | If the output file is created, it is given this mode. If it already exists and |
| 16804 | has wider permissions, they are reduced to this mode. If it has narrower |
| 16805 | permissions, an error occurs unless \mode__fail__narrower\ is false. However, |
| 16806 | if the delivery is the result of a \save\ command in a filter file specifing a |
| 16807 | particular mode, the mode of the output file is always forced to take that |
| 16808 | value, and this option is ignored. |
| 16809 | |
| 16810 | .conf mode@_fail@_narrower boolean true |
| 16811 | This option applies in the case when an existing mailbox file has a narrower |
| 16812 | mode than that specified by the \mode\ option. If \mode@_fail@_narrower\ is |
| 16813 | true, the delivery is deferred (`mailbox has the wrong mode'); otherwise Exim |
| 16814 | continues with the delivery attempt, using the existing mode of the file. |
| 16815 | |
| 16816 | .conf notify@_comsat boolean false |
| 16817 | If this option is true, the \*comsat*\ daemon is notified after every successful |
| 16818 | delivery to a user mailbox. This is the daemon that notifies logged on users |
| 16819 | about incoming mail. |
| 16820 | |
| 16821 | .conf quota string$**$ unset |
| 16822 | .index quota||imposed by Exim |
| 16823 | This option imposes a limit on the size of the file to which Exim is appending, |
| 16824 | or to the total space used in the directory tree when the \directory\ option is |
| 16825 | set. In the latter case, computation of the space used is expensive, because |
| 16826 | all the files in the directory (and any sub-directories) have to be |
| 16827 | individually inspected and their sizes summed. |
| 16828 | (See \quota@_size@_regex\ and \maildir@_use@_size@_file\ for ways to avoid this |
| 16829 | in environments where users have no shell access to their mailboxes). |
| 16830 | |
| 16831 | As there is no interlock against two simultaneous deliveries into a |
| 16832 | multi-file mailbox, it is possible for the quota to be overrun in this case. |
| 16833 | For single-file mailboxes, of course, an interlock is a necessity. |
| 16834 | |
| 16835 | A file's size is taken as its \*used*\ value. Because of blocking effects, this |
| 16836 | may be a lot less than the actual amount of disk space allocated to the file. |
| 16837 | If the sizes of a number of files are being added up, the rounding effect can |
| 16838 | become quite noticeable, especially on systems that have large block sizes. |
| 16839 | Nevertheless, it seems best to stick to the \*used*\ figure, because this is |
| 16840 | the obvious value which users understand most easily. |
| 16841 | |
| 16842 | The value of the option is expanded, and must then be a numerical value |
| 16843 | (decimal point allowed), optionally followed by one of the letters K or M. The |
| 16844 | expansion happens while Exim is running as root, before it changes uid for the |
| 16845 | delivery. This means that files which are inaccessible to the end user can be |
| 16846 | used to hold quota values that are looked up in the expansion. When delivery |
| 16847 | fails because this quota is exceeded, the handling of the error is as for |
| 16848 | system quota failures. |
| 16849 | |
| 16850 | \**Note**\: A value of zero is interpreted as `no quota'. |
| 16851 | |
| 16852 | By default, Exim's quota checking mimics system quotas, and restricts the |
| 16853 | mailbox to the specified maximum size, though the value is not accurate to the |
| 16854 | last byte, owing to separator lines and additional headers that may get added |
| 16855 | during message delivery. When a mailbox is nearly full, large messages may get |
| 16856 | refused even though small ones are accepted, because the size of the current |
| 16857 | message is added to the quota when the check is made. This behaviour can be |
| 16858 | changed by setting \quota@_is@_inclusive\ false. When this is done, the check |
| 16859 | for exceeding the quota does not include the current message. Thus, deliveries |
| 16860 | continue until the quota has been exceeded; thereafter, no further messages are |
| 16861 | delivered. See also \quota@_warn@_threshold\. |
| 16862 | |
| 16863 | .conf quota@_directory string$**$ unset |
| 16864 | This option defines the directory to check for quota purposes when delivering |
| 16865 | into individual files. The default is the delivery directory, or, if a file |
| 16866 | called \(maildirfolder)\ exists in a maildir directory, the parent of the |
| 16867 | delivery directory. |
| 16868 | |
| 16869 | .conf quota@_filecount string$**$ 0 |
| 16870 | This option applies when the \directory\ option is set. It limits the total |
| 16871 | number of files in the directory (compare the inode limit in system quotas). It |
| 16872 | can only be used if \quota\ is also set. The value is expanded; an expansion |
| 16873 | failure causes delivery to be deferred. |
| 16874 | |
| 16875 | .conf quota@_is@_inclusive boolean true |
| 16876 | See \quota\ above. |
| 16877 | |
| 16878 | .conf quota@_size@_regex string unset |
| 16879 | This option applies when one of the delivery modes that writes a separate file |
| 16880 | for each message is being used. When Exim wants to find the size of one of |
| 16881 | these files in order to test the quota, it first checks \quota@_size@_regex\. |
| 16882 | If this is set to a regular expression that matches the file name, and it |
| 16883 | captures one string, that string is interpreted as a representation of the |
| 16884 | file's size. The value of \quota@_size@_regex\ is not expanded. |
| 16885 | |
| 16886 | This feature is useful only when users have no shell access to their mailboxes |
| 16887 | -- otherwise they could defeat the quota simply by renaming the files. This |
| 16888 | facility can be used with maildir deliveries, by setting \maildir@_tag\ to add |
| 16889 | the file length to the file name. For example: |
| 16890 | .display asis |
| 16891 | maildir_tag = ,S=$message_size |
| 16892 | quota_size_regex = ,S=(\d+) |
| 16893 | .endd |
| 16894 | The regular expression should not assume that the length is at the end of the |
| 16895 | file name (even though \maildir@_tag\ puts it there) because maildir MUAs |
| 16896 | sometimes add other information onto the ends of message file names. |
| 16897 | |
| 16898 | .conf quota@_warn@_message string$**$ "see below" |
| 16899 | See below for the use of this option. If it is not set when |
| 16900 | \quota@_warn@_threshold\ is set, it defaults to |
| 16901 | .display asis |
| 16902 | quota_warn_message = "\ |
| 16903 | To: $local_part@$domain\n\ |
| 16904 | Subject: Your mailbox\n\n\ |
| 16905 | This message is automatically created \ |
| 16906 | by mail delivery software.\n\n\ |
| 16907 | The size of your mailbox has exceeded \ |
| 16908 | a warning threshold that is\n\ |
| 16909 | set by the system administrator.\n" |
| 16910 | .endd |
| 16911 | |
| 16912 | .conf quota@_warn@_threshold string$**$ 0 |
| 16913 | .index quota||warning threshold |
| 16914 | .index mailbox||size warning |
| 16915 | .index size||of mailbox |
| 16916 | This option is expanded in the same way as \quota\ (see above). If the |
| 16917 | resulting value is greater than zero, and delivery of the message causes the |
| 16918 | size of the file or total space in the directory tree to cross the given |
| 16919 | threshold, a warning message is sent. If \quota\ is also set, the threshold may |
| 16920 | be specified as a percentage of it by following the value with a percent sign. |
| 16921 | For example: |
| 16922 | .display asis |
| 16923 | quota = 10M |
| 16924 | quota_warn_threshold = 75% |
| 16925 | .endd |
| 16926 | If \quota\ is not set, a setting of \quota@_warn@_threshold\ that ends with a |
| 16927 | percent sign is ignored. |
| 16928 | |
| 16929 | The warning message itself is specified by the \quota@_warn@_message\ option, |
| 16930 | and it must start with a ::To:: header line containing the recipient(s). A |
| 16931 | ::Subject:: line should also normally be supplied. The \quota\ option does not |
| 16932 | have to be set in order to use this option; they are independent of one |
| 16933 | another except when the threshold is specified as a percentage. |
| 16934 | |
| 16935 | .conf use@_bsmtp boolean false |
| 16936 | .index envelope sender |
| 16937 | If this option is set true, \%appendfile%\ writes messages in `batch SMTP' |
| 16938 | format, with the envelope sender and recipient(s) included as SMTP commands. If |
| 16939 | you want to include a leading \\HELO\\ command with such messages, you can do |
| 16940 | so by setting the \message@_prefix\ option. See section ~~SECTbatchSMTP for |
| 16941 | details of batch SMTP. |
| 16942 | |
| 16943 | .conf use@_crlf boolean false |
| 16944 | .index carriage return |
| 16945 | .index linefeed |
| 16946 | This option causes lines to be terminated with the two-character CRLF sequence |
| 16947 | (carriage return, linefeed) instead of just a linefeed character. In the case |
| 16948 | of batched SMTP, the byte sequence written to the file is then an exact image |
| 16949 | of what would be sent down a real SMTP connection. |
| 16950 | |
| 16951 | The contents of the \message@_prefix\ and \message@_suffix\ options are written |
| 16952 | verbatim, so must contain their own carriage return characters if these are |
| 16953 | needed. In cases where these options have non-empty defaults, the values end |
| 16954 | with a single linefeed, so they |
| 16955 | must |
| 16956 | be changed to end with \"@\r@\n"\ if \use@_crlf\ is set. |
| 16957 | |
| 16958 | .conf use@_fcntl@_lock boolean "see below" |
| 16959 | This option controls the use of the \*fcntl()*\ function to lock a file for |
| 16960 | exclusive use when a message is being appended. It is set by default unless |
| 16961 | \use@_flock@_lock\ is set. Otherwise, it should be turned off only if you know |
| 16962 | that all your MUAs use lock file locking. When both \use@_fcntl@_lock\ and |
| 16963 | \use@_flock@_lock\ are unset, \use@_lockfile\ must be set. |
| 16964 | |
| 16965 | .conf use@_flock@_lock boolean false |
| 16966 | This option is provided to support the use of \*flock()*\ for file locking, for |
| 16967 | the few situations where it is needed. Most modern operating systems support |
| 16968 | \*fcntl()*\ and \*lockf()*\ locking, and these two functions interwork with |
| 16969 | each other. Exim uses \*fcntl()*\ locking by default. |
| 16970 | |
| 16971 | This option is required only if you are using an operating system where |
| 16972 | \*flock()*\ is used by programs that access mailboxes (typically MUAs), and |
| 16973 | where \*flock()*\ does not correctly interwork with \*fcntl()*\. You can use |
| 16974 | both \*fcntl()*\ and \*flock()*\ locking simultaneously if you want. |
| 16975 | |
| 16976 | .index Solaris||\*flock()*\ support |
| 16977 | Not all operating systems provide \*flock()*\. Some versions of Solaris do not |
| 16978 | have it (and some, I think, provide a not quite right version built on top of |
| 16979 | \*lockf()*\). If the OS does not have \*flock()*\, Exim will be built without |
| 16980 | the ability to use it, and any attempt to do so will cause a configuration |
| 16981 | error. |
| 16982 | |
| 16983 | \**Warning**\: \*flock()*\ locks do not work on NFS files (unless \*flock()*\ |
| 16984 | is just being mapped onto \*fcntl()*\ by the OS). |
| 16985 | |
| 16986 | .conf use@_lockfile boolean "see below" |
| 16987 | If this option is turned off, Exim does not attempt to create a lock file when |
| 16988 | appending to a mailbox file. In this situation, the only locking is by |
| 16989 | \*fcntl()*\. You should only turn \use@_lockfile\ off if you are absolutely |
| 16990 | sure that every MUA that is ever going to look at your users' mailboxes uses |
| 16991 | \*fcntl()*\ rather than a lock file, and even then only when you are not |
| 16992 | delivering over NFS from more than one host. |
| 16993 | |
| 16994 | .index NFS||lock file |
| 16995 | In order to append to an NFS file safely from more than one host, it is |
| 16996 | necessary to take out a lock $it{before} opening the file, and the lock file |
| 16997 | achieves this. Otherwise, even with \*fcntl()*\ locking, there is a risk of |
| 16998 | file corruption. |
| 16999 | |
| 17000 | The \use@_lockfile\ option is set by default unless \use@_mbx@_lock\ is set. It |
| 17001 | is not possible to turn both \use@_lockfile\ and \use@_fcntl@_lock\ off, except |
| 17002 | when \mbx@_format\ is set. |
| 17003 | |
| 17004 | .conf use@_mbx@_lock boolean "see below" |
| 17005 | This option is available only if Exim has been compiled with \\SUPPORT@_MBX\\ |
| 17006 | set in \(Local/Makefile)\. Setting the option specifies that special MBX |
| 17007 | locking rules be used. It is set by default if \mbx@_format\ is set and none of |
| 17008 | the locking options are mentioned in the configuration. The locking rules are |
| 17009 | the same as are used by the \*c-client*\ library that underlies Pine and the |
| 17010 | IMAP4 and POP daemons that come with it (see the discussion below). The rules |
| 17011 | allow for shared access to the mailbox. However, this kind of locking does not |
| 17012 | work when the mailbox is NFS mounted. |
| 17013 | |
| 17014 | You can set \use@_mbx@_lock\ with either (or both) of \use@_fcntl@_lock\ and |
| 17015 | \use@_flock@_lock\ to control what kind of locking is used in implementing the |
| 17016 | MBX locking rules. The default is to use \*fcntl()*\ if \use@_mbx@_lock\ is set |
| 17017 | without \use@_fcntl@_lock\ or \use@_flock@_lock\. |
| 17018 | .endconf |
| 17019 | |
| 17020 | |
| 17021 | .section Operational details for appending |
| 17022 | .rset SECTopappend "~~chapter.~~section" |
| 17023 | .index appending to a file |
| 17024 | .index file||appending |
| 17025 | Before appending to a file, the following preparations are made: |
| 17026 | .numberpars $. |
| 17027 | If the name of the file is \(/dev/null)\, no action is taken, and a success |
| 17028 | return is given. |
| 17029 | .nextp |
| 17030 | .index directory creation |
| 17031 | If any directories on the file's path are missing, Exim creates them if the |
| 17032 | \create@_directory\ option is set. A created directory's mode is given by the |
| 17033 | \directory@_mode\ option. |
| 17034 | .nextp |
| 17035 | If \file@_format\ is set, the format of an existing file is checked. If this |
| 17036 | indicates that a different transport should be used, control is passed to that |
| 17037 | transport. |
| 17038 | .nextp |
| 17039 | .index file||locking |
| 17040 | .index locking files |
| 17041 | .index NFS||lock file |
| 17042 | If \use@_lockfile\ is set, a lock file is built in a way that will work |
| 17043 | reliably over NFS, as follows: |
| 17044 | .numberpars $. |
| 17045 | Create a `hitching post' file whose name is that of the lock file with the |
| 17046 | current time, primary host name, and process id added, by opening for writing |
| 17047 | as a new file. If this fails with an access error, delivery is deferred. |
| 17048 | .nextp |
| 17049 | Close the hitching post file, and hard link it to the lock file name. |
| 17050 | .nextp |
| 17051 | If the call to \*link()*\ succeeds, creation of the lock file has succeeded. |
| 17052 | Unlink the hitching post name. |
| 17053 | .nextp |
| 17054 | Otherwise, use \*stat()*\ to get information about the hitching post file, and |
| 17055 | then unlink hitching post name. If the number of links is exactly two, creation |
| 17056 | of the lock file succeeded but something (for example, an NFS server crash and |
| 17057 | restart) caused this fact not to be communicated to the \*link()*\ call. |
| 17058 | .nextp |
| 17059 | If creation of the lock file failed, wait for \lock@_interval\ and try again, |
| 17060 | up to \lock@_retries\ times. However, since any program that writes to a |
| 17061 | mailbox should complete its task very quickly, it is reasonable to time out old |
| 17062 | lock files that are normally the result of user agent and system crashes. If an |
| 17063 | existing lock file is older than \lockfile@_timeout\ Exim attempts to unlink it |
| 17064 | before trying again. |
| 17065 | .endp |
| 17066 | .nextp |
| 17067 | A call is made to \*lstat()*\ to discover whether the main file exists, and if |
| 17068 | so, what its characteristics are. If \*lstat()*\ fails for any reason other |
| 17069 | than non-existence, delivery is deferred. |
| 17070 | .nextp |
| 17071 | .index symbolic link||to mailbox |
| 17072 | .index mailbox||symbolic link |
| 17073 | If the file does exist and is a symbolic link, delivery is deferred, unless the |
| 17074 | \allow@_symlink\ option is set, in which case the ownership of the link is |
| 17075 | checked, and then \*stat()*\ is called to find out about the real file, which |
| 17076 | is then subjected to the checks below. The check on the top-level link |
| 17077 | ownership prevents one user creating a link for another's mailbox in a sticky |
| 17078 | directory, though allowing symbolic links in this case is definitely not a good |
| 17079 | idea. If there is a chain of symbolic links, the intermediate ones are not |
| 17080 | checked. |
| 17081 | .nextp |
| 17082 | If the file already exists but is not a regular file, or if the file's owner |
| 17083 | and group (if the group is being checked -- see \check@_group\ above) are |
| 17084 | different from the user and group under which the delivery is running, |
| 17085 | delivery is deferred. |
| 17086 | .nextp |
| 17087 | If the file's permissions are more generous than specified, they are reduced. |
| 17088 | If they are insufficient, delivery is deferred, unless \mode@_fail@_narrower\ |
| 17089 | is set false, in which case the delivery is tried using the existing |
| 17090 | permissions. |
| 17091 | .nextp |
| 17092 | The file's inode number is saved, and the file is then opened for appending. If |
| 17093 | this fails because the file has vanished, \%appendfile%\ behaves as if it hadn't |
| 17094 | existed (see below). For any other failures, delivery is deferred. |
| 17095 | .nextp |
| 17096 | If the file is opened successfully, check that the inode number hasn't |
| 17097 | changed, that it is still a regular file, and that the owner and permissions |
| 17098 | have not changed. If anything is wrong, defer delivery and freeze the message. |
| 17099 | .nextp |
| 17100 | If the file did not exist originally, defer delivery if the \file@_must@_exist\ |
| 17101 | option is set. Otherwise, check that the file is being created in a permitted |
| 17102 | directory if the \create@_file\ option is set (deferring on failure), and then |
| 17103 | open for writing as a new file, with the \\O@_EXCL\\ and \\O@_CREAT\\ options, |
| 17104 | except when dealing with a symbolic link (the \allow@_symlink\ option must be |
| 17105 | set). In this case, which can happen if the link points to a non-existent file, |
| 17106 | the file is opened for writing using \\O@_CREAT\\ but not \\O@_EXCL\\, because |
| 17107 | that prevents link following. |
| 17108 | .nextp |
| 17109 | .index loop||while file testing |
| 17110 | If opening fails because the file exists, obey the tests given above for |
| 17111 | existing files. However, to avoid looping in a situation where the file is |
| 17112 | being continuously created and destroyed, the exists/not-exists loop is broken |
| 17113 | after 10 repetitions, and the message is then frozen. |
| 17114 | .nextp |
| 17115 | If opening fails with any other error, defer delivery. |
| 17116 | .nextp |
| 17117 | .index file||locking |
| 17118 | .index locking files |
| 17119 | Once the file is open, unless both \use@_fcntl@_lock\ and \use@_flock@_lock\ |
| 17120 | are false, it is locked using \*fcntl()*\ or \*flock()*\ or both. If |
| 17121 | \use@_mbx@_lock\ is false, an exclusive lock is requested in each case. |
| 17122 | However, if \use@_mbx@_lock\ is true, |
| 17123 | Exim takes out a shared lock on the open file, |
| 17124 | and an exclusive lock on the file whose name is |
| 17125 | .display |
| 17126 | /tmp/.<<device-number>>.<<inode-number>> |
| 17127 | .endd |
| 17128 | using the device and inode numbers of the open mailbox file, in accordance with |
| 17129 | the MBX locking rules. |
| 17130 | |
| 17131 | If Exim fails to lock the file, there are two possible courses of action, |
| 17132 | depending on the value of the locking timeout. This is obtained from |
| 17133 | \lock@_fcntl@_timeout\ or \lock@_flock@_timeout\, as appropriate. |
| 17134 | |
| 17135 | If the timeout value is zero, the file is closed, Exim waits for |
| 17136 | \lock@_interval\, and then goes back and re-opens the file as above and tries |
| 17137 | to lock it again. This happens up to \lock@_retries\ times, after which the |
| 17138 | delivery is deferred. |
| 17139 | |
| 17140 | If the timeout has a value greater than zero, blocking calls to \*fcntl()*\ or |
| 17141 | \*flock()*\ are used (with the given timeout), so there has already been some |
| 17142 | waiting involved by the time locking fails. Nevertheless, Exim does not give up |
| 17143 | immediately. It retries up to |
| 17144 | .display |
| 17145 | (lock@_retries * lock@_interval) / <<timeout>> |
| 17146 | .endd |
| 17147 | times (rounded up). |
| 17148 | .endp |
| 17149 | |
| 17150 | At the end of delivery, Exim closes the file (which releases the \*fcntl()*\ |
| 17151 | and/or \*flock()*\ locks) and then deletes the lock file if one was created. |
| 17152 | |
| 17153 | .section Operational details for delivery to a new file |
| 17154 | .rset SECTopdir "~~chapter.~~section" |
| 17155 | .index delivery||to single file |
| 17156 | .index `From' line |
| 17157 | When the \directory\ option is set instead of \file\, each message is delivered |
| 17158 | into a newly-created file or set of files. When \%appendfile%\ is activated |
| 17159 | directly from a \%redirect%\ router, neither \file\ nor \directory\ is normally |
| 17160 | set, because the path for delivery is supplied by the router. (See for example, |
| 17161 | the \%address@_file%\ transport in the default configuration.) In this case, |
| 17162 | delivery is to a new file if either the path name ends in \"/"\, or the |
| 17163 | \maildir@_format\ or \mailstore@_format\ option is set. |
| 17164 | |
| 17165 | No locking is required while writing the message to a new file, so the various |
| 17166 | locking options of the transport are ignored. The `From' line that by default |
| 17167 | separates messages in a single file is not normally needed, nor is the escaping |
| 17168 | of message lines that start with `From', and there is no need to ensure a |
| 17169 | newline at the end of each message. Consequently, the default values for |
| 17170 | \check@_string\, \message@_prefix\, and \message@_suffix\ are all unset when |
| 17171 | any of \directory\, \maildir@_format\, or \mailstore@_format\ is set. |
| 17172 | |
| 17173 | If Exim is required to check a \quota\ setting, it adds up the sizes of all the |
| 17174 | files in the delivery directory by default. However, you can specify a |
| 17175 | different directory by setting \quota@_directory\. Also, for maildir deliveries |
| 17176 | (see below) the \(maildirfolder)\ convention is honoured. |
| 17177 | |
| 17178 | |
| 17179 | .index maildir format |
| 17180 | .index mailstore format |
| 17181 | There are three different ways in which delivery to individual files can be |
| 17182 | done, controlled by the settings of the \maildir@_format\ and |
| 17183 | \mailstore@_format\ options. Note that code to support maildir or mailstore |
| 17184 | formats is not included in the binary unless \\SUPPORT@_MAILDIR\\ or |
| 17185 | \\SUPPORT@_MAILSTORE\\, respectively, is set in \(Local/Makefile)\. |
| 17186 | |
| 17187 | .index directory creation |
| 17188 | In all three cases an attempt is made to create the directory and any necessary |
| 17189 | sub-directories if they do not exist, provided that the \create@_directory\ |
| 17190 | option is set (the default). The location of a created directory can be |
| 17191 | constrained by setting \create@_file\. A created directory's mode is given by |
| 17192 | the \directory@_mode\ option. If creation fails, or if the \create@_directory\ |
| 17193 | option is not set when creation is required, delivery is deferred. |
| 17194 | |
| 17195 | |
| 17196 | .section Maildir delivery |
| 17197 | .rset SECTmaildirdelivery "~~chapter.~~section" |
| 17198 | .index maildir format||description of |
| 17199 | If the \maildir@_format\ option is true, Exim delivers each message by writing |
| 17200 | it to a file whose name is \(tmp/<<stime>>.H<<mtime>>P<<pid>>.<<host>>)\ in the |
| 17201 | given directory. If the delivery is successful, the file is renamed into the |
| 17202 | \(new)\ subdirectory. |
| 17203 | |
| 17204 | In the file name, <<stime>> is the current time of day in seconds, and |
| 17205 | <<mtime>> is the microsecond fraction of the time. After a maildir delivery, |
| 17206 | Exim checks that the time-of-day clock has moved on by at least one microsecond |
| 17207 | before terminating the delivery process. This guarantees uniqueness for the |
| 17208 | file name. However, as a precaution, Exim calls \*stat()*\ for the file before |
| 17209 | opening it. If any response other than \\ENOENT\\ (does not exist) is given, |
| 17210 | Exim waits 2 seconds and tries again, up to \maildir@_retries\ times. |
| 17211 | |
| 17212 | .index quota||in maildir delivery |
| 17213 | .index maildir++ |
| 17214 | If Exim is required to check a \quota\ setting before a maildir delivery, and |
| 17215 | \quota@_directory\ is not set, it looks for a file called \(maildirfolder)\ in |
| 17216 | the maildir directory (alongside \(new)\, \(cur)\, \(tmp)\). If this exists, |
| 17217 | Exim assumes the directory is a maildir++ folder directory, which is one level |
| 17218 | down from the user's top level mailbox directory. This causes it to start at |
| 17219 | the parent directory instead of the current directory when calculating the |
| 17220 | amount of space used. |
| 17221 | |
| 17222 | |
| 17223 | .section Using tags to record message sizes |
| 17224 | If \maildir@_tag\ is set, the string is expanded for each delivery. |
| 17225 | When the maildir file is renamed into the \(new)\ sub-directory, the |
| 17226 | tag is added to its name. However, if adding the tag takes the length of the |
| 17227 | name to the point where the test \*stat()*\ call fails with \\ENAMETOOLONG\\, |
| 17228 | the tag is dropped and the maildir file is created with no tag. |
| 17229 | |
| 17230 | Tags can be used to encode the size of files in their names; see |
| 17231 | \quota@_size@_regex\ above for an example. The expansion of \maildir@_tag\ |
| 17232 | happens after the message has been written. The value of the \$message@_size$\ |
| 17233 | variable is set to the number of bytes actually written. If the expansion is |
| 17234 | forced to fail, the tag is ignored, but a non-forced failure causes delivery to |
| 17235 | be deferred. The expanded tag may contain any printing characters except `/'. |
| 17236 | Non-printing characters in the string are ignored; if the resulting string is |
| 17237 | empty, it is ignored. If it starts with an alphanumeric character, a leading |
| 17238 | colon is inserted. |
| 17239 | |
| 17240 | |
| 17241 | .section Using a maildirsize file |
| 17242 | .index quota||in maildir delivery |
| 17243 | .index maildir format||\(maildirsize)\ file |
| 17244 | If \maildir@_use@_size@_file\ is true, Exim implements the maildir++ rules for |
| 17245 | storing quota and message size information in a file called \(maildirsize)\ |
| 17246 | within the maildir directory. If this file does not exist, Exim creates it, |
| 17247 | setting the quota from the \quota\ option of the transport. If the maildir |
| 17248 | directory itself does not exist, it is created before any attempt to write a |
| 17249 | \(maildirsize)\ file. |
| 17250 | |
| 17251 | The \(maildirsize)\ file is used to hold information about the sizes of |
| 17252 | messages in the maildir, thus speeding up quota calculations. The quota value |
| 17253 | in the file is just a cache; if the quota is changed in the transport, the new |
| 17254 | value overrides the cached value when the next message is delivered. The cache |
| 17255 | is maintained for the benefit of other programs that access the maildir and |
| 17256 | need to know the quota. |
| 17257 | |
| 17258 | If the \quota\ option in the transport is unset or zero, the \(maildirsize)\ |
| 17259 | file is maintained (with a zero quota setting), but no quota is imposed. |
| 17260 | |
| 17261 | A regular expression is available for controlling which directories in the |
| 17262 | maildir participate in quota calculations. See the description of the |
| 17263 | \maildir@_quota@_directory@_regex\ option above for details. |
| 17264 | |
| 17265 | |
| 17266 | .section Mailstore delivery |
| 17267 | .index mailstore format||description of |
| 17268 | If the \mailstore@_format\ option is true, each message is written as two files |
| 17269 | in the given directory. A unique base name is constructed from the message id |
| 17270 | and the current delivery process, and the files that are written use this base |
| 17271 | name plus the suffixes \(.env)\ and \(.msg)\. The \(.env)\ file contains the |
| 17272 | message's envelope, and the \(.msg)\ file contains the message itself. |
| 17273 | |
| 17274 | During delivery, the envelope is first written to a file with the suffix |
| 17275 | \(.tmp)\. The \(.msg)\ file is then written, and when it is complete, the |
| 17276 | \(.tmp)\ file is renamed as the \(.env)\ file. Programs that access messages in |
| 17277 | mailstore format should wait for the presence of both a \(.msg)\ and a \(.env)\ |
| 17278 | file before accessing either of them. An alternative approach is to wait for |
| 17279 | the absence of a \(.tmp)\ file. |
| 17280 | |
| 17281 | The envelope file starts with any text defined by the \mailstore@_prefix\ |
| 17282 | option, expanded and terminated by a newline if there isn't one. Then follows |
| 17283 | the sender address on one line, then all the recipient addresses, one per line. |
| 17284 | There can be more than one recipient only if the \batch@_max\ option is set |
| 17285 | greater than one. Finally, \mailstore@_suffix\ is expanded and the result |
| 17286 | appended to the file, followed by a newline if it does not end with one. |
| 17287 | |
| 17288 | If expansion of \mailstore@_prefix\ or \mailstore@_suffix\ ends with a forced |
| 17289 | failure, it is ignored. Other expansion errors are treated as serious |
| 17290 | configuration errors, and delivery is deferred. |
| 17291 | |
| 17292 | |
| 17293 | .section Non-special new file delivery |
| 17294 | If neither \maildir@_format\ nor \mailstore@_format\ is set, a single new file |
| 17295 | is created directly in the named directory. For example, when delivering |
| 17296 | messages into files in batched SMTP format for later delivery to some host (see |
| 17297 | section ~~SECTbatchSMTP), a setting such as |
| 17298 | .display asis |
| 17299 | directory = /var/bsmtp/$host |
| 17300 | .endd |
| 17301 | might be used. A message is written to a file with a temporary name, which is |
| 17302 | then renamed when the delivery is complete. The final name is obtained by |
| 17303 | expanding the contents of the \directory@_file\ option. |
| 17304 | |
| 17305 | |
| 17306 | |
| 17307 | |
| 17308 | |
| 17309 | . |
| 17310 | . |
| 17311 | . |
| 17312 | . |
| 17313 | . ============================================================================ |
| 17314 | .chapter The autoreply transport |
| 17315 | .set runningfoot "autoreply transport" |
| 17316 | .index transports||\%autoreply%\ |
| 17317 | .index \%autoreply%\ transport |
| 17318 | The \%autoreply%\ transport is not a true transport in that it does not cause |
| 17319 | the message to be transmitted. Instead, it generates another mail message. It |
| 17320 | is usually run as the result of mail filtering, a `vacation' message being the |
| 17321 | standard example. However, it can also be run directly from a router like any |
| 17322 | other transport. To reduce the possibility of message cascades, messages |
| 17323 | created by the \%autoreply%\ transport always have empty envelope sender |
| 17324 | addresses, like bounce messages. |
| 17325 | |
| 17326 | The parameters of the message to be sent can be specified in the configuration |
| 17327 | by options described below. However, these are used only when the address |
| 17328 | passed to the transport does not contain its own reply information. When the |
| 17329 | transport is run as a consequence of a |
| 17330 | \mail\ |
| 17331 | or \vacation\ command in a filter file, the parameters of the message are |
| 17332 | supplied by the filter, and passed with the address. The transport's options |
| 17333 | that define the message are then ignored (so they are not usually set in this |
| 17334 | case). The message is specified entirely by the filter or by the transport; it |
| 17335 | is never built from a mixture of options. However, the \file@_optional\, |
| 17336 | \mode\, and \return@_message\ options apply in all cases. |
| 17337 | |
| 17338 | \%Autoreply%\ is implemented as a local transport. When used as a result of a |
| 17339 | command in a user's filter file, \%autoreply%\ normally runs under the uid and |
| 17340 | gid of the user, and with appropriate current and home directories (see chapter |
| 17341 | ~~CHAPenvironment). |
| 17342 | |
| 17343 | There is a subtle difference between routing a message to a \%pipe%\ transport |
| 17344 | that generates some text to be returned to the sender, and routing it to an |
| 17345 | \%autoreply%\ transport. This difference is noticeable only if more than one |
| 17346 | address from the same message is so handled. In the case of a pipe, the |
| 17347 | separate outputs from the different addresses are gathered up and returned to |
| 17348 | the sender in a single message, whereas if \%autoreply%\ is used, a separate |
| 17349 | message is generated for each address that is passed to it. |
| 17350 | |
| 17351 | Non-printing characters are not permitted in the header lines generated for the |
| 17352 | message that \%autoreply%\ creates, with the exception of newlines that are |
| 17353 | immediately followed by whitespace. If any non-printing characters are found, |
| 17354 | the transport defers. |
| 17355 | Whether characters with the top bit set count as printing characters or not is |
| 17356 | controlled by the \print@_topbitchars\ global option. |
| 17357 | |
| 17358 | If any of the generic options for manipulating headers (for example, |
| 17359 | \headers@_add\) are set on an \%autoreply%\ transport, they apply to the copy of |
| 17360 | the original message that is included in the generated message when |
| 17361 | \return@_message\ is set. They do not apply to the generated message itself. |
| 17362 | |
| 17363 | If the \%autoreply%\ transport receives return code 2 from Exim when it submits |
| 17364 | the message, indicating that there were no recipients, it does not treat this |
| 17365 | as an error. This means that autoreplies sent to \$sender@_address$\ when this |
| 17366 | is empty (because the incoming message is a bounce message) do not cause |
| 17367 | problems. They are just discarded. |
| 17368 | |
| 17369 | |
| 17370 | .section Private options for autoreply |
| 17371 | |
| 17372 | .startconf |
| 17373 | .index options||\%autoreply%\ transport |
| 17374 | .conf bcc string$**$ unset |
| 17375 | This specifies the addresses that are to receive `blind carbon copies' of the |
| 17376 | message when the message is specified by the transport. |
| 17377 | |
| 17378 | .conf cc string$**$ unset |
| 17379 | This specifies recipients of the message and the contents of the ::Cc:: header |
| 17380 | when the message is specified by the transport. |
| 17381 | |
| 17382 | .conf file string$**$ unset |
| 17383 | The contents of the file are sent as the body of the message when the message |
| 17384 | is specified by the transport. If both \file\ and \text\ are set, the text |
| 17385 | string comes first. |
| 17386 | |
| 17387 | .conf file@_expand boolean false |
| 17388 | If this is set, the contents of the file named by the \file\ option are |
| 17389 | subjected to string expansion as they are added to the message. |
| 17390 | |
| 17391 | .conf file@_optional boolean false |
| 17392 | If this option is true, no error is generated if the file named by the \file\ |
| 17393 | option or passed with the address does not exist or cannot be read. |
| 17394 | |
| 17395 | .conf from string$**$ unset |
| 17396 | This specifies the contents of the ::From:: header when the message is specified |
| 17397 | by the transport. |
| 17398 | |
| 17399 | .conf headers string$**$ unset |
| 17400 | This specifies additional RFC 2822 headers that are to be added to the message when |
| 17401 | the message is specified by the transport. Several can be given by using `@\n' |
| 17402 | to separate them. There is no check on the format. |
| 17403 | |
| 17404 | .conf log string$**$ unset |
| 17405 | This option names a file in which a record of every message sent is logged when |
| 17406 | the message is specified by the transport. |
| 17407 | |
| 17408 | .conf mode "octal integer" 0600 |
| 17409 | If either the log file or the `once' file has to be created, this mode is used. |
| 17410 | |
| 17411 | .conf once string$**$ unset |
| 17412 | This option names a file or DBM database in which a record of each |
| 17413 | ::To:: recipient is kept when the message is specified by the transport. |
| 17414 | \**Note**\: This does not apply to ::Cc:: or ::Bcc:: recipients. |
| 17415 | If \once@_file@_size\ is not set, a DBM database is used, and it is allowed to |
| 17416 | grow as large as necessary. If a potential recipient is already in the |
| 17417 | database, no message is sent by default. However, if \once@_repeat\ specifies a |
| 17418 | time greater than zero, the message is sent if that much time has elapsed since |
| 17419 | a message was last sent to this recipient. If \once\ is unset, the message is |
| 17420 | always sent. |
| 17421 | |
| 17422 | If \once@_file@_size\ is set greater than zero, it changes the way Exim |
| 17423 | implements the \once\ option. Instead of using a DBM file to record every |
| 17424 | recipient it sends to, it uses a regular file, whose size will never get larger |
| 17425 | than the given value. In the file, it keeps a linear list of recipient |
| 17426 | addresses and times at which they were sent messages. If the file is full when |
| 17427 | a new address needs to be added, the oldest address is dropped. If |
| 17428 | \once@_repeat\ is not set, this means that a given recipient may receive |
| 17429 | multiple messages, but at unpredictable intervals that depend on the rate of |
| 17430 | turnover of addresses in the file. If \once@_repeat\ is set, it specifies a |
| 17431 | maximum time between repeats. |
| 17432 | |
| 17433 | .conf once@_file@_size integer 0 |
| 17434 | See \once\ above. |
| 17435 | |
| 17436 | .conf once@_repeat time$**$ 0s |
| 17437 | See \once\ above. |
| 17438 | After expansion, the value of this option must be a valid time value. |
| 17439 | |
| 17440 | .conf reply@_to string$**$ unset |
| 17441 | This specifies the contents of the ::Reply-To:: header when the message is |
| 17442 | specified by the transport. |
| 17443 | |
| 17444 | .conf return@_message boolean false |
| 17445 | If this is set, a copy of the original message is returned with the new |
| 17446 | message, subject to the maximum size set in the \return@_size@_limit\ global |
| 17447 | configuration option. |
| 17448 | |
| 17449 | .conf subject string$**$ unset |
| 17450 | This specifies the contents of the ::Subject:: header when the message is |
| 17451 | specified by the transport. |
| 17452 | |
| 17453 | .conf text string$**$ unset |
| 17454 | This specifies a single string to be used as the body of the message when the |
| 17455 | message is specified by the transport. If both \text\ and \file\ are set, the |
| 17456 | text comes first. |
| 17457 | |
| 17458 | .conf to string$**$ unset |
| 17459 | This specifies recipients of the message and the contents of the ::To:: header |
| 17460 | when the message is specified by the transport. |
| 17461 | |
| 17462 | .endconf |
| 17463 | |
| 17464 | |
| 17465 | |
| 17466 | . |
| 17467 | . |
| 17468 | . |
| 17469 | . |
| 17470 | . ============================================================================ |
| 17471 | .chapter The lmtp transport |
| 17472 | .set runningfoot "lmtp transport" |
| 17473 | .index transports||\%lmtp%\ |
| 17474 | .index \%lmtp%\ transport |
| 17475 | .index LMTP||over a pipe |
| 17476 | .index LMTP||over a socket |
| 17477 | .rset CHAPLMTP "~~chapter" |
| 17478 | The \%lmtp%\ transport runs the LMTP protocol (RFC 2033) over a pipe to a |
| 17479 | specified command |
| 17480 | or by interacting with a Unix domain socket. |
| 17481 | This transport is something of a cross between the \%pipe%\ and \%smtp%\ |
| 17482 | transports. Exim also has support for using LMTP over TCP/IP; this is |
| 17483 | implemented as an option for the \%smtp%\ transport. Because LMTP is expected |
| 17484 | to be of minority interest, the default build-time configure in \(src/EDITME)\ |
| 17485 | has it commented out. You need to ensure that |
| 17486 | .display asis |
| 17487 | TRANSPORT_LMTP=yes |
| 17488 | .endd |
| 17489 | is present in your \(Local/Makefile)\ in order to have the \%lmtp%\ transport |
| 17490 | included in the Exim binary. |
| 17491 | |
| 17492 | The private options of the \%lmtp%\ transport are as follows: |
| 17493 | |
| 17494 | .startconf |
| 17495 | .index options||\%lmtp%\ transport |
| 17496 | |
| 17497 | .conf batch@_id string$**$ unset |
| 17498 | See the description of local delivery batching in chapter ~~CHAPbatching. |
| 17499 | |
| 17500 | .conf batch@_max integer 1 |
| 17501 | This limits the number of addresses that can be handled in a single delivery. |
| 17502 | Most LMTP servers can handle several addresses at once, so it is normally a |
| 17503 | good idea to increase this value. See the description of local delivery |
| 17504 | batching in chapter ~~CHAPbatching. |
| 17505 | |
| 17506 | .conf command string$**$ unset |
| 17507 | This option must be set if \socket\ is not set. |
| 17508 | The string is a command which is run in a separate process. It is split up into |
| 17509 | a command name and list of arguments, each of which is separately expanded (so |
| 17510 | expansion cannot change the number of arguments). The command is run directly, |
| 17511 | not via a shell. The message is passed to the new process using the standard |
| 17512 | input and output to operate the LMTP protocol. |
| 17513 | |
| 17514 | .conf socket string$**$ unset |
| 17515 | This option must be set if \command\ is not set. The result of expansion must |
| 17516 | be the name of a Unix domain socket. The transport connects to the socket and |
| 17517 | delivers the message to it using the LMTP protocol. |
| 17518 | |
| 17519 | .conf timeout time 5m |
| 17520 | The transport is aborted if the created process |
| 17521 | or Unix domain socket |
| 17522 | does not respond to LMTP commands or message input within this timeout. |
| 17523 | |
| 17524 | .endconf |
| 17525 | |
| 17526 | Here is an example of a typical LMTP transport: |
| 17527 | .display asis |
| 17528 | lmtp: |
| 17529 | driver = lmtp |
| 17530 | command = /some/local/lmtp/delivery/program |
| 17531 | batch_max = 20 |
| 17532 | user = exim |
| 17533 | .endd |
| 17534 | This delivers up to 20 addresses at a time, in a mixture of domains if |
| 17535 | necessary, running as the user \*exim*\. |
| 17536 | |
| 17537 | |
| 17538 | |
| 17539 | . |
| 17540 | . |
| 17541 | . |
| 17542 | . |
| 17543 | . ============================================================================ |
| 17544 | .chapter The pipe transport |
| 17545 | .rset CHAPpipetransport "~~chapter" |
| 17546 | .set runningfoot "pipe transport" |
| 17547 | .index transports||\%pipe%\ |
| 17548 | .index \%pipe%\ transport |
| 17549 | The \%pipe%\ transport is used to deliver messages via a pipe to a command |
| 17550 | running in another process. This can happen in one of two ways: |
| 17551 | .numberpars $. |
| 17552 | A router routes an address to a transport in the normal way, and the transport |
| 17553 | is configured as a \%pipe%\ transport. In this case, \$local@_part$\ contains |
| 17554 | the address (as usual), and the command which is run is specified by the |
| 17555 | \command\ option on the transport. An example of this is the use of \%pipe%\ as |
| 17556 | a pseudo-remote transport for passing messages to some other delivery mechanism |
| 17557 | (such as UUCP). |
| 17558 | .nextp |
| 17559 | A router redirects an address directly to a pipe command (for example, from an |
| 17560 | alias or forward file). In this case, \$local@_part$\ contains the local part |
| 17561 | that was redirected, and \$address@_pipe$\ contains the text of the pipe |
| 17562 | command itself. The \command\ option on the transport is ignored. |
| 17563 | .endp |
| 17564 | |
| 17565 | The \%pipe%\ transport is a non-interactive delivery method. Exim can also |
| 17566 | deliver messages over pipes using the LMTP interactive protocol. This is |
| 17567 | implemented by the \%lmtp%\ transport. |
| 17568 | |
| 17569 | In the case when \%pipe%\ is run as a consequence of an entry in a local user's |
| 17570 | \(.forward)\ file, the command runs under the uid and gid of that user. In |
| 17571 | other cases, the uid and gid have to be specified explicitly, either on the |
| 17572 | transport or on the router that handles the address. Current and `home' |
| 17573 | directories are also controllable. See chapter ~~CHAPenvironment for details of |
| 17574 | the local delivery environment. |
| 17575 | |
| 17576 | .section Returned status and data |
| 17577 | .index \%pipe%\ transport||returned data |
| 17578 | If the command exits with a non-zero return code, the delivery is deemed to |
| 17579 | have failed, unless either the \ignore@_status\ option is set (in which case |
| 17580 | the return code is treated as zero), or the return code is one of those listed |
| 17581 | in the \temp@_errors\ option, which are interpreted as meaning `try again |
| 17582 | later'. In this case, delivery is deferred. Details of a permanent failure are |
| 17583 | logged, but are not included in the bounce message, which merely contains |
| 17584 | `local delivery failed'. |
| 17585 | |
| 17586 | If the return code is greater than 128 and the command being run is a shell |
| 17587 | script, it normally means that the script was terminated by a signal whose |
| 17588 | value is the return code minus 128. |
| 17589 | |
| 17590 | If Exim is unable to run the command (that is, if \*execve()*\ fails), the |
| 17591 | return code is set to 127. This is the value that a shell returns if it is |
| 17592 | asked to run a non-existent command. The wording for the log line suggests that |
| 17593 | a non-existent command may be the problem. |
| 17594 | |
| 17595 | The \return@_output\ option can affect the result of a pipe delivery. If it is |
| 17596 | set and the command produces any output on its standard output or standard |
| 17597 | error streams, the command is considered to have failed, even if it gave a zero |
| 17598 | return code or if \ignore@_status\ is set. The output from the command is |
| 17599 | included as part of the bounce message. The \return@_fail@_output\ option is |
| 17600 | similar, except that output is returned only when the command exits with a |
| 17601 | failure return code, that is, a value other than zero or a code that matches |
| 17602 | \temp@_errors\. |
| 17603 | |
| 17604 | |
| 17605 | .section How the command is run |
| 17606 | .rset SECThowcommandrun "~~chapter.~~section" |
| 17607 | .index \%pipe%\ transport||path for command |
| 17608 | The command line is (by default) broken down into a command name and arguments |
| 17609 | by the \%pipe%\ transport itself. The \allow@_commands\ and \restrict@_to@_path\ |
| 17610 | options can be used to restrict the commands that may be run. |
| 17611 | .index quoting||in pipe command |
| 17612 | Unquoted arguments are delimited by white space. If an argument appears in |
| 17613 | double quotes, backslash is interpreted as an escape character in the usual |
| 17614 | way. If an argument appears in single quotes, no escaping is done. |
| 17615 | |
| 17616 | String expansion is applied to the command line except when it comes from a |
| 17617 | traditional \(.forward)\ file (commands from a filter file are expanded). The |
| 17618 | expansion is applied to each argument in turn rather than to the whole line. |
| 17619 | For this reason, any string expansion item that contains white space must be |
| 17620 | quoted so as to be contained within a single argument. A setting such as |
| 17621 | .display asis |
| 17622 | command = /some/path ${if eq{$local_part}{postmaster}{xxx}{yyy}} |
| 17623 | .endd |
| 17624 | will not work, because the expansion item gets split between several |
| 17625 | arguments. You have to write |
| 17626 | .display asis |
| 17627 | command = /some/path "${if eq{$local_part}{postmaster}{xxx}{yyy}}" |
| 17628 | .endd |
| 17629 | to ensure that it is all in one argument. The expansion is done in this way, |
| 17630 | argument by argument, so that the number of arguments cannot be changed as a |
| 17631 | result of expansion, and quotes or backslashes in inserted variables do not |
| 17632 | interact with external quoting. |
| 17633 | |
| 17634 | .index transport||filter |
| 17635 | .index filter||transport filter |
| 17636 | Special handling takes place when an argument consists of precisely the text |
| 17637 | `$tt{@$pipe@_addresses}'. This is not a general expansion variable; the only |
| 17638 | place this string is recognized is when it appears as an argument for a pipe or |
| 17639 | transport filter command. It causes each address that is being handled to be |
| 17640 | inserted in the argument list at that point $it{as a separate argument}. This |
| 17641 | avoids any problems with spaces or shell metacharacters, and is of use when a |
| 17642 | \%pipe%\ transport is handling groups of addresses in a batch. |
| 17643 | |
| 17644 | After splitting up into arguments and expansion, the resulting command is run |
| 17645 | in a subprocess directly from the transport, $it{not} under a shell. The |
| 17646 | message that is being delivered is supplied on the standard input, and the |
| 17647 | standard output and standard error are both connected to a single pipe that is |
| 17648 | read by Exim. The \max@_output\ option controls how much output the command may |
| 17649 | produce, and the \return@_output\ and \return@_fail@_output\ options control |
| 17650 | what is done with it. |
| 17651 | |
| 17652 | Not running the command under a shell (by default) lessens the security risks |
| 17653 | in cases when a command from a user's filter file is built out of data that was |
| 17654 | taken from an incoming message. If a shell is required, it can of course be |
| 17655 | explicitly specified as the command to be run. However, there are circumstances |
| 17656 | where existing commands (for example, in \(.forward)\ files) expect to be run |
| 17657 | under a shell and cannot easily be modified. To allow for these cases, there is |
| 17658 | an option called \use@_shell\, which changes the way the \%pipe%\ transport |
| 17659 | works. Instead of breaking up the command line as just described, it expands it |
| 17660 | as a single string and passes the result to \(/bin/sh)\. The |
| 17661 | \restrict@_to@_path\ option and the \$pipe@_addresses$\ facility cannot be used |
| 17662 | with \use@_shell\, and the whole mechanism is inherently less secure. |
| 17663 | |
| 17664 | |
| 17665 | .section Environment variables |
| 17666 | .rset SECTpipeenv "~~chapter.~~section" |
| 17667 | .index \%pipe%\ transport||environment for command |
| 17668 | .index environment for pipe transport |
| 17669 | The environment variables listed below are set up when the command is invoked. |
| 17670 | This list is a compromise for maximum compatibility with other MTAs. Note that |
| 17671 | the \environment\ option can be used to add additional variables to this |
| 17672 | environment. |
| 17673 | .display flow |
| 17674 | .tabs 20 |
| 17675 | DOMAIN $t $rm{the domain of the address} |
| 17676 | HOME $t $rm{the home directory, if set} |
| 17677 | HOST $t $rm{the host name when called from a router (see below)} |
| 17678 | LOCAL@_PART $t $rm{see below} |
| 17679 | LOCAL@_PART@_PREFIX $t $rm{see below} |
| 17680 | LOCAL@_PART@_SUFFIX $t $rm{see below} |
| 17681 | LOGNAME $t $rm{see below} |
| 17682 | MESSAGE@_ID $t $rm{the message's id} |
| 17683 | PATH $t $rm{as specified by the \path\ option below} |
| 17684 | QUALIFY@_DOMAIN $t $rm{the sender qualification domain} |
| 17685 | RECIPIENT $t $rm{the complete recipient address} |
| 17686 | SENDER $t $rm{the sender of the message (empty if a bounce)} |
| 17687 | SHELL $t `$tt{/bin/sh}' |
| 17688 | TZ $t $rm{the value of the \timezone\ option, if set} |
| 17689 | USER $t $rm{see below} |
| 17690 | .endd |
| 17691 | |
| 17692 | When a \%pipe%\ transport is called directly from (for example) an \%accept%\ |
| 17693 | router, \\LOCAL@_PART\\ is set to the local part of the address. When it is |
| 17694 | called as a result of a forward or alias expansion, \\LOCAL@_PART\\ is set to |
| 17695 | the local part of the address that was expanded. In both cases, any affixes are |
| 17696 | removed from the local part, and made available in \\LOCAL@_PART@_PREFIX\\ and |
| 17697 | \\LOCAL@_PART@_SUFFIX\\, respectively. \\LOGNAME\\ and \\USER\\ are set to the |
| 17698 | same value as \\LOCAL@_PART\\ for compatibility with other MTAs. |
| 17699 | |
| 17700 | .index \\HOST\\ |
| 17701 | \\HOST\\ is set only when a \%pipe%\ transport is called from a router that |
| 17702 | associates hosts with an address, typically when using \%pipe%\ as a |
| 17703 | pseudo-remote transport. \\HOST\\ is set to the first host name specified by |
| 17704 | the router. |
| 17705 | |
| 17706 | .index \\HOME\\ |
| 17707 | If the transport's generic \home@_directory\ option is set, its value is used |
| 17708 | for the \\HOME\\ environment variable. Otherwise, a home directory may be set |
| 17709 | by the router's \transport@_home@_directory\ option, which defaults to the |
| 17710 | user's home directory if \check@_local@_user\ is set. |
| 17711 | |
| 17712 | .section Private options for pipe |
| 17713 | .index options||\%pipe%\ transport |
| 17714 | .startconf |
| 17715 | |
| 17716 | .conf allow@_commands "string list$**$" unset |
| 17717 | .index \%pipe%\ transport||permitted commands |
| 17718 | The string is expanded, and is then interpreted as a colon-separated list of |
| 17719 | permitted commands. If \restrict@_to@_path\ is not set, the only commands |
| 17720 | permitted are those in the \allow@_commands\ list. They need not be absolute |
| 17721 | paths; the \path\ option is still used for relative paths. If |
| 17722 | \restrict@_to@_path\ is set with \allow@_commands\, the command must either be |
| 17723 | in the \allow@_commands\ list, or a name without any slashes that is found on |
| 17724 | the path. In other words, if neither \allow@_commands\ nor \restrict@_to@_path\ |
| 17725 | is set, there is no restriction on the command, but otherwise only commands |
| 17726 | that are permitted by one or the other are allowed. For example, if |
| 17727 | .display asis |
| 17728 | allow_commands = /usr/bin/vacation |
| 17729 | .endd |
| 17730 | and \restrict@_to@_path\ is not set, the only permitted command is |
| 17731 | \(/usr/bin/vacation)\. The \allow@_commands\ option may not be set if |
| 17732 | \use@_shell\ is set. |
| 17733 | |
| 17734 | .conf batch@_id string$**$ unset |
| 17735 | See the description of local delivery batching in chapter ~~CHAPbatching. |
| 17736 | |
| 17737 | .conf batch@_max integer 1 |
| 17738 | This limits the number of addresses that can be handled in a single delivery. |
| 17739 | See the description of local delivery batching in chapter ~~CHAPbatching. |
| 17740 | |
| 17741 | .conf check@_string string unset |
| 17742 | As \%pipe%\ writes the message, the start of each line is tested for matching |
| 17743 | \check@_string\, and if it does, the initial matching characters are replaced |
| 17744 | by the contents of \escape@_string\, provided both are set. The value of |
| 17745 | \check@_string\ is a literal string, not a regular expression, and the case of |
| 17746 | any letters it contains is significant. When \use@_bsmtp\ is set, the contents |
| 17747 | of \check@_string\ and \escape@_string\ are forced to values that implement the |
| 17748 | SMTP escaping protocol. Any settings made in the configuration file are |
| 17749 | ignored. |
| 17750 | |
| 17751 | .conf command string$**$ unset |
| 17752 | This option need not be set when \%pipe%\ is being used to deliver to pipes |
| 17753 | obtained directly from address redirections. In other cases, the option must be |
| 17754 | set, to provide a command to be run. It need not yield an absolute path (see |
| 17755 | the \path\ option below). The command is split up into separate arguments by |
| 17756 | Exim, and each argument is separately expanded, as described in section |
| 17757 | ~~SECThowcommandrun above. |
| 17758 | |
| 17759 | .conf environment string$**$ unset |
| 17760 | .index \%pipe%\ transport||environment for command |
| 17761 | .index environment for \%pipe%\ transport |
| 17762 | This option is used to add additional variables to the environment in which the |
| 17763 | command runs (see section ~~SECTpipeenv for the default list). Its value is a |
| 17764 | string which is expanded, and then interpreted as a colon-separated list of |
| 17765 | environment settings of the form `<<name>>=<<value>>'. |
| 17766 | |
| 17767 | .conf escape@_string string unset |
| 17768 | See \check@_string\ above. |
| 17769 | |
| 17770 | .conf freeze@_exec@_fail boolean false |
| 17771 | .index exec failure |
| 17772 | .index failure of exec |
| 17773 | .index \%pipe%\ transport||failure of exec |
| 17774 | Failure to exec the command in a pipe transport is by default treated like |
| 17775 | any other failure while running the command. However, if \freeze@_exec@_fail\ |
| 17776 | is set, failure to exec is treated specially, and causes the message to be |
| 17777 | frozen, whatever the setting of \ignore@_status\. |
| 17778 | |
| 17779 | .conf ignore@_status boolean false |
| 17780 | If this option is true, the status returned by the subprocess that is set up to |
| 17781 | run the command is ignored, and Exim behaves as if zero had been returned. |
| 17782 | Otherwise, a non-zero status |
| 17783 | or termination by signal |
| 17784 | causes an error return from the transport unless the status value is one of |
| 17785 | those listed in \temp@_errors\; these cause the delivery to be deferred and |
| 17786 | tried again later. |
| 17787 | |
| 17788 | .conf log@_defer@_output boolean false |
| 17789 | .index \%pipe%\ transport||logging output |
| 17790 | If this option is set, and the status returned by the command is |
| 17791 | one of the codes listed in \temp@_errors\ (that is, delivery was deferred), |
| 17792 | and any output was produced, the first line of it is written to the main log. |
| 17793 | |
| 17794 | .conf log@_fail@_output boolean false |
| 17795 | If this option is set, and the command returns any output, and also ends with a |
| 17796 | return code that is neither zero nor one of the return codes listed in |
| 17797 | \temp@_errors\ (that is, the delivery failed), the first line of output is |
| 17798 | written to the main log. |
| 17799 | |
| 17800 | .conf log@_output boolean false |
| 17801 | If this option is set and the command returns any output, the first line of |
| 17802 | output is written to the main log, whatever the return code. |
| 17803 | |
| 17804 | .conf max@_output integer 20K |
| 17805 | This specifies the maximum amount of output that the command may produce on its |
| 17806 | standard output and standard error file combined. If the limit is exceeded, the |
| 17807 | process running the command is killed. This is intended as a safety measure to |
| 17808 | catch runaway processes. The limit is applied independently of the settings of |
| 17809 | the options that control what is done with such output (for example, |
| 17810 | \return@_output\). Because of buffering effects, the amount of output may |
| 17811 | exceed the limit by a small amount before Exim notices. |
| 17812 | |
| 17813 | .conf message@_prefix string$**$ "see below" |
| 17814 | The string specified here is expanded and output at the start of every message. |
| 17815 | The default is unset if \use@_bsmtp\ is set. Otherwise it is |
| 17816 | .display asis |
| 17817 | message_prefix = \ |
| 17818 | From ${if def:return_path{$return_path}{MAILER-DAEMON}}\ |
| 17819 | ${tod_bsdinbox}\n |
| 17820 | .endd |
| 17821 | .index Cyrus |
| 17822 | .index \tmail\ |
| 17823 | .index `From' line |
| 17824 | This is required by the commonly used \(/usr/bin/vacation)\ program. |
| 17825 | However, it must $it{not} be present if delivery is to the Cyrus IMAP server, |
| 17826 | or to the \tmail\ local delivery agent. The prefix can be suppressed by setting |
| 17827 | .display asis |
| 17828 | message_prefix = |
| 17829 | .endd |
| 17830 | |
| 17831 | .conf message@_suffix string$**$ "see below" |
| 17832 | The string specified here is expanded and output at the end of every message. |
| 17833 | The default is unset if \use@_bsmtp\ is set. Otherwise it is a single newline. |
| 17834 | The suffix can be suppressed by setting |
| 17835 | .display asis |
| 17836 | message_suffix = |
| 17837 | .endd |
| 17838 | |
| 17839 | .conf path string $tt{/usr/bin} |
| 17840 | This option specifies the string that is set up in the \\PATH\\ environment |
| 17841 | variable of the subprocess. If the \command\ option does not yield an absolute |
| 17842 | path name, the command is sought in the \\PATH\\ directories, in the usual way. |
| 17843 | \**Warning**\: This does not apply to a command specified as a transport |
| 17844 | filter. |
| 17845 | |
| 17846 | .conf pipe@_as@_creator boolean false |
| 17847 | .index uid (user id)||local delivery |
| 17848 | If the generic \user\ option is not set and this option is true, the delivery |
| 17849 | process is run under the uid that was in force when Exim was originally called |
| 17850 | to accept the message. If the group id is not otherwise set (via the generic |
| 17851 | \group\ option), the gid that was in force when Exim was originally called to |
| 17852 | accept the message is used. |
| 17853 | |
| 17854 | .conf restrict@_to@_path boolean false |
| 17855 | When this option is set, any command name not listed in \allow@_commands\ must |
| 17856 | contain no slashes. The command is searched for only in the directories listed |
| 17857 | in the \path\ option. This option is intended for use in the case when a pipe |
| 17858 | command has been generated from a user's \(.forward)\ file. This is usually |
| 17859 | handled by a \%pipe%\ transport called \address@_pipe\. |
| 17860 | |
| 17861 | .conf return@_fail@_output boolean false |
| 17862 | If this option is true, and the command produced any output and ended with a |
| 17863 | return code other than zero or one of the codes listed in \temp@_errors\ (that |
| 17864 | is, the delivery failed), the output is returned in the bounce message. |
| 17865 | However, if the message has a null sender (that is, it is itself a bounce |
| 17866 | message), output from the command is discarded. |
| 17867 | |
| 17868 | .conf return@_output boolean false |
| 17869 | If this option is true, and the command produced any output, the delivery is |
| 17870 | deemed to have failed whatever the return code from the command, and the output |
| 17871 | is returned in the bounce message. Otherwise, the output is just discarded. |
| 17872 | However, if the message has a null sender (that is, it is a bounce message), |
| 17873 | output from the command is always discarded, whatever the setting of this |
| 17874 | option. |
| 17875 | |
| 17876 | .conf temp@_errors "string list" "see below" |
| 17877 | .index \%pipe%\ transport||temporary failure |
| 17878 | This option contains either a colon-separated list of numbers, or a single |
| 17879 | asterisk. If \ignore@_status\ is false |
| 17880 | and \return@_output\ is not set, |
| 17881 | and the command exits with a non-zero return code, the failure is treated as |
| 17882 | temporary and the delivery is deferred if the return code matches one of the |
| 17883 | numbers, or if the setting is a single asterisk. Otherwise, non-zero return |
| 17884 | codes are treated as permanent errors. The default setting contains the codes |
| 17885 | defined by \\EX@_TEMPFAIL\\ and \\EX@_CANTCREAT\\ in \(sysexits.h)\. If Exim is |
| 17886 | compiled on a system that does not define these macros, it assumes values of 75 |
| 17887 | and 73, respectively. |
| 17888 | |
| 17889 | .conf timeout time 1h |
| 17890 | If the command fails to complete within this time, it is killed. This normally |
| 17891 | causes the delivery to fail. A zero time interval specifies no timeout. In |
| 17892 | order to ensure that any subprocesses created by the command are also killed, |
| 17893 | Exim makes the initial process a process group leader, and kills the whole |
| 17894 | process group on a timeout. However, this can be defeated if one of the |
| 17895 | processes starts a new process group. |
| 17896 | |
| 17897 | .conf umask "octal integer" 022 |
| 17898 | This specifies the umask setting for the subprocess that runs the command. |
| 17899 | |
| 17900 | .conf use@_bsmtp boolean false |
| 17901 | .index envelope sender |
| 17902 | If this option is set true, the \%pipe%\ transport writes messages in `batch |
| 17903 | SMTP' format, with the envelope sender and recipient(s) included as SMTP |
| 17904 | commands. If you want to include a leading \\HELO\\ command with such messages, |
| 17905 | you can do so by setting the \message@_prefix\ option. See section |
| 17906 | ~~SECTbatchSMTP for details of batch SMTP. |
| 17907 | |
| 17908 | .conf use@_crlf boolean false |
| 17909 | .index carriage return |
| 17910 | .index linefeed |
| 17911 | This option causes lines to be terminated with the two-character CRLF sequence |
| 17912 | (carriage return, linefeed) instead of just a linefeed character. In the case |
| 17913 | of batched SMTP, the byte sequence written to the pipe is then an exact image |
| 17914 | of what would be sent down a real SMTP connection. |
| 17915 | |
| 17916 | The contents of the \message@_prefix\ and \message@_suffix\ options are written |
| 17917 | verbatim, so must contain their own carriage return characters if these are |
| 17918 | needed. Since the default values for both \message@_prefix\ and |
| 17919 | \message@_suffix\ end with a single linefeed, their values |
| 17920 | must |
| 17921 | be changed to end with \"@\r@\n"\ if \use@_crlf\ is set. |
| 17922 | |
| 17923 | .conf use@_shell boolean false |
| 17924 | If this option is set, it causes the command to be passed to \(/bin/sh)\ |
| 17925 | instead of being run directly from the transport, as described in section |
| 17926 | ~~SECThowcommandrun. This is less secure, but is needed in some situations |
| 17927 | where the command is expected to be run under a shell and cannot easily be |
| 17928 | modified. The \allow@_commands\ and \restrict@_to@_path\ options, and the |
| 17929 | `$tt{@$pipe@_addresses}' facility are incompatible with \use@_shell\. The |
| 17930 | command is expanded as a single string, and handed to \(/bin/sh)\ as data for |
| 17931 | its \-c-\ option. |
| 17932 | |
| 17933 | .endconf |
| 17934 | |
| 17935 | .section Using an external local delivery agent |
| 17936 | .index local delivery||using an external agent |
| 17937 | .index \*procmail*\ |
| 17938 | .index external local delivery |
| 17939 | .index delivery||\*procmail*\ |
| 17940 | .index delivery||by external agent |
| 17941 | The \%pipe%\ transport can be used to pass all messages that require local |
| 17942 | delivery to a separate local delivery agent such as \procmail\. When doing |
| 17943 | this, care must be taken to ensure that the pipe is run under an appropriate |
| 17944 | uid and gid. In some configurations one wants this to be a uid that is trusted |
| 17945 | by the delivery agent to supply the correct sender of the message. It may be |
| 17946 | necessary to recompile or reconfigure the delivery agent so that it trusts an |
| 17947 | appropriate user. The following is an example transport and router |
| 17948 | configuration for \procmail\: |
| 17949 | .display asis |
| 17950 | # transport |
| 17951 | procmail_pipe: |
| 17952 | driver = pipe |
| 17953 | command = /usr/local/bin/procmail -d $local_part |
| 17954 | return_path_add |
| 17955 | delivery_date_add |
| 17956 | envelope_to_add |
| 17957 | check_string = "From " |
| 17958 | escape_string = ">From " |
| 17959 | user = $local_part |
| 17960 | group = mail |
| 17961 | .endd |
| 17962 | .display asis |
| 17963 | # router |
| 17964 | procmail: |
| 17965 | driver = accept |
| 17966 | check_local_user |
| 17967 | transport = procmail_pipe |
| 17968 | .endd |
| 17969 | |
| 17970 | In this example, the pipe is run as the local user, but with the group set to |
| 17971 | \*mail*\. An alternative is to run the pipe as a specific user such as \*mail*\ |
| 17972 | or \*exim*\, but in this case you must arrange for \procmail\ to trust that |
| 17973 | user to supply a correct sender address. If you do not specify either a \group\ |
| 17974 | or a \user\ option, the pipe command is run as the local user. The home |
| 17975 | directory is the user's home directory by default. |
| 17976 | |
| 17977 | Note that the command that the pipe transport runs does $it{not} begin with |
| 17978 | .display asis |
| 17979 | IFS=" " |
| 17980 | .endd |
| 17981 | as shown in the \procmail\ documentation, because Exim does not by default use |
| 17982 | a shell to run pipe commands. |
| 17983 | |
| 17984 | .index Cyrus |
| 17985 | The next example shows a transport and a router for a system where local |
| 17986 | deliveries are handled by the Cyrus IMAP server. |
| 17987 | .display asis |
| 17988 | # transport |
| 17989 | local_delivery_cyrus: |
| 17990 | driver = pipe |
| 17991 | command = /usr/cyrus/bin/deliver \ |
| 17992 | -m ${substr_1:$local_part_suffix} -- $local_part |
| 17993 | user = cyrus |
| 17994 | group = mail |
| 17995 | return_output |
| 17996 | log_output |
| 17997 | message_prefix = |
| 17998 | message_suffix = |
| 17999 | .endd |
| 18000 | .display asis |
| 18001 | # router |
| 18002 | local_user_cyrus: |
| 18003 | driver = accept |
| 18004 | check_local_user |
| 18005 | local_part_suffix = .* |
| 18006 | transport = local_delivery_cyrus |
| 18007 | .endd |
| 18008 | Note the unsetting of \message@_prefix\ and \message@_suffix\, and the use of |
| 18009 | \return@_output\ to cause any text written by Cyrus to be returned to the |
| 18010 | sender. |
| 18011 | |
| 18012 | |
| 18013 | . |
| 18014 | . |
| 18015 | . |
| 18016 | . |
| 18017 | . ============================================================================ |
| 18018 | .chapter The smtp transport |
| 18019 | .rset CHAPsmtptrans "~~chapter" |
| 18020 | .set runningfoot "smtp transport" |
| 18021 | .index transports||\%smtp%\ |
| 18022 | .index \%smtp%\ transport |
| 18023 | The \%smtp%\ transport delivers messages over TCP/IP connections using the SMTP |
| 18024 | or LMTP protocol. The list of hosts to try can either be taken from the address |
| 18025 | that is being processed (having been set up by the router), or specified |
| 18026 | explicitly for the transport. Timeout and retry processing (see chapter |
| 18027 | ~~CHAPretry) is applied to each IP address independently. |
| 18028 | |
| 18029 | .section Multiple messages on a single connection |
| 18030 | The sending of multiple messages over a single TCP/IP connection can arise in |
| 18031 | two ways: |
| 18032 | .numberpars $. |
| 18033 | If a message contains more than \max@_rcpt\ (see below) addresses that are |
| 18034 | routed to the same host, more than one copy of the message has to be sent to |
| 18035 | that host. In this situation, multiple copies may be sent in a single run of |
| 18036 | the \%smtp%\ transport over a single TCP/IP connection. (What Exim actually does |
| 18037 | when it has too many addresses to send in one message also depends on the value |
| 18038 | of the global \remote@_max@_parallel\ option. Details are given in section |
| 18039 | ~~SECToutSMTPTCP.) |
| 18040 | .nextp |
| 18041 | .index hints database||remembering routing |
| 18042 | When a message has been successfully delivered over a TCP/IP connection, Exim |
| 18043 | looks in its hints database to see if there are any other messages awaiting a |
| 18044 | connection to the same host. If there are, a new delivery process is started |
| 18045 | for one of them, and the current TCP/IP connection is passed on to it. The new |
| 18046 | process may in turn send multiple copies and possibly create yet another |
| 18047 | process. |
| 18048 | .endp |
| 18049 | |
| 18050 | For each copy sent over the same TCP/IP connection, a sequence counter is |
| 18051 | incremented, and if it ever gets to the value of \connection@_max@_messages\, |
| 18052 | no further messages are sent over that connection. |
| 18053 | |
| 18054 | |
| 18055 | .section Use of the @$host variable |
| 18056 | .index \$host$\ |
| 18057 | .index \$host@_address$\ |
| 18058 | At the start of a run of the \%smtp%\ transport, the values of \$host$\ and |
| 18059 | \$host@_address$\ are the name and IP address of the first host on the host list |
| 18060 | passed by the router. However, when the transport is about to connect to a |
| 18061 | specific host, and while it is connected to that host, \$host$\ and |
| 18062 | \$host@_address$\ are set to the values for that host. These are the values |
| 18063 | that are in force when the \helo@_data\, \hosts@_try@_auth\, \interface\, |
| 18064 | \serialize@_hosts\, and the various TLS options are expanded. |
| 18065 | |
| 18066 | |
| 18067 | .section Private options for smtp |
| 18068 | The private options of the \%smtp%\ transport are as follows: |
| 18069 | |
| 18070 | .index options||\%smtp%\ transport |
| 18071 | .startconf |
| 18072 | .conf allow@_localhost boolean false |
| 18073 | .index local host||sending to |
| 18074 | .index fallback||hosts specified on transport |
| 18075 | When a host specified in \hosts\ or \fallback@_hosts\ (see below) turns out to |
| 18076 | be the local host, or is listed in \hosts@_treat@_as@_local\, delivery is |
| 18077 | deferred by default. However, if \allow@_localhost\ is set, Exim goes on to do |
| 18078 | the delivery anyway. This should be used only in special cases when the |
| 18079 | configuration ensures that no looping will result (for example, a differently |
| 18080 | configured Exim is listening on the port to which the message is sent). |
| 18081 | |
| 18082 | .conf authenticated@_sender string$**$ unset |
| 18083 | .index Cyrus |
| 18084 | When Exim has authenticated as a client, this option sets a value for the |
| 18085 | \\AUTH=\\ item on outgoing \\MAIL\\ commands, overriding any existing |
| 18086 | authenticated sender value. If the string expansion is forced to fail, the |
| 18087 | option is ignored. Other expansion failures cause delivery to be deferred. If |
| 18088 | the result of expansion is an empty string, that is also ignored. |
| 18089 | |
| 18090 | If the SMTP session is not authenticated, the expansion of |
| 18091 | \authenticated@_sender\ still happens (and can cause the delivery to be |
| 18092 | deferred if it fails), but no \\AUTH=\\ item is added to \\MAIL\\ commands. |
| 18093 | |
| 18094 | This option allows you to use the \%smtp%\ transport in LMTP mode to |
| 18095 | deliver mail to Cyrus IMAP and provide the proper local part as the |
| 18096 | `authenticated sender', via a setting such as: |
| 18097 | .display asis |
| 18098 | authenticated_sender = $local_part |
| 18099 | .endd |
| 18100 | This removes the need for IMAP subfolders to be assigned special ACLs to |
| 18101 | allow direct delivery to those subfolders. |
| 18102 | |
| 18103 | Because of expected uses such as that just described for Cyrus (when no |
| 18104 | domain is involved), there is no checking on the syntax of the provided |
| 18105 | value. |
| 18106 | |
| 18107 | .conf command@_timeout time 5m |
| 18108 | This sets a timeout for receiving a response to an SMTP command that has been |
| 18109 | sent out. It is also used when waiting for the initial banner line from the |
| 18110 | remote host. Its value must not be zero. |
| 18111 | |
| 18112 | .conf connect@_timeout time 5m |
| 18113 | This sets a timeout for the \*connect()*\ function, which sets up a TCP/IP call |
| 18114 | to a remote host. A setting of zero allows the system timeout (typically |
| 18115 | several minutes) to act. To have any effect, the value of this option must be |
| 18116 | less than the system timeout. However, it has been observed that on some |
| 18117 | systems there is no system timeout, which is why the default value for this |
| 18118 | option is 5 minutes, a value recommended by RFC 1123. |
| 18119 | |
| 18120 | .index SMTP||passed connection |
| 18121 | .index SMTP||multiple deliveries |
| 18122 | .index multiple SMTP deliveries |
| 18123 | .conf connection@_max@_messages integer 500 |
| 18124 | This controls the maximum number of separate message deliveries that are sent |
| 18125 | over a single TCP/IP connection. If the value is zero, there is no limit. |
| 18126 | For testing purposes, this value can be overridden by the \-oB-\ command line |
| 18127 | option. |
| 18128 | |
| 18129 | .conf data@_timeout time 5m |
| 18130 | This sets a timeout for the transmission of each block in the data portion of |
| 18131 | the message. As a result, the overall timeout for a message depends on the size |
| 18132 | of the message. Its value must not be zero. See also \final@_timeout\. |
| 18133 | |
| 18134 | .conf delay@_after@_cutoff boolean true |
| 18135 | This option controls what happens when all remote IP addresses for a given |
| 18136 | domain have been inaccessible for so long that they have passed their retry |
| 18137 | cutoff times. |
| 18138 | |
| 18139 | In the default state, if the next retry time has not been reached for any of |
| 18140 | them, the address is bounced without trying any deliveries. In other words, |
| 18141 | Exim delays retrying an IP address after the final cutoff time until a new |
| 18142 | retry time is reached, and can therefore bounce an address without ever trying |
| 18143 | a delivery, when machines have been down for a long time. Some people are |
| 18144 | unhappy at this prospect, so... |
| 18145 | |
| 18146 | If \delay@_after@_cutoff\ is set false, Exim behaves differently. If all IP |
| 18147 | addresses are past their final cutoff time, Exim tries to deliver to those |
| 18148 | IP addresses that have not been tried since the message arrived. If there are |
| 18149 | none, of if they all fail, the address is bounced. In other words, it does not |
| 18150 | delay when a new message arrives, but immediately tries those expired IP |
| 18151 | addresses that haven't been tried since the message arrived. If there is a |
| 18152 | continuous stream of messages for the dead hosts, unsetting |
| 18153 | \delay@_after@_cutoff\ means that there will be many more attempts to deliver |
| 18154 | to them. |
| 18155 | |
| 18156 | .conf dns@_qualify@_single boolean true |
| 18157 | If the \hosts\ or \fallback@_hosts\ option is being used, |
| 18158 | and the \gethostbyname\ option is false, |
| 18159 | the \\RES@_DEFNAMES\\ resolver option is set. See the \qualify@_single\ option |
| 18160 | in chapter ~~CHAPdnslookup for more details. |
| 18161 | |
| 18162 | .conf dns@_search@_parents boolean false |
| 18163 | .index \search@_parents\ |
| 18164 | If the \hosts\ or \fallback@_hosts\ option is being used, and the |
| 18165 | \gethostbyname\ option is false, the \\RES@_DNSRCH\\ resolver option is set. |
| 18166 | See the \search@_parents\ option in chapter ~~CHAPdnslookup for more details. |
| 18167 | |
| 18168 | |
| 18169 | .conf fallback@_hosts "string list" unset |
| 18170 | .index fallback||hosts specified on transport |
| 18171 | String expansion is not applied to this option. The argument must be a |
| 18172 | colon-separated list of host names or IP addresses. Fallback hosts can also be |
| 18173 | specified on routers, which associate them with the addresses they process. As |
| 18174 | for the \hosts\ option without \hosts@_override\, \fallback@_hosts\ specified |
| 18175 | on the transport is used only if the address does not have its own associated |
| 18176 | fallback host list. Unlike \hosts\, a setting of \fallback@_hosts\ on an |
| 18177 | address is not overridden by \hosts@_override\. However, \hosts@_randomize\ |
| 18178 | does apply to fallback host lists. |
| 18179 | |
| 18180 | If Exim is unable to deliver to any of the hosts for a particular address, and |
| 18181 | the errors are not permanent rejections, the address is put on a separate |
| 18182 | transport queue with its host list replaced by the fallback hosts, unless the |
| 18183 | address was routed via MX records and the current host was in the original MX |
| 18184 | list. In that situation, the fallback host list is not used. |
| 18185 | |
| 18186 | Once normal deliveries are complete, the fallback queue is delivered by |
| 18187 | re-running the same transports with the new host lists. If several failing |
| 18188 | addresses have the same fallback hosts (and \max@_rcpt\ permits it), a single |
| 18189 | copy of the message is sent. |
| 18190 | |
| 18191 | The resolution of the host names on the fallback list is controlled by the |
| 18192 | \gethostbyname\ option, as for the \hosts\ option. Fallback hosts apply |
| 18193 | both to cases when the host list comes with the address and when it is taken |
| 18194 | from \hosts\. This option provides a `use a smart host only if delivery fails' |
| 18195 | facility. |
| 18196 | |
| 18197 | .conf final@_timeout time 10m |
| 18198 | This is the timeout that applies while waiting for the response to the final |
| 18199 | line containing just `.' that terminates a message. Its value must not be zero. |
| 18200 | |
| 18201 | .conf gethostbyname boolean false |
| 18202 | If this option is true when the \hosts\ and/or \fallback@_hosts\ options are |
| 18203 | being used, names are looked up using \*gethostbyname()*\ |
| 18204 | (or \*getipnodebyname()*\ when available) |
| 18205 | instead of using the DNS. Of course, that function may in fact use the DNS, but |
| 18206 | it may also consult other sources of information such as \(/etc/hosts)\. |
| 18207 | |
| 18208 | .index \\HELO\\||argument, setting |
| 18209 | .index \\EHLO\\||argument, setting |
| 18210 | .conf helo@_data string$**$ $tt{@$primary@_hostname} |
| 18211 | The value of this option is expanded, and used as the argument for the \\EHLO\\ |
| 18212 | or \\HELO\\ command that starts the outgoing SMTP session. |
| 18213 | |
| 18214 | .conf hosts "string list$**$" unset |
| 18215 | Hosts are associated with an address by a router such as \%dnslookup%\, which |
| 18216 | finds the hosts by looking up the address domain in the DNS. However, addresses |
| 18217 | can be passed to the \%smtp%\ transport by any router, and not all of them can |
| 18218 | provide an associated host list. The \hosts\ option specifies a list of hosts |
| 18219 | which are used if the address being processed does not have any hosts |
| 18220 | associated with it. The hosts specified by \hosts\ are also used, whether or |
| 18221 | not the address has its own hosts, if \hosts@_override\ is set. |
| 18222 | |
| 18223 | The string is first expanded, before being interpreted as a colon-separated |
| 18224 | list of host names or IP addresses. If the expansion fails, delivery is |
| 18225 | deferred. Unless the failure was caused by the inability to complete a lookup, |
| 18226 | the error is logged to the panic log as well as the main log. Host names are |
| 18227 | looked up either by searching directly for address records in the DNS or by |
| 18228 | calling \*gethostbyname()*\ |
| 18229 | (or \*getipnodebyname()*\ when available), |
| 18230 | depending on the setting of the \gethostbyname\ option. When Exim is compiled |
| 18231 | with IPv6 support, if a host that is looked up in the DNS has both IPv4 and |
| 18232 | IPv6 addresses, both types of address are used. |
| 18233 | |
| 18234 | During delivery, the hosts are tried in order, subject to their retry status, |
| 18235 | unless \hosts@_randomize\ is set. |
| 18236 | |
| 18237 | .conf hosts@_avoid@_esmtp "host list$**$" unset |
| 18238 | .index ESMTP, avoiding use of |
| 18239 | .index \\HELO\\||forcing use of |
| 18240 | .index \\EHLO\\||avoiding use of |
| 18241 | .index \\PIPELINING\\||avoiding the use of |
| 18242 | This option is for use with broken hosts that announce ESMTP facilities (for |
| 18243 | example, \\PIPELINING\\) and then fail to implement them properly. When a host |
| 18244 | matches \hosts@_avoid@_esmtp\, Exim sends \\HELO\\ rather than \\EHLO\\ at the |
| 18245 | start of the SMTP session. This means that it cannot use any of the ESMTP |
| 18246 | facilities such as \\AUTH\\, \\PIPELINING\\, \\SIZE\\, and \\STARTTLS\\. |
| 18247 | |
| 18248 | .conf hosts@_avoid@_tls "host list$**$" unset |
| 18249 | .index TLS||avoiding for certain hosts |
| 18250 | Exim will not try to start a TLS session when delivering to any host that |
| 18251 | matches this list. See chapter ~~CHAPTLS for details of TLS. |
| 18252 | |
| 18253 | .conf hosts@_max@_try integer 5 |
| 18254 | .index host||maximum number to try |
| 18255 | .index limit||number of hosts tried |
| 18256 | .index limit||number of MX tried |
| 18257 | .index MX record||maximum tried |
| 18258 | This option limits the number of IP addresses that are tried for any one |
| 18259 | delivery |
| 18260 | in cases where there are temporary delivery errors. |
| 18261 | Section ~~SECTvalhosmax describes in detail how the value of this option is |
| 18262 | used. |
| 18263 | |
| 18264 | .conf hosts@_nopass@_tls "host list$**$" unset |
| 18265 | .index TLS||passing connection |
| 18266 | .index multiple SMTP deliveries |
| 18267 | .index TLS||multiple message deliveries |
| 18268 | For any host that matches this list, a connection on which a TLS session has |
| 18269 | been started will not be passed to a new delivery process for sending another |
| 18270 | message on the same connection. See section ~~SECTmulmessam for an explanation |
| 18271 | of when this might be needed. |
| 18272 | |
| 18273 | .conf hosts@_override boolean false |
| 18274 | If this option is set and the \hosts\ option is also set, any hosts that are |
| 18275 | attached to the address are ignored, and instead the hosts specified by the |
| 18276 | \hosts\ option are always used. This option does not apply to |
| 18277 | \fallback@_hosts\. |
| 18278 | |
| 18279 | .conf hosts@_randomize boolean false |
| 18280 | .index randomized host list |
| 18281 | .index host||list of, randomized |
| 18282 | .index fallback||randomized hosts |
| 18283 | If this option is set, and either the list of hosts is taken from the |
| 18284 | \hosts\ or the \fallback@_hosts\ option, or the hosts supplied by the router |
| 18285 | were not obtained from MX records (this includes fallback hosts from the |
| 18286 | router), and were not randomizied by the router, the order of trying the hosts |
| 18287 | is randomized each time the transport runs. Randomizing the order of a host |
| 18288 | list can be used to do crude load sharing. |
| 18289 | |
| 18290 | When \hosts@_randomize\ is true, a host list may be split into groups whose |
| 18291 | order is separately randomized. This makes it possible to set up MX-like |
| 18292 | behaviour. The boundaries between groups are indicated by an item that is just |
| 18293 | \"+"\ in the host list. For example: |
| 18294 | .display asis |
| 18295 | hosts = host1:host2:host3:+:host4:host5 |
| 18296 | .endd |
| 18297 | The order of the first three hosts and the order of the last two hosts is |
| 18298 | randomized for each use, but the first three always end up before the last two. |
| 18299 | If \hosts@_randomize\ is not set, a \"+"\ item in the list is ignored. |
| 18300 | |
| 18301 | .index authentication||required by client |
| 18302 | .conf hosts@_require@_auth "host list$**$" unset |
| 18303 | This option provides a list of servers for which authentication must succeed |
| 18304 | before Exim will try to transfer a message. If authentication fails for |
| 18305 | servers which are not in this list, Exim tries to send unauthenticated. If |
| 18306 | authentication fails for one of these servers, delivery is deferred. This |
| 18307 | temporary error is detectable in the retry rules, so it can be turned into a |
| 18308 | hard failure if required. See also \hosts@_try@_auth\, and chapter |
| 18309 | ~~CHAPSMTPAUTH for details of authentication. |
| 18310 | |
| 18311 | .conf hosts@_require@_tls "host list$**$" unset |
| 18312 | .index TLS||requiring for certain servers |
| 18313 | Exim will insist on using a TLS session when delivering to any host that |
| 18314 | matches this list. See chapter ~~CHAPTLS for details of TLS. |
| 18315 | \**Note**\: This option affects outgoing mail only. To insist on TLS for |
| 18316 | incoming messages, use an appropriate ACL. |
| 18317 | |
| 18318 | .index authentication||optional in client |
| 18319 | .conf hosts@_try@_auth "host list$**$" unset |
| 18320 | This option provides a list of servers to which, provided they announce |
| 18321 | authentication support, Exim will attempt to authenticate as a client when it |
| 18322 | connects. If authentication fails, Exim will try to transfer the message |
| 18323 | unauthenticated. See also \hosts@_require@_auth\, and chapter ~~CHAPSMTPAUTH |
| 18324 | for details of authentication. |
| 18325 | |
| 18326 | .index bind IP address |
| 18327 | .index IP address||binding |
| 18328 | .conf interface "string list$**$" unset |
| 18329 | This option specifies which interface to bind to when making an outgoing SMTP |
| 18330 | call. The variables \$host$\ and \$host@_address$\ refer to the host to which a |
| 18331 | connection is about to be made during the expansion of the string. Forced |
| 18332 | expansion failure, or an empty string result causes the option to be ignored. |
| 18333 | Otherwise, after expansion, |
| 18334 | the string must be a list of IP addresses, colon-separated by default, but the |
| 18335 | separator can be changed in the usual way. |
| 18336 | For example: |
| 18337 | .display asis |
| 18338 | interface = <; 192.168.123.123 ; 3ffe:ffff:836f::fe86:a061 |
| 18339 | .endd |
| 18340 | The first interface of the correct type (IPv4 or IPv6) is used for the outgoing |
| 18341 | connection. If none of them are the correct type, the option is ignored. If |
| 18342 | \interface\ is not set, or is ignored, the system's IP functions choose which |
| 18343 | interface to use if the host has more than one. |
| 18344 | |
| 18345 | .conf keepalive boolean true |
| 18346 | .index keepalive||on outgoing connection |
| 18347 | This option controls the setting of \\SO@_KEEPALIVE\\ on outgoing TCP/IP socket |
| 18348 | connections. When set, it causes the kernel to probe idle connections |
| 18349 | periodically, by sending packets with `old' sequence numbers. The other end of |
| 18350 | the connection should send a acknowledgement if the connection is still okay or |
| 18351 | a reset if the connection has been aborted. The reason for doing this is that |
| 18352 | it has the beneficial effect of freeing up certain types of connection that can |
| 18353 | get stuck when the remote host is disconnected without tidying up the TCP/IP |
| 18354 | call properly. The keepalive mechanism takes several hours to detect |
| 18355 | unreachable hosts. |
| 18356 | |
| 18357 | .conf max@_rcpt integer 100 |
| 18358 | .index \\RCPT\\||maximum number of outgoing |
| 18359 | This option limits the number of \\RCPT\\ commands that are sent in a single |
| 18360 | SMTP message transaction. Each set of addresses is treated independently, and |
| 18361 | so can cause parallel connections to the same host if \remote@_max@_parallel\ |
| 18362 | permits this. |
| 18363 | |
| 18364 | .conf multi@_domain boolean true |
| 18365 | When this option is set, the \%smtp%\ transport can handle a number of addresses |
| 18366 | containing a mixture of different domains provided they all resolve to the same |
| 18367 | list of hosts. Turning the option off restricts the transport to handling only |
| 18368 | one domain at a time. This is useful if you want to use \$domain$\ in an |
| 18369 | expansion for the transport, because it is set only when there is a single |
| 18370 | domain involved in a remote delivery. |
| 18371 | |
| 18372 | .conf port string$**$ "see below" |
| 18373 | .index port||sending TCP/IP |
| 18374 | .index TCP/IP||setting outgoing port |
| 18375 | This option specifies the TCP/IP port on the server to which Exim connects. If |
| 18376 | it begins with a digit it is taken as a port number; otherwise it is looked up |
| 18377 | using \*getservbyname()*\. The default value is normally `smtp', but if |
| 18378 | \protocol\ is set to `lmtp', the default is `lmtp'. |
| 18379 | If the expansion fails, or if a port number cannot be found, delivery is |
| 18380 | deferred. |
| 18381 | |
| 18382 | |
| 18383 | .conf protocol string "smtp" |
| 18384 | .index LMTP||over TCP/IP |
| 18385 | If this option is set to `lmtp' instead of `smtp', the default value for the |
| 18386 | \port\ option changes to `lmtp', and the transport operates the LMTP protocol |
| 18387 | (RFC 2033) instead of SMTP. This protocol is sometimes used for local |
| 18388 | deliveries into closed message stores. Exim also has support for running LMTP |
| 18389 | over a pipe to a local process -- see chapter ~~CHAPLMTP. |
| 18390 | |
| 18391 | .conf retry@_include@_ip@_address boolean true |
| 18392 | Exim normally includes both the host name and the IP address in the key it |
| 18393 | constructs for indexing retry data after a temporary delivery failure. This |
| 18394 | means that when one of several IP addresses for a host is failing, it gets |
| 18395 | tried periodically (controlled by the retry rules), but use of the other IP |
| 18396 | addresses is not affected. |
| 18397 | |
| 18398 | However, in some dialup environments hosts are assigned a different IP address |
| 18399 | each time they connect. In this situation the use of the IP address as part of |
| 18400 | the retry key leads to undesirable behaviour. Setting this option false causes |
| 18401 | Exim to use only the host name. This should normally be done on a separate |
| 18402 | instance of the \%smtp%\ transport, set up specially to handle the dialup hosts. |
| 18403 | |
| 18404 | .conf serialize@_hosts "host list$**$" unset |
| 18405 | .index serializing connections |
| 18406 | .index host||serializing connections |
| 18407 | Because Exim operates in a distributed manner, if several messages for the same |
| 18408 | host arrive at around the same time, more than one simultaneous connection to |
| 18409 | the remote host can occur. This is not usually a problem except when there is a |
| 18410 | slow link between the hosts. In that situation it may be helpful to restrict |
| 18411 | Exim to one connection at a time. This can be done by setting |
| 18412 | \serialize@_hosts\ to match the relevant hosts. |
| 18413 | |
| 18414 | .index hints database||serializing deliveries to a host |
| 18415 | Exim implements serialization by means of a hints database in which a record is |
| 18416 | written whenever a process connects to one of the restricted hosts. The record |
| 18417 | is deleted when the connection is completed. Obviously there is scope for |
| 18418 | records to get left lying around if there is a system or program crash. To |
| 18419 | guard against this, Exim ignores any records that are more than six hours old. |
| 18420 | |
| 18421 | If you set up this kind of serialization, you should also arrange to delete the |
| 18422 | relevant hints database whenever your system reboots. The names of the files |
| 18423 | start with \(misc)\ and they are kept in the \(spool/db)\ directory. There |
| 18424 | may be one or two files, depending on the type of DBM in use. The same files |
| 18425 | are used for ETRN serialization. |
| 18426 | |
| 18427 | .conf size@_addition integer 1024 |
| 18428 | .index SMTP||\\SIZE\\ |
| 18429 | .index message||size issue for transport filter |
| 18430 | .index size||of message |
| 18431 | .index transport||filter |
| 18432 | .index filter||transport filter |
| 18433 | If a remote SMTP server indicates that it supports the \\SIZE\\ option of the |
| 18434 | \\MAIL\\ command, Exim uses this to pass over the message size at the start of |
| 18435 | an SMTP transaction. It adds the value of \size@_addition\ to the value it |
| 18436 | sends, to allow for headers and other text that may be added during delivery by |
| 18437 | configuration options or in a transport filter. It may be necessary to increase |
| 18438 | this if a lot of text is added to messages. |
| 18439 | |
| 18440 | Alternatively, if the value of \size@_addition\ is set negative, it disables |
| 18441 | the use of the \\SIZE\\ option altogether. |
| 18442 | |
| 18443 | .conf tls@_certificate string$**$ unset |
| 18444 | .index TLS||client certificate, location of |
| 18445 | .index certificate||for client, location of |
| 18446 | The value of this option must be the absolute path to a file which contains the |
| 18447 | client's certificate, for use when sending a message over an encrypted |
| 18448 | connection. The values of \$host$\ and \$host@_address$\ are set to the name |
| 18449 | and address of the server during the expansion. See chapter ~~CHAPTLS for |
| 18450 | details of TLS. |
| 18451 | |
| 18452 | \**Note**\: This option must be set if you want Exim to use TLS when sending |
| 18453 | messages as a client. The global option of the same name specifies the |
| 18454 | certificate for Exim as a server; it is not automatically assumed that the same |
| 18455 | certificate should be used when Exim is operating as a client. |
| 18456 | |
| 18457 | .conf tls@_crl string$**$ unset |
| 18458 | .index TLS||client certificate revocation list |
| 18459 | .index certificate||revocation list for client |
| 18460 | This option specifies a certificate revocation list. The expanded value must |
| 18461 | be the name of a file that contains a CRL in PEM format. |
| 18462 | |
| 18463 | .conf tls@_privatekey string$**$ unset |
| 18464 | .index TLS||client private key, location of |
| 18465 | The value of this option must be the absolute path to a file which contains the |
| 18466 | client's private key, for use when sending a message over an encrypted |
| 18467 | connection. The values of \$host$\ and \$host@_address$\ are set to the name |
| 18468 | and address of the server during the expansion. |
| 18469 | If this option is unset, the private key is assumed to be in the same file as |
| 18470 | the certificate. |
| 18471 | See chapter ~~CHAPTLS for details of TLS. |
| 18472 | |
| 18473 | .conf tls@_require@_ciphers string$**$ unset |
| 18474 | .index TLS||requiring specific ciphers |
| 18475 | .index cipher||requiring specific |
| 18476 | The value of this option must be a list of permitted cipher suites, for use |
| 18477 | when setting up an |
| 18478 | outgoing encrypted connection. (There is a global option of the same name for |
| 18479 | controlling incoming connections.) |
| 18480 | The values of \$host$\ and \$host@_address$\ are set to the name and address of |
| 18481 | the server during the expansion. See chapter ~~CHAPTLS for details of TLS; note |
| 18482 | that this option is used in different ways by OpenSSL and GnuTLS (see section |
| 18483 | ~~SECTreqciphsslgnu). |
| 18484 | |
| 18485 | .conf tls@_tempfail@_tryclear boolean true |
| 18486 | When the server host is not in \hosts@_require@_tls\, and there is a problem in |
| 18487 | setting up a TLS session, this option determines whether or not Exim should try |
| 18488 | to deliver the message unencrypted. If it is set false, delivery to the |
| 18489 | current host is deferred; if there are other hosts, they are tried. If this |
| 18490 | option is set true, Exim attempts to deliver unencrypted after a 4\*xx*\ |
| 18491 | response to \\STARTTLS\\. Also, if \\STARTTLS\\ is accepted, but the subsequent |
| 18492 | TLS negotiation fails, Exim closes the current connection (because it is in an |
| 18493 | unknown state), opens a new one to the same host, and then tries the delivery |
| 18494 | in clear. |
| 18495 | |
| 18496 | .conf tls@_verify@_certificates string$**$ unset |
| 18497 | .index TLS||server certificate verification |
| 18498 | .index certificate||verification of server |
| 18499 | The value of this option must be the absolute path to a file containing |
| 18500 | permitted server certificates, for use when setting up an encrypted connection. |
| 18501 | Alternatively, if you are using OpenSSL, you can set |
| 18502 | \tls@_verify@_certificates\ to the name of a directory containing certificate |
| 18503 | files. This does not work with GnuTLS; the option must be set to the name of a |
| 18504 | single file if you are using GnuTLS. The values of \$host$\ and |
| 18505 | \$host@_address$\ are set to the name and address of the server during the |
| 18506 | expansion of this option. See chapter ~~CHAPTLS for details of TLS. |
| 18507 | |
| 18508 | .endconf |
| 18509 | |
| 18510 | |
| 18511 | .section How the value of hosts@_max@_try is used |
| 18512 | .rset SECTvalhosmax "~~chapter.~~section" |
| 18513 | .index host||maximum number to try |
| 18514 | .index limit||hosts, maximum number tried |
| 18515 | The \hosts@_max@_try\ option limits the number of hosts that are tried |
| 18516 | for a single delivery. However, despite the term `host' in its name, the option |
| 18517 | actually applies to each IP address independently. In other words, a multihomed |
| 18518 | host is treated as several independent hosts, just as it is for retrying. |
| 18519 | |
| 18520 | Many of the larger ISPs have multiple MX records which often point to |
| 18521 | multihomed hosts. As a result, a list of a dozen or more IP addresses may be |
| 18522 | created as a result of routing one of these domains. |
| 18523 | |
| 18524 | Trying every single IP address on such a long list does not seem sensible; if |
| 18525 | several at the top of the list fail, it is reasonable to assume there is some |
| 18526 | problem that is likely to affect all of them. Roughly speaking, the value of |
| 18527 | \hosts@_max@_try\ is the maximum number that are tried before deferring the |
| 18528 | delivery. However, the logic cannot be quite that simple. |
| 18529 | |
| 18530 | Firstly, IP addresses that are skipped because their retry times have not |
| 18531 | arrived do not count, and in addition, addresses that are past their retry |
| 18532 | limits are also not counted, even when they are tried. This means that when |
| 18533 | some IP addresses are past their retry limits, more than the value of |
| 18534 | \hosts@_max@_retry\ may be tried. The reason for this behaviour is to ensure |
| 18535 | that all IP addresses are considered before timing out an email address. |
| 18536 | |
| 18537 | Secondly, when the \hosts@_max@_try\ limit is reached, Exim looks down the host |
| 18538 | list to see if there is a subsequent host with a different (higher valued) MX. |
| 18539 | If there is, that host is used next, and the current IP address is used but not |
| 18540 | counted. This behaviour helps in the case of a domain with a retry rule that |
| 18541 | hardly ever delays any hosts, as is now explained: |
| 18542 | |
| 18543 | Consider the case of a long list of hosts with one MX value, and a few with a |
| 18544 | higher MX value. If \hosts@_max@_try\ is small (the default is 5) only a few |
| 18545 | hosts at the top of the list are tried at first. With the default retry rule, |
| 18546 | which specifies increasing retry times, the higher MX hosts are eventually |
| 18547 | tried when those at the top of the list are skipped because they have not |
| 18548 | reached their retry times. |
| 18549 | |
| 18550 | However, it is common practice to put a fixed short retry time on domains for |
| 18551 | large ISPs, on the grounds that their servers are rarely down for very long. |
| 18552 | Unfortunately, these are exactly the domains that tend to resolve to long lists |
| 18553 | of hosts. The short retry time means that the lowest MX hosts are tried every |
| 18554 | time. The attempts may be in a different order because of random sorting, but |
| 18555 | without the special MX check mentioned about, the higher MX hosts would never |
| 18556 | be tried at all because the lower MX hosts are never all past their retry |
| 18557 | times. |
| 18558 | |
| 18559 | With the special check, Exim tries least one address from each MX value, even |
| 18560 | if the \hosts@_max@_try\ limit has already been reached. |
| 18561 | |
| 18562 | |
| 18563 | |
| 18564 | |
| 18565 | |
| 18566 | |
| 18567 | . |
| 18568 | . |
| 18569 | . |
| 18570 | . |
| 18571 | . ============================================================================ |
| 18572 | .chapter Address rewriting |
| 18573 | .set runningfoot "address rewriting" |
| 18574 | .rset CHAPrewrite ~~chapter |
| 18575 | .index rewriting||addresses |
| 18576 | There are some circumstances in which Exim automatically rewrites domains in |
| 18577 | addresses. The two most common are when an address is given without a domain |
| 18578 | (referred to as an `unqualified address') or when an address contains an |
| 18579 | abbreviated domain that is expanded by DNS lookup. |
| 18580 | |
| 18581 | Unqualified envelope addresses are accepted only for locally submitted |
| 18582 | messages, or messages from hosts that match \sender@_unqualified@_hosts\ or |
| 18583 | \recipient@_unqualified@_hosts\, respectively. Unqualified addresses in header |
| 18584 | lines are qualified if they are in locally submitted messages, or messages from |
| 18585 | hosts that are permitted to send unqualified envelope addresses. Otherwise, |
| 18586 | unqualified addresses in header lines are neither qualified nor rewritten. |
| 18587 | |
| 18588 | One situation in which Exim does $it{not} automatically rewrite a domain is |
| 18589 | when it is the name of a CNAME record in the DNS. The older RFCs suggest that |
| 18590 | such a domain should be rewritten using the `canonical' name, and some MTAs do |
| 18591 | this. The new RFCs do not contain this suggestion. |
| 18592 | |
| 18593 | .section Explicitly configured address rewriting |
| 18594 | This chapter describes the rewriting rules that can be used in the |
| 18595 | main rewrite section of the configuration file, and also in the generic |
| 18596 | \headers@_rewrite\ option that can be set on any transport. |
| 18597 | |
| 18598 | Some people believe that configured address rewriting is a Mortal Sin. |
| 18599 | Others believe that life is not possible without it. Exim provides the |
| 18600 | facility; you do not have to use it. |
| 18601 | |
| 18602 | The main rewriting rules that appear in the `rewrite' section of the |
| 18603 | configuration file are applied to addresses in incoming messages, both envelope |
| 18604 | addresses and addresses in header lines. Each rule specifies the types of |
| 18605 | address to which it applies. |
| 18606 | |
| 18607 | Rewriting of addresses in header lines applies only to those headers that |
| 18608 | were received with the message, and, in the case of transport rewriting, those |
| 18609 | that were added by a system filter. That is, it applies only to those headers |
| 18610 | that are common to all copies of the message. Header lines that are added by |
| 18611 | individual routers or transports (and which are therefore specific to |
| 18612 | individual recipient addresses) are not rewritten. |
| 18613 | |
| 18614 | In general, rewriting addresses from your own system or domain has some |
| 18615 | legitimacy. Rewriting other addresses should be done only with great care and |
| 18616 | in special circumstances. The author of Exim believes that rewriting should be |
| 18617 | used sparingly, and mainly for `regularizing' addresses in your own domains. |
| 18618 | Although it can sometimes be used as a routing tool, this is very strongly |
| 18619 | discouraged. |
| 18620 | |
| 18621 | There are two commonly encountered circumstances where rewriting is used, as |
| 18622 | illustrated by these examples: |
| 18623 | .numberpars $. |
| 18624 | The company whose domain is \*hitch.fict.example*\ has a number of hosts that |
| 18625 | exchange mail with each other behind a firewall, but there is only a single |
| 18626 | gateway to the outer world. The gateway rewrites \*@*.hitch.fict.example*\ as |
| 18627 | \*hitch.fict.example*\ when sending mail off-site. |
| 18628 | .nextp |
| 18629 | A host rewrites the local parts of its own users so that, for example, |
| 18630 | \*fp42@@hitch.fict.example*\ becomes \*Ford.Prefect@@hitch.fict.example*\. |
| 18631 | .endp |
| 18632 | |
| 18633 | .section When does rewriting happen? |
| 18634 | .index rewriting||timing of |
| 18635 | .index ~~ACL||rewriting addresses in |
| 18636 | Configured address rewriting can take place at several different stages of a |
| 18637 | message's processing. |
| 18638 | |
| 18639 | At the start of an ACL for \\MAIL\\, the sender address may have been rewritten |
| 18640 | by a special SMTP-time rewrite rule (see section ~~SECTrewriteS), but no |
| 18641 | ordinary rewrite rules have yet been applied. If, however, the sender address |
| 18642 | is verified in the ACL, it is rewritten before verification, and remains |
| 18643 | rewritten thereafter. The subsequent value of \$sender@_address$\ is the |
| 18644 | rewritten address. This also applies if sender verification happens in a |
| 18645 | \\RCPT\\ ACL. Otherwise, when the sender address is not verified, it is |
| 18646 | rewritten as soon as a message's header lines have been received. |
| 18647 | |
| 18648 | Similarly, at the start of an ACL for \\RCPT\\, the current recipient's address |
| 18649 | may have been rewritten by a special SMTP-time rewrite rule, but no ordinary |
| 18650 | rewrite rules have yet been applied to it. However, the behaviour is different |
| 18651 | from the sender address when a recipient is verified. The address is rewritten |
| 18652 | for the verification, but the rewriting is not remembered at this stage. The |
| 18653 | value of \$local@_part$\ and \$domain$\ after verification are always the same |
| 18654 | as they were before (that is, they contain the unrewritten -- except for |
| 18655 | SMTP-time rewriting -- address). |
| 18656 | |
| 18657 | Once a message's header lines have been received, all the envelope recipient |
| 18658 | addresses are permanently rewritten, and rewriting is also applied to the |
| 18659 | addresses in the header lines (if configured). |
| 18660 | .index \*local@_scan()*\ function||address rewriting, timing of |
| 18661 | Thus, all the rewriting is completed before the \\DATA\\ ACL and |
| 18662 | \*local@_scan()*\ functions are run. |
| 18663 | |
| 18664 | When an address is being routed, either for delivery or for verification, |
| 18665 | rewriting is applied immediately to child addresses that are generated by |
| 18666 | redirection, unless \no@_rewrite\ is set on the router. |
| 18667 | |
| 18668 | .index envelope sender, rewriting |
| 18669 | .index rewriting||at transport time |
| 18670 | At transport time, additional rewriting of addresses in header lines can be |
| 18671 | specified by setting the generic \headers@_rewrite\ option on a transport. This |
| 18672 | option contains rules that are identical in form to those in the rewrite |
| 18673 | section of the configuration file. In addition, the outgoing envelope sender |
| 18674 | can be rewritten by means of the \return@_path\ transport option. However, it |
| 18675 | is not possible to rewrite envelope recipients at transport time. |
| 18676 | |
| 18677 | |
| 18678 | |
| 18679 | .section Testing the rewriting rules that apply on input |
| 18680 | .index rewriting||testing |
| 18681 | .index testing||rewriting |
| 18682 | Exim's input rewriting configuration appears in a part of the run time |
| 18683 | configuration file headed by `begin rewrite'. It can be tested by the \-brw-\ |
| 18684 | command line option. This takes an address (which can be a full RFC 2822 |
| 18685 | address) as its argument. The output is a list of how the address would be |
| 18686 | transformed by the rewriting rules for each of the different places it might |
| 18687 | appear in an incoming message, that is, for each different header and for the |
| 18688 | envelope sender and recipient fields. For example, |
| 18689 | .display asis |
| 18690 | exim -brw ph10@exim.workshop.example |
| 18691 | .endd |
| 18692 | might produce the output |
| 18693 | .display asis |
| 18694 | sender: Philip.Hazel@exim.workshop.example |
| 18695 | from: Philip.Hazel@exim.workshop.example |
| 18696 | to: ph10@exim.workshop.example |
| 18697 | cc: ph10@exim.workshop.example |
| 18698 | bcc: ph10@exim.workshop.example |
| 18699 | reply-to: Philip.Hazel@exim.workshop.example |
| 18700 | env-from: Philip.Hazel@exim.workshop.example |
| 18701 | env-to: ph10@exim.workshop.example |
| 18702 | .endd |
| 18703 | which shows that rewriting has been set up for that address when used in any of |
| 18704 | the source fields, but not when it appears as a recipient address. At the |
| 18705 | present time, there is no equivalent way of testing rewriting rules that are |
| 18706 | set for a particular transport. |
| 18707 | |
| 18708 | .section Rewriting rules |
| 18709 | .index rewriting||rules |
| 18710 | The rewrite section of the configuration file consists of lines of rewriting |
| 18711 | rules in the form |
| 18712 | .display |
| 18713 | <<source pattern>> <<replacement>> <<flags>> |
| 18714 | .endd |
| 18715 | Rewriting rules that are specified for the \headers@_rewrite\ generic transport |
| 18716 | option are given as a colon-separated list. Each item in the list takes the |
| 18717 | same form as a line in the main rewriting configuration |
| 18718 | (except that any colons must be doubled, of course). |
| 18719 | |
| 18720 | The formats of source patterns and replacement strings are described below. |
| 18721 | Each is terminated by white space, unless enclosed in double quotes, in which |
| 18722 | case normal quoting conventions apply inside the quotes. The flags are single |
| 18723 | characters which may appear in any order. Spaces and tabs between them are |
| 18724 | ignored. |
| 18725 | |
| 18726 | For each address that could potentially be rewritten, the rules are scanned in |
| 18727 | order, and replacements for the address from earlier rules can themselves be |
| 18728 | replaced by later rules (but see the `q' and `R' flags). |
| 18729 | |
| 18730 | The order in which addresses are rewritten is undefined, may change between |
| 18731 | releases, and must not be relied on, with one exception: when a message is |
| 18732 | received, the envelope sender is always rewritten first, before any header |
| 18733 | lines are rewritten. For example, the replacement string for a rewrite of an |
| 18734 | address in ::To:: must not assume that the message's address in ::From:: has (or |
| 18735 | has not) already been rewritten. However, a rewrite of ::From:: may assume that |
| 18736 | the envelope sender has already been rewritten. |
| 18737 | |
| 18738 | The variables \$local@_part$\ and \$domain$\ can be used in the replacement |
| 18739 | string to refer to the address that is being rewritten. Note that lookup-driven |
| 18740 | rewriting can be done by a rule of the form |
| 18741 | .display asis |
| 18742 | *@* ${lookup ... |
| 18743 | .endd |
| 18744 | where the lookup key uses \$1$\ and \$2$\ or \$local@_part$\ and \$domain$\ to |
| 18745 | refer to the address that is being rewritten. |
| 18746 | |
| 18747 | .section Rewriting patterns |
| 18748 | .index rewriting||patterns |
| 18749 | .index address list||in a rewriting pattern |
| 18750 | The source pattern in a rewriting rule is any item which may appear in an |
| 18751 | address list (see section ~~SECTaddresslist). It is in fact processed as a |
| 18752 | single-item address list, which means that it is expanded before being tested |
| 18753 | against the address. |
| 18754 | |
| 18755 | Domains in patterns should be given in lower case. Local parts in patterns are |
| 18756 | case-sensitive. If you want to do case-insensitive matching of local parts, you |
| 18757 | can use a regular expression that starts with \"^(?i)"\. |
| 18758 | |
| 18759 | .index numerical variables (\$1$\, \$2$\, etc)||in rewriting rules |
| 18760 | After matching, the numerical variables \$1$\, \$2$\, etc. may be set, |
| 18761 | depending on the type of match which occurred. These can be used in the |
| 18762 | replacement string to insert portions of the incoming address. \$0$\ always |
| 18763 | refers to the complete incoming address. When a regular expression is used, the |
| 18764 | numerical variables are set from its capturing subexpressions. For other types |
| 18765 | of pattern they are set as follows: |
| 18766 | |
| 18767 | .numberpars $. |
| 18768 | If a local part or domain starts with an asterisk, the numerical variables |
| 18769 | refer to the character strings matched by asterisks, with \$1$\ associated with |
| 18770 | the first asterisk, and \$2$\ with the second, if present. For example, if the |
| 18771 | pattern |
| 18772 | .display |
| 18773 | *queen@@*.fict.example |
| 18774 | .endd |
| 18775 | is matched against the address \*hearts-queen@@wonderland.fict.example*\ then |
| 18776 | .display asis |
| 18777 | $0 = hearts-queen@wonderland.fict.example |
| 18778 | $1 = hearts- |
| 18779 | $2 = wonderland |
| 18780 | .endd |
| 18781 | Note that if the local part does not start with an asterisk, but the domain |
| 18782 | does, it is \$1$\ that contains the wild part of the domain. |
| 18783 | .nextp |
| 18784 | If the domain part of the pattern is a partial lookup, the wild and fixed parts |
| 18785 | of the domain are placed in the next available numerical variables. Suppose, |
| 18786 | for example, that the address \*foo@@bar.baz.example*\ is processed by a |
| 18787 | rewriting rule of the form |
| 18788 | .display |
| 18789 | *@@partial-dbm;/some/dbm/file <<replacement string>> |
| 18790 | .endd |
| 18791 | and the key in the file that matches the domain is \"*.baz.example"\. Then |
| 18792 | .display asis |
| 18793 | $1 = foo |
| 18794 | $2 = bar |
| 18795 | $3 = baz.example |
| 18796 | .endd |
| 18797 | If the address \*foo@@baz.example*\ is looked up, this matches the same |
| 18798 | wildcard file entry, and in this case \$2$\ is set to the empty string, but |
| 18799 | \$3$\ is still set to \*baz.example*\. If a non-wild key is matched in a |
| 18800 | partial lookup, \$2$\ is again set to the empty string and \$3$\ is set to the |
| 18801 | whole domain. For non-partial domain lookups, no numerical variables are set. |
| 18802 | .endp |
| 18803 | |
| 18804 | .section Rewriting replacements |
| 18805 | .index rewriting||replacements |
| 18806 | If the replacement string for a rule is a single asterisk, addresses that |
| 18807 | match the pattern and the flags are $it{not} rewritten, and no subsequent |
| 18808 | rewriting rules are scanned. For example, |
| 18809 | .display asis |
| 18810 | hatta@lookingglass.fict.example * f |
| 18811 | .endd |
| 18812 | specifies that \*hatta@@lookingglass.fict.example*\ is never to be rewritten in |
| 18813 | ::From:: headers. |
| 18814 | |
| 18815 | If the replacement string is not a single asterisk, it is expanded, and must |
| 18816 | yield a fully qualified address. Within the expansion, the variables |
| 18817 | \$local@_part$\ and \$domain$\ refer to the address that is being rewritten. |
| 18818 | Any letters they contain retain their original case -- they are not lower |
| 18819 | cased. The numerical variables are set up according to the type of pattern that |
| 18820 | matched the address, as described above. If the expansion is forced to fail by |
| 18821 | the presence of `fail' in a conditional or lookup item, rewriting by the |
| 18822 | current rule is abandoned, but subsequent rules may take effect. Any other |
| 18823 | expansion failure causes the entire rewriting operation to be abandoned, and an |
| 18824 | entry written to the panic log. |
| 18825 | |
| 18826 | |
| 18827 | .section Rewriting flags |
| 18828 | There are three different kinds of flag that may appear on rewriting rules: |
| 18829 | .numberpars $. |
| 18830 | Flags that specify which headers and envelope addresses to rewrite: E, F, T, b, |
| 18831 | c, f, h, r, s, t. |
| 18832 | .nextp |
| 18833 | A flag that specifies rewriting at SMTP time: S. |
| 18834 | .nextp |
| 18835 | Flags that control the rewriting process: Q, q, R, w. |
| 18836 | .endp |
| 18837 | For rules that are part of the \headers@_rewrite\ generic transport option, |
| 18838 | E, F, T, and S are not permitted. |
| 18839 | |
| 18840 | |
| 18841 | .section Flags specifying which headers and envelope addresses to rewrite |
| 18842 | .index rewriting||flags |
| 18843 | If none of the following flag letters, nor the `S' flag (see section |
| 18844 | ~~SECTrewriteS) are present, a main rewriting rule applies to all headers and |
| 18845 | to both the sender and recipient fields of the envelope, whereas a |
| 18846 | transport-time rewriting rule just applies to all headers. Otherwise, the |
| 18847 | rewriting rule is skipped unless the relevant addresses are being processed. |
| 18848 | .display |
| 18849 | E $rm{rewrite all envelope fields} |
| 18850 | F $rm{rewrite the envelope From field} |
| 18851 | T $rm{rewrite the envelope To field} |
| 18852 | b $rm{rewrite the ::Bcc:: header} |
| 18853 | c $rm{rewrite the ::Cc:: header} |
| 18854 | f $rm{rewrite the ::From:: header} |
| 18855 | h $rm{rewrite all headers} |
| 18856 | r $rm{rewrite the ::Reply-To:: header} |
| 18857 | s $rm{rewrite the ::Sender:: header} |
| 18858 | t $rm{rewrite the ::To:: header} |
| 18859 | .endd |
| 18860 | You should be particularly careful about rewriting ::Sender:: headers, and |
| 18861 | restrict this to special known cases in your own domains. |
| 18862 | |
| 18863 | .section The SMTP-time rewriting flag |
| 18864 | .rset SECTrewriteS "~~chapter.~~section" |
| 18865 | .index SMTP||rewriting malformed addresses |
| 18866 | .index \\RCPT\\||rewriting argument of |
| 18867 | .index \\MAIL\\||rewriting argument of |
| 18868 | The rewrite flag `S' specifies a rewrite of incoming envelope addresses at SMTP |
| 18869 | time, as soon as an address is received in a \\MAIL\\ or \\RCPT\\ command, and |
| 18870 | before any other processing; even before syntax checking. The pattern is |
| 18871 | required to be a regular expression, and it is matched against the whole of the |
| 18872 | data for the command, including any surrounding angle brackets. |
| 18873 | |
| 18874 | This form of rewrite rule allows for the handling of addresses that are not |
| 18875 | compliant with RFCs 2821 and 2822 (for example, `bang paths' in batched SMTP |
| 18876 | input). Because the input is not required to be a syntactically valid address, |
| 18877 | the variables \$local@_part$\ and \$domain$\ are not available during the |
| 18878 | expansion of the replacement string. The result of rewriting replaces the |
| 18879 | original address in the \\MAIL\\ or \\RCPT\\ command. |
| 18880 | |
| 18881 | .section Flags controlling the rewriting process |
| 18882 | There are four flags which control the way the rewriting process works. These |
| 18883 | take effect only when a rule is invoked, that is, when the address is of the |
| 18884 | correct type (matches the flags) and matches the pattern: |
| 18885 | .numberpars $. |
| 18886 | If the `Q' flag is set on a rule, the rewritten address is permitted to be an |
| 18887 | unqualified local part. It is qualified with \qualify@_recipient\. In the |
| 18888 | absence of `Q' the rewritten address must always include a domain. |
| 18889 | .nextp |
| 18890 | If the `q' flag is set on a rule, no further rewriting rules are considered, |
| 18891 | even if no rewriting actually takes place because of a `fail' in the expansion. |
| 18892 | The `q' flag is not effective if the address is of the wrong type (does not |
| 18893 | match the flags) or does not match the pattern. |
| 18894 | .nextp |
| 18895 | The `R' flag causes a successful rewriting rule to be re-applied to the new |
| 18896 | address, up to ten times. It can be combined with the `q' flag, to stop |
| 18897 | rewriting once it fails to match (after at least one successful rewrite). |
| 18898 | .nextp |
| 18899 | .index rewriting||whole addresses |
| 18900 | When an address in a header is rewritten, the rewriting normally applies only |
| 18901 | to the working part of the address, with any comments and RFC 2822 `phrase' |
| 18902 | left unchanged. For example, rewriting might change |
| 18903 | .display asis |
| 18904 | From: Ford Prefect <fp42@restaurant.hitch.fict.example> |
| 18905 | .endd |
| 18906 | into |
| 18907 | .display asis |
| 18908 | From: Ford Prefect <prefectf@hitch.fict.example> |
| 18909 | .endd |
| 18910 | Sometimes there is a need to replace the whole address item, and this can be |
| 18911 | done by adding the flag letter `w' to a rule. If this is set on a rule that |
| 18912 | causes an address in a header line to be rewritten, the entire address is |
| 18913 | replaced, not just the working part. The replacement must be a complete RFC |
| 18914 | 2822 address, including the angle brackets if necessary. If text outside angle |
| 18915 | brackets contains a character whose value is greater than 126 or less than 32 |
| 18916 | (except for tab), the text is encoded according to RFC 2047. |
| 18917 | The character set is taken from \headers@_charset\, which defaults to |
| 18918 | ISO-8859-1. |
| 18919 | |
| 18920 | When the `w' flag is set on a rule that causes an envelope address to be |
| 18921 | rewritten, all but the working part of the replacement address is discarded. |
| 18922 | .endp |
| 18923 | |
| 18924 | .section Rewriting examples |
| 18925 | Here is an example of the two common rewriting paradigms: |
| 18926 | .display asis |
| 18927 | *@*.hitch.fict.example $1@hitch.fict.example |
| 18928 | *@hitch.fict.example ${lookup{$1}dbm{/etc/realnames}\ |
| 18929 | {$value}fail}@hitch.fict.example bctfrF |
| 18930 | .endd |
| 18931 | Note the use of `fail' in the lookup expansion in the second rule, forcing |
| 18932 | the string expansion to fail if the lookup does not succeed. In this context it |
| 18933 | has the effect of leaving the original address unchanged, but Exim goes on to |
| 18934 | consider subsequent rewriting rules, if any, because the `q' flag is not |
| 18935 | present in that rule. An alternative to `fail' would be to supply \$1$\ |
| 18936 | explicitly, which would cause the rewritten address to be the same as before, |
| 18937 | at the cost of a small bit of processing. Not supplying either of these is an |
| 18938 | error, since the rewritten address would then contain no local part. |
| 18939 | |
| 18940 | The first example above replaces the domain with a superior, more general |
| 18941 | domain. This may not be desirable for certain local parts. If the rule |
| 18942 | .display asis |
| 18943 | root@*.hitch.fict.example * |
| 18944 | .endd |
| 18945 | were inserted before the first rule, rewriting would be suppressed for the |
| 18946 | local part \*root*\ at any domain ending in \*hitch.fict.example*\. |
| 18947 | |
| 18948 | Rewriting can be made conditional on a number of tests, by making use of |
| 18949 | \${if$\ in the expansion item. For example, to apply a rewriting rule only to |
| 18950 | messages that originate outside the local host: |
| 18951 | .display asis |
| 18952 | *@*.hitch.fict.example "${if !eq {$sender_host_address}{}\ |
| 18953 | {$1@hitch.fict.example}fail}" |
| 18954 | .endd |
| 18955 | The replacement string is quoted in this example because it contains white |
| 18956 | space. |
| 18957 | |
| 18958 | .index rewriting||bang paths |
| 18959 | .index bang paths||rewriting |
| 18960 | Exim does not handle addresses in the form of `bang paths'. If it sees such an |
| 18961 | address it treats it as an unqualified local part which it qualifies with the |
| 18962 | local qualification domain (if the source of the message is local or if the |
| 18963 | remote host is permitted to send unqualified addresses). Rewriting can |
| 18964 | sometimes be used to handle simple bang paths with a fixed number of |
| 18965 | components. For example, the rule |
| 18966 | .display asis |
| 18967 | \N^([^!]+)!(.*)@your.domain.example$\N $2@$1 |
| 18968 | .endd |
| 18969 | rewrites a two-component bang path \*host.name!user*\ as the domain address |
| 18970 | \*user@@host.name*\. However, there is a security implication in using this as |
| 18971 | a global rewriting rule for envelope addresses. It can provide a backdoor |
| 18972 | method for using your system as a relay, because the incoming addresses appear |
| 18973 | to be local. If the bang path addresses are received via SMTP, it is safer to |
| 18974 | use the `S' flag to rewrite them as they are received, so that relay checking |
| 18975 | can be done on the rewritten addresses. |
| 18976 | |
| 18977 | |
| 18978 | |
| 18979 | |
| 18980 | |
| 18981 | . |
| 18982 | . |
| 18983 | . |
| 18984 | . |
| 18985 | . ============================================================================ |
| 18986 | .chapter Retry configuration |
| 18987 | .set runningfoot "retry configuration" |
| 18988 | .rset CHAPretry ~~chapter |
| 18989 | .index retry||configuration, description of |
| 18990 | .index configuration file||retry section |
| 18991 | The `retry' section of the run time configuration file contains a list of retry |
| 18992 | rules which control how often Exim tries to deliver messages that cannot be |
| 18993 | delivered at the first attempt. If there are no retry rules, temporary errors |
| 18994 | are treated as permanent. The \-brt-\ command line option can be used to test |
| 18995 | which retry rule will be used for a given address or domain. |
| 18996 | |
| 18997 | The most common cause of retries is temporary failure to deliver to a remote |
| 18998 | host because the host is down, or inaccessible because of a network problem. |
| 18999 | Exim's retry processing in this case is applied on a per-host (strictly, per IP |
| 19000 | address) basis, not on a per-message basis. Thus, if one message has recently |
| 19001 | been delayed, delivery of a new message to the same host is not immediately |
| 19002 | tried, but waits for the host's retry time to arrive. If the \retry@_defer\ log |
| 19003 | selector is set, the message |
| 19004 | .index retry||time not reached |
| 19005 | `retry time not reached' is written to the main log whenever a delivery is |
| 19006 | skipped for this reason. Section ~~SECToutSMTPerr contains more details of the |
| 19007 | handling of errors during remote deliveries. |
| 19008 | |
| 19009 | Retry processing applies to routing as well as to delivering, except as covered |
| 19010 | in the next paragraph. The retry rules do not distinguish between these |
| 19011 | actions. It is not possible, for example, to specify different behaviour for |
| 19012 | failures to route the domain \*snark.fict.example*\ and failures to deliver to |
| 19013 | the host \*snark.fict.example*\. I didn't think anyone would ever need this |
| 19014 | added complication, so did not implement it. However, although they share the |
| 19015 | same retry rule, the actual retry times for routing and transporting a given |
| 19016 | domain are maintained independently. |
| 19017 | |
| 19018 | When a delivery is not part of a queue run (typically an immediate delivery on |
| 19019 | receipt of a message), the routers are always run, and local deliveries are |
| 19020 | always attempted, even if retry times are set for them. This makes for better |
| 19021 | behaviour if one particular message is causing problems (for example, causing |
| 19022 | quota overflow, or provoking an error in a filter file). If such a delivery |
| 19023 | suffers a temporary failure, the retry data is updated as normal, and |
| 19024 | subsequent delivery attempts from queue runs occur only when the retry time for |
| 19025 | the local address is reached. |
| 19026 | |
| 19027 | |
| 19028 | .section Retry rules |
| 19029 | .index retry||rules |
| 19030 | Each retry rule occupies one line and consists of three parts, separated by |
| 19031 | white space: a pattern, an error name, and a list of retry parameters. The |
| 19032 | pattern must be enclosed in double quotes if it contains white space. The rules |
| 19033 | are searched in order until one is found whose pattern matches the failing host |
| 19034 | or address. |
| 19035 | |
| 19036 | The pattern is any single item that may appear in an address list (see section |
| 19037 | ~~SECTaddresslist). It is in fact processed as a one-item address list, which |
| 19038 | means that it is expanded before being tested against the address that has |
| 19039 | been delayed. Address list processing treats a plain domain name as if it were |
| 19040 | preceded by `*@@', which makes it possible for many retry rules to start with |
| 19041 | just a domain. For example, |
| 19042 | .display asis |
| 19043 | lookingglass.fict.example * F,24h,30m; |
| 19044 | .endd |
| 19045 | provides a rule for any address in the \*lookingglass.fict.example*\ domain, |
| 19046 | whereas |
| 19047 | .display asis |
| 19048 | alice@lookingglass.fict.example * F,24h,30m; |
| 19049 | .endd |
| 19050 | applies only to temporary failures involving the local part \alice\. |
| 19051 | In practice, almost all rules start with a domain name pattern without a local |
| 19052 | part. |
| 19053 | |
| 19054 | .index regular expressions||in retry rules |
| 19055 | \**Warning**\: If you use a regular expression in a routing rule, it must match |
| 19056 | a complete address, not just a domain, because that is how regular expressions |
| 19057 | work in address lists. |
| 19058 | .display |
| 19059 | ^@\Nxyz@\d+@\.abc@\.example@$@\N * G,1h,10m,2 \Wrong\ |
| 19060 | ^@\N[^@@]+@@xyz@\d+@\.abc@\.example@$@\N * G,1h,10m,2 \Right\ |
| 19061 | .endd |
| 19062 | |
| 19063 | |
| 19064 | .section Choosing which retry rule to use |
| 19065 | When Exim is looking for a retry rule after a routing attempt has failed (for |
| 19066 | example, after a DNS timeout), each line in the retry configuration is tested |
| 19067 | against the complete address only if \retry__use@_local@_part\ is set for the |
| 19068 | router. Otherwise, only the domain is used, except when matching against a |
| 19069 | regular expression, when the local part of the address is replaced with `*'. A |
| 19070 | domain on its own can match a domain pattern, or a pattern that starts with |
| 19071 | `*@@'. By default, \retry@_use@_local@_part\ is true for routers where |
| 19072 | \check@_local@_user\ is true, and false for other routers. |
| 19073 | |
| 19074 | Similarly, when Exim is looking for a retry rule after a local delivery has |
| 19075 | failed (for example, after a mailbox full error), each line in the retry |
| 19076 | configuration is tested against the complete address only if |
| 19077 | \retry@_use@_local@_part\ is set for the transport (it defaults true for all |
| 19078 | local transports). |
| 19079 | |
| 19080 | When Exim is looking for a retry rule after a remote delivery attempt has |
| 19081 | failed, what happens depends on the type of failure. After a 4\*xx*\ SMTP |
| 19082 | response for a recipient address, the whole address is used when searching the |
| 19083 | retry rules. The rule that is found is used to create a retry time for the |
| 19084 | failing address. |
| 19085 | |
| 19086 | For a temporary error that is not related to an individual address, |
| 19087 | (for example, a connection timeout), each line in the retry configuration is |
| 19088 | checked twice. First, the name of the remote host is used as a domain name |
| 19089 | (preceded by `*@@' when matching a regular expression). If this does not match |
| 19090 | the line, the domain from the email address is tried in a similar fashion. For |
| 19091 | example, suppose the MX records for \*a.b.c.example*\ are |
| 19092 | .display asis |
| 19093 | a.b.c.example MX 5 x.y.z.example |
| 19094 | MX 6 p.q.r.example |
| 19095 | MX 7 m.n.o.example |
| 19096 | .endd |
| 19097 | and the retry rules are |
| 19098 | .display asis |
| 19099 | p.q.r.example * F,24h,30m; |
| 19100 | a.b.c.example * F,4d,45m; |
| 19101 | .endd |
| 19102 | and a delivery to the host \*x.y.z.example*\ fails. The first rule matches |
| 19103 | neither the host nor the domain, so Exim looks at the second rule. This does |
| 19104 | not match the host, but it does match the domain, so it is used to calculate |
| 19105 | the retry time for the host \*x.y.z.example*\. Meanwhile, Exim tries to deliver |
| 19106 | to \*p.q.r.example*\. If this fails, the first retry rule is used, because it |
| 19107 | matches the host. |
| 19108 | |
| 19109 | In other words, failures to deliver to host \*p.q.r.example*\ use the first |
| 19110 | rule to determine retry times, but for all the other hosts for the domain |
| 19111 | \*a.b.c.example*\, the second rule is used. The second rule is also used if |
| 19112 | routing to \*a.b.c.example*\ suffers a temporary failure. |
| 19113 | |
| 19114 | .section Retry rules for specific errors |
| 19115 | .index retry||specific errors, specifying |
| 19116 | The second field in a retry rule is the name of a particular error, or an |
| 19117 | asterisk, which matches any error. The errors that can be tested for are: |
| 19118 | .numberpars " " |
| 19119 | \*auth@_failed*\: authentication failed when trying to send to a host in the |
| 19120 | \hosts@_require@_auth\ list in an \%smtp%\ transport |
| 19121 | .nextp |
| 19122 | \*refused@_MX*\: connection refused from a host obtained from an MX record |
| 19123 | .nextp |
| 19124 | \*refused@_A*\: connection refused from a host not obtained from an MX record |
| 19125 | .nextp |
| 19126 | \*refused*\: any connection refusal |
| 19127 | .nextp |
| 19128 | \*timeout@_connect@_MX*\: connection timeout from a host obtained from an MX |
| 19129 | record |
| 19130 | .nextp |
| 19131 | \*timeout@_connect@_A*\: connection timeout from a host not obtained from an MX |
| 19132 | record |
| 19133 | .nextp |
| 19134 | \*timeout@_connect*\: any connection timeout |
| 19135 | .nextp |
| 19136 | \*timeout@_MX*\: any timeout from a host obtained from an MX |
| 19137 | record |
| 19138 | .nextp |
| 19139 | \*timeout@_A*\: any timeout from a host not obtained from an MX |
| 19140 | record |
| 19141 | .nextp |
| 19142 | \*timeout*\: any timeout |
| 19143 | .nextp |
| 19144 | \*quota*\: quota exceeded in local delivery by \%appendfile%\ |
| 19145 | .nextp |
| 19146 | .index quota||error testing in retry rule |
| 19147 | .index retry||quota error testing |
| 19148 | \*quota@_*\<<time>>: quota exceeded in local delivery, and the mailbox has not |
| 19149 | been read for <<time>>. For example, \*quota@_4d*\ applies to a quota error |
| 19150 | when the mailbox has not been read for four days. |
| 19151 | |
| 19152 | .index mailbox||time of last read |
| 19153 | \**Warning**\: It is not always possible to determine a `time of last read' for |
| 19154 | a mailbox: |
| 19155 | .numberpars $. |
| 19156 | If the mailbox is a single file, the time of last access is used. |
| 19157 | .nextp |
| 19158 | .index maildir format||time of last read |
| 19159 | For a maildir delivery, the time of last modification of the \(new)\ |
| 19160 | subdirectory is used. As the mailbox is over quota, no new files will be |
| 19161 | created in the \(new)\ subdirectory, so any change is assumed to be the result |
| 19162 | of an MUA moving a new message to the \(cur)\ directory when it is first read. |
| 19163 | .nextp |
| 19164 | For other kinds of multi-file delivery, the time of last read cannot be |
| 19165 | obtained, and so a retry rule that uses this type of error field is never |
| 19166 | matched. |
| 19167 | .endp |
| 19168 | .endp |
| 19169 | The quota errors apply both to system-enforced quotas and to Exim's own quota |
| 19170 | mechanism in the \%appendfile%\ transport. The \*quota*\ error also applies |
| 19171 | when a local delivery is deferred because a partition is full (the \\ENOSPC\\ |
| 19172 | error). |
| 19173 | |
| 19174 | |
| 19175 | .section Retry rule parameters |
| 19176 | .index retry||parameters in rules |
| 19177 | The third field in a retry rule is a sequence of retry parameter sets, |
| 19178 | separated by semicolons. Each set consists of |
| 19179 | .display |
| 19180 | <<letter>>,<<cutoff time>>,<<arguments>> |
| 19181 | .endd |
| 19182 | The letter identifies the algorithm for computing a new retry time; the cutoff |
| 19183 | time is the time beyond which this algorithm no longer applies, and the |
| 19184 | arguments vary the algorithm's action. The cutoff time is measured from the |
| 19185 | time that the first failure for the domain (combined with the local part if |
| 19186 | relevant) was detected, not from the time the message was received. |
| 19187 | .index retry||algorithms |
| 19188 | The available algorithms are: |
| 19189 | .numberpars $. |
| 19190 | \*F*\: retry at fixed intervals. There is a single time parameter specifying the |
| 19191 | interval. |
| 19192 | .nextp |
| 19193 | \*G*\: retry at geometrically increasing intervals. The first argument specifies |
| 19194 | a starting value for the interval, and the second a multiplier, which is used |
| 19195 | to increase the size of the interval at each retry. |
| 19196 | .endp |
| 19197 | When computing the next retry time, the algorithm definitions are scanned in |
| 19198 | order until one whose cutoff time has not yet passed is reached. This is then |
| 19199 | used to compute a new retry time that is later than the current time. In the |
| 19200 | case of fixed interval retries, this simply means adding the interval to the |
| 19201 | current time. For geometrically increasing intervals, retry intervals are |
| 19202 | computed from the rule's parameters until one that is greater than the previous |
| 19203 | interval is found. The main configuration variable |
| 19204 | .index limit||retry interval |
| 19205 | .index retry||interval, maximum |
| 19206 | .index \retry@_interval@_max\ |
| 19207 | \retry@_interval@_max\ limits the maximum interval between retries. |
| 19208 | |
| 19209 | A single remote domain may have a number of hosts associated with it, and each |
| 19210 | host may have more than one IP address. Retry algorithms are selected on the |
| 19211 | basis of the domain name, but are applied to each IP address independently. If, |
| 19212 | for example, a host has two IP addresses and one is unusable, Exim will |
| 19213 | generate retry times for it and will not try to use it until its next retry |
| 19214 | time comes. Thus the good IP address is likely to be tried first most of the |
| 19215 | time. |
| 19216 | |
| 19217 | .index hints database||use for retrying |
| 19218 | Retry times are hints rather than promises. Exim does not make any attempt to |
| 19219 | run deliveries exactly at the computed times. Instead, a queue runner process |
| 19220 | starts delivery processes for delayed messages periodically, and these attempt |
| 19221 | new deliveries only for those addresses that have passed their next retry time. |
| 19222 | If a new message arrives for a deferred address, an immediate delivery attempt |
| 19223 | occurs only if the address has passed its retry time. In the absence of new |
| 19224 | messages, the minimum time between retries is the interval between queue runner |
| 19225 | processes. There is not much point in setting retry times of five minutes if |
| 19226 | your queue runners happen only once an hour, unless there are a significant |
| 19227 | number of incoming messages (which might be the case on a system that is |
| 19228 | sending everything to a smart host, for example). |
| 19229 | |
| 19230 | The data in the retry hints database can be inspected by using the |
| 19231 | \*exim@_dumpdb*\ or \*exim@_fixdb*\ utility programs (see chapter ~~CHAPutils). The |
| 19232 | latter utility can also be used to change the data. The \*exinext*\ utility |
| 19233 | script can be used to find out what the next retry times are for the hosts |
| 19234 | associated with a particular mail domain, and also for local deliveries that |
| 19235 | have been deferred. |
| 19236 | |
| 19237 | .section Retry rule examples |
| 19238 | Here are some example retry rules: |
| 19239 | .display asis |
| 19240 | alice@wonderland.fict.example quota_5d F,7d,3h |
| 19241 | wonderland.fict.example quota_5d |
| 19242 | wonderland.fict.example * F,1h,15m; G,2d,1h,2; |
| 19243 | lookingglass.fict.example * F,24h,30m; |
| 19244 | * refused_A F,2h,20m; |
| 19245 | * * F,2h,15m; G,16h,1h,1.5; F,5d,8h |
| 19246 | .endd |
| 19247 | The first rule sets up special handling for mail to |
| 19248 | \*alice@@wonderland.fict.example*\ when there is an over-quota error and the |
| 19249 | mailbox has not been read for at least 5 days. Retries continue every three |
| 19250 | hours for 7 days. The second rule handles over-quota errors for all other local |
| 19251 | parts at \*wonderland.fict.example*\; the absence of a local part has the same |
| 19252 | effect as supplying `$*$@@'. As no retry algorithms are supplied, messages that |
| 19253 | fail are bounced immediately if the mailbox has not been read for at least 5 |
| 19254 | days. |
| 19255 | |
| 19256 | The third rule handles all other errors at \*wonderland.fict.example*\; retries |
| 19257 | happen every 15 minutes for an hour, then with geometrically increasing |
| 19258 | intervals until two days have passed since a delivery first failed. After the |
| 19259 | first hour there is a delay of one hour, then two hours, then four hours, and |
| 19260 | so on (this is a rather extreme example). |
| 19261 | |
| 19262 | The fourth rule controls retries for the domain \*lookingglass.fict.example*\. |
| 19263 | They happen every 30 minutes for 24 hours only. The remaining two rules handle |
| 19264 | all other domains, with special action for connection refusal from hosts that |
| 19265 | were not obtained from an MX record. |
| 19266 | |
| 19267 | The final rule in a retry configuration should always have asterisks in the |
| 19268 | first two fields so as to provide a general catch-all for any addresses that do |
| 19269 | not have their own special handling. This example tries every 15 minutes for 2 |
| 19270 | hours, then with intervals starting at one hour and increasing by a factor of |
| 19271 | 1.5 up to 16 hours, then every 8 hours up to 5 days. |
| 19272 | |
| 19273 | |
| 19274 | .section Timeout of retry data |
| 19275 | .index timeout||of retry data |
| 19276 | .index \retry@_data@_expire\ |
| 19277 | .index hints database||data expiry |
| 19278 | .index retry||timeout of data |
| 19279 | Exim timestamps the data that it writes to its retry hints database. When it |
| 19280 | consults the data during a delivery it ignores any that is older than the value |
| 19281 | set in \retry@_data@_expire\ (default 7 days). If, for example, a host hasn't |
| 19282 | been tried for 7 days, Exim will try to deliver to it immediately a message |
| 19283 | arrives, and if that fails, it will calculate a retry time as if it were |
| 19284 | failing for the first time. |
| 19285 | |
| 19286 | This improves the behaviour for messages routed to rarely-used hosts such as MX |
| 19287 | backups. If such a host was down at one time, and happens to be down again when |
| 19288 | Exim tries a month later, using the old retry data would imply that it had been |
| 19289 | down all the time, which is not a justified assumption. |
| 19290 | |
| 19291 | If a host really is permanently dead, this behaviour causes a burst of retries |
| 19292 | every now and again, but only if messages routed to it are rare. It there is a |
| 19293 | message at least once every 7 days the retry data never expires. |
| 19294 | |
| 19295 | |
| 19296 | |
| 19297 | .section Long-term failures |
| 19298 | .index delivery||failure, long-term |
| 19299 | .index retry||after long-term failure |
| 19300 | Special processing happens when an email address has been failing for so long |
| 19301 | that the cutoff time for the last algorithm is reached. For example, using the |
| 19302 | default retry rule: |
| 19303 | .display asis |
| 19304 | * * F,2h,15m; G,16h,1h,1.5; F,4d,6h |
| 19305 | .endd |
| 19306 | the cutoff time is four days. Reaching the retry cutoff is independent of how |
| 19307 | long any specific message has been failing; it is the length of continuous |
| 19308 | failure for the recipient address that counts. |
| 19309 | |
| 19310 | When the cutoff time is reached for a local delivery, or for all the IP |
| 19311 | addresses associated with a remote delivery, a subsequent delivery failure |
| 19312 | causes Exim to give up on the address, and a bounce message is generated. |
| 19313 | In order to cater for new messages that use the failing address, a next retry |
| 19314 | time is still computed from the final algorithm, and is used as follows: |
| 19315 | |
| 19316 | For local deliveries, one delivery attempt is always made for any subsequent |
| 19317 | messages. If this delivery fails, the address fails immediately. The |
| 19318 | post-cutoff retry time is not used. |
| 19319 | |
| 19320 | If the delivery is remote, there are two possibilities, controlled by the |
| 19321 | .index \delay@_after@_cutoff\ |
| 19322 | \delay@_after@_cutoff\ option of the \%smtp%\ transport. The option is true by |
| 19323 | default and in that case: |
| 19324 | .numberpars " " |
| 19325 | Until the post-cutoff retry time for one of the IP addresses is reached, |
| 19326 | the failing email address is bounced immediately, without a delivery attempt |
| 19327 | taking place. After that time, one new delivery attempt is made to those IP |
| 19328 | addresses that are past their retry times, and if that still fails, the address |
| 19329 | is bounced and new retry times are computed. |
| 19330 | .endp |
| 19331 | |
| 19332 | In other words, when all the hosts for a given email address have been failing |
| 19333 | for a long time, Exim bounces rather then defers until one of the hosts' retry |
| 19334 | times is reached. Then it tries once, and bounces if that attempt fails. This |
| 19335 | behaviour ensures that few resources are wasted in repeatedly trying to deliver |
| 19336 | to a broken destination, but if the host does recover, Exim will eventually |
| 19337 | notice. |
| 19338 | |
| 19339 | If \delay@_after@_cutoff\ is set false, Exim behaves differently. If all IP |
| 19340 | addresses are past their final cutoff time, Exim tries to deliver to those IP |
| 19341 | addresses that have not been tried since the message arrived. If there are |
| 19342 | no suitable IP addresses, or if they all fail, the address is bounced. In other |
| 19343 | words, it does not delay when a new message arrives, but tries the expired |
| 19344 | addresses immediately, unless they have been tried since the message arrived. |
| 19345 | If there is a continuous stream of messages for the failing domains, setting |
| 19346 | \delay@_after@_cutoff\ false means that there will be many more attempts to |
| 19347 | deliver to permanently failing IP addresses than when \delay@_after@_cutoff\ is |
| 19348 | true. |
| 19349 | |
| 19350 | .section Ultimate address timeout |
| 19351 | .index retry||ultimate address timeout |
| 19352 | An additional rule is needed to cope with cases where a host is intermittently |
| 19353 | available, or when a message has some attribute that prevents its delivery when |
| 19354 | others to the same address get through. In this situation, because some |
| 19355 | messages are successfully delivered, the `retry clock' for the address keeps |
| 19356 | getting restarted, and so a message could remain on the queue for ever. To |
| 19357 | prevent this, if a message has been on the queue for longer than the cutoff |
| 19358 | time of any applicable retry rule for a given address, a delivery is attempted |
| 19359 | for that address, even if it is not yet time, and if this delivery fails, the |
| 19360 | address is timed out. A new retry time is not computed in this case, so that |
| 19361 | other messages for the same address are considered immediately. |
| 19362 | |
| 19363 | |
| 19364 | |
| 19365 | |
| 19366 | |
| 19367 | . |
| 19368 | . |
| 19369 | . |
| 19370 | . |
| 19371 | . ============================================================================ |
| 19372 | .chapter SMTP authentication |
| 19373 | .set runningfoot "SMTP authentication" |
| 19374 | .rset CHAPSMTPAUTH "~~chapter" |
| 19375 | .index SMTP||authentication configuration |
| 19376 | .index authentication |
| 19377 | The `authenticators' section of Exim's run time configuration is concerned with |
| 19378 | SMTP authentication. This facility is an extension to the SMTP protocol, |
| 19379 | described in RFC 2554, which allows a client SMTP host to authenticate itself |
| 19380 | to a server. This is a common way for a server to recognize clients that |
| 19381 | are permitted to use it as a relay. SMTP authentication is not of relevance to |
| 19382 | the transfer of mail between servers that have no managerial connection with |
| 19383 | each other. |
| 19384 | |
| 19385 | .index \\AUTH\\||description of |
| 19386 | Very briefly, the way SMTP authentication works is as follows: |
| 19387 | .numberpars $. |
| 19388 | The server advertises a number of authentication \*mechanisms*\ in response to |
| 19389 | the client's \\EHLO\\ command. |
| 19390 | .nextp |
| 19391 | The client issues an \\AUTH\\ command, naming a specific mechanism. The command |
| 19392 | may, optionally, contain some authentication data. |
| 19393 | .nextp |
| 19394 | The server may issue one or more \*challenges*\, to which the client must send |
| 19395 | appropriate responses. In simple authentication mechanisms, the challenges are |
| 19396 | just prompts for user names and passwords. The server does not have to issue |
| 19397 | any challenges -- in some mechanisms the relevant data may all be transmitted |
| 19398 | with the \\AUTH\\ command. |
| 19399 | .nextp |
| 19400 | The server either accepts or denies authentication. |
| 19401 | .nextp |
| 19402 | If authentication succeeds, the client may optionally make use of the \\AUTH\\ |
| 19403 | option on the \\MAIL\\ command to pass an authenticated sender in subsequent |
| 19404 | mail transactions. Authentication lasts for the remainder of the SMTP |
| 19405 | connection. |
| 19406 | .nextp |
| 19407 | If authentication fails, the client may give up, or it may try a different |
| 19408 | authentication mechanism, or it may try transferring mail over the |
| 19409 | unauthenticated connection. |
| 19410 | .endp |
| 19411 | If you are setting up a client, and want to know which authentication |
| 19412 | mechanisms the server supports, you can use Telnet to connect to port 25 (the |
| 19413 | SMTP port) on the server, and issue an \\EHLO\\ command. The response to this |
| 19414 | includes the list of supported mechanisms. For example: |
| 19415 | .display |
| 19416 | @$ $cb{telnet server.example 25} |
| 19417 | Trying 192.168.34.25... |
| 19418 | Connected to server.example. |
| 19419 | Escape character is '@^]'. |
| 19420 | 220 server.example ESMTP Exim 4.20 ... |
| 19421 | $cb{ehlo client.example} |
| 19422 | 250-server.example Hello client.example [10.8.4.5] |
| 19423 | 250-SIZE 52428800 |
| 19424 | 250-PIPELINING |
| 19425 | 250-AUTH PLAIN |
| 19426 | 250 HELP |
| 19427 | .endd |
| 19428 | The second-last line of this example output shows that the server supports |
| 19429 | authentication using the PLAIN mechanism. In Exim, the different authentication |
| 19430 | mechanisms are configured by specifying \*authenticator*\ drivers. Like the |
| 19431 | routers and transports, which authenticators are included in the binary is |
| 19432 | controlled by build-time definitions. The following are currently available, |
| 19433 | included by setting |
| 19434 | .display asis |
| 19435 | AUTH_CRAM_MD5=yes |
| 19436 | AUTH_PLAINTEXT=yes |
| 19437 | AUTH_SPA=yes |
| 19438 | .endd |
| 19439 | in \(Local/Makefile)\, respectively. The first of these supports the CRAM-MD5 |
| 19440 | authentication mechanism (RFC 2195), and the second can be configured to |
| 19441 | support the PLAIN authentication mechanism (RFC 2595) or the LOGIN mechanism, |
| 19442 | which is not formally documented, but used by several MUAs. The third |
| 19443 | authenticator supports Microsoft's \*Secure Password Authentication*\ |
| 19444 | mechanism. |
| 19445 | |
| 19446 | The authenticators are configured using the same syntax as other drivers (see |
| 19447 | section ~~SECTfordricon). If no authenticators are required, no authentication |
| 19448 | section need be present in the configuration file. Each authenticator can in |
| 19449 | principle have both server and client functions. When Exim is receiving SMTP |
| 19450 | mail, it is acting as a server; when it is sending out messages over SMTP, it |
| 19451 | is acting as a client. Authenticator configuration options are provided for use |
| 19452 | in both these circumstances. |
| 19453 | |
| 19454 | To make it clear which options apply to which situation, the prefixes |
| 19455 | \server@_\ and \client@_\ are used on option names that are specific to either |
| 19456 | the server or the client function, respectively. Server and client functions |
| 19457 | are disabled if none of their options are set. If an authenticator is to be |
| 19458 | used for both server and client functions, a single definition, using both sets |
| 19459 | of options, is required. For example: |
| 19460 | .display asis |
| 19461 | cram: |
| 19462 | driver = cram_md5 |
| 19463 | public_name = CRAM-MD5 |
| 19464 | server_secret = ${if eq{$1}{ph10}{secret1}fail} |
| 19465 | client_name = ph10 |
| 19466 | client_secret = secret2 |
| 19467 | .endd |
| 19468 | The \server@_\ option is used when Exim is acting as a server, and the |
| 19469 | \client@_\ options when it is acting as a client. |
| 19470 | |
| 19471 | Descriptions of the individual authenticators are given in subsequent chapters. |
| 19472 | The remainder of this chapter covers the generic options for the |
| 19473 | authenticators, followed by general discussion of the way authentication works |
| 19474 | in Exim. |
| 19475 | |
| 19476 | |
| 19477 | .section Generic options for authenticators |
| 19478 | .index authentication||generic options |
| 19479 | |
| 19480 | .startconf |
| 19481 | .index options||generic, for authenticators |
| 19482 | |
| 19483 | .conf driver string unset |
| 19484 | This option must always be set. It specifies which of the available |
| 19485 | authenticators is to be used. |
| 19486 | |
| 19487 | .conf public@_name string unset |
| 19488 | This option specifies the name of the authentication mechanism that the driver |
| 19489 | implements, and by which it is known to the outside world. These names should |
| 19490 | contain only upper case letters, digits, underscores, and hyphens (RFC 2222), |
| 19491 | but Exim in fact matches them caselessly. If \public@_name\ is not set, it |
| 19492 | defaults to the driver's instance name. |
| 19493 | |
| 19494 | .conf server@_advertise@_condition string$**$ unset |
| 19495 | When a server is about to advertise an authentication mechanism, the condition |
| 19496 | is expanded. If it yields the empty string, `0', `no', or `false', the |
| 19497 | mechanism is not advertised. |
| 19498 | If the expansion fails, the mechanism is not advertised. If the failure was not |
| 19499 | forced, and was not caused by a lookup defer, the incident is logged. |
| 19500 | See section ~~SECTauthexiser below for further discussion. |
| 19501 | |
| 19502 | .conf server@_debug@_print string$**$ unset |
| 19503 | If this option is set and authentication debugging is enabled (see the \-d-\ |
| 19504 | command line option), the string is expanded and included in the debugging |
| 19505 | output when the authenticator is run as a server. This can help with checking |
| 19506 | out the values of variables. |
| 19507 | If expansion of the string fails, the error message is written to the debugging |
| 19508 | output, and Exim carries on processing. |
| 19509 | |
| 19510 | .conf server@_set@_id string$**$ unset |
| 19511 | When an Exim server successfully authenticates a client, this string is |
| 19512 | expanded using data from the authentication, and preserved for any incoming |
| 19513 | messages in the variable \$authenticated@_id$\. It is also included in the log |
| 19514 | lines for incoming messages. For example, a user/password authenticator |
| 19515 | configuration might preserve the user name that was used to authenticate, and |
| 19516 | refer to it subsequently during delivery of the message. |
| 19517 | If expansion fails, the option is ignored. |
| 19518 | |
| 19519 | .conf server@_mail@_auth@_condition string$**$ unset |
| 19520 | This option allows a server to discard authenticated sender addresses supplied |
| 19521 | as part of \\MAIL\\ commands in SMTP connections that are authenticated by the |
| 19522 | driver on which \server__mail__auth@_condition\ is set. The option is not used |
| 19523 | as part of the authentication process; instead its (unexpanded) value is |
| 19524 | remembered for later use. |
| 19525 | How it is used is described in the following section. |
| 19526 | .endconf |
| 19527 | |
| 19528 | |
| 19529 | |
| 19530 | .section The AUTH parameter on MAIL commands |
| 19531 | .rset SECTauthparamail "~~chapter.~~section" |
| 19532 | .index authentication||sender, authenticated |
| 19533 | .index \\AUTH\\||on \\MAIL\\ command |
| 19534 | When a client supplied an \\AUTH=\\ item on a \\MAIL\\ command, Exim applies |
| 19535 | the following checks before accepting it as the authenticated sender of the |
| 19536 | message: |
| 19537 | .numberpars $. |
| 19538 | If the connection is not using extended SMTP (that is, \\HELO\\ was used rather |
| 19539 | than \\EHLO\\), the use of \\AUTH=\\ is a syntax error. |
| 19540 | .nextp |
| 19541 | If the value of the \\AUTH=\\ parameter is `@<@>', it is ignored. |
| 19542 | .nextp |
| 19543 | If \acl@_smtp@_mailauth\ is defined, the ACL it specifies is run. While it is |
| 19544 | running, the value of \$authenticated@_sender$\ is set to the value obtained |
| 19545 | from the \\AUTH=\\ parameter. If the ACL does not yield `accept', the value of |
| 19546 | \$authenticated@_sender$\ is deleted. The \acl@_smtp@_mailauth\ ACL may not |
| 19547 | return `drop' or `discard'. If it defers, a temporary error code (451) is given |
| 19548 | for the \\MAIL\\ command. |
| 19549 | .nextp |
| 19550 | If \acl@_smtp@_mailauth\ is not defined, the value of the \\AUTH=\\ parameter |
| 19551 | is accepted and placed in \$authenticated@_sender$\ only if the client has |
| 19552 | authenticated. |
| 19553 | .nextp |
| 19554 | If the \\AUTH=\\ value was accepted by either of the two previous rules, and |
| 19555 | the client has authenticated, and the authenticator has a setting for the |
| 19556 | \server@_mail@_auth@_condition\, the condition is checked at this point. The |
| 19557 | valued that was saved from the authenticator is expanded. If the expansion |
| 19558 | fails, or yields an empty string, `0', `no', or `false', the value of |
| 19559 | \$authenticated__sender$\ is deleted. If the expansion yields any other value, |
| 19560 | the value of \$authenticated@_sender$\ is retained and passed on with the |
| 19561 | message. |
| 19562 | .endp |
| 19563 | |
| 19564 | When \$authenticated@_sender$\ is set for a message, it is passed on to other |
| 19565 | hosts to which Exim authenticates as a client. Do not confuse this value with |
| 19566 | \$authenticated@_id$\, which is a string obtained from the authentication |
| 19567 | process, and which is not usually a complete email address. |
| 19568 | |
| 19569 | Whenever an \\AUTH=\\ value is ignored, the incident is logged. The ACL for |
| 19570 | \\MAIL\\, if defined, is run after \\AUTH=\\ is accepted or ignored. It can |
| 19571 | therefore make use of \$authenticated@_sender$\. The converse is not true: the |
| 19572 | value of \$sender@_address$\ is not yet set up when the \acl@_smtp@_mailauth\ |
| 19573 | ACL is run. |
| 19574 | |
| 19575 | |
| 19576 | .section Authentication on an Exim server |
| 19577 | .rset SECTauthexiser "~~chapter.~~section" |
| 19578 | .index authentication||on an Exim server |
| 19579 | When Exim receives an \\EHLO\\ command, it advertises the public names of those |
| 19580 | authenticators that are configured as servers, subject to the following |
| 19581 | conditions: |
| 19582 | .numberpars $. |
| 19583 | The client host must match \auth@_advertise@_hosts\ (default $*$). |
| 19584 | .nextp |
| 19585 | It the \server@_advertise@_condition\ option is set, its expansion must not |
| 19586 | yield the empty string, `0', `no', or `false'. |
| 19587 | .endp |
| 19588 | The order in which the authenticators are defined controls the order in which |
| 19589 | the mechanisms are advertised. |
| 19590 | |
| 19591 | Some mail clients (for example, some versions of Netscape) require the user to |
| 19592 | provide a name and password for authentication whenever \\AUTH\\ is advertised, |
| 19593 | even though authentication may not in fact be needed (for example, Exim may be |
| 19594 | set up to allow unconditional relaying from the client by an IP address check). |
| 19595 | You can make such clients more friendly by not advertising \\AUTH\\ to them. |
| 19596 | For example, if clients on the 10.9.8.0/24 network are permitted (by the ACL |
| 19597 | that runs for \\RCPT\\) to relay without authentication, you should set |
| 19598 | .display asis |
| 19599 | auth_advertise_hosts = ! 10.9.8.0/24 |
| 19600 | .endd |
| 19601 | so that no authentication mechanisms are advertised to them. |
| 19602 | |
| 19603 | The \server@_advertise@_condition\ controls the advertisement of individual |
| 19604 | authentication mechanisms. For example, it can be used to restrict the |
| 19605 | advertisement of a patricular mechanism to encrypted connections, by a setting |
| 19606 | such as: |
| 19607 | .display asis |
| 19608 | server_advertise_condition = ${if eq{$tls_cipher}{}{no}{yes}} |
| 19609 | .endd |
| 19610 | If the session is encrypted, \$tls@_cipher$\ is not empty, and so the expansion |
| 19611 | yields `yes', which allows the advertisement to happen. |
| 19612 | |
| 19613 | When an Exim server receives an \\AUTH\\ command from a client, it rejects it |
| 19614 | immediately if \\AUTH\\ was not advertised in response to an earlier \\EHLO\\ |
| 19615 | command. This is the case if |
| 19616 | .numberpars $. |
| 19617 | The client host does not match \auth@_advertise@_hosts\; or |
| 19618 | .nextp |
| 19619 | No authenticators are configured with server options; or |
| 19620 | .nextp |
| 19621 | Expansion of \server@_advertise@_condition\ blocked the advertising of all the |
| 19622 | server authenticators. |
| 19623 | .endp |
| 19624 | |
| 19625 | Otherwise, Exim runs the ACL specified by \acl@_smtp@_auth\ in order |
| 19626 | to decide whether to accept the command. If \acl@_smtp@_auth\ is not set, |
| 19627 | \\AUTH\\ is accepted from any client host. |
| 19628 | |
| 19629 | If \\AUTH\\ is not rejected by the ACL, Exim searches its configuration for a |
| 19630 | server authentication mechanism that was advertised in response to \\EHLO\\ and |
| 19631 | that matches the one named in the \\AUTH\\ command. If it finds one, it runs |
| 19632 | the appropriate authentication protocol, and authentication either succeeds or |
| 19633 | fails. If there is no matching advertised mechanism, the \\AUTH\\ command is |
| 19634 | rejected with a 504 error. |
| 19635 | |
| 19636 | When a message is received from an authenticated host, the value of |
| 19637 | \$received@_protocol$\ is set to `asmtp' instead of `esmtp', and |
| 19638 | \$sender@_host@_authenticated$\ contains the name (not the public name) of the |
| 19639 | authenticator driver that successfully authenticated the client from which the |
| 19640 | message was received. This variable is empty if there was no successful |
| 19641 | authentication. |
| 19642 | |
| 19643 | |
| 19644 | |
| 19645 | .section Testing server authentication |
| 19646 | .index authentication||testing a server |
| 19647 | .index \\AUTH\\||testing a server |
| 19648 | .index base64 encoding||creating authentication test data |
| 19649 | Exim's \-bh-\ option can be useful for testing server authentication |
| 19650 | configurations. The data for the \\AUTH\\ command has to be sent using base64 |
| 19651 | encoding. A quick way to produce such data for testing is the following Perl |
| 19652 | script: |
| 19653 | .display asis |
| 19654 | use MIME::Base64; |
| 19655 | printf ("%s", encode_base64(eval "\"$ARGV[0]\"")); |
| 19656 | .endd |
| 19657 | .index binary zero||in authentication data |
| 19658 | This interprets its argument as a Perl string, and then encodes it. The |
| 19659 | interpretation as a Perl string allows binary zeros, which are required for |
| 19660 | some kinds of authentication, to be included in the data. For example, a |
| 19661 | command line to run this script on such data might be |
| 19662 | .display asis |
| 19663 | encode '\0user\0password' |
| 19664 | .endd |
| 19665 | Note the use of single quotes to prevent the shell interpreting the |
| 19666 | backslashes, so that they can be interpreted by Perl to specify characters |
| 19667 | whose code value is zero. |
| 19668 | |
| 19669 | \**Warning 1**\: If either of the user or password strings starts with an octal |
| 19670 | digit, you must use three zeros instead of one after the leading backslash. If |
| 19671 | you do not, the octal digit that starts your string will be incorrectly |
| 19672 | interpreted as part of the code for the first character. |
| 19673 | |
| 19674 | \**Warning 2**\: If there are characters in the strings that Perl interprets |
| 19675 | specially, you must use a Perl escape to prevent them being misinterpreted. For |
| 19676 | example, a command such as |
| 19677 | .display asis |
| 19678 | encode '\0user@domain.com\0pas$$word' |
| 19679 | .endd |
| 19680 | gives an incorrect answer because of the unescaped `@@' and `@$' characters. |
| 19681 | |
| 19682 | If you have the \mimencode\ command installed, another way to do produce |
| 19683 | base64-encoded strings is to run the command |
| 19684 | .display asis |
| 19685 | echo -e -n `\0user\0password' | mimencode |
| 19686 | .endd |
| 19687 | The \-e-\ option of \echo\ enables the interpretation of backslash escapes in |
| 19688 | the argument, and the \-n-\ option specifies no newline at the end of its |
| 19689 | output. However, not all versions of \echo\ recognize these options, so you |
| 19690 | should check your version before relying on this suggestion. |
| 19691 | |
| 19692 | |
| 19693 | .section Authentication by an Exim client |
| 19694 | .index authentication||on an Exim client |
| 19695 | The \%smtp%\ transport has two options called \hosts@_require@_auth\ and |
| 19696 | \hosts@_try@_auth\. When the \%smtp%\ transport connects to a server that |
| 19697 | announces support for authentication, and the host matches an entry in either |
| 19698 | of these options, Exim (as a client) tries to authenticate as follows: |
| 19699 | .numberpars $. |
| 19700 | For each authenticator that is configured as a client, it searches the |
| 19701 | authentication mechanisms announced by the server for one whose name |
| 19702 | matches the public name of the authenticator. |
| 19703 | .nextp |
| 19704 | When it finds one that matches, it runs the authenticator's client code. |
| 19705 | The variables \$host$\ and \$host@_address$\ are available for any string |
| 19706 | expansions that the client might do. They are set to the server's name and |
| 19707 | IP address. If any expansion is forced to fail, the authentication attempt |
| 19708 | is abandoned, |
| 19709 | and Exim moves on to the next authenticator. |
| 19710 | Otherwise an expansion failure causes delivery to be |
| 19711 | deferred. |
| 19712 | .nextp |
| 19713 | If the result of the authentication attempt is a temporary error or a timeout, |
| 19714 | Exim abandons trying to send the message to the host for the moment. It will |
| 19715 | try again later. If there are any backup hosts available, they are tried in the |
| 19716 | usual way. |
| 19717 | .nextp |
| 19718 | If the response to authentication is a permanent error (5xx code), Exim carries |
| 19719 | on searching the list of authenticators and tries another one if possible. If |
| 19720 | all authentication attempts give permanent errors, or if there are no attempts |
| 19721 | because no mechanisms match |
| 19722 | (or option expansions force failure), |
| 19723 | what happens depends on whether the host matches \hosts@_require@_auth\ or |
| 19724 | \hosts@_try@_auth\. In the first case, a temporary error is generated, and |
| 19725 | delivery is deferred. The error can be detected in the retry rules, and thereby |
| 19726 | turned into a permanent error if you wish. In the second case, Exim tries to |
| 19727 | deliver the message unauthenticated. |
| 19728 | .endp |
| 19729 | .index \\AUTH\\||on \\MAIL\\ command |
| 19730 | When Exim has authenticated itself to a remote server, it adds the \\AUTH\\ |
| 19731 | parameter to the \\MAIL\\ commands it sends, if it has an authenticated sender |
| 19732 | for the message. |
| 19733 | If the message came from a remote host, the authenticated sender is the one |
| 19734 | that was receiving on an incoming \\MAIL\\ command, provided that the incoming |
| 19735 | connection was authenticated and the \server@_mail@_auth\ condition allowed the |
| 19736 | authenticated sender to be retained. If a local process calls Exim to send a |
| 19737 | message, the sender address that is built from the login name and |
| 19738 | \qualify@_domain\ is treated as authenticated. However, if the |
| 19739 | \authenticated@_sender\ option is set on the \%smtp%\ transport, it overrides |
| 19740 | the authenticated sender that was received with the message. |
| 19741 | |
| 19742 | |
| 19743 | |
| 19744 | |
| 19745 | |
| 19746 | |
| 19747 | . |
| 19748 | . |
| 19749 | . |
| 19750 | . |
| 19751 | . ============================================================================ |
| 19752 | .chapter The plaintext authenticator |
| 19753 | .rset CHAPplaintext "~~chapter" |
| 19754 | .set runningfoot "plaintext authenticator" |
| 19755 | .index \%plaintext%\ authenticator |
| 19756 | .index authenticators||\%plaintext%\ |
| 19757 | The \%plaintext%\ authenticator can be configured to support the PLAIN and |
| 19758 | LOGIN authentication mechanisms, both of which transfer authentication data as |
| 19759 | plain (unencrypted) text (though base64 encoded). The use of plain text is a |
| 19760 | security risk. If you use one of these mechanisms without also making use of |
| 19761 | SMTP encryption (see chapter ~~CHAPTLS) you should not use the same passwords |
| 19762 | for SMTP connections as you do for login accounts. |
| 19763 | |
| 19764 | .section Using plaintext in a server |
| 19765 | When running as a server, \%plaintext%\ performs the authentication test by |
| 19766 | expanding a string. It has the following options: |
| 19767 | |
| 19768 | .startconf |
| 19769 | .index options||\%plaintext%\ authenticator (server) |
| 19770 | |
| 19771 | .conf server@_prompts string$**$ unset |
| 19772 | The contents of this option, after expansion, must be a colon-separated list of |
| 19773 | prompt strings. If expansion fails, a temporary authentication rejection is |
| 19774 | given. |
| 19775 | |
| 19776 | .conf server@_condition string$**$ unset |
| 19777 | This option must be set in order to configure the driver as a server. Its use |
| 19778 | is described below. |
| 19779 | |
| 19780 | .endconf |
| 19781 | |
| 19782 | .index \\AUTH\\||in \%plaintext%\ authenticator |
| 19783 | .index binary zero||in \%plaintext%\ authenticator |
| 19784 | .index numerical variables (\$1$\, \$2$\, etc)||in \%plaintext%\ authenticator |
| 19785 | .index base64 encoding||in \%plaintext%\ authenticator |
| 19786 | The data sent by the client with the \\AUTH\\ command, or in response to |
| 19787 | subsequent prompts, is base64 encoded, and so may contain any byte values |
| 19788 | when decoded. If any data is supplied with the command, it is treated as a |
| 19789 | list of strings, separated by NULs (binary zeros), which are placed in the |
| 19790 | expansion variables \$1$\, \$2$\, etc. If there are more strings in |
| 19791 | \server@_prompts\ than the number of strings supplied with the \\AUTH\\ |
| 19792 | command, the remaining prompts are used to obtain more data. Each response from |
| 19793 | the client may be a list of NUL-separated strings. |
| 19794 | |
| 19795 | Once a sufficient number of data strings have been received, |
| 19796 | \server@_condition\ is expanded. |
| 19797 | If the expansion is forced to fail, authentication fails. Any other expansion |
| 19798 | failure causes a temporary error code to be returned. |
| 19799 | If the result of a successful expansion is an empty string, `0', `no', or |
| 19800 | `false', authentication fails. If the result of the expansion is `1', `yes', or |
| 19801 | `true', authentication succeeds and the generic \server@_set@_id\ option is |
| 19802 | expanded and saved in \$authenticated@_id$\. For any other result, a temporary |
| 19803 | error code is returned, with the expanded string as the error text. |
| 19804 | |
| 19805 | \**Warning**\: If you use a lookup in the expansion to find the user's |
| 19806 | password, be sure to make the authentication fail if the user is unknown. |
| 19807 | There are good and bad examples at the end of the next section. |
| 19808 | |
| 19809 | |
| 19810 | .section The PLAIN authentication mechanism |
| 19811 | .index PLAIN authentication mechanism |
| 19812 | .index authentication||PLAIN mechanism |
| 19813 | .index binary zero||in \%plaintext%\ authenticator |
| 19814 | The PLAIN authentication mechanism (RFC 2595) specifies that three strings be |
| 19815 | sent as one item of data (that is, one combined string containing two NUL |
| 19816 | separators). The data is sent either as part of the \\AUTH\\ command, or |
| 19817 | subsequently in response to an empty prompt from the server. |
| 19818 | |
| 19819 | The second and third strings are a user name and a corresponding password. |
| 19820 | Using a single fixed user name and password as an example, this could be |
| 19821 | configured as follows: |
| 19822 | .display asis |
| 19823 | fixed_plain: |
| 19824 | driver = plaintext |
| 19825 | public_name = PLAIN |
| 19826 | server_prompts = : |
| 19827 | server_condition = \ |
| 19828 | ${if and {{eq{$2}{username}}{eq{$3}{mysecret}}}{yes}{no}} |
| 19829 | server_set_id = $2 |
| 19830 | .endd |
| 19831 | The \server@_prompts\ setting specifies a single, empty prompt (empty items at |
| 19832 | the end of a string list are ignored). If all the data comes as part of the |
| 19833 | \\AUTH\\ command, as is commonly the case, the prompt is not used. This |
| 19834 | authenticator is advertised in the response to \\EHLO\\ as |
| 19835 | .display asis |
| 19836 | 250-AUTH PLAIN |
| 19837 | .endd |
| 19838 | and a client host can authenticate itself by sending the command |
| 19839 | .display asis |
| 19840 | AUTH PLAIN AHVzZXJuYW1lAG15c2VjcmV0 |
| 19841 | .endd |
| 19842 | As this contains three strings (more than the number of prompts), no further |
| 19843 | data is required from the client. Alternatively, the client may just send |
| 19844 | .display asis |
| 19845 | AUTH PLAIN |
| 19846 | .endd |
| 19847 | to initiate authentication, in which case the server replies with an empty |
| 19848 | prompt. The client must respond with the combined data string. |
| 19849 | |
| 19850 | The data string is base64 encoded, as required by the RFC. This example, |
| 19851 | when decoded, is \"<<NUL>>username<<NUL>>mysecret"\, where <<NUL>> represents a |
| 19852 | zero byte. This is split up into three strings, the first of which is empty. |
| 19853 | The \server@_condition\ option in the authenticator checks that the second two |
| 19854 | are \"username"\ and \"mysecret"\ respectively. |
| 19855 | |
| 19856 | Having just one fixed user name and password, as in this example, is not very |
| 19857 | realistic, though for a small organization with only a handful of |
| 19858 | authenticating clients it could make sense. |
| 19859 | |
| 19860 | A more sophisticated instance of this authenticator could use the user name in |
| 19861 | \$2$\ to look up a password in a file or database, and maybe do an encrypted |
| 19862 | comparison (see \crypteq\ in chapter ~~CHAPexpand). Here is a example of this |
| 19863 | approach, where the passwords are looked up in a DBM file. \**Warning**\: This |
| 19864 | is an incorrect example: |
| 19865 | .display asis |
| 19866 | server_condition = \ |
| 19867 | ${if eq{$3}{${lookup{$2}dbm{/etc/authpwd}}}{yes}{no}} |
| 19868 | .endd |
| 19869 | The expansion uses the user name (\$2$\) as the key to look up a password, |
| 19870 | which it then compares to the supplied password (\$3$\). Why is this example |
| 19871 | incorrect? It works fine for existing users, but consider what happens if a |
| 19872 | non-existent user name is given. The lookup fails, but as no success/failure |
| 19873 | strings are given for the lookup, it yields an empty string. Thus, to defeat |
| 19874 | the authentication, all a client has to do is to supply a non-existent user |
| 19875 | name and an empty password. The correct way of writing this test is: |
| 19876 | .display asis |
| 19877 | server_condition = ${lookup{$2}dbm{/etc/authpwd}\ |
| 19878 | {${if eq{$value}{$3}{yes}{no}}}{no}} |
| 19879 | .endd |
| 19880 | In this case, if the lookup succeeds, the result is checked; if the lookup |
| 19881 | fails, authentication fails. If \crypteq\ is being used instead of \eq\, the |
| 19882 | first example is in fact safe, because \crypteq\ always fails if its second |
| 19883 | argument is empty. However, the second way of writing the test makes the logic |
| 19884 | clearer. |
| 19885 | |
| 19886 | |
| 19887 | .section The LOGIN authentication mechanism |
| 19888 | .index LOGIN authentication mechanism |
| 19889 | .index authentication||LOGIN mechanism |
| 19890 | The LOGIN authentication mechanism is not documented in any RFC, but is in use |
| 19891 | in a number of programs. No data is sent with the \\AUTH\\ command. Instead, a |
| 19892 | user name and password are supplied separately, in response to prompts. The |
| 19893 | plaintext authenticator can be configured to support this as in this example: |
| 19894 | .display asis |
| 19895 | fixed_login: |
| 19896 | driver = plaintext |
| 19897 | public_name = LOGIN |
| 19898 | server_prompts = User Name : Password |
| 19899 | server_condition = \ |
| 19900 | ${if and {{eq{$1}{username}}{eq{$2}{mysecret}}}{yes}{no}} |
| 19901 | server_set_id = $1 |
| 19902 | .endd |
| 19903 | Because of the way plaintext operates, this authenticator accepts data supplied |
| 19904 | with the \\AUTH\\ command (in contravention of the specification of LOGIN), but |
| 19905 | if the client does not supply it (as is the case for LOGIN clients), the prompt |
| 19906 | strings are used to obtain two data items. |
| 19907 | |
| 19908 | Some clients are very particular about the precise text of the prompts. For |
| 19909 | example, Outlook Express is reported to recognize only `Username:' and |
| 19910 | `Password:'. Here is an example of a LOGIN authenticator which uses those |
| 19911 | strings, and which uses the \ldapauth\ expansion condition to check the user |
| 19912 | name and password by binding to an LDAP server: |
| 19913 | .display asis |
| 19914 | login: |
| 19915 | driver = plaintext |
| 19916 | public_name = LOGIN |
| 19917 | server_prompts = Username:: : Password:: |
| 19918 | server_condition = ${if ldapauth \ |
| 19919 | .newline |
| 19920 | {user="cn=${quote_ldap_dn:$1},ou=people,o=example.org" \ |
| 19921 | pass=${quote:$2} \ |
| 19922 | .newline |
| 19923 | ldap://ldap.example.org/}{yes}{no}} |
| 19924 | server_set_id = uid=$1,ou=people,o=example.org |
| 19925 | .endd |
| 19926 | Note the use of the \quote@_ldap@_dn\ operator to correctly quote the DN for |
| 19927 | authentication. However, the basic \quote\ operator, rather than any of the |
| 19928 | LDAP quoting operators, is the correct one to use for the password, because |
| 19929 | quoting is needed only to make the password conform to the Exim syntax. At the |
| 19930 | LDAP level, the password is an uninterpreted string. |
| 19931 | |
| 19932 | |
| 19933 | .section Support for different kinds of authentication |
| 19934 | A number of string expansion features are provided for the purpose of |
| 19935 | interfacing to different ways of user authentication. These include checking |
| 19936 | traditionally encrypted passwords from \(/etc/passwd)\ (or equivalent), PAM, |
| 19937 | Radius, \ldapauth\, and \*pwcheck*\. For details see section ~~SECTexpcond. |
| 19938 | |
| 19939 | |
| 19940 | |
| 19941 | .section Using plaintext in a client |
| 19942 | The \%plaintext%\ authenticator has just one client option: |
| 19943 | |
| 19944 | .startconf |
| 19945 | .index options||\%plaintext%\ authenticator (client) |
| 19946 | |
| 19947 | .conf client@_send string$**$ unset |
| 19948 | The string is a colon-separated list of authentication data strings. Each |
| 19949 | string is independently expanded before being sent to the server. The first |
| 19950 | string is sent with the \\AUTH\\ command; any more strings are sent in response |
| 19951 | to prompts from the server. |
| 19952 | |
| 19953 | \**Note**\: you cannot use expansion to create multiple strings, because |
| 19954 | splitting takes priority and happens first. |
| 19955 | |
| 19956 | Because the PLAIN authentication mechanism requires NUL (binary zero) bytes in |
| 19957 | the data, further processing is applied to each string before it is sent. If |
| 19958 | there are any single circumflex characters in the string, they are converted to |
| 19959 | NULs. Should an actual circumflex be required as data, it must be doubled in |
| 19960 | the string. |
| 19961 | |
| 19962 | .endconf |
| 19963 | |
| 19964 | This is an example of a client configuration that implements the PLAIN |
| 19965 | authentication mechanism with a fixed user name and password: |
| 19966 | .display asis |
| 19967 | fixed_plain: |
| 19968 | driver = plaintext |
| 19969 | public_name = PLAIN |
| 19970 | client_send = ^username^mysecret |
| 19971 | .endd |
| 19972 | The lack of colons means that the entire text is sent with the \\AUTH\\ |
| 19973 | command, with the circumflex characters converted to NULs. A similar example |
| 19974 | that uses the LOGIN mechanism is: |
| 19975 | .display asis |
| 19976 | fixed_login: |
| 19977 | driver = plaintext |
| 19978 | public_name = LOGIN |
| 19979 | client_send = : username : mysecret |
| 19980 | .endd |
| 19981 | The initial colon means that the first string is empty, so no data is sent with |
| 19982 | the \\AUTH\\ command itself. The remaining strings are sent in response to |
| 19983 | prompts. |
| 19984 | |
| 19985 | |
| 19986 | |
| 19987 | |
| 19988 | . |
| 19989 | . |
| 19990 | . |
| 19991 | . |
| 19992 | . ============================================================================ |
| 19993 | .chapter The cram@_md5 authenticator |
| 19994 | .set runningfoot "cram@_md5 authenticator" |
| 19995 | .index \%cram@_md5%\ authenticator |
| 19996 | .index authenticators||\%cram@_md5%\ |
| 19997 | .index CRAM-MD5 authentication mechanism |
| 19998 | .index authentication||CRAM-MD5 mechanism |
| 19999 | The CRAM-MD5 authentication mechanism is described in RFC 2195. The server |
| 20000 | sends a challenge string to the client, and the response consists of a user |
| 20001 | name and the CRAM-MD5 digest of the challenge string combined with a secret |
| 20002 | string (password) which is known to both server and client. Thus, the secret |
| 20003 | is not sent over the network as plain text, which makes this authenticator more |
| 20004 | secure than \%plaintext%\. However, the downside is that the secret has to be |
| 20005 | available in plain text at either end. |
| 20006 | |
| 20007 | .section Using cram@_md5 as a server |
| 20008 | This authenticator has one server option, which must be set to configure the |
| 20009 | authenticator as a server: |
| 20010 | |
| 20011 | .startconf |
| 20012 | .index options||\%cram@_md5%\ authenticator (server) |
| 20013 | |
| 20014 | .conf server@_secret string$**$ unset |
| 20015 | .index numerical variables (\$1$\, \$2$\, etc)||in \%cram@_md5%\ authenticator |
| 20016 | When the server receives the client's response, the user name is placed in |
| 20017 | the expansion variable \$1$\, and \server@_secret\ is expanded to obtain the |
| 20018 | password for that user. The server then computes the CRAM-MD5 digest that the |
| 20019 | client should have sent, and checks that it received the correct string. If the |
| 20020 | expansion of \server@_secret\ is forced to fail, authentication fails. If the |
| 20021 | expansion fails for some other reason, a temporary error code is returned to |
| 20022 | the client. |
| 20023 | |
| 20024 | .endconf |
| 20025 | |
| 20026 | For example, the following authenticator checks that the user name given by the |
| 20027 | client is `ph10', and if so, uses `secret' as the password. For any other user |
| 20028 | name, authentication fails. |
| 20029 | .display asis |
| 20030 | fixed_cram: |
| 20031 | driver = cram_md5 |
| 20032 | public_name = CRAM-MD5 |
| 20033 | server_secret = ${if eq{$1}{ph10}{secret}fail} |
| 20034 | server_set_id = $1 |
| 20035 | .endd |
| 20036 | If authentication succeeds, the setting of \server@_set@_id\ preserves the user |
| 20037 | name in \$authenticated@_id$\. |
| 20038 | A more tyical configuration might look up the secret string in a file, using |
| 20039 | the user name as the key. For example: |
| 20040 | .display asis |
| 20041 | lookup_cram: |
| 20042 | driver = cram_md5 |
| 20043 | public_name = CRAM-MD5 |
| 20044 | server_secret = ${lookup{$1}lsearch{/etc/authpwd}{$value}fail} |
| 20045 | server_set_id = $1 |
| 20046 | .endd |
| 20047 | Note that this expansion explicitly forces failure if the lookup fails |
| 20048 | because \$1$\ contains an unknown user name. |
| 20049 | |
| 20050 | .section Using cram@_md5 as a client |
| 20051 | When used as a client, the \%cram@_md5%\ authenticator has two options: |
| 20052 | |
| 20053 | .startconf |
| 20054 | .index options||\%cram@_md5%\ authenticator (client) |
| 20055 | |
| 20056 | .conf client@_name string$**$ "the primary host name" |
| 20057 | This string is expanded, and the result used as the user name data when |
| 20058 | computing the response to the server's challenge. |
| 20059 | |
| 20060 | .conf client@_secret string$**$ unset |
| 20061 | This option must be set for the authenticator to work as a client. Its value is |
| 20062 | expanded and the result used as the secret string when computing the response. |
| 20063 | |
| 20064 | .endconf |
| 20065 | |
| 20066 | Different user names and secrets can be used for different servers by referring |
| 20067 | to \$host$\ or \$host@_address$\ in the options. |
| 20068 | |
| 20069 | Forced failure of either expansion string is treated as an indication that this |
| 20070 | authenticator is not prepared to handle this case. Exim moves on to the next |
| 20071 | configured client authenticator. Any other expansion failure causes Exim to |
| 20072 | give up trying to send the message to the current server. |
| 20073 | |
| 20074 | A simple example configuration of a \%cram@_md5%\ authenticator, using fixed |
| 20075 | strings, is: |
| 20076 | .display asis |
| 20077 | fixed_cram: |
| 20078 | driver = cram_md5 |
| 20079 | public_name = CRAM-MD5 |
| 20080 | client_name = ph10 |
| 20081 | client_secret = secret |
| 20082 | .endd |
| 20083 | |
| 20084 | |
| 20085 | |
| 20086 | |
| 20087 | |
| 20088 | . |
| 20089 | . |
| 20090 | . |
| 20091 | . |
| 20092 | . ============================================================================ |
| 20093 | .chapter The spa authenticator |
| 20094 | .set runningfoot "spa authenticator" |
| 20095 | .index \%spa%\ authenticator |
| 20096 | .index authenticators||\%spa%\ |
| 20097 | .index authentication||Microsoft Secure Password |
| 20098 | .index authentication||NTLM |
| 20099 | .index Microsoft Secure Password Authentication |
| 20100 | .index NTLM authentication |
| 20101 | The \%spa%\ authenticator provides client support for Microsoft's \*Secure |
| 20102 | Password Authentication*\ mechanism, |
| 20103 | which is also sometimes known as NTLM (NT LanMan). The code for client side of |
| 20104 | this authenticator was contributed by Marc Prud'hommeaux, and much of it is |
| 20105 | taken from the Samba project (\?http://www.samba.org?\). The code for the |
| 20106 | server side was subsequently contributed by Tom Kistner. |
| 20107 | |
| 20108 | The mechanism works as follows: |
| 20109 | .numberpars $. |
| 20110 | After the \\AUTH\\ command has been accepted, the client sends an SPA |
| 20111 | authentication request based on the user name and optional domain. |
| 20112 | .nextp |
| 20113 | The server sends back a challenge. |
| 20114 | .nextp |
| 20115 | The client builds a challenge response which makes use of the user's password |
| 20116 | and sends it to the server, which then accepts or rejects it. |
| 20117 | .endp |
| 20118 | Encryption is used to protect the password in transit. |
| 20119 | |
| 20120 | |
| 20121 | .section Using spa as a server |
| 20122 | The \%spa%\ authenticator has just one server option: |
| 20123 | |
| 20124 | .startconf |
| 20125 | .index options||\%spa%\ authenticator (server) |
| 20126 | |
| 20127 | .conf server@_password string$**$ unset |
| 20128 | .index numerical variables (\$1$\, \$2$\, etc)||in \%spa%\ authenticator |
| 20129 | This option is expanded, and the result must be the cleartext password for the |
| 20130 | authenticating user, whose name is at this point in \$1$\. For example: |
| 20131 | .display asis |
| 20132 | spa: |
| 20133 | driver = spa |
| 20134 | public_name = NTLM |
| 20135 | server_password = ${lookup{$1}lsearch{/etc/exim/spa_clearpass}} |
| 20136 | .endd |
| 20137 | If the expansion is forced to fail, authentication fails. Any other expansion |
| 20138 | failure causes a temporary error code to be returned. |
| 20139 | |
| 20140 | .endconf |
| 20141 | |
| 20142 | |
| 20143 | |
| 20144 | .section Using spa as a client |
| 20145 | The \%spa%\ authenticator has the following client options: |
| 20146 | |
| 20147 | .startconf |
| 20148 | .index options||\%spa%\ authenticator (client) |
| 20149 | |
| 20150 | .conf client@_domain string$**$ unset |
| 20151 | This option specifies an optional domain for the authentication. |
| 20152 | |
| 20153 | .conf client@_password string$**$ unset |
| 20154 | This option specifies the user's password, and must be set. |
| 20155 | |
| 20156 | .conf client@_username string$**$ unset |
| 20157 | This option specifies the user name, and must be set. |
| 20158 | |
| 20159 | .endconf |
| 20160 | |
| 20161 | Here is an example of a configuration of this authenticator for use with the |
| 20162 | mail servers at \*msn.com*\: |
| 20163 | .display asis |
| 20164 | msn: |
| 20165 | driver = spa |
| 20166 | public_name = MSN |
| 20167 | client_username = msn/msn_username |
| 20168 | client_password = msn_plaintext_password |
| 20169 | client_domain = DOMAIN_OR_UNSET |
| 20170 | .endd |
| 20171 | |
| 20172 | |
| 20173 | |
| 20174 | |
| 20175 | |
| 20176 | |
| 20177 | . |
| 20178 | . |
| 20179 | . |
| 20180 | . |
| 20181 | . ============================================================================ |
| 20182 | .chapter Encrypted SMTP connections using TLS/SSL |
| 20183 | .set runningfoot "TLS encryption" |
| 20184 | .rset CHAPTLS "~~chapter" |
| 20185 | .index encryption||on SMTP connection |
| 20186 | .index SMTP||encryption |
| 20187 | .index TLS||on SMTP connection |
| 20188 | .index OpenSSL |
| 20189 | .index GnuTLS |
| 20190 | Support for TLS (Transport Layer Security), formerly known as SSL (Secure |
| 20191 | Sockets Layer), is implemented by making use of the OpenSSL library or the |
| 20192 | GnuTLS library (Exim requires GnuTLS release 1.0 or later). |
| 20193 | There is no cryptographic code in the Exim distribution itself for implementing |
| 20194 | TLS. In order to use this feature you must install OpenSSL or GnuTLS, and then |
| 20195 | build a version of Exim that includes TLS support (see section |
| 20196 | ~~SECTinctlsssl). You also need to understand the basic concepts of encryption |
| 20197 | at a managerial level, and in particular, the way that public keys, private |
| 20198 | keys, and certificates are used. |
| 20199 | |
| 20200 | RFC 2487 defines how SMTP connections can make use of encryption. Once a |
| 20201 | connection is established, the client issues a \\STARTTLS\\ command. If the |
| 20202 | server accepts this, the client and the server negotiate an encryption |
| 20203 | mechanism. If the negotiation succeeds, the data that subsequently passes |
| 20204 | between them is encrypted. |
| 20205 | |
| 20206 | Exim also has support for legacy clients that do not use the \\STARTTLS\\ |
| 20207 | mechanism. Instead, they connect to a different port on the server (usually |
| 20208 | called the `ssmtp' port), and expect to negotiate a TLS session as soon as the |
| 20209 | connection to the server is established. The \-tls-on-connect-\ command line |
| 20210 | option can be used to run an Exim server in this way from \*inetd*\, and it can |
| 20211 | also be used to run a special daemon that operates in this manner (use \-oX-\ |
| 20212 | to specify the port). |
| 20213 | |
| 20214 | Exim's ACLs can detect whether the current SMTP session is encrypted or not, |
| 20215 | and if so, what cipher suite is in use, whether the client supplied a |
| 20216 | certificate, and whether or not that certificate was verified. This makes it |
| 20217 | possible for an Exim server to deny or accept certain commands based on the |
| 20218 | encryption state. |
| 20219 | |
| 20220 | \**Warning**\: certain types of firewall and certain anti-virus products can |
| 20221 | disrupt TLS connections. You need to turn off SMTP scanning for these products |
| 20222 | in order to get TLS to work. |
| 20223 | |
| 20224 | |
| 20225 | .section OpenSSL vs GnuTLS |
| 20226 | .index TLS||OpenSSL \*vs*\ GnuTLS |
| 20227 | .rset SECTopenvsgnu "~~chapter.~~section" |
| 20228 | The first TLS support in Exim was implemented using OpenSSL. Support for GnuTLS |
| 20229 | followed later, when the first versions of GnuTLS were released. To build Exim |
| 20230 | to use GnuTLS, you need to set |
| 20231 | .display asis |
| 20232 | USE_GNUTLS=yes |
| 20233 | .endd |
| 20234 | in Local/Makefile, in addition to |
| 20235 | .display asis |
| 20236 | SUPPORT_TLS=yes |
| 20237 | .endd |
| 20238 | You must also set \\TLS@_LIBS\\ and \\TLS@_INCLUDE\\ appropriately, so that the |
| 20239 | include files and libraries for GnuTLS can be found. |
| 20240 | |
| 20241 | There are some differences in usage when using GnuTLS instead of OpenSSL: |
| 20242 | .numberpars $. |
| 20243 | The \tls@_verify@_certificates\ option must contain the name of a file, not the |
| 20244 | name of a directory (for OpenSSL it can be either). |
| 20245 | .nextp |
| 20246 | The \tls@_dhparam\ option is ignored, because early versions of GnuTLS had no |
| 20247 | facility for varying its Diffie-Hellman parameters. I understand that this has |
| 20248 | changed, but Exim has not been updated to provide this facility. |
| 20249 | .nextp |
| 20250 | GnuTLS uses RSA and D-H parameters that take a substantial amount of |
| 20251 | time to compute. It is unreasonable to re-compute them for every TLS |
| 20252 | session. Therefore, Exim keeps this data in a file in its spool |
| 20253 | directory, called \(gnutls-params)\. The file is owned by the Exim user and is |
| 20254 | readable only by its owner. Every Exim process that start up GnuTLS reads the |
| 20255 | RSA and D-H parameters from this file. If the file does not exist, the first |
| 20256 | Exim process that needs it computes the data and writes it to a temporary file |
| 20257 | which is renamed once it is complete. It does not matter if several Exim |
| 20258 | processes do this simultaneously (apart from wasting a few resources). Once a |
| 20259 | file is in place, new Exim processes immediately start using it. |
| 20260 | |
| 20261 | For maximum security, the parameters that are stored in this file should be |
| 20262 | recalculated periodically, the frequency depending on your paranoia level. |
| 20263 | Arranging this is easy; just delete the file when you want new values to be |
| 20264 | computed. |
| 20265 | .nextp |
| 20266 | Distinguished Name (DN) strings reported by the OpenSSL library use a slash for |
| 20267 | separating fields; GnuTLS uses commas, in accordance with RFC 2253. This |
| 20268 | affects the value of the \$tls@_peerdn$\ variable. |
| 20269 | .nextp |
| 20270 | OpenSSL identifies cipher suites using hyphens as separators, for example: |
| 20271 | DES-CBC3-SHA. GnuTLS uses underscores, for example: RSA@_ARCFOUR@_SHA. What is |
| 20272 | more, OpenSSL complains if underscores are present in a cipher list. To make |
| 20273 | life simpler, Exim changes underscores to hyhens for OpenSSL and hyphens to |
| 20274 | underscores for GnuTLS when processing lists of cipher suites in the |
| 20275 | \tls@_require@_ciphers\ options (the global option and the \%smtp%\ transport |
| 20276 | option). |
| 20277 | .nextp |
| 20278 | The \tls@_require@_ciphers\ options operate differently, as described in the |
| 20279 | following section. |
| 20280 | .endp |
| 20281 | |
| 20282 | .section Requiring specific ciphers in OpenSSL and GnuTLS |
| 20283 | .rset SECTreqciphsslgnu "~~chapter.~~section" |
| 20284 | .index TLS||requiring specific ciphers |
| 20285 | .index \tls@_require@_ciphers\||OpenSSL \*vs*\ GnuTLS |
| 20286 | This section documents the different ways the \tls@_require@_ciphers\ options |
| 20287 | (the global option and the \%smtp%\ transport option) operate in OpenSSL and |
| 20288 | GnuTLS. |
| 20289 | |
| 20290 | There is a function in the OpenSSL library that can be passed a list of |
| 20291 | cipher suites before the cipher negotiation takes place. This specifies which |
| 20292 | ciphers are acceptable. The list is colon separated and may contain names like |
| 20293 | DES-CBC3-SHA. Exim passes the expanded value of \tls@_require@_ciphers\ |
| 20294 | directly to this function call. The following quotation from |
| 20295 | the OpenSSL documentation specifies what forms of item are allowed in the |
| 20296 | cipher string: |
| 20297 | .numberpars $. |
| 20298 | It can consist of a single cipher suite such as RC4-SHA. |
| 20299 | .nextp |
| 20300 | It can represent a list of cipher suites containing a certain algorithm, |
| 20301 | or cipher suites of a certain type. For example SHA1 represents all |
| 20302 | ciphers suites using the digest algorithm SHA1 and SSLv3 represents all |
| 20303 | SSL v3 algorithms. |
| 20304 | .nextp |
| 20305 | Lists of cipher suites can be combined in a single cipher string using |
| 20306 | the + character. This is used as a logical and operation. For example |
| 20307 | SHA1+DES represents all cipher suites containing the SHA1 and the DES |
| 20308 | algorithms. |
| 20309 | .nextp |
| 20310 | Each cipher string can be optionally preceded by the characters \"!"\, \"-"\ or |
| 20311 | \"+"\. |
| 20312 | .numberpars " " |
| 20313 | If \"!"\ is used then the ciphers are permanently deleted from the list. The |
| 20314 | ciphers deleted can never reappear in the list even if they are explicitly |
| 20315 | stated. |
| 20316 | .nextp |
| 20317 | If \"-"\ is used then the ciphers are deleted from the list, but some or all |
| 20318 | of the ciphers can be added again by later options. |
| 20319 | .nextp |
| 20320 | If \"+"\ is used then the ciphers are moved to the end of the list. This |
| 20321 | option doesn't add any new ciphers it just moves matching existing ones. |
| 20322 | .nextp |
| 20323 | If none of these characters is present then the string is just interpreted as a |
| 20324 | list of ciphers to be appended to the current preference list. If the list |
| 20325 | includes any ciphers already present they will be ignored: that is, they will |
| 20326 | not moved to the end of the list. |
| 20327 | .endp |
| 20328 | .endp |
| 20329 | |
| 20330 | The GnuTLS library does not have a combined function like OpenSSL. Instead, |
| 20331 | it allows the caller to specify separate lists of key-exchange methods, |
| 20332 | main cipher algorithms, and MAC algorithms. Unfortunately, these lists are |
| 20333 | numerical, and the library does not have a function for turning names into |
| 20334 | numbers. Consequently, the list of recognized names has to be built into |
| 20335 | the application. |
| 20336 | |
| 20337 | At present, Exim permits only the list of main cipher algorithms to be |
| 20338 | changed. The \tls@_require@_ciphers\ option is in the same format as for |
| 20339 | OpenSSL. Exim searches each item for the name of available algorithm. For |
| 20340 | example, if the list contains RSA@_ARCFOUR@_SHA then ARCFOUR is recognized. |
| 20341 | |
| 20342 | The cipher algorithms list starts out with a default set of algorithms. If |
| 20343 | the first item in \tls@_require@_ciphers\ does \*not*\ start with an |
| 20344 | exclamation mark, all the default items are deleted. Thus, only those specified |
| 20345 | can be used. If the first item in \tls@_require@_ciphers\ \*does*\ start with |
| 20346 | an exclamation mark, the defaults are left on the list. |
| 20347 | |
| 20348 | Then, any item that starts with an exclamation mark causes the relevent |
| 20349 | algorithms to be removed from the list, and any item that does not start |
| 20350 | with an exclamation mark causes the relevant algorithms to be added to the |
| 20351 | list. Thus, |
| 20352 | .display asis |
| 20353 | tls_require_ciphers = !RSA_ARCFOUR_SHA |
| 20354 | .endd |
| 20355 | allows all the defaults except those that use ARCFOUR, whereas |
| 20356 | .display asis |
| 20357 | tls_require_ciphers = AES : 3DES |
| 20358 | .endd |
| 20359 | allows only cipher suites that use AES and 3DES. The currently recognized |
| 20360 | algorithms are: ARCFOUR@_128, ARCFOUR@_40, ARCFOUR (both of the preceding), |
| 20361 | AES@_256, AES@_128, AES (both of the preceding), and 3DES. |
| 20362 | |
| 20363 | Unrecognized algorithms are ignored. In a client, the order of the list |
| 20364 | specifies a preference order for the algorithms. |
| 20365 | |
| 20366 | |
| 20367 | .section Configuring an Exim server to use TLS |
| 20368 | .index TLS||configuring an Exim server |
| 20369 | When Exim has been built with TLS support, it advertises the availability of |
| 20370 | the \\STARTTLS\\ command to client hosts that match \tls@_advertise@_hosts\, |
| 20371 | but not to any others. The default value of this option is unset, which means |
| 20372 | that \\STARTTLS\\ is not advertised at all. This default is chosen because you |
| 20373 | need to set some other options in order to make TLS avaliable, and also it is |
| 20374 | sensible for systems that want to use TLS only as a client. |
| 20375 | |
| 20376 | If a client issues a \\STARTTLS\\ command and there is some configuration |
| 20377 | problem in the server, the command is rejected with a 454 error. If the client |
| 20378 | persists in trying to issue SMTP commands, all except \\QUIT\\ are rejected |
| 20379 | with the error |
| 20380 | .display asis |
| 20381 | 554 Security failure |
| 20382 | .endd |
| 20383 | If a \\STARTTLS\\ command is issued within an existing TLS session, it is |
| 20384 | rejected with a 554 error code. |
| 20385 | |
| 20386 | To enable TLS operations on a server, you must set \tls@_advertise@_hosts\ to |
| 20387 | match some hosts. You can, of course, set it to $*$ to match all hosts. |
| 20388 | However, this is not all you need to do. TLS sessions to a server won't work |
| 20389 | without some further configuration at the server end. |
| 20390 | |
| 20391 | It is rumoured that all existing clients that support TLS/SSL use RSA |
| 20392 | encryption. To make this work you need to set, in the server, |
| 20393 | .display asis |
| 20394 | tls_certificate = /some/file/name |
| 20395 | tls_privatekey = /some/file/name |
| 20396 | .endd |
| 20397 | The first file contains the server's X509 certificate, and the second contains |
| 20398 | the private key that goes with it. These files need to be readable by the Exim |
| 20399 | user, and must always be given as full path names. They can be the same file if |
| 20400 | both the certificate and the key are contained within it. If \tls@_privatekey\ |
| 20401 | is not set, this is assumed to be the case. The certificate file may also |
| 20402 | contain intermediate certificates that need to be sent to the client to enable |
| 20403 | it to authenticate the server's certificate. |
| 20404 | |
| 20405 | If you do not understand about certificates and keys, please try to find a |
| 20406 | source of this background information, which is not Exim-specific. (There are a |
| 20407 | few comments below in section ~~SECTcerandall.) |
| 20408 | |
| 20409 | \**Note**\: These options do not apply when Exim is operating as a client -- |
| 20410 | they apply only in the case of a server. For a client, you must set the options |
| 20411 | of the same name in an \%smtp%\ transport. |
| 20412 | |
| 20413 | With just these options, Exim will work as a server with clients such as |
| 20414 | Netscape. It does not require the client to have a certificate (but see below |
| 20415 | for how to insist on this). There is one other option that may be needed in |
| 20416 | other situations. If |
| 20417 | .display asis |
| 20418 | tls_dhparam = /some/file/name |
| 20419 | .endd |
| 20420 | is set, the SSL library is initialized for the use of Diffie-Hellman ciphers |
| 20421 | with the parameters contained in the file. This increases the set of cipher |
| 20422 | suites that the server supports. See the command |
| 20423 | .display asis |
| 20424 | openssl dhparam |
| 20425 | .endd |
| 20426 | for a way of generating this data. |
| 20427 | At present, \tls@_dhparam\ is used only when Exim is linked with OpenSSL. It is |
| 20428 | ignored if GnuTLS is being used. |
| 20429 | |
| 20430 | The strings supplied for these three options are expanded every time a client |
| 20431 | host connects. It is therefore possible to use different certificates and keys |
| 20432 | for different hosts, if you so wish, by making use of the client's IP address |
| 20433 | in \$sender@_host@_address$\ to control the expansion. If a string expansion is |
| 20434 | forced to fail, Exim behaves as if the option is not set. |
| 20435 | |
| 20436 | .index cipher||logging |
| 20437 | .index log||TLS cipher |
| 20438 | The variable \$tls@_cipher$\ is set to the cipher suite that was negotiated for |
| 20439 | an incoming TLS connection. It is included in the ::Received:: header of an |
| 20440 | incoming message (by default -- you can, of course, change this), and it is |
| 20441 | also included in the log line that records a message's arrival, keyed by `X=', |
| 20442 | unless the \tls@_cipher\ log selector is turned off. |
| 20443 | The \encrypted\ condition can be used to test for specific cipher suites in |
| 20444 | ACLs. |
| 20445 | |
| 20446 | The ACLs that run for subsequent SMTP commands can check the name of the cipher |
| 20447 | suite and vary their actions accordingly. The cipher suite names are those used |
| 20448 | by OpenSSL. These may differ from the names used elsewhere. For example, |
| 20449 | OpenSSL uses the name DES-CBC3-SHA for the cipher suite which in other contexts |
| 20450 | is known as TLS@_RSA@_WITH@_3DES@_EDE@_CBC@_SHA. Check the OpenSSL |
| 20451 | documentation for more details. |
| 20452 | |
| 20453 | |
| 20454 | .section Requesting and verifying client certificates |
| 20455 | .index certificate||verification of client |
| 20456 | .index TLS||client certificate verification |
| 20457 | If you want an Exim server to request a certificate when negotiating a TLS |
| 20458 | session with a client, you must set either \tls@_verify@_hosts\ or |
| 20459 | \tls@_try@_verify@_hosts\. You can, of course, set either of them to $*$ to |
| 20460 | apply to all TLS connections. For any host that matches one of these options, |
| 20461 | Exim requests a certificate as part of the setup of the TLS session. The |
| 20462 | contents of the certificate are verified by comparing it with a list of |
| 20463 | expected certificates. These must be available in a file or, |
| 20464 | for OpenSSL only (not GnuTLS), a directory, identified by |
| 20465 | \tls@_verify@_certificates\. |
| 20466 | |
| 20467 | A file can contain multiple certificates, concatenated end to end. If a |
| 20468 | directory is used |
| 20469 | (OpenSSL only), |
| 20470 | each certificate must be in a separate file, with a name (or a symbolic link) |
| 20471 | of the form <<hash>>.0, where <<hash>> is a hash value constructed from the |
| 20472 | certificate. You can compute the relevant hash by running the command |
| 20473 | .display asis |
| 20474 | openssl x509 -hash -noout -in /cert/file |
| 20475 | .endd |
| 20476 | where \(/cert/file)\ contains a single certificate. |
| 20477 | |
| 20478 | The difference between \tls@_verify@_hosts\ and \tls@_try@_verify@_hosts\ is |
| 20479 | what happens if the client does not supply a certificate, or if the certificate |
| 20480 | does not match any of the certificates in the collection named by |
| 20481 | \tls@_verify@_certificates\. If the client matches \tls@_verify@_hosts\, the |
| 20482 | attempt to set up a TLS session is aborted, and the incoming connection is |
| 20483 | dropped. If the client matches \tls@_try@_verify@_hosts\, the (encrypted) SMTP |
| 20484 | session continues. ACLs that run for subsequent SMTP commands can detect the |
| 20485 | fact that no certificate was verified, and vary their actions accordingly. For |
| 20486 | example, you can insist on a certificate before accepting a message for |
| 20487 | relaying, but not when the message is destined for local delivery. |
| 20488 | |
| 20489 | When a client supplies a certificate (whether it verifies or not), the value of |
| 20490 | the Distinguished Name of the certificate is made available in the variable |
| 20491 | \$tls@_peerdn$\ during subsequent processing of the message. |
| 20492 | .index log||distinguished name |
| 20493 | Because it is often a long text string, it is not included in the log line or |
| 20494 | ::Received:: header by default. You can arrange for it to be logged, keyed by |
| 20495 | `DN=', by setting the \tls@_peerdn\ log selector, and you can use |
| 20496 | \received@_header@_text\ to change the ::Received:: header. When no certificate |
| 20497 | is supplied, \$tls@_peerdn$\ is empty. |
| 20498 | |
| 20499 | .section Revoked certificates |
| 20500 | .index TLS||revoked certificates |
| 20501 | .index revocation list |
| 20502 | .index certificate||revocation list |
| 20503 | Certificate issuing authorities issue Certificate Revocation Lists (CRLs) when |
| 20504 | certificates are revoked. If you have such a list, you can pass it to an Exim |
| 20505 | server using the global option called \tls@_crl\ and to an Exim client using an |
| 20506 | identically named option for the \%smtp%\ transport. In each case, the value of |
| 20507 | the option is expanded and must then be the name of a file that contains a CRL |
| 20508 | in PEM format. |
| 20509 | |
| 20510 | .section Configuring an Exim client to use TLS |
| 20511 | .index cipher||logging |
| 20512 | .index log||TLS cipher |
| 20513 | .index log||distinguished name |
| 20514 | .index TLS||configuring an Exim client |
| 20515 | The \tls@_cipher\ and \tls@_peerdn\ log selectors apply to outgoing SMTP |
| 20516 | deliveries as well as to incoming, the latter one causing logging of the |
| 20517 | server certificate's DN. The remaining client configuration for TLS is all |
| 20518 | within the \%smtp%\ transport. |
| 20519 | |
| 20520 | It is not necessary to set any options to have TLS work in the \%smtp%\ |
| 20521 | transport. If Exim is built with TLS support, and TLS is advertised by a |
| 20522 | server, the \%smtp%\ transport always tries to start a TLS session. However, |
| 20523 | this can be prevented by setting \hosts@_avoid@_tls\ (an option of the |
| 20524 | transport) to a list of server hosts for which TLS should not be used. |
| 20525 | |
| 20526 | If you do not want Exim to attempt to send messages unencrypted when an attempt |
| 20527 | to set up an encrypted connection fails in any way, you can set |
| 20528 | \hosts@_require@_tls\ to a list of hosts for which encryption is mandatory. For |
| 20529 | those hosts, delivery is always deferred if an encrypted connection cannot be |
| 20530 | set up. If there are any other hosts for the address, they are tried in the |
| 20531 | usual way. |
| 20532 | |
| 20533 | When the server host is not in \hosts@_require@_tls\, Exim may try to deliver |
| 20534 | the message unencrypted. It always does this if the response to \\STARTTLS\\ is |
| 20535 | a 5\*xx*\ code. For a temporary error code, or for a failure to negotiate a TLS |
| 20536 | session after a success response code, what happens is controlled by the |
| 20537 | \tls@_tempfail@_tryclear\ option of the \%smtp%\ transport. If it is false, |
| 20538 | delivery to this host is deferred, and other hosts (if available) are tried. If |
| 20539 | it is true, Exim attempts to deliver unencrypted after a 4\*xx*\ response to |
| 20540 | \\STARTTLS\\, and if \\STARTTLS\\ is accepted, but the subsequent TLS |
| 20541 | negotiation fails, Exim closes the current connection (because it is in an |
| 20542 | unknown state), opens a new one to the same host, and then tries the delivery |
| 20543 | unencrypted. |
| 20544 | |
| 20545 | |
| 20546 | The \tls@_certificate\ and \tls@_privatekey\ options of the \%smtp%\ transport |
| 20547 | provide the client with a certificate, which is passed to the server if it |
| 20548 | requests it. If the server is Exim, it will request a certificate only if |
| 20549 | \tls@_verify@_hosts\ or \tls@_try@_verify@_hosts\ matches the client. |
| 20550 | \**Note**\: these options must be set in the \%smtp%\ transport for Exim to use |
| 20551 | TLS when it is operating as a client. Exim does not assume that a server |
| 20552 | certificate (set by the global options of the same name) should also be used |
| 20553 | when operating as a client. |
| 20554 | |
| 20555 | If \tls@_verify@_certificates\ is set, it must name a file or, |
| 20556 | for OpenSSL only (not GnuTLS), a directory, that contains a collection of |
| 20557 | expected server certificates. The client verifies the server's certificate |
| 20558 | against this collection, taking into account any revoked certificates that are |
| 20559 | in the list defined by \tls@_crl\. |
| 20560 | |
| 20561 | If |
| 20562 | \tls@_require@_ciphers\ is set on the \%smtp%\ transport, it must contain a |
| 20563 | list of permitted cipher suites. If either of these checks fails, delivery to |
| 20564 | the current host is abandoned, and the \%smtp%\ transport tries to deliver to |
| 20565 | alternative hosts, if any. |
| 20566 | |
| 20567 | All the TLS options in the \%smtp%\ transport are expanded before use, with |
| 20568 | \$host$\ and \$host@_address$\ containing the name and address of the server to |
| 20569 | which the client is connected. Forced failure of an expansion causes Exim to |
| 20570 | behave as if the relevant option were unset. |
| 20571 | |
| 20572 | |
| 20573 | .section Multiple messages on the same encrypted TCP/IP connection |
| 20574 | .rset SECTmulmessam "~~chapter.~~section" |
| 20575 | .index multiple SMTP deliveries with TLS |
| 20576 | .index TLS||multiple message deliveries |
| 20577 | Exim sends multiple messages down the same TCP/IP connection by starting up |
| 20578 | an entirely new delivery process for each message, passing the socket from |
| 20579 | one process to the next. This implementation does not fit well with the use |
| 20580 | of TLS, because there is quite a lot of state information associated with a TLS |
| 20581 | connection, not just a socket identification. Passing all the state information |
| 20582 | to a new process is not feasible. Consequently, Exim shuts down an existing TLS |
| 20583 | session before passing the socket to a new process. The new process may then |
| 20584 | try to start a new TLS session, and if successful, may try to re-authenticate |
| 20585 | if \\AUTH\\ is in use, before sending the next message. |
| 20586 | |
| 20587 | The RFC is not clear as to whether or not an SMTP session continues in clear |
| 20588 | after TLS has been shut down, or whether TLS may be restarted again later, as |
| 20589 | just described. However, if the server is Exim, this shutdown and |
| 20590 | reinitialization works. It is not known which (if any) other servers operate |
| 20591 | successfully if the client closes a TLS session and continues with unencrypted |
| 20592 | SMTP, but there are certainly some that do not work. For such servers, Exim |
| 20593 | should not pass the socket to another process, because the failure of the |
| 20594 | subsequent attempt to use it would cause Exim to record a temporary host error, |
| 20595 | and delay other deliveries to that host. |
| 20596 | |
| 20597 | To test for this case, Exim sends an \\EHLO\\ command to the server after |
| 20598 | closing down the TLS session. If this fails in any way, the connection is |
| 20599 | closed instead of being passed to a new delivery process, but no retry |
| 20600 | information is recorded. |
| 20601 | |
| 20602 | There is also a manual override; you can set \hosts@_nopass@_tls\ on the |
| 20603 | \%smtp%\ transport to match those hosts for which Exim should not pass |
| 20604 | connections to new processes if TLS has been used. |
| 20605 | |
| 20606 | |
| 20607 | |
| 20608 | .section Certificates and all that |
| 20609 | .rset SECTcerandall "~~chapter.~~section" |
| 20610 | .index certificate||references to discussion |
| 20611 | In order to understand fully how TLS works, you need to know about |
| 20612 | certificates, certificate signing, and certificate authorities. This is not the |
| 20613 | place to give a tutorial, especially as I do not know very much about it |
| 20614 | myself. Some helpful introduction can be found in the FAQ for the SSL addition |
| 20615 | to Apache, currently at |
| 20616 | .display rm |
| 20617 | \?http://www.modssl.org/docs/2.7/ssl@_faq.html@#ToC24?\ |
| 20618 | .endd |
| 20619 | Other parts of the \*modssl*\ documentation are also helpful, and have |
| 20620 | links to further files. |
| 20621 | Eric Rescorla's book, \*SSL and TLS*\, published by Addison-Wesley (ISBN |
| 20622 | 0-201-61598-3), contains both introductory and more in-depth descriptions. |
| 20623 | Some sample programs taken from the book are available from |
| 20624 | .display rm |
| 20625 | \?http://www.rtfm.com/openssl-examples/?\ |
| 20626 | .endd |
| 20627 | |
| 20628 | .section Certificate chains |
| 20629 | The file named by \tls@_certificate\ may contain more than one |
| 20630 | certificate. This is useful in the case where the certificate that is being |
| 20631 | sent is validated by an intermediate certificate which the other end does |
| 20632 | not have. Multiple certificates must be in the correct order in the file. |
| 20633 | First the host's certificate itself, then the first intermediate |
| 20634 | certificate to validate the issuer of the host certificate, then the next |
| 20635 | intermediate certificate to validate the issuer of the first intermediate |
| 20636 | certificate, and so on, until finally (optionally) the root certificate. |
| 20637 | The root certificate must already be trusted by the recipient for |
| 20638 | validation to succeed, of course, but if it's not preinstalled, sending the |
| 20639 | root certificate along with the rest makes it available for the user to |
| 20640 | install if the receiving end is a client MUA that can interact with a user. |
| 20641 | |
| 20642 | .section Self-signed certificates |
| 20643 | .index certificate||self-signed |
| 20644 | You can create a self-signed certificate using the \*req*\ command provided |
| 20645 | with OpenSSL, like this: |
| 20646 | .display asis |
| 20647 | openssl req -x509 -newkey rsa:1024 -keyout file1 -out file2 \ |
| 20648 | -days 9999 -nodes |
| 20649 | .endd |
| 20650 | \(file1)\ and \(file2)\ can be the same file; the key and the certificate are |
| 20651 | delimited and so can be identified independently. The \-days-\ option |
| 20652 | specifies a period for which the certificate is valid. The \-nodes-\ option is |
| 20653 | important: if you do not set it, the key is encrypted with a passphrase |
| 20654 | that you are prompted for, and any use that is made of the key causes more |
| 20655 | prompting for the passphrase. This is not helpful if you are going to use |
| 20656 | this certificate and key in an MTA, where prompting is not possible. |
| 20657 | |
| 20658 | A self-signed certificate made in this way is sufficient for testing, and |
| 20659 | may be adequate for all your requirements if you are mainly interested in |
| 20660 | encrypting transfers, and not in secure identification. |
| 20661 | |
| 20662 | However, many clients require that the certificate presented by the server be a |
| 20663 | user (also called `leaf' or `site') certificate, and not a self-signed |
| 20664 | certificate. In this situation, the self-signed certificate described above |
| 20665 | must be installed on the client host as a trusted root \*certification |
| 20666 | authority*\ (CA), and the certificate used by Exim must be a user certificate |
| 20667 | signed with that self-signed certificate. |
| 20668 | |
| 20669 | For information on creating self-signed CA certificates and using them to sign |
| 20670 | user certificates, see the \*General implementation overview*\ chapter of the |
| 20671 | Open-source PKI book, available online at \?http://ospkibook.sourceforge.net/?\. |
| 20672 | |
| 20673 | |
| 20674 | |
| 20675 | . |
| 20676 | . |
| 20677 | . |
| 20678 | . |
| 20679 | . ============================================================================ |
| 20680 | .chapter Access control lists |
| 20681 | .set runningfoot "ACL" |
| 20682 | .rset CHAPACL "~~chapter" |
| 20683 | .index ~~ACL||description |
| 20684 | .index control of incoming mail |
| 20685 | .index message||controlling incoming |
| 20686 | .index policy control||access control lists |
| 20687 | Access Control Lists (ACLs) are defined in a separate section of the run time |
| 20688 | configuration file, headed by `begin acl'. Each ACL definition starts with a |
| 20689 | name, terminated by a colon. Here is a complete ACL section that contains just |
| 20690 | one very small ACL: |
| 20691 | .display asis |
| 20692 | begin acl |
| 20693 | |
| 20694 | small_acl: |
| 20695 | accept hosts = one.host.only |
| 20696 | .endd |
| 20697 | You can have as many lists as you like in the ACL section, and the order in |
| 20698 | which they appear does not matter. The lists are self-terminating. |
| 20699 | |
| 20700 | The majority of ACLs are used to control Exim's behaviour when it receives |
| 20701 | certain SMTP commands. This applies both to incoming TCP/IP connections, and |
| 20702 | when a local process submits a message using SMTP by specifying the \-bs-\ |
| 20703 | option. The most common use is for controlling which recipients are accepted |
| 20704 | in incoming messages. In addition, you can define an ACL that is used to check |
| 20705 | local non-SMTP messages. The default configuration file contains an example of |
| 20706 | a realistic ACL for checking \\RCPT\\ commands. This is discussed in chapter |
| 20707 | ~~CHAPdefconfil. |
| 20708 | |
| 20709 | .section Testing ACLs |
| 20710 | The \-bh-\ command line option provides a way of testing your ACL configuration |
| 20711 | locally by running a fake SMTP session with which you interact. The host |
| 20712 | \*relay-test.mail-abuse.org*\ provides a service for checking your relaying |
| 20713 | configuration (see section ~~SECTcheralcon for more details). |
| 20714 | |
| 20715 | |
| 20716 | .section Specifying when ACLs are used |
| 20717 | .index ~~ACL||options for specifying |
| 20718 | In order to cause an ACL to be used, you have to name it in one of the relevant |
| 20719 | options in the main part of the configuration. These options are: |
| 20720 | .index \\AUTH\\||ACL for |
| 20721 | .index \\DATA\\, ACLs for |
| 20722 | .index \\ETRN\\||ACL for |
| 20723 | .index \\EXPN\\||ACL for |
| 20724 | .index \\HELO\\||ACL for |
| 20725 | .index \\EHLO\\||ACL for |
| 20726 | .index \\MAIL\\||ACL for |
| 20727 | .index \\QUIT\\, ACL for |
| 20728 | .index \\RCPT\\||ACL for |
| 20729 | .index \\STARTTLS\\, ACL for |
| 20730 | .index \\VRFY\\||ACL for |
| 20731 | .index SMTP||connection, ACL for |
| 20732 | .index non-smtp message, ACL for |
| 20733 | .display |
| 20734 | .tabs 20 |
| 20735 | .if !~~sys.fancy |
| 20736 | .tabs 24 |
| 20737 | .fi |
| 20738 | \acl@_not@_smtp\ $t $rm{ACL for non-SMTP messages} |
| 20739 | \acl@_smtp@_auth\ $t $rm{ACL for \\AUTH\\} |
| 20740 | \acl@_smtp@_connect\ $t $rm{ACL for start of SMTP connection} |
| 20741 | \acl@_smtp@_data\ $t $rm{ACL after \\DATA\\ is complete} |
| 20742 | \acl@_smtp@_etrn\ $t $rm{ACL for \\ETRN\\} |
| 20743 | \acl@_smtp@_expn\ $t $rm{ACL for \\EXPN\\} |
| 20744 | \acl@_smtp@_helo\ $t $rm{ACL for \\HELO\\ or \\EHLO\\} |
| 20745 | \acl@_smtp@_mail\ $t $rm{ACL for \\MAIL\\} |
| 20746 | \acl@_smtp@_mailauth\ $t $rm{ACL for the \\AUTH\\ parameter of \\MAIL\\} |
| 20747 | .newline |
| 20748 | .em |
| 20749 | \acl@_smtp@_mime\ $t $rm{ACL for content-scanning MIME parts} |
| 20750 | \acl@_smtp@_predata\ $t $rm{ACL at start of \\DATA\\ command} |
| 20751 | \acl@_smtp@_quit\ $t $rm{ACL for \\QUIT\\} |
| 20752 | .nem |
| 20753 | .newline |
| 20754 | \acl@_smtp@_rcpt\ $t $rm{ACL for \\RCPT\\} |
| 20755 | \acl@_smtp@_starttls\ $t $rm{ACL for \\STARTTLS\\} |
| 20756 | \acl@_smtp@_vrfy\ $t $rm{ACL for \\VRFY\\} |
| 20757 | .endd |
| 20758 | For example, if you set |
| 20759 | .display asis |
| 20760 | acl_smtp_rcpt = small_acl |
| 20761 | .endd |
| 20762 | the little ACL defined above is used whenever Exim receives a \\RCPT\\ command |
| 20763 | in an SMTP dialogue. The majority of policy tests on incoming messages can be |
| 20764 | done when \\RCPT\\ commands arrive. A rejection of \\RCPT\\ should cause the |
| 20765 | sending MTA to give up on the recipient address contained in the \\RCPT\\ |
| 20766 | command, whereas rejection at other times may cause the client MTA to keep on |
| 20767 | trying to deliver the message. It is therefore recommended that you do as much |
| 20768 | testing as possible at \\RCPT\\ time. |
| 20769 | |
| 20770 | .em |
| 20771 | .section The MIME ACLs |
| 20772 | The \acl@_smtp@_mime\ option is available only when Exim is compiled with the |
| 20773 | content-scanning extension. For details, see chapter ~~CHAPexiscan. |
| 20774 | |
| 20775 | |
| 20776 | .section The DATA ACLs |
| 20777 | .index \\DATA\\, ACLs for |
| 20778 | Two ACLs are associated with the \\DATA\\ command. When the command is |
| 20779 | received, the ACL defined by \acl@_smtp@_predata\ is obeyed. This gives you |
| 20780 | control after all the \\RCPT\\ commands, but before the message itself |
| 20781 | is received. It offers the opportunity to give a negative response to the |
| 20782 | \\DATA\\ command itself. Header lines added by \\MAIL\\ or \\RCPT\\ ACLs are |
| 20783 | not visible at this time, but any that are defined here are visible when the |
| 20784 | \acl@_smtp@_data\ ACL is run. |
| 20785 | |
| 20786 | You cannot test the contents of the message, for example, to verify |
| 20787 | addresses in the headers, at \\RCPT\\ time or when the \\DATA\\ command is |
| 20788 | received. |
| 20789 | .nem |
| 20790 | Such tests have to appear in the ACL that is run after the message has been |
| 20791 | received, before the final response to the \\DATA\\ command is sent. This is |
| 20792 | the ACL specified by \acl@_smtp@_data\. At this time, it is no longer possible |
| 20793 | to reject individual recipients. An error response rejects the entire message. |
| 20794 | Unfortunately, it is known that some MTAs do not treat hard (5$it{xx}) errors |
| 20795 | correctly at this point -- they keep the message on their queues and try again |
| 20796 | later, but that is their problem, though it does waste some of your resources. |
| 20797 | |
| 20798 | .section The connect ACL |
| 20799 | .index SMTP||connection, ACL for |
| 20800 | The ACL test specified by \acl@_smtp@_connect\ happens after the test specified |
| 20801 | by \host__reject__connection\ (which is now an anomaly) and any TCP Wrappers |
| 20802 | testing (if configured). |
| 20803 | |
| 20804 | .em |
| 20805 | .section The QUIT ACL |
| 20806 | .rset SECTQUITACL "~~chapter.~~section" |
| 20807 | .index \\QUIT\\, ACL for |
| 20808 | The ACL for the SMTP \\QUIT\\ command is anomalous, in that the |
| 20809 | outcome of the ACL does not affect the response code to \\QUIT\\, |
| 20810 | which is always 221. Thus, the ACL does not in fact control any access. |
| 20811 | For this reason, the only verbs that are permitted are \accept\ and \warn\. |
| 20812 | |
| 20813 | This ACL can be used for tasks such as custom logging at the end of an SMTP |
| 20814 | session. For example, you can use ACL variables in other ACLs to count |
| 20815 | messages, recipients, etc., and log the totals at \\QUIT\\ time using one or |
| 20816 | more \logwrite\ modifiers on a \warn\ verb. |
| 20817 | |
| 20818 | You do not need to have a final \accept\, but if you do, you can use a |
| 20819 | \message\ modifier to specify custom text that is sent as part of the 221 |
| 20820 | response to \\QUIT\\. |
| 20821 | |
| 20822 | This ACL is run only for a `normal' \\QUIT\\. For certain kinds of disastrous |
| 20823 | failure (for example, failure to open a log file, or when Exim is bombing out |
| 20824 | because it has detected an unrecoverable error), all SMTP commands from the |
| 20825 | client are given temporary error responses until \\QUIT\\ is received or the |
| 20826 | connection is closed. In these special cases, the \\QUIT\\ ACL does not run. |
| 20827 | .nem |
| 20828 | |
| 20829 | .section The non-SMTP ACL |
| 20830 | .index non-smtp message, ACL for |
| 20831 | The non-SMTP ACL applies to all non-interactive incoming messages, that is, it |
| 20832 | applies to batch SMTP as well as to non-SMTP messages. (Batch SMTP is not |
| 20833 | really SMTP.) This ACL is run just before the \*local@_scan()*\ function. Any |
| 20834 | kind of rejection is treated as permanent, because there is no way of sending a |
| 20835 | temporary error for these kinds of message. Many of the ACL conditions (for |
| 20836 | example, host tests, and tests on the state of the SMTP connection such as |
| 20837 | encryption and authentication) are not relevant and are forbidden in this ACL. |
| 20838 | |
| 20839 | |
| 20840 | .section Finding an ACL to use |
| 20841 | .index ~~ACL||finding which to use |
| 20842 | The value of an \acl@_smtp@_$it{xxx}\ option is expanded before use, so you can |
| 20843 | use different ACLs in different circumstances. The resulting string does not |
| 20844 | have to be the name of an ACL in the configuration file; there are other |
| 20845 | possibilities. Having expanded the string, Exim searches for an ACL as follows: |
| 20846 | .numberpars $. |
| 20847 | If the string begins with a slash, Exim uses it as a file name, and reads its |
| 20848 | contents as an ACL. The lines are processed in the same way as lines in the |
| 20849 | Exim configuration file. In particular, continuation lines are supported, blank |
| 20850 | lines are ignored, as are lines whose first non-whitespace character is `@#'. |
| 20851 | If the file does not exist or cannot be read, an error occurs (typically |
| 20852 | causing a temporary failure of whatever caused the ACL to be run). For example: |
| 20853 | .display asis |
| 20854 | acl_smtp_data = /etc/acls/\ |
| 20855 | ${lookup{$sender_host_address}lsearch\ |
| 20856 | {/etc/acllist}{$value}{default}} |
| 20857 | .endd |
| 20858 | This looks up an ACL file to use on the basis of the host's IP address, falling |
| 20859 | back to a default if the lookup fails. If an ACL is successfully read from a |
| 20860 | file, it is retained in memory for the duration of the Exim process, so that it |
| 20861 | can be re-used without having to re-read the file. |
| 20862 | .nextp |
| 20863 | If the string does not start with a slash, and does not contain any spaces, |
| 20864 | Exim searches the ACL section of the configuration for an ACL whose name |
| 20865 | matches the string. |
| 20866 | .nextp |
| 20867 | If no named ACL is found, or if the string contains spaces, Exim parses |
| 20868 | the string as an inline ACL. This can save typing in cases where you just |
| 20869 | want to have something like |
| 20870 | .display asis |
| 20871 | acl_smtp_vrfy = accept |
| 20872 | .endd |
| 20873 | in order to allow free use of the \\VRFY\\ command. Such a string may contain |
| 20874 | newlines; it is processed in the same way as an ACL that is read from a file. |
| 20875 | .endp |
| 20876 | |
| 20877 | |
| 20878 | .section ACL return codes |
| 20879 | .index ~~ACL||return codes |
| 20880 | .em |
| 20881 | Except for the \\QUIT\\ ACL, which does not affect the SMTP return code (see |
| 20882 | section ~~SECTQUITACL above), the |
| 20883 | .nem |
| 20884 | result of running an ACL is either `accept' or `deny', or, if some test |
| 20885 | cannot be completed (for example, if a database is down), `defer'. These |
| 20886 | results cause 2$it{xx}, 5$it{xx}, and 4$it{xx} return codes, respectively, to |
| 20887 | be used in the SMTP dialogue. A fourth return, `error', occurs when there is an |
| 20888 | error such as invalid syntax in the ACL. This also causes a 4$it{xx} return |
| 20889 | code. |
| 20890 | |
| 20891 | .em |
| 20892 | For the non-SMTP ACL, `defer' and `error' are treated in the same way as |
| 20893 | `deny', because there is no mechanism for passing temporary errors to the |
| 20894 | submitters of non-SMTP messages. |
| 20895 | .nem |
| 20896 | |
| 20897 | ACLs that are relevant to message reception may also return `discard'. This |
| 20898 | has the effect of `accept', but causes either the entire message or an |
| 20899 | individual recipient address to be discarded. In other words, it is a |
| 20900 | blackholing facility. Use it with care. |
| 20901 | |
| 20902 | If the ACL for \\MAIL\\ returns `discard', all recipients are discarded, and no |
| 20903 | ACL is run for subsequent \\RCPT\\ commands. The effect of `discard' in a |
| 20904 | \\RCPT\\ ACL is to discard just the one recipient address. If there are no |
| 20905 | recipients left when the message's data is received, the \\DATA\\ ACL is not |
| 20906 | run. A `discard' return from the \\DATA\\ or the non-SMTP ACL discards all the |
| 20907 | remaining recipients. |
| 20908 | .em |
| 20909 | The `discard' return is not permitted for the \acl@_smtp@_predata\ ACL. |
| 20910 | .nem |
| 20911 | |
| 20912 | .index \*local@_scan()*\ function||when all recipients discarded |
| 20913 | The \*local@_scan()*\ function is always run, even if there are no remaining |
| 20914 | recipients; it may create new recipients. |
| 20915 | |
| 20916 | |
| 20917 | .section Unset ACL options |
| 20918 | .index ~~ACL||unset options |
| 20919 | The default actions when any of the \acl@_$it{xxx}\ options are unset are not |
| 20920 | all the same. \**Note**\: These defaults apply only when the relevant ACL is |
| 20921 | not defined at all. For any defined ACL, the default action when control reaches |
| 20922 | the end of the ACL statements is `deny'. |
| 20923 | |
| 20924 | For \acl@_not@_smtp\, \acl@_smtp@_auth\, \acl@_smtp@_connect\, |
| 20925 | \acl@_smtp@_data\, \acl@_smtp@_helo\, \acl__smtp__mail\, \acl@_smtp@_mailauth\, |
| 20926 | .em |
| 20927 | \acl@_smtp@_predata\, \acl@_smtp@_quit\, |
| 20928 | .nem |
| 20929 | and \acl@_smtp@_starttls\, the action when the ACL is not defined is `accept'. |
| 20930 | |
| 20931 | For the others (\acl@_smtp@_etrn\, \acl@_smtp@_expn\, \acl@_smtp@_rcpt\, and |
| 20932 | \acl@_smtp@_vrfy\), the action when the ACL is not defined is `deny'. |
| 20933 | This means that \acl@_smtp@_rcpt\ must be defined in order to receive any |
| 20934 | messages over an SMTP connection. For an example, see the ACL in the default |
| 20935 | configuration file. |
| 20936 | |
| 20937 | |
| 20938 | |
| 20939 | .section Data for message ACLs |
| 20940 | .index ~~ACL||data for message ACL |
| 20941 | When an ACL for \\MAIL\\, \\RCPT\\, or \\DATA\\ is being run, the variables |
| 20942 | that contain information about the host and the message's sender (for example, |
| 20943 | \$sender@_host@_address$\ and \$sender@_address$\) are set, and can be used in |
| 20944 | ACL statements. In the case of \\RCPT\\ (but not \\MAIL\\ or \\DATA\\), |
| 20945 | \$domain$\ and \$local@_part$\ are set from the argument address. |
| 20946 | |
| 20947 | When an ACL for the \\AUTH\\ parameter of \\MAIL\\ is being run, the variables |
| 20948 | that contain information about the host are set, but \$sender@_address$\ is not |
| 20949 | yet set. |
| 20950 | .em |
| 20951 | Section ~~SECTauthparamail contains a discussion of this parameter and |
| 20952 | how it is used. |
| 20953 | .nem |
| 20954 | |
| 20955 | The \$message@_size$\ variable is set to the value of the \\SIZE\\ parameter on |
| 20956 | the \\MAIL\\ command at \\MAIL\\ and \\RCPT\\ time, or -1 if that parameter was |
| 20957 | not given. Its value is updated to the true message size by the time the ACL |
| 20958 | after \\DATA\\ is run. |
| 20959 | |
| 20960 | The \$rcpt@_count$\ variable increases by one for each \\RCPT\\ command |
| 20961 | received. The \$recipients@_count$\ variable increases by one each time a |
| 20962 | \\RCPT\\ command is accepted, so while an ACL for \\RCPT\\ is being processed, |
| 20963 | it contains the number of previously accepted recipients. At \\DATA\\ time, |
| 20964 | \$rcpt@_count$\ contains the total number of \\RCPT\\ commands, and |
| 20965 | \$recipients@_count$\ contains the total number of accepted recipients. |
| 20966 | |
| 20967 | |
| 20968 | |
| 20969 | .section Data for non-message ACLs |
| 20970 | .rset SECTdatfornon "~~chapter.~~section" |
| 20971 | .index ~~ACL||data for non-message ACL |
| 20972 | .em |
| 20973 | When an ACL is being run for \\AUTH\\, \\EHLO\\, \\ETRN\\, \\EXPN\\, \\HELO\\, |
| 20974 | .nem |
| 20975 | \\STARTTLS\\, or \\VRFY\\, the remainder of the SMTP command line is placed in |
| 20976 | \$smtp@_command@_argument$\. This can be tested using a \condition\ condition. |
| 20977 | For example, here is an ACL for use with \\AUTH\\, which insists that either |
| 20978 | the session is encrypted, or the CRAM-MD5 authentication method is used. In |
| 20979 | other words, it does not permit authentication methods that use cleartext |
| 20980 | passwords on unencrypted connections. |
| 20981 | .display asis |
| 20982 | acl_check_auth: |
| 20983 | accept encrypted = * |
| 20984 | .newline |
| 20985 | .em |
| 20986 | accept condition = ${if eq{${uc:$smtp_command_argument}}\ |
| 20987 | {CRAM-MD5}} |
| 20988 | .nem |
| 20989 | .newline |
| 20990 | deny message = TLS encryption or CRAM-MD5 required |
| 20991 | .endd |
| 20992 | (Another way of applying this restriction is to arrange for the authenticators |
| 20993 | that use cleartext passwords not to be advertised when the connection is not |
| 20994 | encrypted. You can use the generic \server@_advertise@_condition\ authenticator |
| 20995 | option to do this.) |
| 20996 | |
| 20997 | |
| 20998 | .section Format of an ACL |
| 20999 | .index ~~ACL||format of |
| 21000 | .index ~~ACL||verbs, definition of |
| 21001 | An individual ACL consists of a number of statements. Each statement starts |
| 21002 | with a verb, optionally followed by a number of conditions and `modifiers'. |
| 21003 | .em |
| 21004 | Modifiers can change the way the verb operates, define error and log messages, |
| 21005 | set variables, insert delays, and vary the processing of accepted messages. |
| 21006 | .nem |
| 21007 | |
| 21008 | If all the conditions are met, the verb is obeyed. The same condition may be |
| 21009 | used (with different arguments) more than once in the same statement. This |
| 21010 | provides a means of specifying an `and' conjunction between conditions. For |
| 21011 | example: |
| 21012 | .display asis |
| 21013 | deny dnslists = list1.example |
| 21014 | dnslists = list2.example |
| 21015 | .endd |
| 21016 | If there are no conditions, the verb is always obeyed. |
| 21017 | .em |
| 21018 | Exim stops evaluating the conditions and modifiers when it reaches a condition |
| 21019 | that fails. What happens then |
| 21020 | .nem |
| 21021 | depends on the verb (and in one case, on a special modifier). Not all the |
| 21022 | conditions make sense at every testing point. For example, you cannot test a |
| 21023 | sender address in the ACL that is run for a \\VRFY\\ command. |
| 21024 | |
| 21025 | .section ACL verbs |
| 21026 | The ACL verbs are as follows: |
| 21027 | .numberpars $. |
| 21028 | \accept\: If all the conditions are met, the ACL returns `accept'. If any of |
| 21029 | the conditions are not met, what happens depends on whether \endpass\ appears |
| 21030 | among the conditions (for syntax see below). If the failing condition is before |
| 21031 | \endpass\, control is passed to the next ACL statement; if it is after |
| 21032 | \endpass\, the ACL returns `deny'. Consider this statement, used to check a |
| 21033 | \\RCPT\\ command: |
| 21034 | .display asis |
| 21035 | accept domains = +local_domains |
| 21036 | endpass |
| 21037 | verify = recipient |
| 21038 | .endd |
| 21039 | If the recipient domain does not match the \domains\ condition, control passes |
| 21040 | to the next statement. If it does match, the recipient is verified, and the |
| 21041 | command is accepted if verification succeeds. However, if verification fails, |
| 21042 | the ACL yields `deny', because the failing condition is after \endpass\. |
| 21043 | .nextp |
| 21044 | \defer\: If all the conditions are met, the ACL returns `defer' which, in an |
| 21045 | SMTP session, causes a 4\*xx*\ response to be given. For a non-SMTP ACL, |
| 21046 | \defer\ is the same as \deny\, because there is no way of sending a temporary |
| 21047 | error. For a \\RCPT\\ command, \defer\ is much the same as using a |
| 21048 | \%redirect%\ router and \":defer:"\ while verifying, but the \defer\ verb can |
| 21049 | be used in any ACL, and even for a recipient it might be a simpler approach. |
| 21050 | .nextp |
| 21051 | \deny\: If all the conditions are met, the ACL returns `deny'. If any of the |
| 21052 | conditions are not met, control is passed to the next ACL statement. For |
| 21053 | example, |
| 21054 | .display asis |
| 21055 | deny dnslists = blackholes.mail-abuse.org |
| 21056 | .endd |
| 21057 | rejects commands from hosts that are on a DNS black list. |
| 21058 | .nextp |
| 21059 | \discard\: This verb behaves like \accept\, except that it returns `discard' |
| 21060 | from the ACL instead of `accept'. It is permitted only on ACLs that are |
| 21061 | concerned with receiving messages, and it causes recipients to be discarded. |
| 21062 | If the \log@_message\ modifier is set when \discard\ operates, its contents are |
| 21063 | added to the line that is automatically written to the log. |
| 21064 | |
| 21065 | If \discard\ is used in an ACL for \\RCPT\\, just the one recipient is |
| 21066 | discarded; if used for \\MAIL\\, \\DATA\\ or in the non-SMTP ACL, all the |
| 21067 | message's recipients are discarded. Recipients that are discarded before |
| 21068 | \\DATA\\ do not appear in the log line when the \log@_recipients\ log selector |
| 21069 | is set. |
| 21070 | .nextp |
| 21071 | \drop\: This verb behaves like \deny\, except that an SMTP connection is |
| 21072 | forcibly closed after the 5\*xx*\ error message has been sent. For example: |
| 21073 | .display asis |
| 21074 | drop message = I don't take more than 20 RCPTs |
| 21075 | .newline |
| 21076 | .em |
| 21077 | condition = ${if > {$rcpt_count}{20}} |
| 21078 | .nem |
| 21079 | .endd |
| 21080 | There is no difference between \deny\ and \drop\ for the connect-time ACL. The |
| 21081 | connection is always dropped after sending a 550 response. |
| 21082 | .nextp |
| 21083 | \require\: If all the conditions are met, control is passed to the next ACL |
| 21084 | statement. If any of the conditions are not met, the ACL returns `deny'. For |
| 21085 | example, when checking a \\RCPT\\ command, |
| 21086 | .display asis |
| 21087 | require verify = sender |
| 21088 | .endd |
| 21089 | passes control to subsequent statements only if the message's sender can be |
| 21090 | verified. Otherwise, it rejects the command. |
| 21091 | .nextp |
| 21092 | \warn\: If all the conditions are met, a header line is added to an incoming |
| 21093 | message and/or a line is written to Exim's main log. In all cases, control |
| 21094 | passes to the next ACL statement. The text of the added header line and the log |
| 21095 | line are specified by modifiers; if they are not present, a \warn\ verb just |
| 21096 | checks its conditions and obeys any `immediate' modifiers such as \set\ and |
| 21097 | \logwrite\. |
| 21098 | .em |
| 21099 | There is more about adding header lines in section ~~SECTaddheadwarn. |
| 21100 | .nem |
| 21101 | |
| 21102 | If any condition on a \warn\ statement cannot be completed (that is, there is |
| 21103 | some sort of defer), no header lines are added and the configured log line is |
| 21104 | not written. No further conditions or modifiers in the \warn\ statement are |
| 21105 | processed. The incident is logged, but the ACL continues to be processed, from |
| 21106 | the next statement onwards. |
| 21107 | |
| 21108 | If a \message\ modifier is present on a \warn\ verb in an ACL that is not |
| 21109 | testing an incoming message, it is ignored, and the incident is logged. |
| 21110 | |
| 21111 | A \warn\ statement may use the \log@_message\ modifier to cause a line to be |
| 21112 | written to the main log when the statement's conditions are true. |
| 21113 | If an identical log line is requested several times in the same message, only |
| 21114 | one copy is actually written to the log. If you want to force duplicates to be |
| 21115 | written, use the \logwrite\ modifier instead. |
| 21116 | |
| 21117 | When one of the \warn\ conditions is an address verification that fails, the |
| 21118 | text of the verification failure message is in \$acl@_verify@_message$\. If you |
| 21119 | want this logged, you must set it up explicitly. For example: |
| 21120 | .display asis |
| 21121 | warn !verify = sender |
| 21122 | log_message = sender verify failed: $acl_verify_message |
| 21123 | .endd |
| 21124 | .endp |
| 21125 | |
| 21126 | At the end of each ACL there is an implicit unconditional \deny\. |
| 21127 | |
| 21128 | As you can see from the examples above, the conditions and modifiers are |
| 21129 | written one to a line, with the first one on the same line as the verb, and |
| 21130 | subsequent ones on following lines. If you have a very long condition, you can |
| 21131 | continue it onto several physical lines by the usual backslash continuation |
| 21132 | mechanism. It is conventional to align the conditions vertically. |
| 21133 | |
| 21134 | |
| 21135 | .section ACL variables |
| 21136 | .rset SECTaclvariables "~~chapter.~~section" |
| 21137 | .index ~~ACL||variables |
| 21138 | There are some special variables that can be set during ACL processing. They |
| 21139 | can be used to pass information between different ACLs, different invocations |
| 21140 | of the same ACL in the same SMTP connection, and between ACLs and the routers, |
| 21141 | transports, and filters that are used to deliver a message. There are two sets |
| 21142 | of these variables: |
| 21143 | .numberpars $. |
| 21144 | The values of \$acl@_c0$\ to \$acl@_c9$\ persist throughout an SMTP connection. |
| 21145 | They are never reset. Thus, a value that is set while receiving one message is |
| 21146 | still available when receiving the next message on the same SMTP connection. |
| 21147 | .nextp |
| 21148 | The values of \$acl@_m0$\ to \$acl@_m9$\ persist only while a message is being |
| 21149 | received. They are reset afterwards. They are also reset by \\MAIL\\, \\RSET\\, |
| 21150 | \\EHLO\\, \\HELO\\, and after starting up a TLS session. |
| 21151 | .endp |
| 21152 | When a message is accepted, the current values of all the ACL variables are |
| 21153 | preserved with the message and are subsequently made available at delivery |
| 21154 | time. The ACL variables are set by modifier called \set\. For example: |
| 21155 | .display asis |
| 21156 | accept hosts = whatever |
| 21157 | set acl_m4 = some value |
| 21158 | .endd |
| 21159 | \**Note**\: a leading dollar sign is not used when naming a variable that is to |
| 21160 | be set. If you want to set a variable without taking any action, you can use a |
| 21161 | \warn\ verb without any other modifiers or conditions. |
| 21162 | |
| 21163 | |
| 21164 | .section Condition and modifier processing |
| 21165 | .index ~~ACL||conditions, processing |
| 21166 | .index ~~ACL||modifiers, processing |
| 21167 | An exclamation mark preceding a condition negates its result. For example, |
| 21168 | .display asis |
| 21169 | deny domains = *.dom.example |
| 21170 | !verify = recipient |
| 21171 | .endd |
| 21172 | causes the ACL to return `deny' if the recipient domain ends in |
| 21173 | \*dom.example*\ and the recipient address cannot be verified. |
| 21174 | |
| 21175 | The arguments of conditions and modifiers are expanded. A forced failure |
| 21176 | of an expansion causes a condition to be ignored, that is, it behaves as if the |
| 21177 | condition is true. Consider these two statements: |
| 21178 | .display asis |
| 21179 | accept senders = ${lookup{$host_name}lsearch\ |
| 21180 | {/some/file}{$value}fail} |
| 21181 | accept senders = ${lookup{$host_name}lsearch\ |
| 21182 | {/some/file}{$value}{}} |
| 21183 | .endd |
| 21184 | Each attempts to look up a list of acceptable senders. If the lookup succeeds, |
| 21185 | the returned list is searched, but if the lookup fails the behaviour is |
| 21186 | different in the two cases. The \fail\ in the first statement causes the |
| 21187 | condition to be ignored, leaving no further conditions. The \accept\ verb |
| 21188 | therefore succeeds. The second statement, however, generates an empty list when |
| 21189 | the lookup fails. No sender can match an empty list, so the condition fails, |
| 21190 | and therefore the \accept\ also fails. |
| 21191 | |
| 21192 | ACL modifiers appear mixed in with conditions in ACL statements. Some of them |
| 21193 | specify actions that are taken as the conditions for a statement are checked; |
| 21194 | others specify text for messages that are used when access is denied or a |
| 21195 | warning is generated. |
| 21196 | .em |
| 21197 | The \control\ modifier affects the way an incoming message is handled. |
| 21198 | .nem |
| 21199 | |
| 21200 | The positioning of the modifiers in an ACL statement important, because the |
| 21201 | processing of a verb ceases as soon as its outcome is known. Only those |
| 21202 | modifiers that have already been encountered will take effect. For example, |
| 21203 | consider this use of the \message\ modifier: |
| 21204 | .display asis |
| 21205 | require message = Can't verify sender |
| 21206 | verify = sender |
| 21207 | message = Can't verify recipient |
| 21208 | verify = recipient |
| 21209 | message = This message cannot be used |
| 21210 | .endd |
| 21211 | If sender verification fails, Exim knows that the result of the statement is |
| 21212 | `deny', so it goes no further. The first \message\ modifier has been seen, so |
| 21213 | its text is used as the error message. If sender verification succeeds, but |
| 21214 | recipient verification fails, the second message is used. If recipient |
| 21215 | verification succeeds, the third message becomes `current', but is never used |
| 21216 | because there are no more conditions to cause failure. |
| 21217 | |
| 21218 | For the \deny\ verb, on the other hand, it is always the last \message\ |
| 21219 | modifier that is used, because all the conditions must be true for rejection to |
| 21220 | happen. Specifying more than one \message\ modifier does not make sense, and |
| 21221 | the message can even be specified after all the conditions. For example: |
| 21222 | .display asis |
| 21223 | deny hosts = ... |
| 21224 | !senders = *@my.domain.example |
| 21225 | message = Invalid sender from client host |
| 21226 | .endd |
| 21227 | The `deny' result does not happen until the end of the statement is reached, by |
| 21228 | which time Exim has set up the message. |
| 21229 | |
| 21230 | |
| 21231 | .section ACL modifiers |
| 21232 | .rset SECTACLmodi "~~chapter.~~section" |
| 21233 | .index ~~ACL||modifiers, list of |
| 21234 | The ACL modifiers are as follows: |
| 21235 | |
| 21236 | .startitems |
| 21237 | |
| 21238 | .item "control = <<text>>" |
| 21239 | .em |
| 21240 | This modifier affects the subsequent processing of the SMTP connection or of an |
| 21241 | incoming message that is accepted. As there are now quite a few controls that |
| 21242 | can be applied, they are described separately in section ~~SECTcontrols below. |
| 21243 | .nem |
| 21244 | |
| 21245 | Once one of these controls is set, it remains set for the message. For example, |
| 21246 | if \control\ is used in a \\RCPT\\ ACL, it applies to the whole message, not |
| 21247 | just the individual recipient. The \control\ modifier can be used in several |
| 21248 | different ways. For example: |
| 21249 | .numberpars $. |
| 21250 | It can be at the end of an \accept\ statement: |
| 21251 | .display asis |
| 21252 | accept ...some conditions |
| 21253 | control = queue_only |
| 21254 | .endd |
| 21255 | In this case, the control is applied when this statement yields `accept', in |
| 21256 | other words, when the conditions are all true. |
| 21257 | .nextp |
| 21258 | It can be in the middle of an \accept\ statement: |
| 21259 | .display asis |
| 21260 | accept ...some conditions... |
| 21261 | control = queue_only |
| 21262 | ...some more conditions... |
| 21263 | .endd |
| 21264 | If the first set of conditions are true, the control is applied, even if the |
| 21265 | statement does not accept because one of the second set of conditions is false. |
| 21266 | In this case, some subsequent statement must yield `accept' for the control to |
| 21267 | be relevant. |
| 21268 | .nextp |
| 21269 | It can be used with \warn\ to apply the control, leaving the |
| 21270 | decision about accepting or denying to a subsequent verb. For |
| 21271 | example: |
| 21272 | .display asis |
| 21273 | warn ...some conditions... |
| 21274 | control = freeze |
| 21275 | accept ... |
| 21276 | .endd |
| 21277 | This example of \warn\ does not contain \message\, \log@_message\, or |
| 21278 | \logwrite\, so it does not add anything to the message and does not write a log |
| 21279 | entry. |
| 21280 | .endp |
| 21281 | |
| 21282 | .item "delay = <<time>>" |
| 21283 | .index \-bh-\ option |
| 21284 | This modifier causes Exim to wait for the time interval before proceeding. The |
| 21285 | time is given in the usual Exim notation. This modifier may appear in any ACL. |
| 21286 | The delay happens as soon as the modifier is processed. However, when testing |
| 21287 | Exim using the \-bh-\ option, the delay is not actually imposed (an appropriate |
| 21288 | message is output instead). |
| 21289 | |
| 21290 | Like \control\, \delay\ can be used with \accept\ or |
| 21291 | \deny\, for example: |
| 21292 | .display asis |
| 21293 | deny ...some conditions... |
| 21294 | delay = 30s |
| 21295 | .endd |
| 21296 | The delay happens if all the conditions are true, before the statement returns |
| 21297 | `deny'. Compare this with: |
| 21298 | .display asis |
| 21299 | deny delay = 30s |
| 21300 | ...some conditions... |
| 21301 | .endd |
| 21302 | which waits for 30s before processing the conditions. The \delay\ modifier can |
| 21303 | also be used with \warn\ and together with \control\: |
| 21304 | .display |
| 21305 | warn ...some conditions... |
| 21306 | delay = 2m |
| 21307 | control = freeze |
| 21308 | accept ... |
| 21309 | .endd |
| 21310 | |
| 21311 | .item endpass |
| 21312 | This modifier, which has no argument, is recognized only in \accept\ |
| 21313 | statements. It marks the boundary between the conditions whose failure causes |
| 21314 | control to pass to the next statement, and the conditions whose failure causes |
| 21315 | the ACL to return `deny'. See the description of \accept\ above. |
| 21316 | |
| 21317 | .item "log@_message = <<text>>" |
| 21318 | This modifier sets up a message that is used as part of the log message if the |
| 21319 | ACL denies access or a \warn\ statement's conditions are true. For example: |
| 21320 | .display asis |
| 21321 | require log_message = wrong cipher suite $tls_cipher |
| 21322 | encrypted = DES-CBC3-SHA |
| 21323 | .endd |
| 21324 | \log@_message\ adds to any underlying error message that may exist because of |
| 21325 | the condition failure. For example, while verifying a recipient address, a |
| 21326 | :::fail:: redirection might have already set up a message. Although the message |
| 21327 | is usually defined before the conditions to which it applies, the expansion |
| 21328 | does not happen until Exim decides that access is to be denied. This means that |
| 21329 | any variables that are set by the condition are available for inclusion in the |
| 21330 | message. For example, the \$dnslist@_<<xxx>>$\ variables are set after a DNS |
| 21331 | black list lookup succeeds. If the expansion of \log@_message\ fails, or if the |
| 21332 | result is an empty string, the modifier is ignored. |
| 21333 | |
| 21334 | If you want to use a \warn\ statement to log the result of an address |
| 21335 | verification, you can use \$acl__verify__message$\ to include the verification |
| 21336 | error message. |
| 21337 | |
| 21338 | If \log@_message\ is used with a \warn\ statement, `Warning:' is added to the |
| 21339 | start of the logged message. If the same warning log message is requested more |
| 21340 | than once while receiving a single email message, only one copy is actually |
| 21341 | logged. If you want to log multiple copies, use \logwrite\ instead of |
| 21342 | \log@_message\. In the absence of \log@_message\ and \logwrite\, nothing is |
| 21343 | logged for a succesful \warn\ statement. |
| 21344 | |
| 21345 | If \log@_message\ is not present and there is no underlying error message (for |
| 21346 | example, from the failure of address verification), but \message\ is present, |
| 21347 | the \message\ text is used for logging rejections. However, if any text for |
| 21348 | logging contains newlines, only the first line is logged. In the absence of |
| 21349 | both \log@_message\ and \message\, a default built-in message is used for |
| 21350 | logging rejections. |
| 21351 | |
| 21352 | .item "logwrite = <<text>>" |
| 21353 | .index log||in ACL, immediate |
| 21354 | This modifier writes a message to a log file as soon as it is encountered when |
| 21355 | processing an ACL. (Compare \log@_message\, which, except in the case of |
| 21356 | \warn\, is used only if the ACL statement denies access.) The \logwrite\ |
| 21357 | modifier can be used to log special incidents in ACLs. For example: |
| 21358 | .display |
| 21359 | accept <<some special conditions>> |
| 21360 | control = freeze |
| 21361 | logwrite = froze message because ... |
| 21362 | .endd |
| 21363 | By default, the message is written to the main log. However, it may begin |
| 21364 | with a colon, followed by a comma-separated list of log names, and then |
| 21365 | another colon, to specify exactly which logs are to be written. For |
| 21366 | example: |
| 21367 | .display asis |
| 21368 | logwrite = :main,reject: text for main and reject logs |
| 21369 | logwrite = :panic: text for panic log only |
| 21370 | .endd |
| 21371 | |
| 21372 | .item "message = <<text>>" |
| 21373 | This modifier sets up a text string that is expanded and used as an error |
| 21374 | message if the current statement causes the ACL to deny access. The expansion |
| 21375 | happens at the time Exim decides that access is to be denied, not at the time |
| 21376 | it processes \message\. If the expansion fails, or generates an empty string, |
| 21377 | the modifier is ignored. For ACLs that are triggered by SMTP commands, the |
| 21378 | message is returned as part of the SMTP error response. |
| 21379 | |
| 21380 | The \message\ modifier is also used with the \warn\ verb to specify one or more |
| 21381 | header lines to be added to an incoming message when all the conditions are |
| 21382 | true. See section ~~SECTaddheadwarn for more details. If \message\ is used with |
| 21383 | \warn\ in an ACL that is not concerned with receiving a message, it has no |
| 21384 | effect. |
| 21385 | |
| 21386 | The text is literal; any quotes are taken as literals, but because the string |
| 21387 | is expanded, backslash escapes are processed anyway. If the message contains |
| 21388 | newlines, this gives rise to a multi-line SMTP response. Like \log@_message\, |
| 21389 | the contents of \message\ are not expanded until after a condition has failed. |
| 21390 | |
| 21391 | If \message\ is used on a statement that verifies an address, the message |
| 21392 | specified overrides any message that is generated by the verification process. |
| 21393 | However, the original message is available in the variable |
| 21394 | \$acl@_verify@_message$\, so you can incorporate it into your message if you |
| 21395 | wish. In particular, if you want the text from \:fail:\ items in \%redirect%\ |
| 21396 | routers to be passed back as part of the SMTP response, you should either not |
| 21397 | use a \message\ modifier, or make use of \$acl@_verify@_message$\. |
| 21398 | |
| 21399 | .item "set <<acl@_name>> = <<value>>" |
| 21400 | This modifier puts a value into one of the ACL variables (see section |
| 21401 | ~~SECTaclvariables). |
| 21402 | |
| 21403 | .enditems |
| 21404 | |
| 21405 | |
| 21406 | .em |
| 21407 | .section Use of the control modifier |
| 21408 | .rset SECTcontrols "~~chapter.~~section" |
| 21409 | .index \control\ modifier |
| 21410 | The \control\ modifier supports the following settings: |
| 21411 | |
| 21412 | .startitems |
| 21413 | |
| 21414 | .item "control = caseful@_local@_part" |
| 21415 | .item "control = caselower@_local@_part" |
| 21416 | .index ~~ACL||case of local part in |
| 21417 | .index case of local parts |
| 21418 | These two controls are permitted only in the ACL specified by \acl@_smtp@_rcpt\ |
| 21419 | (that is, during \\RCPT\\ processing). By default, the contents of |
| 21420 | \$local@_part$\ are lower cased before ACL processing. If |
| 21421 | `caseful@_local@_part' is specified, any uppercase letters in the original |
| 21422 | local part are restored in \$local@_part$\ for the rest of the ACL, or until a |
| 21423 | control that sets `caselower@_local@_part' is encountered. However, this |
| 21424 | applies only to local part handling that takes place directly in the ACL (for |
| 21425 | example, as a key in lookups). If a test to verify the recipient is obeyed, the |
| 21426 | case-related handling of the local part during the verification is controlled |
| 21427 | by the router configuration (see the \caseful@_local@_part\ generic router |
| 21428 | option). |
| 21429 | |
| 21430 | This facility could be used, for example, to add a spam score to local parts |
| 21431 | containing upper case letters. For example, using \$acl@_m4$\ to accumulate the |
| 21432 | spam score: |
| 21433 | .display asis |
| 21434 | warn control = caseful_local_part |
| 21435 | set acl_m4 = ${eval:\ |
| 21436 | $acl_m4 + \ |
| 21437 | ${if match{$local_part}{[A-Z]}{1}{0}}\ |
| 21438 | } |
| 21439 | control = caselower_local_part |
| 21440 | .endd |
| 21441 | Notice that we put back the lower cased version afterwards, assuming that |
| 21442 | is what is wanted for subsequent tests. |
| 21443 | |
| 21444 | .item "control = enforce@_sync" |
| 21445 | .item "control = no@_enforce@_sync" |
| 21446 | .index SMTP||synchronization checking |
| 21447 | .index synchronization checking in SMTP |
| 21448 | These controls make it possible to be selective about when SMTP synchronization |
| 21449 | is enforced. The global option \smtp@_enforce@_sync\ specifies the initial |
| 21450 | state of the switch (it is true by default). See the description of this option |
| 21451 | in chapter ~~CHAPmainconfig for details of SMTP synchronization checking. |
| 21452 | |
| 21453 | These two controls can appear in any ACL except the one for the non-SMTP |
| 21454 | messages. The most straightforward place to put them is in the ACL defined by |
| 21455 | \acl@_smtp@_connect\, which is run at the start of an incoming SMTP connection, |
| 21456 | before the first synchronization check. The expected use is to turn off the |
| 21457 | synchronization checks for badly-behaved hosts that you nevertheless need to |
| 21458 | work with. |
| 21459 | |
| 21460 | .item "control = fakereject/<<message>>" |
| 21461 | .index fake rejection |
| 21462 | .index rejection, fake |
| 21463 | This control is permitted only for the \\MAIL\\, \\RCPT\\, and \\DATA\\ ACLs, |
| 21464 | in other words, only when an SMTP message is being received. If Exim accepts |
| 21465 | the message, instead the final 250 response, a 550 rejection message is sent. |
| 21466 | However, Exim proceeds to deliver the message as normal. |
| 21467 | |
| 21468 | The text for the 550 response is taken from the \control\ modifier. If no |
| 21469 | message is supplied, the following is used: |
| 21470 | .display asis |
| 21471 | 550-Your message has been rejected but is being |
| 21472 | 550-kept for evaluation. |
| 21473 | 550-If it was a legit message, it may still be |
| 21474 | 550 delivered to the target recipient(s). |
| 21475 | .endd |
| 21476 | This facilty should be used with extreme caution. |
| 21477 | |
| 21478 | |
| 21479 | .item "control = freeze" |
| 21480 | .index frozen messages||forcing in ACL |
| 21481 | This control is permitted only for the \\MAIL\\, \\RCPT\\, \\DATA\\, and |
| 21482 | non-SMTP ACLs, in other words, only when a message is being received. If the |
| 21483 | message is accepted, it is placed on Exim's queue and frozen. |
| 21484 | |
| 21485 | |
| 21486 | .item "control = no@_multiline@_response" |
| 21487 | .index multiline responses, suppressing |
| 21488 | This control is permitted for any ACL except the one for non-SMTP messages. |
| 21489 | It seems that there are broken clients in use that cannot handle multiline |
| 21490 | SMTP responses, despite the fact that RFC 821 defined them over 20 years ago. |
| 21491 | |
| 21492 | If this control is set, multiline SMTP responses from ACL rejections are |
| 21493 | suppressed. One way of doing this would have been to put out these responses as |
| 21494 | one long line. However, RFC 2821 specifies a maximum of 512 bytes per response |
| 21495 | (`use multiline responses for more' it says -- ha!), and some of the responses |
| 21496 | might get close to that. So this facility, which is after all only a sop to |
| 21497 | broken clients, is implemented by doing two very easy things: |
| 21498 | .numberpars |
| 21499 | Extra information that is normally output as part of a rejection |
| 21500 | caused by sender verification failure is omitted. Only the final line |
| 21501 | (typically `sender verification failed') is sent. |
| 21502 | .nextp |
| 21503 | If a \message\ modifier supplies a multiline response, only the first |
| 21504 | line is output. |
| 21505 | .endp |
| 21506 | The setting of the switch can, of course, be made conditional on the |
| 21507 | calling host. |
| 21508 | |
| 21509 | |
| 21510 | .item "control = queue@_only" |
| 21511 | .index \queue@_only\ |
| 21512 | .index queueing incoming messages |
| 21513 | This control is permitted only for the \\MAIL\\, \\RCPT\\, \\DATA\\, and |
| 21514 | non-SMTP ACLs, in other words, only when a message is being received. If the |
| 21515 | message is accepted, it is placed on Exim's queue and left there for delivery |
| 21516 | by a subsequent queue runner. No immediate delivery process is started. In |
| 21517 | other words, it has the effect of the \queue@_only\ global option for just the |
| 21518 | one message. |
| 21519 | |
| 21520 | |
| 21521 | .item "control = submission/<<options>>" |
| 21522 | .index message||submission |
| 21523 | .index submission mode |
| 21524 | This control is permitted only for the \\MAIL\\, \\RCPT\\, and start of data |
| 21525 | ACLs (the latter is the one defined by \acl@_smtp@_predata\). Setting it tells |
| 21526 | Exim that the message is a submission from a local MUA. In this case, Exim |
| 21527 | operates in `submission mode', and applies certain fixups to the message if |
| 21528 | necessary. For example, it add a ::Date:: header line if one is not present. |
| 21529 | This control is not permitted in the \\DATA\\ ACL, because that is too late |
| 21530 | (the message has already been created). |
| 21531 | |
| 21532 | Chapter ~~CHAPmsgproc describes the processing that Exim applies to messages. |
| 21533 | Section ~~SECTsubmodnon covers the processing that happens in submission mode; |
| 21534 | the available options for this control are described there. |
| 21535 | |
| 21536 | .enditems |
| 21537 | .nem |
| 21538 | |
| 21539 | |
| 21540 | .em |
| 21541 | .section Adding header lines with the warn verb |
| 21542 | .rset SECTaddheadwarn "~~chapter.~~section" |
| 21543 | .index header lines||adding in an ACL |
| 21544 | .index header lines||position of added lines |
| 21545 | The \message\ modifier can be used on a \warn\ statement to add an extra header |
| 21546 | line to an incoming message, as in this example: |
| 21547 | .display asis |
| 21548 | warn message = X-blacklisted-at: $dnslist_domain |
| 21549 | dnslists = sbl.spamhaus.org : \ |
| 21550 | dialup.mail-abuse.org |
| 21551 | .endd |
| 21552 | If an identical header line is requested several times (provoked, for example, |
| 21553 | by multiple \\RCPT\\ commands), only one copy is actually added to the message. |
| 21554 | If the text of the \message\ modifier contains one or more newlines that are |
| 21555 | not followed by a space or a tab, it is assumed to contain multiple header |
| 21556 | lines. Each one is checked for valid syntax; \"X-ACL-Warn:"\ is added to the |
| 21557 | front of any line that is not a valid header line. |
| 21558 | |
| 21559 | By default, new lines are added at the end of the existing header lines. |
| 21560 | However, you can specify that any particular header line should be added right |
| 21561 | at the start (before all the ::Received:: lines), immediately after the first |
| 21562 | block of ::Received:: lines, or immediately before any line that is not a |
| 21563 | ::Received:: or ::Resent-something:: header. |
| 21564 | |
| 21565 | This is done by specifying `:at@_start:', `:after@_received:', or |
| 21566 | `:at@_start@_rfc:' (or, for completeness, `:at@_end:') before the text of the |
| 21567 | header line, respectively. (Header text cannot start with a colon, as there has |
| 21568 | to be a header name first.) For example: |
| 21569 | .display asis |
| 21570 | warn message = :after_received:X-My-Header: something or other... |
| 21571 | .endd |
| 21572 | |
| 21573 | If more than one header is supplied in a single warn statement, each one is |
| 21574 | treated independently and can therefore be placed differently. If you add |
| 21575 | more than one line at the start, or after the Received: block, they will |
| 21576 | end up in reverse order. |
| 21577 | |
| 21578 | \**Warning**\: This facility currently applies only to header lines that are |
| 21579 | added in an ACL. It does NOT work for header lines that are added in a |
| 21580 | system filter or in a router or transport. |
| 21581 | |
| 21582 | .index header lines||added, visibility of |
| 21583 | Header lines that are added by an ACL at \\MAIL\\ or \\RCPT\\ time are not |
| 21584 | visible in string expansions in ACLs for subsequent \\RCPT\\ commands or in the |
| 21585 | \acl@_smtp@_predata\ ACL. However, they are visible in string expansions in the |
| 21586 | ACL that is run after \\DATA\\ is complete (the \acl@_smtp@_data\ ACL). This is |
| 21587 | also true for header lines that are added in the \acl@_smtp@_predata\ ACL. |
| 21588 | If a message is rejected after \\DATA\\, all added header lines are included in |
| 21589 | the entry that is written to the reject log. |
| 21590 | |
| 21591 | If you want to preserve data between \\MAIL\\, \\RCPT\\, and the |
| 21592 | \acl@_smtp@_predata\ ACLs, you can use ACL variables, as described in section |
| 21593 | ~~SECTaclvariables. |
| 21594 | .nem |
| 21595 | |
| 21596 | |
| 21597 | |
| 21598 | .section ACL conditions |
| 21599 | .rset SECTaclconditions "~~chapter.~~section" |
| 21600 | .index ~~ACL||conditions, list of |
| 21601 | .em |
| 21602 | Some of conditions listed in this section are available only when Exim is |
| 21603 | compiled with the content-scanning extension. They are included here briefly |
| 21604 | for completeness. More detailed descriptions can be found in the discussion on |
| 21605 | content scanning in chapter ~~CHAPexiscan. |
| 21606 | .nem |
| 21607 | |
| 21608 | Not all conditions are relevant in all circumstances. For example, testing |
| 21609 | senders and recipients does not make sense in an ACL that is being run as the |
| 21610 | result of the arrival of an \\ETRN\\ command, and checks on message headers can |
| 21611 | be done only in the ACLs specified by \acl@_smtp@_data\ and \acl__not__smtp\. |
| 21612 | You can use the same condition (with different parameters) more than once in |
| 21613 | the same ACL statement. This provides a way of specifying an `and' conjunction. |
| 21614 | The conditions are as follows: |
| 21615 | |
| 21616 | .startitems |
| 21617 | |
| 21618 | .item "acl = <<name of acl or ACL string or file name >>" |
| 21619 | .index ~~ACL||nested |
| 21620 | .index ~~ACL||indirect |
| 21621 | The possible values of the argument are the same as for the |
| 21622 | \acl@_smtp@_$it{xxx}\ options. The named or inline ACL is run. If it returns |
| 21623 | `accept' the condition is true; if it returns `deny' the condition is false. If |
| 21624 | it returns `defer', the current ACL returns `defer' |
| 21625 | .em |
| 21626 | unless the condition is on a \warn\ verb. In that case, a `defer' return makes |
| 21627 | the condition false. This means that further processing of the \warn\ verb |
| 21628 | ceases, but processing of the ACL continues. |
| 21629 | .nem |
| 21630 | |
| 21631 | If the nested \acl\ returns `drop' and the outer condition denies access, |
| 21632 | the connection is dropped. If it returns `discard', the verb must be \accept\ |
| 21633 | or \discard\, and the action is taken immediately -- no further conditions are |
| 21634 | tested. |
| 21635 | |
| 21636 | ACLs may be nested up to 20 deep; the limit exists purely to catch runaway |
| 21637 | loops. This condition allows you to use different ACLs in different |
| 21638 | circumstances. For example, different ACLs can be used to handle \\RCPT\\ |
| 21639 | commands for different local users or different local domains. |
| 21640 | |
| 21641 | .item "authenticated = <<string list>>" |
| 21642 | .index authentication||ACL checking |
| 21643 | .index ~~ACL||testing for authentication |
| 21644 | If the SMTP connection is not authenticated, the condition is false. Otherwise, |
| 21645 | the name of the authenticator is tested against the list. To test for |
| 21646 | authentication by any authenticator, you can set |
| 21647 | .display asis |
| 21648 | authenticated = * |
| 21649 | .endd |
| 21650 | |
| 21651 | .item "condition = <<string>>" |
| 21652 | .index customizing||ACL condition |
| 21653 | .index ~~ACL||customized test |
| 21654 | This feature allows you to make up custom conditions. If the result of |
| 21655 | expanding the string is an empty string, the number zero, or one of the strings |
| 21656 | `no' or `false', the condition is false. If the result is any non-zero number, |
| 21657 | or one of the strings `yes' or `true', the condition is true. For any other |
| 21658 | values, some error is assumed to have occured, and the ACL returns `defer'. |
| 21659 | |
| 21660 | |
| 21661 | .em |
| 21662 | .item "decode = <<location>>" |
| 21663 | This condition is available only when Exim is compiled with the |
| 21664 | content-scanning extension, and it is allowed only the the ACL defined by |
| 21665 | \acl@_smtp@_mime\. It causes the current MIME part to be decoded into a file. |
| 21666 | For details, see chapter ~~CHAPexiscan. |
| 21667 | .nem |
| 21668 | |
| 21669 | |
| 21670 | .item "dnslists = <<list of domain names and other data>>" |
| 21671 | .index DNS list||in ACL |
| 21672 | .index black list (DNS) |
| 21673 | .index ~~ACL||testing a DNS list |
| 21674 | This condition checks for entries in DNS black lists. These are also known as |
| 21675 | `RBL lists', after the original Realtime Blackhole List, but note that the use |
| 21676 | of the lists at \*mail-abuse.org*\ now carries a charge. |
| 21677 | There are too many different variants of this condition to describe briefly |
| 21678 | here. See sections ~~SECTmorednslists--~~SECTmorednslistslast for details. |
| 21679 | |
| 21680 | .item "domains = <<domain list>>" |
| 21681 | .index domain||ACL checking |
| 21682 | .index ~~ACL||testing a recipient domain |
| 21683 | This condition is relevant only after a \\RCPT\\ command. It checks that the |
| 21684 | domain of the recipient address is in the domain list. If percent-hack |
| 21685 | processing is enabled, it is done before this test is done. If the check |
| 21686 | succeeds with a lookup, the result of the lookup is placed in \$domain@_data$\ |
| 21687 | until the next \domains\ test. |
| 21688 | |
| 21689 | .item "encrypted = <<string list>>" |
| 21690 | .index encryption||checking in an ACL |
| 21691 | .index ~~ACL||testing for encryption |
| 21692 | If the SMTP connection is not encrypted, the condition is false. Otherwise, the |
| 21693 | name of the cipher suite in use is tested against the list. To test for |
| 21694 | encryption without testing for any specific cipher suite(s), set |
| 21695 | .display asis |
| 21696 | encrypted = * |
| 21697 | .endd |
| 21698 | |
| 21699 | .item "hosts = << host list>>" |
| 21700 | .index host||ACL checking |
| 21701 | .index ~~ACL||testing the client host |
| 21702 | This condition tests that the calling host matches the host list. If you have |
| 21703 | name lookups or wildcarded host names and IP addresses in the same host list, |
| 21704 | you should normally put the IP addresses first. For example, you could have: |
| 21705 | .display asis |
| 21706 | accept hosts = 10.9.8.7 : dbm;/etc/friendly/hosts |
| 21707 | .endd |
| 21708 | The reason for this lies in the left-to-right way that Exim processes lists. |
| 21709 | It can test IP addresses without doing any DNS lookups, but when it reaches an |
| 21710 | item that requires a host name, it fails if it cannot find a host name to |
| 21711 | compare with the pattern. If the above list is given in the opposite order, the |
| 21712 | \accept\ statement fails for a host whose name cannot be found, even if its |
| 21713 | IP address is 10.9.8.7. |
| 21714 | |
| 21715 | If you really do want to do the name check first, and still recognize the IP |
| 21716 | address even if the name lookup fails, you can rewrite the ACL like this: |
| 21717 | .display asis |
| 21718 | accept hosts = dbm;/etc/friendly/hosts |
| 21719 | accept hosts = 10.9.8.7 |
| 21720 | .endd |
| 21721 | The default action on failing to find the host name is to assume that the host |
| 21722 | is not in the list, so the first \accept\ statement fails. The second statement |
| 21723 | can then check the IP address. |
| 21724 | |
| 21725 | If a \hosts\ condition is satisfied by means of a lookup, the result |
| 21726 | of the lookup is made available in the \$host@_data$\ variable. This |
| 21727 | allows you, for example, to set up a statement like this: |
| 21728 | .display asis |
| 21729 | deny hosts = net-lsearch;/some/file |
| 21730 | message = $host_data |
| 21731 | .endd |
| 21732 | which gives a custom error message for each denied host. |
| 21733 | |
| 21734 | .item "local@_parts = <<local part list>>" |
| 21735 | .index local part||ACL checking |
| 21736 | .index ~~ACL||testing a local part |
| 21737 | This condition is relevant only after a \\RCPT\\ command. It checks that the |
| 21738 | local part of the recipient address is in the list. If percent-hack processing |
| 21739 | is enabled, it is done before this test. If the check succeeds with a lookup, |
| 21740 | the result of the lookup is placed in \$local@_part@_data$\ until the next |
| 21741 | \local@_parts\ test. |
| 21742 | |
| 21743 | |
| 21744 | .em |
| 21745 | .item "malware = <<option>>" |
| 21746 | This condition is available only when Exim is compiled with the |
| 21747 | content-scanning extension. It causes the incoming message to be scanned for |
| 21748 | viruses. For details, see chapter ~~CHAPexiscan. |
| 21749 | .nem |
| 21750 | |
| 21751 | |
| 21752 | .em |
| 21753 | .item "mime@_regex = <<list of regular expressions>>" |
| 21754 | This condition is available only when Exim is compiled with the |
| 21755 | content-scanning extension, and it is allowed only the the ACL defined by |
| 21756 | \acl@_smtp@_mime\. It causes the current MIME part to be scanned for a match |
| 21757 | with any of the regular expressions. For details, see chapter ~~CHAPexiscan. |
| 21758 | .nem |
| 21759 | |
| 21760 | |
| 21761 | .item "recipients = <<address list>>" |
| 21762 | .index recipient||ACL checking |
| 21763 | .index ~~ACL||testing a recipient |
| 21764 | This condition is relevant only after a \\RCPT\\ command. It checks the entire |
| 21765 | recipient address against a list of recipients. |
| 21766 | |
| 21767 | |
| 21768 | .em |
| 21769 | .item "regex = <<list of regular expressions>>" |
| 21770 | This condition is available only when Exim is compiled with the |
| 21771 | content-scanning extension. It causes the incoming message to be scanned |
| 21772 | for a match with any of the regular expressions. For details, see chapter |
| 21773 | ~~CHAPexiscan. |
| 21774 | .nem |
| 21775 | |
| 21776 | |
| 21777 | .item "sender@_domains = <<domain list>>" |
| 21778 | .index sender||ACL checking |
| 21779 | .index ~~ACL||testing a sender domain |
| 21780 | This condition tests the domain of the sender of the message against the given |
| 21781 | domain list. |
| 21782 | \**Note**\: the domain of the sender address is in |
| 21783 | \$sender@_address@_domain$\. It is \*not*\ put in \$domain$\ during the testing |
| 21784 | of this condition. This is an exception to the general rule for testing |
| 21785 | domain lists. It is done this way so that, if this condition is used in an |
| 21786 | ACL for a \\RCPT\\ command, the recipient's domain (which is in \$domain$\) can |
| 21787 | be used to influence the sender checking. |
| 21788 | |
| 21789 | .item "senders = <<address list>>" |
| 21790 | .index sender||ACL checking |
| 21791 | .index ~~ACL||testing a sender |
| 21792 | This condition tests the sender of the message against the given list. To test |
| 21793 | for a bounce message, which has an empty sender, set |
| 21794 | .display asis |
| 21795 | senders = : |
| 21796 | .endd |
| 21797 | |
| 21798 | |
| 21799 | .em |
| 21800 | .item "spam = <<username>>" |
| 21801 | This condition is available only when Exim is compiled with the |
| 21802 | content-scanning extension. It causes the incoming message to be scanned by |
| 21803 | SpamAssassin. For details, see chapter ~~CHAPexiscan. |
| 21804 | .nem |
| 21805 | |
| 21806 | |
| 21807 | .item "verify = certificate" |
| 21808 | .index TLS||client certificate verification |
| 21809 | .index certificate||verification of client |
| 21810 | .index ~~ACL||certificate verification |
| 21811 | This condition is true in an SMTP session if the session is encrypted, and a |
| 21812 | certificate was received from the client, and the certificate was verified. The |
| 21813 | server requests a certificate only if the client matches \tls@_verify@_hosts\ |
| 21814 | or \tls@_try@_verify@_hosts\ (see chapter ~~CHAPTLS). |
| 21815 | |
| 21816 | .item "verify = header@_sender/<<options>>" |
| 21817 | .index ~~ACL||verifying sender in the header |
| 21818 | .index header lines||verifying the sender in |
| 21819 | .index sender||verifying in header |
| 21820 | .index verifying||sender in header |
| 21821 | This condition is relevant only in an ACL that is run after a message has been |
| 21822 | received, that is, in an ACL specified by \acl@_smtp@_data\ |
| 21823 | .em |
| 21824 | or \acl@_not@_smtp\. It checks that there is a verifiable address in at least |
| 21825 | one of the ::Sender::, ::Reply-To::, or ::From:: header lines. Such an address |
| 21826 | is loosely thought of as a `sender' address (hence the name of the test). |
| 21827 | However, an address that appears in one of these headers need not be an address |
| 21828 | that accepts bounce messages; only sender addresses in envelopes are required |
| 21829 | to accept bounces. Therefore, if you use the callout option on this check, you |
| 21830 | might want to arrange for a non-empty address in the \\MAIL\\ command. |
| 21831 | .nem |
| 21832 | |
| 21833 | Details of address verification and the options are given later, starting at |
| 21834 | section ~~SECTaddressverification (callouts are described in section |
| 21835 | ~~SECTcallver). You can combine this condition with the \senders\ condition to |
| 21836 | restrict it to bounce messages only: |
| 21837 | .display asis |
| 21838 | deny senders = : |
| 21839 | message = A valid sender header is required for bounces |
| 21840 | !verify = header_sender |
| 21841 | .endd |
| 21842 | |
| 21843 | .item "verify = header@_syntax" |
| 21844 | .index ~~ACL||verifying header syntax |
| 21845 | .index header lines||verifying syntax |
| 21846 | .index verifying||header syntax |
| 21847 | This condition is relevant only in an ACL that is run after a message has been |
| 21848 | received, that is, in an ACL specified by \acl@_smtp@_data\ |
| 21849 | or \acl@_not@_smtp\. |
| 21850 | It checks the syntax of all header lines that can contain lists of addresses |
| 21851 | (::Sender::, ::From::, ::Reply-To::, ::To::, ::Cc::, and ::Bcc::). |
| 21852 | Unqualified addresses (local parts without domains) are permitted only in |
| 21853 | locally generated messages and from hosts that match |
| 21854 | \sender@_unqualified@_hosts\ or \recipient@_unqualified@_hosts\, as |
| 21855 | appropriate. |
| 21856 | |
| 21857 | Note that this condition is a syntax check only. However, a common spamming |
| 21858 | ploy is to send syntactically invalid headers such as |
| 21859 | .display asis |
| 21860 | To: @ |
| 21861 | .endd |
| 21862 | and this condition can be used to reject such messages. |
| 21863 | |
| 21864 | .item "verify = helo" |
| 21865 | .index ~~ACL||verifying HELO/EHLO |
| 21866 | .index \\HELO\\||verifying |
| 21867 | .index \\EHLO\\||verifying |
| 21868 | .index verifying||\\EHLO\\ |
| 21869 | .index verifying||\\HELO\\ |
| 21870 | This condition is true if a \\HELO\\ or \\EHLO\\ command has been received from |
| 21871 | the client host, and its contents have been verified. Verification of these |
| 21872 | commands does not happen by default. See the description of the |
| 21873 | \helo@_verify@_hosts\ and \helo@_try@_verify@_hosts\ options for details of how |
| 21874 | to request it. |
| 21875 | |
| 21876 | .item "verify = recipient/<<options>>" |
| 21877 | .index ~~ACL||verifying recipient |
| 21878 | .index recipient||verifying |
| 21879 | .index verifying||recipient |
| 21880 | This condition is relevant only after a \\RCPT\\ command. It verifies the |
| 21881 | current recipient. Details of address verification are given later, starting at |
| 21882 | section ~~SECTaddressverification. After a recipient has been verified, the |
| 21883 | value of \$address@_data$\ is the last value that was set while routing the |
| 21884 | address. This applies even if the verification fails. When an address that is |
| 21885 | being verified is redirected to a single address, verification continues with |
| 21886 | the new address, and in that case, the subsequent value of \$address@_data$\ is |
| 21887 | the value for the child address. |
| 21888 | |
| 21889 | |
| 21890 | .item "verify = reverse@_host@_lookup" |
| 21891 | .index ~~ACL||verifying host reverse lookup |
| 21892 | .index host||verifying reverse lookup |
| 21893 | This condition ensures that a verified host name has been looked up from the IP |
| 21894 | address of the client host. (This may have happened already if the host name |
| 21895 | was needed for checking a host list, or if the host matched \host@_lookup\.) |
| 21896 | Verification ensures that the host name obtained from a reverse DNS lookup, or |
| 21897 | one of its aliases, does, when it is itself looked up in the DNS, yield the |
| 21898 | original IP address. |
| 21899 | |
| 21900 | If this condition is used for a locally generated message (that is, when there |
| 21901 | is no client host involved), it always succeeds. |
| 21902 | |
| 21903 | |
| 21904 | .item "verify = sender/<<options>>" |
| 21905 | .index ~~ACL||verifying sender |
| 21906 | .index sender||verifying |
| 21907 | .index verifying||sender |
| 21908 | This condition is relevant only after a |
| 21909 | \\MAIL\\ or \\RCPT\\ command, or after a message has been received (the |
| 21910 | \acl@_smtp@_data\ or \acl@_not@_smtp\ ACLs). |
| 21911 | If the message's sender is empty (that is, this is a bounce message), the |
| 21912 | condition is true. Otherwise, the sender address is verified. Details of |
| 21913 | verification are given later, starting at section ~~SECTaddressverification. |
| 21914 | Exim caches the result of sender verification, to avoid doing it more than once |
| 21915 | per message. |
| 21916 | |
| 21917 | .item "verify = sender=address/<<options>>" |
| 21918 | This is a variation of the previous option, in which a modified address is |
| 21919 | verified as a sender. |
| 21920 | |
| 21921 | .enditems |
| 21922 | |
| 21923 | |
| 21924 | |
| 21925 | .section Using DNS lists |
| 21926 | .rset SECTmorednslists "~~chapter.~~section" |
| 21927 | .index DNS list||in ACL |
| 21928 | .index black list (DNS) |
| 21929 | .index ~~ACL||testing a DNS list |
| 21930 | In its simplest form, the \dnslists\ condition tests whether the calling host |
| 21931 | is on at least one of a number of DNS lists by looking up the inverted IP |
| 21932 | address in one or more DNS domains. For example, if the calling host's IP |
| 21933 | address is 192.168.62.43, and the ACL statement is |
| 21934 | .display asis |
| 21935 | deny dnslists = blackholes.mail-abuse.org : \ |
| 21936 | dialups.mail-abuse.org |
| 21937 | .endd |
| 21938 | the following records are looked up: |
| 21939 | .display asis |
| 21940 | 43.62.168.192.blackholes.mail-abuse.org |
| 21941 | 43.62.168.192.dialups.mail-abuse.org |
| 21942 | .endd |
| 21943 | .em |
| 21944 | As soon as Exim finds an existing DNS record, processing of the list stops. |
| 21945 | Thus, multiple entries on the list provide an `or' conjunction. If you want to |
| 21946 | test that a host is on more than one list (an `and' conjunction), you can use |
| 21947 | two separate conditions: |
| 21948 | .display asis |
| 21949 | deny dnslists = blackholes.mail-abuse.org |
| 21950 | dnslists = dialups.mail-abuse.org |
| 21951 | .endd |
| 21952 | .nem |
| 21953 | If a DNS lookup times out or otherwise fails to give a decisive answer, Exim |
| 21954 | behaves as if the host |
| 21955 | .em |
| 21956 | does not match the list item, that is, as if the DNS record does not exist. If |
| 21957 | there are further items in the DNS list, they are processed. |
| 21958 | .nem |
| 21959 | This is usually the required action when \dnslists\ is used with \deny\ (which |
| 21960 | is the most common usage), because it prevents a DNS failure from blocking |
| 21961 | mail. However, you can change this behaviour by putting one of the following |
| 21962 | special items in the list: |
| 21963 | .index \"+include@_unknown"\ |
| 21964 | .index \"+exclude@_unknown"\ |
| 21965 | .index \"+defer@_unknown"\ |
| 21966 | .display |
| 21967 | +include@_unknown $rm{behave as if the item is on the list} |
| 21968 | +exclude@_unknown $rm{behave as if the item is not on the list (default)} |
| 21969 | +defer@_unknown $rm{give a temporary error} |
| 21970 | .endd |
| 21971 | Each of these applies to any subsequent items on the list. For example: |
| 21972 | .display asis |
| 21973 | deny dnslists = +defer_unknown : foo.bar.example |
| 21974 | .endd |
| 21975 | |
| 21976 | Testing the list of domains stops as soon as a match is found. If you want to |
| 21977 | warn for one list and block for another, you can use two different statements: |
| 21978 | .display asis |
| 21979 | deny dnslists = blackholes.mail-abuse.org |
| 21980 | warn message = X-Warn: sending host is on dialups list |
| 21981 | dnslists = dialups.mail-abuse.org |
| 21982 | .endd |
| 21983 | |
| 21984 | DNS list lookups are cached by Exim for the duration of the SMTP session, |
| 21985 | so a lookup based on the IP address is done at most once for any incoming |
| 21986 | connection. Exim does not share information between multiple incoming |
| 21987 | connections (but your local name server cache should be active). |
| 21988 | |
| 21989 | |
| 21990 | .em |
| 21991 | .section Specifying the IP address for a DNS list lookup |
| 21992 | .index DNS list||keyed by explicit IP address |
| 21993 | By default, the IP address that is used in a DNS list lookup is the IP address |
| 21994 | of the calling host. However, you can specify another IP address by listing it |
| 21995 | after the domain name, introduced by a slash. For example: |
| 21996 | .display asis |
| 21997 | deny dnslists = black.list.tls/192.168.1.2 |
| 21998 | .endd |
| 21999 | This feature is not very helpful with explicit IP addresses; it is intended for |
| 22000 | use with IP addresses that are looked up, for example, the IP addresses of the |
| 22001 | MX hosts or nameservers of an email sender address. For an example, see section |
| 22002 | ~~SECTmulkeyfor below. |
| 22003 | .nem |
| 22004 | |
| 22005 | |
| 22006 | .section DNS lists keyed on domain names |
| 22007 | .index DNS list||keyed by domain name |
| 22008 | There are some lists that are keyed on domain names rather than inverted IP |
| 22009 | addresses (see for example the \*domain based zones*\ link at |
| 22010 | \?http://www.rfc-ignorant.org/?\). No reversing of components is used with |
| 22011 | these lists. You can change the name that is looked up in a DNS list by listing |
| 22012 | it after the domain name, introduced by a slash. For example, |
| 22013 | .display asis |
| 22014 | deny message = Sender's domain is listed at $dnslist_domain |
| 22015 | dnslists = dsn.rfc-ignorant.org/$sender_address_domain |
| 22016 | .endd |
| 22017 | This particular example is useful only in ACLs that are obeyed after the |
| 22018 | \\RCPT\\ or \\DATA\\ commands, when a sender address is available. If (for |
| 22019 | example) the message's sender is \*user@@tld.example*\ the name that is looked |
| 22020 | up by this example is |
| 22021 | .display asis |
| 22022 | tld.example.dsn.rfc-ignorant.org |
| 22023 | .endd |
| 22024 | .em |
| 22025 | A single \dnslists\ condition can contain entries for both names and IP |
| 22026 | addresses. For example: |
| 22027 | .display asis |
| 22028 | deny dnslists = sbl.spamhaus.org : \ |
| 22029 | dsn.rfc-ignorant.org/$sender_address_domain |
| 22030 | .endd |
| 22031 | The first item checks the sending host's IP address; the second checks a domain |
| 22032 | name. The whole condition is true if either of the DNS lookups succeeds. |
| 22033 | .nem |
| 22034 | |
| 22035 | |
| 22036 | .em |
| 22037 | .section Multiple explicit keys for a DNS list |
| 22038 | .rset SECTmulkeyfor "~~chapter.~~section" |
| 22039 | .index DNS list||multiple keys for |
| 22040 | The syntax described above for looking up explicitly-defined values (either |
| 22041 | names or IP addresses) in a DNS blacklist is a simplification. After the domain |
| 22042 | name for the DNS list, what follows the slash can in fact be a list of items. |
| 22043 | As with all lists in Exim, the default separator is a colon. However, because |
| 22044 | this is a sublist within the list of DNS blacklist domains, it is necessary |
| 22045 | either to double the separators like this: |
| 22046 | .display asis |
| 22047 | dnslists = black.list.tld/name.1::name.2 |
| 22048 | .endd |
| 22049 | or to change the separator character, like this: |
| 22050 | .display asis |
| 22051 | dnslists = black.list.tld/<;name.1;name.2 |
| 22052 | .endd |
| 22053 | If an item in the list is an IP address, it is inverted before the DNS |
| 22054 | blacklist domain is appended. If it is not an IP address, no inversion |
| 22055 | occurs. Consider this condition: |
| 22056 | .display asis |
| 22057 | dnslists = black.list.tld/<;192.168.1.2;a.domain |
| 22058 | .endd |
| 22059 | The DNS lookups that occur are: |
| 22060 | .display asis |
| 22061 | 2.1.168.192.black.list.tld |
| 22062 | a.domain.black.list.tld |
| 22063 | .endd |
| 22064 | Once a DNS record has been found (that matches a specific IP return |
| 22065 | address, if specified -- see section ~~SECTaddmatcon), no further lookups are |
| 22066 | done. If there is a temporary DNS error, the rest of the sublist of domains or |
| 22067 | IP addresses is tried. A temporary error for the whole dnslists item occurs |
| 22068 | only if no other DNS lookup in this sublist succeeds. In other words, a |
| 22069 | successful lookup for any of the items in the sublist overrides a temporary |
| 22070 | error for a previous item. |
| 22071 | |
| 22072 | The ability to supply a list of items after the slash is in some sense just a |
| 22073 | syntactic convenience. These two examples have the same effect: |
| 22074 | .display asis |
| 22075 | dnslists = black.list.tld/a.domain : black.list.tld/b.domain |
| 22076 | dnslists = black.list.tld/a.domain::b.domain |
| 22077 | .endd |
| 22078 | However, when the data for the list is obtained from a lookup, the second form |
| 22079 | is usually much more convenient. Consider this example: |
| 22080 | .display asis |
| 22081 | deny message = The mail servers for the domain \ |
| 22082 | $sender_address_domain \ |
| 22083 | are listed at $dnslist_domain ($dnslist_value); \ |
| 22084 | see $dnslist_text. |
| 22085 | dnslists = sbl.spamhaus.org/<|${lookup dnsdb {>|a=<|\ |
| 22086 | ${lookup dnsdb {>|mxh=\ |
| 22087 | $sender_address_domain} }} } |
| 22088 | .endd |
| 22089 | Note the use of \">|"\ in the dnsdb lookup to specify the separator for |
| 22090 | multiple DNS records. The inner dnsdb lookup produces a list of MX hosts |
| 22091 | and the outer dnsdb lookup finds the IP addresses for these hosts. The result |
| 22092 | of expanding the condition might be something like this: |
| 22093 | .display asis |
| 22094 | dnslists = sbl.spahmaus.org/<|192.168.2.3|192.168.5.6|... |
| 22095 | .endd |
| 22096 | Thus, this example checks whether or not the IP addresses of the sender |
| 22097 | domain's mail servers are on the Spamhaus black list. |
| 22098 | .nem |
| 22099 | |
| 22100 | |
| 22101 | |
| 22102 | .section Data returned by DNS lists |
| 22103 | .index DNS list||data returned from |
| 22104 | DNS lists are constructed using address records in the DNS. The original RBL |
| 22105 | just used the address 127.0.0.1 on the right hand side of each record, but the |
| 22106 | RBL+ list and some other lists use a number of values with different meanings. |
| 22107 | The values used on the RBL+ list are: |
| 22108 | .display rm |
| 22109 | .tabs 12 |
| 22110 | 127.1.0.1 $t RBL |
| 22111 | 127.1.0.2 $t DUL |
| 22112 | 127.1.0.3 $t DUL and RBL |
| 22113 | 127.1.0.4 $t RSS |
| 22114 | 127.1.0.5 $t RSS and RBL |
| 22115 | 127.1.0.6 $t RSS and DUL |
| 22116 | 127.1.0.7 $t RSS and DUL and RBL |
| 22117 | .endd |
| 22118 | Some DNS lists may return more than one address record. |
| 22119 | |
| 22120 | .section Variables set from DNS lists |
| 22121 | .index DNS list||variables set from |
| 22122 | When an entry is found in a DNS list, the variable \$dnslist@_domain$\ |
| 22123 | contains the name of the domain that matched, \$dnslist@_value$\ contains the |
| 22124 | data from the entry, and \$dnslist@_text$\ contains the contents of any |
| 22125 | associated TXT record. If more than one address record is returned by the DNS |
| 22126 | lookup, all the IP addresses are included in \$dnslist@_value$\, separated by |
| 22127 | commas and spaces. |
| 22128 | |
| 22129 | You can use these variables in \message\ or \log@_message\ modifiers -- |
| 22130 | although these appear before the condition in the ACL, they are not expanded |
| 22131 | until after it has failed. For example: |
| 22132 | .display asis |
| 22133 | deny hosts = !+local_networks |
| 22134 | message = $sender_host_address is listed \ |
| 22135 | at $dnslist_domain |
| 22136 | dnslists = rbl-plus.mail-abuse.example |
| 22137 | .endd |
| 22138 | |
| 22139 | |
| 22140 | .section Additional matching conditions for DNS lists |
| 22141 | .rset SECTaddmatcon "~~chapter.~~section" |
| 22142 | .index DNS list||matching specific returned data |
| 22143 | You can add an equals sign and an IP address after a \dnslists\ domain name in |
| 22144 | order to restrict its action to DNS records with a matching right hand side. |
| 22145 | For example, |
| 22146 | .display asis |
| 22147 | deny dnslists = rblplus.mail-abuse.org=127.0.0.2 |
| 22148 | .endd |
| 22149 | rejects only those hosts that yield 127.0.0.2. Without this additional data, |
| 22150 | any address record is considered to be a match. If more than one address record |
| 22151 | is found on the list, they are all checked for a matching right-hand side. |
| 22152 | |
| 22153 | More than one IP address may be given for checking, using a comma as a |
| 22154 | separator. These are alternatives -- if any one of them matches, the \dnslists\ |
| 22155 | condition is true. For example: |
| 22156 | .display asis |
| 22157 | deny dnslists = a.b.c=127.0.0.2,127.0.0.3 |
| 22158 | .endd |
| 22159 | |
| 22160 | If you want to specify a constraining address list and also specify names or IP |
| 22161 | addresses to be looked up, the constraining address list must be specified |
| 22162 | first. For example: |
| 22163 | .display asis |
| 22164 | deny dnslists = dsn.rfc-ignorant.org\ |
| 22165 | =127.0.0.2/$sender_address_domain |
| 22166 | .endd |
| 22167 | |
| 22168 | If the character `&' is used instead of `=', the comparison for each listed |
| 22169 | IP address is done by a bitwise `and' instead of by an equality test. In |
| 22170 | other words, the listed addresses are used as bit masks. The comparison is |
| 22171 | true if all the bits in the mask are present in the address that is being |
| 22172 | tested. For example: |
| 22173 | .display asis |
| 22174 | dnslists = a.b.c&0.0.0.3 |
| 22175 | .endd |
| 22176 | matches if the address is \*x.x.x.*\3, \*x.x.x.*\7, \*x.x.x.*\11, etc. If you |
| 22177 | want to test whether one bit or another bit is present (as opposed to both |
| 22178 | being present), you must use multiple values. For example: |
| 22179 | .display asis |
| 22180 | dnslists = a.b.c&0.0.0.1,0.0.0.2 |
| 22181 | .endd |
| 22182 | matches if the final component of the address is an odd number or two times |
| 22183 | an odd number. |
| 22184 | |
| 22185 | |
| 22186 | .section Negated DNS matching conditions |
| 22187 | You can supply a negative list of IP addresses as part of a \dnslists\ |
| 22188 | condition. Whereas |
| 22189 | .display asis |
| 22190 | deny dnslists = a.b.c=127.0.0.2,127.0.0.3 |
| 22191 | .endd |
| 22192 | means `deny if the host is in the black list at the domain \*a.b.c*\ and the IP |
| 22193 | address yielded by the list is either 127.0.0.2 or 127.0.0.3', |
| 22194 | .display asis |
| 22195 | deny dnslists = a.b.c!=127.0.0.2,127.0.0.3 |
| 22196 | .endd |
| 22197 | means `deny if the host is in the black list at the domain \*a.b.c*\ and the IP |
| 22198 | address yielded by the list is not 127.0.0.2 and not 127.0.0.3'. In other |
| 22199 | words, the result of the test is inverted if an exclamation mark appears before |
| 22200 | the `=' (or the `&') sign. |
| 22201 | |
| 22202 | \**Note**\: this kind of negation is not the same as negation in a domain, |
| 22203 | host, or address list (which is why the syntax is different). |
| 22204 | |
| 22205 | If you are using just one list, the negation syntax does not gain you much. The |
| 22206 | previous example is precisely equivalent to |
| 22207 | .display asis |
| 22208 | deny dnslists = a.b.c |
| 22209 | !dnslists = a.b.c=127.0.0.2,127.0.0.3 |
| 22210 | .endd |
| 22211 | However, if you are using multiple lists, the negation syntax is clearer. |
| 22212 | Consider this example: |
| 22213 | .display asis |
| 22214 | deny dnslists = sbl.spamhaus.org : \ |
| 22215 | list.dsbl.org : \ |
| 22216 | dnsbl.njabl.org!=127.0.0.3 : \ |
| 22217 | relays.ordb.org |
| 22218 | .endd |
| 22219 | Using only positive lists, this would have to be: |
| 22220 | .display asis |
| 22221 | deny dnslists = sbl.spamhaus.org : \ |
| 22222 | list.dsbl.org |
| 22223 | deny dnslists = dnsbl.njabl.org |
| 22224 | !dnslists = dnsbl.njabl.org=127.0.0.3 |
| 22225 | deny dnslists = relays.ordb.org |
| 22226 | .endd |
| 22227 | which is less clear, and harder to maintain. |
| 22228 | |
| 22229 | |
| 22230 | |
| 22231 | .section DNS lists and IPv6 |
| 22232 | .rset SECTmorednslistslast "~~chapter.~~section" |
| 22233 | .index IPv6||DNS black lists |
| 22234 | .index DNS list||IPv6 usage |
| 22235 | If Exim is asked to do a dnslist lookup for an IPv6 address, it inverts it |
| 22236 | nibble by nibble. For example, if the calling host's IP address is |
| 22237 | 3ffe:ffff:836f:0a00:000a:0800:200a:c031, Exim might look up |
| 22238 | .display asis |
| 22239 | 1.3.0.c.a.0.0.2.0.0.8.0.a.0.0.0.0.0.a.0.f.6.3.8. |
| 22240 | f.f.f.f.e.f.f.3.blackholes.mail-abuse.org |
| 22241 | .endd |
| 22242 | (split over two lines here to fit on the page). Unfortunately, some of the DNS |
| 22243 | lists contain wildcard records, intended for IPv4, that interact badly with |
| 22244 | IPv6. For example, the DNS entry |
| 22245 | .display asis |
| 22246 | *.3.some.list.example. A 127.0.0.1 |
| 22247 | .endd |
| 22248 | is probably intended to put the entire 3.0.0.0/8 IPv4 network on the list. |
| 22249 | Unfortunately, it also matches the entire 3@:@:/4 IPv6 network. |
| 22250 | |
| 22251 | You can exclude IPv6 addresses from DNS lookups by making use of a suitable |
| 22252 | \condition\ condition, as in this example: |
| 22253 | .display asis |
| 22254 | .newline |
| 22255 | .em |
| 22256 | deny condition = ${if isip4{$sender_host_address}} |
| 22257 | .nem |
| 22258 | .newline |
| 22259 | dnslists = some.list.example |
| 22260 | .endd |
| 22261 | |
| 22262 | |
| 22263 | .section Address verification |
| 22264 | .rset SECTaddressverification "~~chapter.~~section" |
| 22265 | .index verifying||address, options for |
| 22266 | .index policy control||address verification |
| 22267 | Several of the \verify\ conditions described in section ~~SECTaclconditions |
| 22268 | cause addresses to be verified. These conditions can be followed by options |
| 22269 | that modify the verification process. The options are separated from the |
| 22270 | keyword and from each other by slashes, and some of them contain parameters. |
| 22271 | For example: |
| 22272 | .display asis |
| 22273 | verify = sender/callout |
| 22274 | verify = recipient/defer_ok/callout=10s,defer_ok |
| 22275 | .endd |
| 22276 | .em |
| 22277 | The first stage of address verification, which always happens, is to run the |
| 22278 | address through the routers, in `verify mode'. Routers can detect the |
| 22279 | difference between verification and routing for delivery, and their actions can |
| 22280 | be varied by a number of generic options such as \verify\ and \verify@_only\ |
| 22281 | (see chapter ~~CHAProutergeneric). If routing fails, verification fails. |
| 22282 | The available options are as follows: |
| 22283 | .numberpars $. |
| 22284 | If the \callout\ option is specified, successful routing to one or more remote |
| 22285 | hosts is followed by a `callout' to those hosts as an additional check. |
| 22286 | Callouts and their sub-options are discussed in the next section. |
| 22287 | .nextp |
| 22288 | If there is a defer error while doing verification routing, the ACL |
| 22289 | normally returns `defer'. However, if you include \defer@_ok\ in the options, |
| 22290 | the condition is forced to be true instead. Note that this is a main |
| 22291 | verification option as well as a suboption for callouts. |
| 22292 | .nextp |
| 22293 | The \no@_details\ option is covered in section ~~SECTsenaddver, which discusses |
| 22294 | the reporting of sender address verification failures. |
| 22295 | .endp |
| 22296 | |
| 22297 | .index verifying||address, differentiating failures |
| 22298 | After an address verification failure, \$sender@_verify@_failure$\ or |
| 22299 | \$recipient@_verify@_failure$\ (as appropriate) contains one of the following |
| 22300 | words: |
| 22301 | .numberpars $. |
| 22302 | \qualify\: The address was unqualified (no domain), and the message |
| 22303 | was neither local nor came from an exempted host. |
| 22304 | .nextp |
| 22305 | \route\: Routing failed. |
| 22306 | .nextp |
| 22307 | \mail\: Routing succeeded, and a callout was attempted; rejection |
| 22308 | occurred at or before the \\MAIL\\ command (that is, on initial |
| 22309 | connection, \\HELO\\, or \\MAIL\\). |
| 22310 | .nextp |
| 22311 | \recipient\: The \\RCPT\\ command in a callout was rejected. |
| 22312 | .nextp |
| 22313 | \postmaster\: The postmaster check in a callout was rejected. |
| 22314 | .endp |
| 22315 | |
| 22316 | The main use of these variables is expected to be to distinguish between |
| 22317 | rejections of \\MAIL\\ and rejections of \\RCPT\\ in callouts. |
| 22318 | |
| 22319 | .nem |
| 22320 | |
| 22321 | |
| 22322 | .section Callout verification |
| 22323 | .rset SECTcallver "~~chapter.~~section" |
| 22324 | .index verifying||address, by callout |
| 22325 | .index callout||verification |
| 22326 | .index SMTP||callout verification |
| 22327 | For non-local addresses, routing verifies the domain, but is unable to do any |
| 22328 | checking of the local part. There are situations where some means of verifying |
| 22329 | the local part is desirable. One way this can be done is to make an SMTP |
| 22330 | \*callback*\ to the sending host (for a sender address) or a \*callforward*\ to |
| 22331 | a subsequent host (for a recipient address), to see if the host accepts the |
| 22332 | address. We use the term \*callout*\ to cover both cases. This facility should |
| 22333 | be used with care, because it can add a lot of resource usage to the cost of |
| 22334 | verifying an address. However, Exim does cache the results of callouts, which |
| 22335 | helps to reduce the cost. Details of caching are in the next section. |
| 22336 | |
| 22337 | Recipient callouts are usually used only between hosts that are controlled by |
| 22338 | the same administration. For example, a corporate gateway host could use |
| 22339 | callouts to check for valid recipients on an internal mailserver. |
| 22340 | A successful callout does not guarantee that a real delivery to the address |
| 22341 | would succeed; on the other hand, a failing callout does guarantee that |
| 22342 | a delivery would fail. |
| 22343 | |
| 22344 | If the \callout\ option is present on a condition that verifies an address, a |
| 22345 | second stage of verification occurs if the address is successfully routed to |
| 22346 | one or more remote hosts. The usual case is routing by a \%dnslookup%\ or a |
| 22347 | \%manualroute%\ router, where the router specifies the hosts. However, if a |
| 22348 | router that does not set up hosts routes to an \%smtp%\ transport with a |
| 22349 | \hosts\ setting, the transport's hosts are used. If an \%smtp%\ transport has |
| 22350 | \hosts@_override\ set, its hosts are always used, whether or not the router |
| 22351 | supplies a host list. |
| 22352 | |
| 22353 | The port that is used is taken from the transport, if it is specified and is a |
| 22354 | remote transport. (For routers that do verification only, no transport need be |
| 22355 | specified.) Otherwise, the default SMTP port is used. If a remote transport |
| 22356 | specifies an outgoing interface, this is used; otherwise the interface is not |
| 22357 | specified. |
| 22358 | |
| 22359 | For a sender callout check, Exim makes SMTP connections to the remote hosts, to |
| 22360 | test whether a bounce message could be delivered to the sender address. The |
| 22361 | following SMTP commands are sent: |
| 22362 | .display |
| 22363 | .newline |
| 22364 | .em |
| 22365 | HELO <<smtp active host name>> |
| 22366 | .nem |
| 22367 | .newline |
| 22368 | MAIL FROM:@<@> |
| 22369 | RCPT TO:<<the address to be tested>> |
| 22370 | QUIT |
| 22371 | .endd |
| 22372 | \\LHLO\\ is used instead of \\HELO\\ if the transport's \protocol\ option is |
| 22373 | set to `lmtp'. |
| 22374 | |
| 22375 | A recipient callout check is similar. By default, it also uses an empty address |
| 22376 | for the sender. This default is chosen because most hosts do not make use of |
| 22377 | the sender address when verifying a recipient. Using the same address means |
| 22378 | that a single cache entry can be used for each recipient. Some sites, however, |
| 22379 | do make use of the sender address when verifying. These are catered for by the |
| 22380 | \use@_sender\ and \use@_postmaster\ options, described in the next section. |
| 22381 | |
| 22382 | If the response to the \\RCPT\\ command is a 2$it{xx} code, the verification |
| 22383 | succeeds. If it is 5$it{xx}, the verification fails. For any other condition, |
| 22384 | Exim tries the next host, if any. If there is a problem with all the remote |
| 22385 | hosts, the ACL yields `defer', unless the \defer@_ok\ parameter of the |
| 22386 | \callout\ option is given, in which case the condition is forced to succeed. |
| 22387 | |
| 22388 | |
| 22389 | |
| 22390 | |
| 22391 | .section Additional parameters for callouts |
| 22392 | .rset CALLaddparcall "~~chapter.~~section" |
| 22393 | .index callout||additional parameters for |
| 22394 | The \callout\ option can be followed by an equals sign and a number of optional |
| 22395 | parameters, separated by commas. For example: |
| 22396 | .display asis |
| 22397 | verify = recipient/callout=10s,defer_ok |
| 22398 | .endd |
| 22399 | The old syntax, which had \callout@_defer@_ok\ and \check@_postmaster\ as |
| 22400 | separate verify options, is retained for backwards compatibility, but is now |
| 22401 | deprecated. The additional parameters for \callout\ are as follows: |
| 22402 | |
| 22403 | .startitems |
| 22404 | |
| 22405 | .item "<<a time interval>>" |
| 22406 | .index callout||timeout, specifying |
| 22407 | This specifies the timeout that applies for the callout attempt to each host. |
| 22408 | For example: |
| 22409 | .display asis |
| 22410 | verify = sender/callout=5s |
| 22411 | .endd |
| 22412 | The default is 30 seconds. The timeout is used for each response from the |
| 22413 | remote host. |
| 22414 | .em |
| 22415 | It is also used for the intial connection, unless overridden by the \connect\ |
| 22416 | parameter. |
| 22417 | .nem |
| 22418 | |
| 22419 | .em |
| 22420 | .item "connect = <<time interval>>" |
| 22421 | .index callout||connection timeout, specifying |
| 22422 | This parameter makes it possible to set a different (usually |
| 22423 | smaller) timeout for making the SMTP connection. |
| 22424 | For example: |
| 22425 | .display asis |
| 22426 | verify = sender/callout=5s,connect=1s |
| 22427 | .endd |
| 22428 | If not specified, this timeout defaults to the general timeout value. |
| 22429 | .nem |
| 22430 | |
| 22431 | .item "defer@_ok" |
| 22432 | .index callout||defer, action on |
| 22433 | When this parameter is present, failure to contact any host, or any other kind |
| 22434 | of temporary error, is treated as success by the ACL. However, the cache is not |
| 22435 | updated in this circumstance. |
| 22436 | |
| 22437 | .em |
| 22438 | .item "mailfrom = <<email address>>" |
| 22439 | .index callout||sender when verifying header |
| 22440 | When verifying addresses in header lines using the \header@_sender\ |
| 22441 | verification option, Exim behaves by default as if the addresses are envelope |
| 22442 | sender addresses from a message. Callout verification therefore tests to see |
| 22443 | whether a bounce message could be delivered, by using an empty address in the |
| 22444 | \\MAIL\\ command. However, it is arguable that these addresses might never be |
| 22445 | used as envelope senders, and could therefore justifiably reject bounce |
| 22446 | messages (empty senders). The \mailfrom\ callout parameter allows you to |
| 22447 | specify what address to use in the \\MAIL\\ command. For example: |
| 22448 | .display asis |
| 22449 | require verify = header_sender/callout=mailfrom=abcd@x.y.z |
| 22450 | .endd |
| 22451 | This parameter is available only for the \header@_sender\ verification option. |
| 22452 | .nem |
| 22453 | |
| 22454 | .em |
| 22455 | .item "maxwait = <<time interval>>" |
| 22456 | .index callout||overall timeout, specifying |
| 22457 | This parameter sets an overall timeout for performing a callout verification. |
| 22458 | For example: |
| 22459 | .display asis |
| 22460 | verify = sender/callout=5s,maxwait=30s |
| 22461 | .endd |
| 22462 | This timeout defaults to four times the callout timeout for individual SMTP |
| 22463 | commands. The overall timeout applies when there is more than one host that can |
| 22464 | be tried. The timeout is checked before trying the next host. This prevents |
| 22465 | very long delays if there are a large number of hosts and all are timing out |
| 22466 | (for example, when network connections are timing out). |
| 22467 | .nem |
| 22468 | |
| 22469 | .item "no@_cache" |
| 22470 | .index callout||cache, suppressing |
| 22471 | .index caching||callout, suppressing |
| 22472 | When this parameter is given, the callout cache is neither read nor updated. |
| 22473 | |
| 22474 | .item "postmaster" |
| 22475 | .index callout||postmaster, checking |
| 22476 | When this parameter is set, a sucessful callout check is followed by a similar |
| 22477 | check for the local part \*postmaster*\ at the same domain. If this address is |
| 22478 | rejected, the callout fails. The result of the postmaster check is recorded in |
| 22479 | a cache record; if it is a failure, this is used to fail subsequent callouts |
| 22480 | for the domain without a connection being made, until the cache record expires. |
| 22481 | |
| 22482 | .em |
| 22483 | .item "postmaster@_mailfrom = <<email address>>" |
| 22484 | The postmaster check uses an empty sender in the \\MAIL\\ command by default. |
| 22485 | You can use this parameter to do a postmaster check using a different address. |
| 22486 | For example: |
| 22487 | .display asis |
| 22488 | require verify = sender/callout=postmaster_mailfrom=abc@x.y.z |
| 22489 | .endd |
| 22490 | If both \postmaster\ and \postmaster@_mailfrom\ are present, the rightmost one |
| 22491 | overrides. The \postmaster\ parameter is equivalent to this example: |
| 22492 | .display asis |
| 22493 | require verify = sender/callout=postmaster_mailfrom= |
| 22494 | .endd |
| 22495 | \**Warning**\: The caching arrangements for postmaster checking do not take |
| 22496 | account of the sender address. It is assumed that either the empty address or |
| 22497 | a fixed non-empty address will be used. All that Exim remembers is that the |
| 22498 | postmaster check for the domain succeeded or failed. |
| 22499 | .nem |
| 22500 | |
| 22501 | .item "random" |
| 22502 | .index callout||`random' check |
| 22503 | When this parameter is set, before doing the normal callout check, Exim does a |
| 22504 | check for a `random' local part at the same domain. The local part is not |
| 22505 | really random -- it is defined by the expansion of the option |
| 22506 | \callout@_random@_local@_part\, which defaults to |
| 22507 | .display asis |
| 22508 | $primary_host_name-$tod_epoch-testing |
| 22509 | .endd |
| 22510 | The idea here is to try to determine whether the remote host accepts all local |
| 22511 | parts without checking. If it does, there is no point in doing callouts for |
| 22512 | specific local parts. If the `random' check succeeds, the result is saved in |
| 22513 | a cache record, and used to force the current and subsequent callout checks to |
| 22514 | succeed without a connection being made, until the cache record expires. |
| 22515 | |
| 22516 | .item "use@_postmaster" |
| 22517 | .index callout||sender for recipient check |
| 22518 | This parameter applies to recipient callouts only. For example: |
| 22519 | .display asis |
| 22520 | deny !verify = recipient/callout=use_postmaster |
| 22521 | .endd |
| 22522 | It causes a non-empty postmaster address to be used in the \\MAIL\\ command |
| 22523 | when performing the callout. The local part of the address is \"postmaster"\ |
| 22524 | and the domain is the contents of \$qualify@_domain$\. |
| 22525 | |
| 22526 | .item "use@_sender" |
| 22527 | This option applies to recipient callouts only. For example: |
| 22528 | .display asis |
| 22529 | require verify = recipient/callout=use_sender |
| 22530 | .endd |
| 22531 | It causes the message's actual sender address to be used in the \\MAIL\\ |
| 22532 | command when performing the callout, instead of an empty address. There is no |
| 22533 | need to use this option unless you know that the called hosts make use of the |
| 22534 | sender when checking recipients. If used indiscriminately, it reduces the |
| 22535 | usefulness of callout caching. |
| 22536 | |
| 22537 | .enditems |
| 22538 | |
| 22539 | .em |
| 22540 | If you use any of the parameters that set a non-empty sender for the \\MAIL\\ |
| 22541 | command (\mailfrom\, \postmaster@_mailfrom\, \use@_postmaster\, or |
| 22542 | \use@_sender\), you should think about possible loops. Recipient checking is |
| 22543 | usually done between two hosts that are under the same management, and the host |
| 22544 | that receives the callouts is not normally configured to do callouts itself. |
| 22545 | Therefore, it is normally safe to use \use@_postmaster\ or \use@_sender\ in |
| 22546 | these circumstances. |
| 22547 | |
| 22548 | However, if you use a non-empty sender address for a callout to an arbitrary |
| 22549 | host, there is the likelihood that the remote host will itself initiate a |
| 22550 | callout check back to your host. As it is checking what appears to be a message |
| 22551 | sender, it is likely to use an empty address in \\MAIL\\, thus avoiding a |
| 22552 | callout loop. However, to be on the safe side it would be best to set up your |
| 22553 | own ACLs so that they do not do sender verification checks when the recipient |
| 22554 | is the address you use for header sender or postmaster callout checking. |
| 22555 | |
| 22556 | Another issue to think about when using non-empty senders for callouts is |
| 22557 | caching. When you set \mailfrom\ or \use@_sender\, the cache record is keyed by |
| 22558 | the sender/recipient combination; thus, for any given recipient, many more |
| 22559 | actual callouts are performed than when an empty sender or postmaster is used. |
| 22560 | |
| 22561 | .nem |
| 22562 | |
| 22563 | |
| 22564 | .section Callout caching |
| 22565 | .rset SECTcallvercache "~~chapter.~~section" |
| 22566 | .index hints database||callout cache |
| 22567 | .index callout||caching |
| 22568 | .index caching||callout |
| 22569 | Exim caches the results of callouts in order to reduce the amount of resources |
| 22570 | used, unless you specify the \no@_cache\ parameter with the \callout\ option. |
| 22571 | A hints database called `callout' is used for the cache. Two different record |
| 22572 | types are used: one records the result of a callout check for a specific |
| 22573 | address, and the other records information that applies to the entire domain |
| 22574 | (for example, that it accepts the local part \*postmaster*\). |
| 22575 | |
| 22576 | When an original callout fails, a detailed SMTP error message is given about |
| 22577 | the failure. However, for subsequent failures use the cache data, this message |
| 22578 | is not available. |
| 22579 | |
| 22580 | The expiry times for negative and positive address cache records are |
| 22581 | independent, and can be set by the global options \callout@_negative@_expire\ |
| 22582 | (default 2h) and \callout@_positive@_expire\ (default 24h), respectively. |
| 22583 | |
| 22584 | If a host gives a negative response to an SMTP connection, or rejects any |
| 22585 | commands up to and including |
| 22586 | .display asis |
| 22587 | MAIL FROM:<> |
| 22588 | .endd |
| 22589 | (but not including the \\MAIL\\ command with a non-empty address), |
| 22590 | any callout attempt is bound to fail. Exim remembers such failures in a |
| 22591 | domain cache record, which it uses to fail callouts for the domain without |
| 22592 | making new connections, until the domain record times out. There are two |
| 22593 | separate expiry times for domain cache records: |
| 22594 | \callout@_domain@_negative@_expire\ (default 3h) and |
| 22595 | \callout__domain__positive@_expire\ (default 7d). |
| 22596 | |
| 22597 | Domain records expire when the negative expiry time is reached if callouts |
| 22598 | cannot be made for the domain, or if the postmaster check failed. |
| 22599 | Otherwise, they expire when the positive expiry time is reached. This |
| 22600 | ensures that, for example, a host that stops accepting `random' local parts |
| 22601 | will eventually be noticed. |
| 22602 | |
| 22603 | The callout caching mechanism is based on the domain of the address that is |
| 22604 | being tested. If the domain routes to several hosts, it is assumed that their |
| 22605 | behaviour will be the same. |
| 22606 | |
| 22607 | |
| 22608 | .section Sender address verification reporting |
| 22609 | .rset SECTsenaddver "~~chapter.~~section" |
| 22610 | .index verifying||suppressing error details |
| 22611 | When sender verification fails in an ACL, the details of the failure are |
| 22612 | given as additional output lines before the 550 response to the relevant |
| 22613 | SMTP command (\\RCPT\\ or \\DATA\\). For example, if sender callout is in use, |
| 22614 | you might see: |
| 22615 | .display asis |
| 22616 | MAIL FROM:<xyz@abc.example> |
| 22617 | 250 OK |
| 22618 | RCPT TO:<pqr@def.example> |
| 22619 | 550-Verification failed for <xyz@abc.example> |
| 22620 | 550-Called: 192.168.34.43 |
| 22621 | 550-Sent: RCPT TO:<xyz@abc.example> |
| 22622 | 550-Response: 550 Unknown local part xyz in <xyz@abc.example> |
| 22623 | 550 Sender verification failed |
| 22624 | .endd |
| 22625 | If more than one \\RCPT\\ command fails in the same way, the details are given |
| 22626 | only for the first of them. However, some administrators do not want to send |
| 22627 | out this much information. You can suppress the details by adding |
| 22628 | `/no@_details' to the ACL statement that requests sender verification. For |
| 22629 | example: |
| 22630 | .display asis |
| 22631 | verify = sender/no_details |
| 22632 | .endd |
| 22633 | |
| 22634 | |
| 22635 | .section Redirection while verifying |
| 22636 | .index verifying||redirection while |
| 22637 | .index address redirection||while verifying |
| 22638 | A dilemma arises when a local address is redirected by aliasing or forwarding |
| 22639 | during verification: should the generated addresses themselves be verified, |
| 22640 | or should the successful expansion of the original address be enough to verify |
| 22641 | it? Exim takes the following pragmatic approach: |
| 22642 | .numberpars $. |
| 22643 | When an incoming address is redirected to just one child address, verification |
| 22644 | continues with the child address, and if that fails to verify, the original |
| 22645 | verification also fails. |
| 22646 | .nextp |
| 22647 | When an incoming address is redirected to more than one child address, |
| 22648 | verification does not continue. A success result is returned. |
| 22649 | .endp |
| 22650 | This seems the most reasonable behaviour for the common use of aliasing as a |
| 22651 | way of redirecting different local parts to the same mailbox. It means, for |
| 22652 | example, that a pair of alias entries of the form |
| 22653 | .display asis |
| 22654 | A.Wol: aw123 |
| 22655 | aw123: :fail: Gone away, no forwarding address |
| 22656 | .endd |
| 22657 | work as expected, with both local parts causing verification failure. When a |
| 22658 | redirection generates more than one address, the behaviour is more like a |
| 22659 | mailing list, where the existence of the alias itself is sufficient for |
| 22660 | verification to succeed. |
| 22661 | |
| 22662 | |
| 22663 | .section Using an ACL to control relaying |
| 22664 | .rset SECTrelaycontrol "~~chapter.~~section" |
| 22665 | .index ~~ACL||relay control |
| 22666 | .index relaying||control by ACL |
| 22667 | .index policy control||relay control |
| 22668 | An MTA is said to \*relay*\ a message if it receives it from some host and |
| 22669 | delivers it directly to another host as a result of a remote address contained |
| 22670 | within it. Redirecting a local address via an alias or forward file and then |
| 22671 | passing the message on to another host is not relaying, |
| 22672 | .index `percent hack' |
| 22673 | but a redirection as a result of the `percent hack' is. |
| 22674 | |
| 22675 | Two kinds of relaying exist, which are termed `incoming' and `outgoing'. A host |
| 22676 | which is acting as a gateway or an MX backup is concerned with incoming |
| 22677 | relaying from arbitrary hosts to a specific set of domains. On the other hand, |
| 22678 | a host which is acting as a smart host for a number of clients is concerned |
| 22679 | with outgoing relaying from those clients to the Internet at large. Often the |
| 22680 | same host is fulfilling both functions, as illustrated in the diagram below, |
| 22681 | but in principle these two kinds of relaying are entirely independent. What is |
| 22682 | not wanted is the transmission of mail from arbitrary remote hosts through your |
| 22683 | system to arbitrary domains. |
| 22684 | .if ~~sys.fancy |
| 22685 | .figure "Controlled relaying" rm |
| 22686 | .indent 0 |
| 22687 | .call aspic -sgcal -nv |
| 22688 | centre ~~sys.linelength; |
| 22689 | magnify 0.8; |
| 22690 | boundingbox 30; |
| 22691 | textdepth 16; |
| 22692 | boxwidth 120; |
| 22693 | boxdepth 44; |
| 22694 | A: box "Arbitrary" "remote hosts"; |
| 22695 | C: ibox; |
| 22696 | D: box "Arbitrary" "domains"; |
| 22697 | iline down 50 from bottom of C; |
| 22698 | H: box width 180 "Local host"; |
| 22699 | iline down 50; |
| 22700 | E: ibox; |
| 22701 | SH: box "Specific" "hosts"; |
| 22702 | SD: box join right to E "Specific" "domains"; |
| 22703 | arcarrow clockwise from top of SH to bottom of D plus (-10,-4) |
| 22704 | via right of H plus (-20,0); |
| 22705 | arcarrow clockwise from bottom of A to top of SD plus (10,4) |
| 22706 | via left of H plus (20,0); |
| 22707 | |
| 22708 | ibox join left to right of H "$it{Outgoing}"; |
| 22709 | goto H; |
| 22710 | ibox join right to left of H "$it{Incoming}"; |
| 22711 | |
| 22712 | L: line dashed from right of A to top of H plus (-15,0); |
| 22713 | arc dashed to top of H plus (15,0); |
| 22714 | arrow dashed to left of D plus (-2,0); |
| 22715 | |
| 22716 | arrow dashed back up 72 right 32 from middle of L plus (8,0); |
| 22717 | text at end plus (0, 4) "$it{Not wanted}"; |
| 22718 | .endcall |
| 22719 | .endfigure |
| 22720 | .elif !~~html |
| 22721 | .display asis |
| 22722 | -------------- ----------- |
| 22723 | | Arbitrary | |Arbitrary| |
| 22724 | |remote hosts| | domains | |
| 22725 | -------------- ----------- |
| 22726 | I v ^ O |
| 22727 | n v ^ u |
| 22728 | c ---v----------------^--- t |
| 22729 | o | v Local ^ | g |
| 22730 | m | v host ^ | o |
| 22731 | i ---v----------------^--- i |
| 22732 | n v ^ n |
| 22733 | g v ^ g |
| 22734 | Specific Specific |
| 22735 | domains hosts |
| 22736 | .endd |
| 22737 | .else |
| 22738 | [(IMG SRC="relaying.gif" alt="Controlled relaying")][(br)] |
| 22739 | .fi |
| 22740 | |
| 22741 | You can implement relay control by means of suitable statements in the ACL that |
| 22742 | runs for each \\RCPT\\ command. For convenience, it is often easiest to use |
| 22743 | Exim's named list facility to define the domains and hosts involved. For |
| 22744 | example, suppose you want to do the following: |
| 22745 | .numberpars $. |
| 22746 | Deliver a number of domains to mailboxes on the local host (or process them |
| 22747 | locally in some other way). Let's say these are \*my.dom1.example*\ and |
| 22748 | \*my.dom2.example*\. |
| 22749 | .nextp |
| 22750 | Relay mail for a number of other domains for which you are the secondary MX. |
| 22751 | These might be \*friend1.example*\ and \*friend2.example*\. |
| 22752 | .nextp |
| 22753 | Relay mail from the hosts on your local LAN, to whatever domains are involved. |
| 22754 | Suppose your LAN is 192.168.45.0/24. |
| 22755 | .endp |
| 22756 | In the main part of the configuration, you put the following definitions: |
| 22757 | .display asis |
| 22758 | domainlist local_domains = my.dom1.example : my.dom2.example |
| 22759 | domainlist relay_domains = friend1.example : friend2.example |
| 22760 | hostlist relay_hosts = 192.168.45.0/24 |
| 22761 | .endd |
| 22762 | Now you can use these definitions in the ACL that is run for every \\RCPT\\ |
| 22763 | command: |
| 22764 | .display asis |
| 22765 | acl_check_rcpt: |
| 22766 | accept domains = +local_domains : +relay_domains |
| 22767 | accept hosts = +relay_hosts |
| 22768 | .endd |
| 22769 | The first statement accepts any \\RCPT\\ command that contains an address in |
| 22770 | the local or relay domains. For any other domain, control passes to the second |
| 22771 | statement, which accepts the command only if it comes from one of the relay |
| 22772 | hosts. In practice, you will probably want to make your ACL more sophisticated |
| 22773 | than this, for example, by including sender and recipient verification. The |
| 22774 | default configuration includes a more comprehensive example, which is described |
| 22775 | in chapter ~~CHAPdefconfil. |
| 22776 | |
| 22777 | |
| 22778 | .section Checking a relay configuration |
| 22779 | .rset SECTcheralcon "~~chapter.~~section" |
| 22780 | .index relaying||checking control of |
| 22781 | You can check the relay characteristics of your configuration in the same way |
| 22782 | that you can test any ACL behaviour for an incoming SMTP connection, by using |
| 22783 | the \-bh-\ option to run a fake SMTP session with which you interact. |
| 22784 | |
| 22785 | For specifically testing for unwanted relaying, the host |
| 22786 | \*relay-test.mail-abuse.org*\ provides a useful service. If you telnet to this |
| 22787 | host from the host on which Exim is running, using the normal telnet port, you |
| 22788 | will see a normal telnet connection message and then quite a long delay. Be |
| 22789 | patient. The remote host is making an SMTP connection back to your host, and |
| 22790 | trying a number of common probes to test for open relay vulnerability. The |
| 22791 | results of the tests will eventually appear on your terminal. |
| 22792 | |
| 22793 | |
| 22794 | |
| 22795 | |
| 22796 | . |
| 22797 | . |
| 22798 | . |
| 22799 | . |
| 22800 | . ============================================================================ |
| 22801 | .chapter Content scanning using the `exiscan' features |
| 22802 | .set runningfoot "content scanning" |
| 22803 | .rset CHAPexiscan "~~chapter" |
| 22804 | .index content scanning |
| 22805 | .em |
| 22806 | The content-scanning extension of Exim, also known as `exiscan', was originally |
| 22807 | implemented as a patch by Tom Kistner. The code was integrated into the main |
| 22808 | source for Exim release 4.50, and Tom continues to maintain it. Most of the |
| 22809 | wording of this chapter is taken from Tom's exiscan specification. |
| 22810 | |
| 22811 | If you want to include the content-scanning features when you compile Exim, you |
| 22812 | need to arrange for \\WITH@_CONTENT@_SCAN\\ to be defined in your |
| 22813 | \(Local/Makefile)\. When you do that, the Exim binary is built with: |
| 22814 | .numberpars $. |
| 22815 | An additional ACL (\acl@_smtp@_mime\) that is run for all MIME parts. |
| 22816 | .nextp |
| 22817 | Additional ACL conditions and modifiers: \decode\, \malware\, \mime@_regex\, |
| 22818 | \regex\, and \spam\. These can be used in the ACL that is run at the end of |
| 22819 | message reception (the \acl@_smtp@_data\ ACL). |
| 22820 | .nextp |
| 22821 | Additional expansion variables that are set in the new ACL and by the new |
| 22822 | conditions. |
| 22823 | .nextp |
| 22824 | Two new main configuration options: \av@_scanner\ and \spamd@_address\. |
| 22825 | .endp |
| 22826 | There is another content-scanning configuration option for \(Local/Makefile)\, |
| 22827 | called \\WITH@_OLD@_DEMIME\\. If this is set, the old, deprecated \demime\ ACL |
| 22828 | condition is compiled, in addition to all the other content-scanning features. |
| 22829 | |
| 22830 | Content-scanning is continually evolving, and new features are still being |
| 22831 | added. While such features are still unstable and liable to incompatible |
| 22832 | changes, they are made available in Exim by setting options whose names begin |
| 22833 | \\EXPERIMENTAL@_\\ in \(Local/Makefile)\. Such features are not documented in |
| 22834 | this manual. You can find out about them by reading the file called |
| 22835 | \(doc/experimental.txt)\. |
| 22836 | |
| 22837 | All the content-scanning facilites work on a MBOX copy of the message that is |
| 22838 | temporarily created in a file called: |
| 22839 | .display |
| 22840 | <<spool@_directory>>/scan/<<message@_id>>/<<message@_id>>.eml |
| 22841 | .endd |
| 22842 | The \(.eml)\ extension is a friendly hint to virus scanners that they can |
| 22843 | expect an MBOX-like structure inside that file. The file is created when the |
| 22844 | first content scanning facility is called. Subsequent calls to content |
| 22845 | scanning conditions open the same file again. The directory is recursively |
| 22846 | removed when the \acl@_smtp@_data\ ACL has finished running. When the MIME |
| 22847 | ACL decodes files, they are put into that same directory by default. |
| 22848 | |
| 22849 | |
| 22850 | .section Scanning for viruses |
| 22851 | .rset SECTscanvirus "~~chapter.~~section" |
| 22852 | .index virus scanning |
| 22853 | .index content scanning||for viruses |
| 22854 | .index content scanning||the \malware\ condition |
| 22855 | The \malware\ ACL condition lets you connect virus scanner software to Exim. It |
| 22856 | supports a `generic' interface to scanners called via the shell, and |
| 22857 | specialized interfaces for `daemon' type virus scanners, which are resident in |
| 22858 | memory and thus are much faster. |
| 22859 | |
| 22860 | .index \av@_scanner\ |
| 22861 | You can set the \av@_scanner\ option in first part of the Exim configuration |
| 22862 | file to specify which scanner to use, together with any additional options that |
| 22863 | are needed. The basic syntax is as follows: |
| 22864 | .display |
| 22865 | av@_scanner = <<scanner-type>>:<<option1>>:<<option2>>:[...] |
| 22866 | .endd |
| 22867 | If you do not set \av@_scanner\, it defaults to |
| 22868 | .display asis |
| 22869 | av_scanner = sophie:/var/run/sophie |
| 22870 | .endd |
| 22871 | If the value of \av@_scanner\ starts with dollar character, it is expanded |
| 22872 | before use. |
| 22873 | |
| 22874 | The following scanner types are supported in this release: |
| 22875 | .numberpars $. |
| 22876 | .index virus scanners||Kaspersky |
| 22877 | \aveserver\: This is the scanner daemon of Kaspersky Version 5. You can get a |
| 22878 | trial version at \?http://www.kaspersky.com?\. This scanner type takes one |
| 22879 | option, which is the path to the daemon's UNIX socket. The default is shown in |
| 22880 | this example: |
| 22881 | .display asis |
| 22882 | av_scanner = aveserver:/var/run/aveserver |
| 22883 | .endd |
| 22884 | |
| 22885 | .nextp |
| 22886 | .index virus scanners||clamd |
| 22887 | \clamd\: This daemon-type scanner is GPL and free. You can get it at |
| 22888 | \?http://www.clamav.net/?\. Clamd does not seem to unpack MIME containers, |
| 22889 | so it is recommended to unpack MIME attachments in the MIME ACL. It takes one option: |
| 22890 | either the path and name of a UNIX socket file, or a hostname or IP number, and |
| 22891 | a port, separated by space, as in the second of these examples: |
| 22892 | .display asis |
| 22893 | av_scanner = clamd:/opt/clamd/socket |
| 22894 | av_scanner = clamd:192.168.2.100 1234 |
| 22895 | .endd |
| 22896 | If the option is unset, the default is \(/tmp/clamd)\. |
| 22897 | |
| 22898 | .nextp |
| 22899 | .index virus scanners||command line interface |
| 22900 | \cmdline\: This is the keyword for the generic command line scanner interface. |
| 22901 | It can be used to attach virus scanners that are invoked from the shell. This |
| 22902 | scanner type takes 3 mantadory options: |
| 22903 | .numberpars |
| 22904 | The full path and name of the scanner binary, with all command line options, |
| 22905 | and a placeholder (%s) for the directory to scan. |
| 22906 | .nextp |
| 22907 | A regular expression to match against the STDOUT and STDERR output of the virus |
| 22908 | scanner. If the expression matches, a virus was found. You must make absolutely |
| 22909 | sure that this expression matches on `virus found'. This is called the |
| 22910 | `trigger' expression. |
| 22911 | .nextp |
| 22912 | Another regular expression, containing exactly one pair of parentheses, to match the |
| 22913 | name of the virus found in the scanners output. This is called the `name' |
| 22914 | expression. |
| 22915 | .endp |
| 22916 | For example, Sophos Sweep reports a virus on a line like this: |
| 22917 | .display asis |
| 22918 | Virus 'W32/Magistr-B' found in file ./those.bat |
| 22919 | .endd |
| 22920 | For the trigger expression, we can just match the word `found'. For the name |
| 22921 | expression, we want to extract the W32/Magistr-B string, so we can match for |
| 22922 | the single quotes left and right of it. Altogether, this makes the |
| 22923 | configuration setting: |
| 22924 | .display asis |
| 22925 | av_scanner = cmdline:\ |
| 22926 | /path/to/sweep -all -rec -archive %s:\ |
| 22927 | found:'(.+)' |
| 22928 | .endd |
| 22929 | |
| 22930 | .nextp |
| 22931 | .index virus scanners||DrWeb |
| 22932 | \drweb\: The DrWeb daemon scanner (\?http://www.sald.com/?\) interface |
| 22933 | takes one argument, either a full path to a UNIX socket, or an IP address and |
| 22934 | port separated by whitespace, as in these examples: |
| 22935 | .display asis |
| 22936 | av_scanner = drweb:/var/run/drwebd.sock |
| 22937 | av_scanner = drweb:192.168.2.20 31337 |
| 22938 | .endd |
| 22939 | If you omit the argument, the default path \(/usr/local/drweb/run/drwebd.sock)\ |
| 22940 | is used. Thanks to Alex Miller for contributing the code for this scanner. |
| 22941 | |
| 22942 | .nextp |
| 22943 | .index virus scanners||F-Secure |
| 22944 | \fsecure\: The F-Secure daemon scanner (\?http://www.f-secure.com?\) takes one |
| 22945 | argument which is the path to a UNIX socket. For example: |
| 22946 | .display asis |
| 22947 | av_scanner = fsecure:/path/to/.fsav |
| 22948 | .endd |
| 22949 | If no argument is given, the default is \(/var/run/.fsav)\. Thanks to Johan |
| 22950 | Thelmen for contributing the code for this scanner. |
| 22951 | |
| 22952 | .nextp |
| 22953 | .index virus scanners||Kaspersky |
| 22954 | \kavdaemon\: This is the scanner daemon of Kaspersky Version 4. This version of |
| 22955 | the Kaspersky scanner is outdated. Please upgrade (see \aveserver\ above). This |
| 22956 | scanner type takes one option, which is the path to the daemon's UNIX socket. |
| 22957 | For example: |
| 22958 | .display asis |
| 22959 | av_scanner = kavdaemon:/opt/AVP/AvpCtl |
| 22960 | .endd |
| 22961 | The default path is \(/var/run/AvpCtl)\. |
| 22962 | |
| 22963 | .nextp |
| 22964 | .index virus scanners||mksd |
| 22965 | \mksd\: This is a daemon type scanner that is aimed mainly at Polish users, |
| 22966 | though some parts of documentation are now available in English. You can get it |
| 22967 | at \?http://linux.mks.com.pl/?\. The only option for this scanner type is the |
| 22968 | maximum number of processes used simultaneously to scan the attachments, |
| 22969 | provided that the demime facility is employed and also provided that mksd has |
| 22970 | been run with at least the same number of child processes. For example: |
| 22971 | .display asis |
| 22972 | av_scanner = mksd:2 |
| 22973 | .endd |
| 22974 | You can safely omit this option (the default value is 1). |
| 22975 | |
| 22976 | .nextp |
| 22977 | .index virus scanners||Sophos and Sophie |
| 22978 | \sophie\: Sophie is a daemon that uses Sophos' \libsavi\ library to scan for |
| 22979 | viruses. You can get Sophie at \?http://www.vanja.com/tools/sophie/?\. The only |
| 22980 | option for this scanner type is the path to the UNIX socket that Sophie uses |
| 22981 | for client communication. For example: |
| 22982 | .display asis |
| 22983 | av_scanner = sophie:/tmp/sophie |
| 22984 | .endd |
| 22985 | The default path is \(/var/run/sophie)\, so if you are using this, you can omit |
| 22986 | the option. |
| 22987 | .endp |
| 22988 | |
| 22989 | When \av@_scanner\ is correctly set, you can use the \malware\ condition in the |
| 22990 | DATA ACL. |
| 22991 | |
| 22992 | The \malware\ condition caches its results, so when you use it multiple times |
| 22993 | for the same message, the actual scanning process is only carried out once. |
| 22994 | |
| 22995 | \av@_scanner\ is expanded each time \malware\ is called. This makes |
| 22996 | it possible to use different scanners. See further below for an example. |
| 22997 | However, using expandable items in \av@_scanner\ disables the result caching |
| 22998 | of the \malware\ condition. |
| 22999 | |
| 23000 | The condition takes a right-hand argument that is expanded before |
| 23001 | use. It can then be one of |
| 23002 | .numberpars $. |
| 23003 | `true', `*', or `1', in which case the message is scanned for viruses. The |
| 23004 | condition succeeds if a virus was found, and fail otherwise. This is the |
| 23005 | recommended usage. |
| 23006 | .nextp |
| 23007 | `false' or `0', in which case no scanning is done and the condition fails |
| 23008 | immediately. |
| 23009 | .nextp |
| 23010 | A regular expression, in which case the message is scanned for viruses. The |
| 23011 | condition succeeds if a virus is found and its name matches the regular |
| 23012 | expression. This allows you to take special actions on certain types of virus. |
| 23013 | .endp |
| 23014 | You can append \"/defer@_ok"\ to the \malware\ condition to accept messages even |
| 23015 | if there is a problem with the virus scanner. |
| 23016 | |
| 23017 | .index \$malware@_name$\ |
| 23018 | When a virus is found, the condition sets up an expansion variable called |
| 23019 | \$malware@_name$\ that contains the name of the virus. You can use it in a |
| 23020 | \message\ modifier that specifies the error returned to the sender, and/or in |
| 23021 | logging data. |
| 23022 | |
| 23023 | If your virus scanner cannot unpack MIME and TNEF containers itself, you should |
| 23024 | use the \demime\ condition (see section ~~SECTdemimecond) before the \malware\ |
| 23025 | condition. |
| 23026 | |
| 23027 | Here is a very simple scanning example: |
| 23028 | .display asis |
| 23029 | deny message = This message contains malware ($malware_name) |
| 23030 | demime = * |
| 23031 | malware = * |
| 23032 | .endd |
| 23033 | The next example accepts messages when there is a problem with the scanner: |
| 23034 | .display asis |
| 23035 | deny message = This message contains malware ($malware_name) |
| 23036 | demime = * |
| 23037 | malware = */defer_ok |
| 23038 | .endd |
| 23039 | The next example shows how to use an ACL variable to scan with both sophie and |
| 23040 | aveserver. It assumes you have set: |
| 23041 | .display asis |
| 23042 | av_scanner = $acl_m0 |
| 23043 | .endd |
| 23044 | in the main Exim configuration. |
| 23045 | .display asis |
| 23046 | deny message = This message contains malware ($malware_name) |
| 23047 | set acl_m0 = sophie |
| 23048 | malware = * |
| 23049 | |
| 23050 | deny message = This message contains malware ($malware_name) |
| 23051 | set acl_m0 = aveserver |
| 23052 | malware = * |
| 23053 | .endd |
| 23054 | |
| 23055 | |
| 23056 | .section Scanning with SpamAssassin |
| 23057 | .rset SECTscanspamass "~~chapter.~~section" |
| 23058 | .index content scanning||for spam |
| 23059 | .index spam scanning |
| 23060 | .index SpamAssassin, scanning with |
| 23061 | The \spam\ ACL condition calls SpamAssassin's \spamd\ daemon to get a spam |
| 23062 | score and a report for the message. You can get SpamAssassin at |
| 23063 | \?http://www.spamassassin.org?\, or, if you have a working Perl installation, |
| 23064 | you can use CPAN by running: |
| 23065 | .display asis |
| 23066 | perl -MCPAN -e 'install Mail::SpamAssassin' |
| 23067 | .endd |
| 23068 | SpamAssassin has its own set of configuration files. Please review its |
| 23069 | documentation to see how you can tweak it. The default installation should work |
| 23070 | nicely, however. |
| 23071 | |
| 23072 | .index \spamd@_address\ |
| 23073 | After having installed and configured SpamAssassin, start the \spamd\ daemon. |
| 23074 | By default, it listens on 127.0.0.1, TCP port 783. If you use another host or |
| 23075 | port for \spamd\, you must set the \spamd@_address\ option in the global part |
| 23076 | of the Exim configuration as follows (example): |
| 23077 | .display asis |
| 23078 | spamd_address = 192.168.99.45 387 |
| 23079 | .endd |
| 23080 | You do not need to set this option if you use the default. As of version 2.60, |
| 23081 | \spamd\ also supports communication over UNIX sockets. If you want to use |
| 23082 | these, supply \spamd@_address\ with an absolute file name instead of a |
| 23083 | address/port pair: |
| 23084 | .display asis |
| 23085 | spamd_address = /var/run/spamd_socket |
| 23086 | .endd |
| 23087 | |
| 23088 | You can have multiple \spamd\ servers to improve scalability. These can reside |
| 23089 | on other hardware reachable over the network. To specify multiple \spamd\ |
| 23090 | servers, put multiple address/port pairs in the \spamd@_address\ option, |
| 23091 | separated with colons: |
| 23092 | .display asis |
| 23093 | spamd_address = 192.168.2.10 783 : \ |
| 23094 | 192.168.2.11 783 : \ |
| 23095 | 192.168.2.12 783 |
| 23096 | .endd |
| 23097 | Up to 32 \spamd\ servers are supported. The servers are |
| 23098 | queried in a random fashion. When a server fails to respond |
| 23099 | to the connection attempt, all other servers are tried |
| 23100 | until one succeeds. If no server responds, the \spam\ |
| 23101 | condition defers. |
| 23102 | |
| 23103 | \**Warning**\: It is not possible to use the UNIX socket connection method with |
| 23104 | multiple \spamd\ servers. |
| 23105 | |
| 23106 | Here is a simple example of the use of the \spam\ condition in a DATA ACL: |
| 23107 | .display asis |
| 23108 | deny message = This message was classified as SPAM |
| 23109 | spam = joe |
| 23110 | .endd |
| 23111 | The right-hand side of the \spam\ condition specifies the username that |
| 23112 | SpamAssassin should scan for. If you do not want to scan for a particular user, |
| 23113 | but rather use the SpamAssassin system-wide default profile, you can scan for |
| 23114 | an unknown user, or simply use `nobody'. However, you must put something on the |
| 23115 | right-hand side. |
| 23116 | |
| 23117 | The username allows you to use per-domain or per-user antispam profiles. The |
| 23118 | right-hand side is expanded before being used, so you can put lookups or |
| 23119 | conditions there. When the right-hand side evaluates to `0' or `false', no |
| 23120 | scanning is done and the condition fails immediately. |
| 23121 | |
| 23122 | The \spam\ condition returns true if the threshold specified in the user's |
| 23123 | SpamAssassin profile has been matched or exceeded. If you want to use the |
| 23124 | \spam\ condition for its side effects (see the variables below), you can make |
| 23125 | it always return `true' by appending \":true"\ to the username. |
| 23126 | |
| 23127 | .index spam scanning||returned variables |
| 23128 | When the \spam\ condition is run, it sets up the following expansion |
| 23129 | variables: |
| 23130 | |
| 23131 | .push |
| 23132 | .indent 2em |
| 23133 | |
| 23134 | .tempindent 0 |
| 23135 | \$spam@_score$\: The spam score of the message, for example `3.4' or `30.5'. |
| 23136 | This is useful for inclusion in log or reject messages. |
| 23137 | |
| 23138 | .tempindent 0 |
| 23139 | \$spam@_score@_int$\: The spam score of the message, multiplied by ten, as an |
| 23140 | integer value. For example `34' or `305'. This is useful for numeric |
| 23141 | comparisons in conditions. This variable is special; it is saved with the |
| 23142 | message, and written to Exim's spool file. This means that it can be used |
| 23143 | during the whole life of the message on your Exim system, in particualr, in |
| 23144 | routers or transports during the later delivery phase. |
| 23145 | |
| 23146 | .tempindent 0 |
| 23147 | \$spam@_bar$\: A string consisting of a number of `+' or `@-' characters, |
| 23148 | representing the integer part of the spam score value. A spam score of 4.4 |
| 23149 | would have a \$spam@_bar$\ value of `++++'. This is useful for inclusion in |
| 23150 | warning headers, since MUAs can match on such strings. |
| 23151 | |
| 23152 | .tempindent 0 |
| 23153 | \$spam@_report$\: A multiline text table, containing the full SpamAssassin |
| 23154 | report for the message. Useful for inclusion in headers or reject messages. |
| 23155 | |
| 23156 | .pop |
| 23157 | |
| 23158 | The \spam\ condition caches its results. If you call it again with the same user |
| 23159 | name, it does not scan again, but rather returns the same values as before. |
| 23160 | |
| 23161 | The \spam\ condition returns DEFER if there is any error while running the |
| 23162 | message through SpamAssassin. If you want to treat DEFER as FAIL (to pass on to |
| 23163 | the next ACL statement block), append \"/defer@_ok"\ to the right-hand side of |
| 23164 | the spam condition, like this: |
| 23165 | .display asis |
| 23166 | deny message = This message was classified as SPAM |
| 23167 | spam = joe/defer_ok |
| 23168 | .endd |
| 23169 | This causes messages to be accepted even if there is a |
| 23170 | problem with \spamd\. |
| 23171 | |
| 23172 | Here is a longer, commented example of the use of the \spam\ |
| 23173 | condition: |
| 23174 | .display asis |
| 23175 | # put headers in all messages (no matter if spam or not) |
| 23176 | warn message = X-Spam-Score: $spam_score ($spam_bar) |
| 23177 | spam = nobody:true |
| 23178 | warn message = X-Spam-Report: $spam_report |
| 23179 | spam = nobody:true |
| 23180 | |
| 23181 | # add second subject line with *SPAM* marker when message |
| 23182 | # is over threshold |
| 23183 | warn message = Subject: *SPAM* $h_Subject: |
| 23184 | spam = nobody |
| 23185 | |
| 23186 | # reject spam at high scores (> 12) |
| 23187 | deny message = This message scored $spam_score spam points. |
| 23188 | spam = nobody:true |
| 23189 | condition = ${if >{$spam_score_int}{120}{1}{0}} |
| 23190 | .endd |
| 23191 | |
| 23192 | |
| 23193 | |
| 23194 | .section Scanning MIME parts |
| 23195 | .rset SECTscanmimepart "~~chapter.~~section" |
| 23196 | .index content scanning||MIME parts |
| 23197 | .index MIME content scanning |
| 23198 | .index \acl@_smtp@_mime\ |
| 23199 | The \acl@_smtp@_mime\ global option defines an ACL that is called once for each |
| 23200 | MIME part of a message, including multipart types, in the sequence of their |
| 23201 | position in the message. |
| 23202 | |
| 23203 | This ACL is called (possibly many times) just before the \acl@_smtp@_data\ ACL, |
| 23204 | but only if the message has a ::MIME-Version:: header. When a call to the MIME |
| 23205 | ACL does not yield `accept', ACL processing is aborted and the appropriate |
| 23206 | result code is sent to the remote client. The \acl@_smtp@_data\ ACL is not |
| 23207 | called in this circumstance. |
| 23208 | |
| 23209 | At the start of the MIME ACL, a number of variables are set from the header |
| 23210 | information for the relevant MIME part. These are described below. The contents |
| 23211 | of the MIME part are not by default decoded into a disk file except for MIME |
| 23212 | parts whose content-type is `message/rfc822'. If you want to decode a MIME part |
| 23213 | into a disk file, you can use the \decode\ modifier. The general syntax is: |
| 23214 | .display |
| 23215 | decode = [/<<path>>/]<<filename>> |
| 23216 | .endd |
| 23217 | The right hand side is expanded before use. After expansion, |
| 23218 | the value can be: |
| 23219 | .numberpars |
| 23220 | `0' or `false', in which case no decoding is done. |
| 23221 | .nextp |
| 23222 | The string `default'. In that case, the file is put in the temporary `default' |
| 23223 | directory \(<<spool@_directory>>/scan/<<message@_id>>/)\ with a sequential file |
| 23224 | name consisting of the message id and a sequence number. The full path and name |
| 23225 | is available in \$mime@_decoded@_filename$\ after decoding. |
| 23226 | .nextp |
| 23227 | A full path name starting with a slash. If the full name is an existing |
| 23228 | directory, it is used as a replacement for the default directory. The filename |
| 23229 | is then sequentially assigned. If the path does not exist, it is used as |
| 23230 | the full path and file name. |
| 23231 | .nextp |
| 23232 | If the string does not start with a slash, it is used as the |
| 23233 | filename, and the default path is then used. |
| 23234 | .endp |
| 23235 | You can easily decode a file with its original, proposed |
| 23236 | filename using |
| 23237 | .display asis |
| 23238 | decode = $mime_filename |
| 23239 | .endd |
| 23240 | However, you should keep in mind that \$mime@_filename$\ might contain |
| 23241 | anything. If you place files outside of the default path, they are not |
| 23242 | automatically unlinked. |
| 23243 | |
| 23244 | For RFC822 attachments (these are messages attached to messages, with a |
| 23245 | content-type of `message/rfc822'), the ACL is called again in the same manner |
| 23246 | as for the primary message, only that the \$mime@_is@_rfc822$\ expansion |
| 23247 | variable is set (see below). Attached messages are always decoded to disk |
| 23248 | before being checked, and the files are unlinked once the check is done. |
| 23249 | |
| 23250 | The MIME ACL supports the \regex\ and \mime@_regex\ conditions. These can be |
| 23251 | used to match regular expressions against raw and decoded MIME parts, |
| 23252 | respectively. They are described in section ~~SECTscanregex. |
| 23253 | |
| 23254 | .index MIME content scanning||returned variables |
| 23255 | The following list describes all expansion variables that are |
| 23256 | available in the MIME ACL: |
| 23257 | |
| 23258 | .push |
| 23259 | .indent 2em |
| 23260 | |
| 23261 | .tempindent 0 |
| 23262 | \$mime@_boundary$\: |
| 23263 | If the current part is a multipart (see \$mime@_is@_multipart$\) below, it |
| 23264 | should have a boundary string, which is stored in this variable. If the current |
| 23265 | part has no boundary parameter in the ::Content-Type:: header, this variable |
| 23266 | contains the empty string. |
| 23267 | |
| 23268 | .tempindent 0 |
| 23269 | \$mime@_charset$\: |
| 23270 | This variable contains the character set identifier, if one was found in the |
| 23271 | ::Content-Type:: header. Examples for charset identifiers are: |
| 23272 | .display asis |
| 23273 | us-ascii |
| 23274 | gb2312 (Chinese) |
| 23275 | iso-8859-1 |
| 23276 | .endd |
| 23277 | Please note that this value is not normalized, so you should do matches |
| 23278 | case-insensitively. |
| 23279 | |
| 23280 | .tempindent 0 |
| 23281 | \$mime@_content@_description$\: |
| 23282 | This variable contains the normalized content of the ::Content-Description:: |
| 23283 | header. It can contain a human-readable description of the parts content. Some |
| 23284 | implementations repeat the filename for attachments here, but they are |
| 23285 | usually only used for display purposes. |
| 23286 | |
| 23287 | .tempindent 0 |
| 23288 | \$mime@_content@_disposition$\: |
| 23289 | This variable contains the normalized content of the ::Content-Disposition:: |
| 23290 | header. You can expect strings like `attachment' or `inline' here. |
| 23291 | |
| 23292 | .tempindent 0 |
| 23293 | \$mime@_content@_id$\: |
| 23294 | This variable contains the normalized content of the ::Content-ID:: header. |
| 23295 | This is a unique ID that can be used to reference a part from another part. |
| 23296 | |
| 23297 | .tempindent 0 |
| 23298 | \$mime@_content@_size$\: |
| 23299 | This variable is set only after the \decode\ modifier (see above) has been |
| 23300 | successfully run. It contains the size of the decoded part in kilobytes. The |
| 23301 | size is always rounded up to full kilobytes, so only a completely empty part |
| 23302 | has a \$mime@_content@_size$\ of zero. |
| 23303 | |
| 23304 | .tempindent 0 |
| 23305 | \$mime@_content@_transfer@_encoding$\: |
| 23306 | This variable contains the normalized content of the |
| 23307 | ::Content-transfer-encoding:: header. This is a symbolic name for an encoding |
| 23308 | type. Typical values are `base64' and `quoted-printable'. |
| 23309 | |
| 23310 | .tempindent 0 |
| 23311 | \$mime@_content@_type$\: If the MIME part has a ::Content-Type:: header, this |
| 23312 | variable contains its value, lowercased, and without any options (like `name' |
| 23313 | or `charset'). Here are some examples of popular MIME types, as they may appear |
| 23314 | in this variable: |
| 23315 | .display asis |
| 23316 | text/plain |
| 23317 | text/html |
| 23318 | application/octet-stream |
| 23319 | image/jpeg |
| 23320 | audio/midi |
| 23321 | .endd |
| 23322 | If the MIME part has no ::Content-Type:: header, this variable contains the |
| 23323 | empty string. |
| 23324 | |
| 23325 | .tempindent 0 |
| 23326 | \$mime@_decoded@_filename$\: |
| 23327 | This variable is set only after the \decode\ modifier (see above) has been |
| 23328 | successfully run. It contains the full path and file name of the file |
| 23329 | containing the decoded data. |
| 23330 | |
| 23331 | .tempindent 0 |
| 23332 | \$mime@_filename$\: This is perhaps the most important of the MIME variables. |
| 23333 | It contains a proposed filename for an attachment, if one was found in either |
| 23334 | the ::Content-Type:: or ::Content-Disposition:: headers. The filename will be |
| 23335 | RFC2047 decoded, but no additional sanity checks are done. If no filename was |
| 23336 | found, this variable contains the empty string. |
| 23337 | |
| 23338 | .tempindent 0 |
| 23339 | \$mime@_is@_coverletter$\: |
| 23340 | This variable attempts to differentiate the `cover letter' of an e-mail from |
| 23341 | attached data. It can be used to clamp down on flashy or unneccessarily encoded |
| 23342 | content in the cover letter, while not restricting attachments at all. |
| 23343 | |
| 23344 | The variable contains 1 (true) for a MIME part believed to be part of the |
| 23345 | cover letter, and 0 (false) for an attachment. At present, the algorithm is as |
| 23346 | follows: |
| 23347 | .numberpars |
| 23348 | The outermost MIME part of a message always a cover letter. |
| 23349 | .nextp |
| 23350 | If a multipart/alternative or multipart/related MIME part is a cover letter, so |
| 23351 | are all MIME subparts within that multipart. |
| 23352 | .nextp |
| 23353 | If any other multipart is a cover letter, the first subpart is a cover letter, |
| 23354 | and the rest are attachments. |
| 23355 | .nextp |
| 23356 | All parts contained within an attachment multipart are attachments. |
| 23357 | .endp |
| 23358 | |
| 23359 | As an example, the following will ban `HTML mail' (including that sent with |
| 23360 | alternative plain text), while allowing HTML files to be attached. HTML |
| 23361 | coverletter mail attached to non-HMTL coverletter mail will also be allowed: |
| 23362 | .display asis |
| 23363 | deny message = HTML mail is not accepted here |
| 23364 | !condition = $mime_is_rfc822 |
| 23365 | condition = $mime_is_coverletter |
| 23366 | condition = ${if eq{$mime_content_type}{text/html}{1}{0}} |
| 23367 | .endd |
| 23368 | |
| 23369 | |
| 23370 | .tempindent 0 |
| 23371 | \$mime@_is@_multipart$\: |
| 23372 | This variable has the value 1 (true) when the current part has the main type |
| 23373 | `multipart', for example `multipart/alternative' or `multipart/mixed'. Since |
| 23374 | multipart entities only serve as containers for other parts, you may not want |
| 23375 | to carry out specific actions on them. |
| 23376 | |
| 23377 | .tempindent 0 |
| 23378 | \$mime@_is@_rfc822$\: |
| 23379 | This variable has the value 1 (true) if the current part is not a part of the |
| 23380 | checked message itself, but part of an attached message. Attached message |
| 23381 | decoding is fully recursive. |
| 23382 | |
| 23383 | .tempindent 0 |
| 23384 | \$mime@_part@_count$\: |
| 23385 | This variable is a counter that is raised for each processed MIME part. It |
| 23386 | starts at zero for the very first part (which is usually a multipart). The |
| 23387 | counter is per-message, so it is reset when processing RFC822 attachments (see |
| 23388 | \$mime@_is@_rfc822$\). The counter stays set after \acl@_smtp@_mime\ is |
| 23389 | complete, so you can use it in the DATA ACL to determine the number of MIME |
| 23390 | parts of a message. For non-MIME messages, this variable contains the value -1. |
| 23391 | |
| 23392 | .pop |
| 23393 | |
| 23394 | |
| 23395 | |
| 23396 | |
| 23397 | .section Scanning with regular expressions |
| 23398 | .rset SECTscanregex "~~chapter.~~section" |
| 23399 | .index content scanning||with regular expressions |
| 23400 | .index regular expressions||content scanning with |
| 23401 | You can specify your own custom regular expression matches on the full body of |
| 23402 | the message, or on individual MIME parts. |
| 23403 | |
| 23404 | The \regex\ condition takes one or more regular expressions as arguments and |
| 23405 | matches them against the full message (when called in the DATA ACL) or a raw |
| 23406 | MIME part (when called in the MIME ACL). The \regex\ condition matches |
| 23407 | linewise, with a maximum line length of 32K characters. That means you cannot |
| 23408 | have multiline matches with the \regex\ condition. |
| 23409 | |
| 23410 | The \mime@_regex\ condition can be called only in the MIME ACL. It matches up |
| 23411 | to 32K of decoded content (the whole content at once, not linewise). If the |
| 23412 | part has not been decoded with the \decode\ modifier earlier in the ACL, it is |
| 23413 | decoded automatically when \mime@_regex\ is executed (using default path and |
| 23414 | filename values). If the decoded data is larger than 32K, only the first 32K |
| 23415 | characters are checked. |
| 23416 | |
| 23417 | The regular expressions are passed as a colon-separated list. To include a |
| 23418 | literal colon, you must double it. Since the whole right-hand side string is |
| 23419 | expanded before being used, you must also escape dollar signs and backslashes |
| 23420 | with more backslashes, or use the \"@\N"\ facility to disable expansion. |
| 23421 | Here is a simple example that contains two regular expressions: |
| 23422 | .display asis |
| 23423 | deny message = contains blacklisted regex ($regex_match_string) |
| 23424 | regex = [Mm]ortgage : URGENT BUSINESS PROPOSAL |
| 23425 | .endd |
| 23426 | The conditions returns true if any one of the regular expressions matches. The |
| 23427 | \$regex@_match@_string$\ expansion variable is then set up and contains the |
| 23428 | matching regular expression. |
| 23429 | |
| 23430 | \**Warning**\: With large messages, these conditions can be fairly |
| 23431 | CPU-intensive. |
| 23432 | |
| 23433 | |
| 23434 | |
| 23435 | .section The demime condition |
| 23436 | .rset SECTdemimecond "~~chapter.~~section" |
| 23437 | .index content scanning||MIME checking |
| 23438 | .index MIME content scanning |
| 23439 | The \demime\ ACL condition provides MIME unpacking, sanity checking and file |
| 23440 | extension blocking. It uses a simpler interface to MIME decoding than the MIME |
| 23441 | ACL functionality, but provides no additional facilities. Please note that this |
| 23442 | condition is deprecated and kept only for for backward compatibility. You must |
| 23443 | set the WITH_OLD_DEMIME option in the Makefile at build time to be able to use |
| 23444 | the \demime\ condition. |
| 23445 | |
| 23446 | The \demime\ condition unpacks MIME containers in the message. It detects |
| 23447 | errors in MIME containers and can match file extensions found in the message |
| 23448 | against a list. Using this facility produces files containing the unpacked MIME |
| 23449 | parts of the message in the temporary scan directory. If you do antivirus |
| 23450 | scanning, it is recommened that you use the \demime\ condition before the |
| 23451 | antivirus (\malware\) condition. |
| 23452 | |
| 23453 | On the right-hand side of the \demime\ condition you can pass a colon-separated |
| 23454 | list of file extensions that it should match against. For example: |
| 23455 | .display asis |
| 23456 | deny message = Found blacklisted file attachment |
| 23457 | demime = vbs:com:bat:pif:prf:lnk |
| 23458 | .endd |
| 23459 | If one of the file extensions is found, the condition is true, otherwise it is |
| 23460 | false. If there is a temporary error while demimeing (for example, `disk |
| 23461 | full'), the condition defers, and the message is temporarily rejected (unless |
| 23462 | the condition is on a \warn\ verb). |
| 23463 | |
| 23464 | The right-hand side is expanded before being treated as a list, so you can have |
| 23465 | conditions and lookups there. If it expands to an empty string, `false', or |
| 23466 | zero (`0'), no demimeing is done and the condition is false. |
| 23467 | |
| 23468 | The \demime\ condition set the following variables: |
| 23469 | |
| 23470 | .push |
| 23471 | .indent 2em |
| 23472 | |
| 23473 | .tempindent 0 |
| 23474 | \$demime@_errorlevel$\: When an error is detected in a MIME container, this |
| 23475 | variable contains the severity of the error, as an integer number. The higher |
| 23476 | the value, the more severe the error. If this variable is unset or zero, no |
| 23477 | error occurred. |
| 23478 | |
| 23479 | .tempindent 0 |
| 23480 | \$demime@_reason$\: When \$demime@_errorlevel$\ is greater than zero, this |
| 23481 | variable contains a human-readable text string describing the MIME error that |
| 23482 | occurred. |
| 23483 | |
| 23484 | .tempindent 0 |
| 23485 | \$found@_extension$\: When the \demime\ condition is true, this variable |
| 23486 | contains the file extension it found. |
| 23487 | |
| 23488 | .pop |
| 23489 | |
| 23490 | Both \$demime@_errorlevel$\ and \$demime@_reason$\ are set by the first call of |
| 23491 | the \demime\ condition, and are not changed on subsequent calls. |
| 23492 | |
| 23493 | If you do not want to check for file extensions, but rather use the \demime\ |
| 23494 | condition for unpacking or error checking purposes, pass `*' as the |
| 23495 | right-hand side value. Here is a more elaborate example of how to use this |
| 23496 | facility: |
| 23497 | .display asis |
| 23498 | # Reject messages with serious MIME container errors |
| 23499 | deny message = Found MIME error ($demime_reason). |
| 23500 | demime = * |
| 23501 | condition = ${if >{$demime_errorlevel}{2}{1}{0}} |
| 23502 | |
| 23503 | # Reject known virus spreading file extensions. |
| 23504 | # Accepting these is pretty much braindead. |
| 23505 | deny message = contains $found_extension file (blacklisted). |
| 23506 | demime = com:vbs:bat:pif:scr |
| 23507 | |
| 23508 | # Freeze .exe and .doc files. Postmaster can |
| 23509 | # examine them and eventually thaw them. |
| 23510 | deny log_message = Another $found_extension file. |
| 23511 | demime = exe:doc |
| 23512 | control = freeze |
| 23513 | .endd |
| 23514 | |
| 23515 | |
| 23516 | .nem |
| 23517 | |
| 23518 | |
| 23519 | |
| 23520 | . |
| 23521 | . |
| 23522 | . |
| 23523 | . |
| 23524 | . ============================================================================ |
| 23525 | .chapter Adding a local scan function to Exim |
| 23526 | .set runningfoot "local scan function" |
| 23527 | .rset CHAPlocalscan "~~chapter" |
| 23528 | .index \*local@_scan()*\ function||description of |
| 23529 | .index customizing||input scan using C function |
| 23530 | .index policy control||by local scan function |
| 23531 | |
| 23532 | In these days of email worms, viruses, and ever-increasing spam, some sites |
| 23533 | want to apply a lot of checking to messages before accepting them. You can do a |
| 23534 | certain amount through string expansions and the \condition\ condition in the |
| 23535 | ACL that runs after the SMTP \\DATA\\ command or the ACL for non-SMTP messages |
| 23536 | (see chapter ~~CHAPACL), but this has its limitations. |
| 23537 | |
| 23538 | To allow for even more general checking that can be customized to a site's own |
| 23539 | requirements, there is the possibility of linking Exim with a private message |
| 23540 | scanning function, written in C. If you want to run code that is written in |
| 23541 | something other than C, you can of course use a little C stub to call it. |
| 23542 | |
| 23543 | The local scan function is run once for every incoming message, at the point |
| 23544 | when Exim is just about to accept the message. |
| 23545 | It can therefore be used to control non-SMTP messages from local processes as |
| 23546 | well as messages arriving via SMTP. |
| 23547 | |
| 23548 | Exim applies a timeout to calls of the local scan function, and there is an |
| 23549 | option called \local@_scan@_timeout\ for setting it. The default is 5 minutes. |
| 23550 | Zero means `no timeout'. |
| 23551 | Exim also sets up signal handlers for SIGSEGV, SIGILL, SIGFPE, and SIGBUS |
| 23552 | before calling the local scan function, so that the most common types of crash |
| 23553 | are caught. If the timeout is exceeded or one of those signals is caught, the |
| 23554 | incoming message is rejected with a temporary error if it is an SMTP message. |
| 23555 | For a non-SMTP message, the message is dropped and Exim ends with a non-zero |
| 23556 | code. The incident is logged on the main and reject logs. |
| 23557 | |
| 23558 | |
| 23559 | .section Building Exim to use a local scan function |
| 23560 | .index \*local@_scan()*\ function||building Exim to use |
| 23561 | To make use of the local scan function feature, you must tell Exim where your |
| 23562 | function is before building Exim, by setting \\LOCAL@_SCAN@_SOURCE\\ in your |
| 23563 | \(Local/Makefile)\. A recommended place to put it is in the \(Local)\ |
| 23564 | directory, so you might set |
| 23565 | .display asis |
| 23566 | LOCAL_SCAN_SOURCE=Local/local_scan.c |
| 23567 | .endd |
| 23568 | for example. The function must be called \*local@_scan()*\. It is called by |
| 23569 | Exim after it has received a message, when the success return code is about to |
| 23570 | be sent. This is after all the ACLs have been run. The return code from your |
| 23571 | function controls whether the message is actually accepted or not. There is a |
| 23572 | commented template function (that just accepts the message) in the file |
| 23573 | \(src/local@_scan.c)\. |
| 23574 | |
| 23575 | If you want to make use of Exim's run time configuration file to set options |
| 23576 | for your \*local@_scan()*\ function, you must also set |
| 23577 | .display asis |
| 23578 | LOCAL_SCAN_HAS_OPTIONS=yes |
| 23579 | .endd |
| 23580 | in \(Local/Makefile)\ (see section ~~SECTconoptloc below). |
| 23581 | |
| 23582 | |
| 23583 | |
| 23584 | .section API for local@_scan() |
| 23585 | .rset SECTapiforloc "~~chapter.~~section" |
| 23586 | .index \*local@_scan()*\ function||API description |
| 23587 | You must include this line near the start of your code: |
| 23588 | .display asis |
| 23589 | #include "local_scan.h" |
| 23590 | .endd |
| 23591 | This header file defines a number of variables and other values, and the |
| 23592 | prototype for the function itself. Exim is coded to use unsigned char values |
| 23593 | almost exclusively, and one of the things this header defines is a shorthand |
| 23594 | for \"unsigned char"\ called \"uschar"\. |
| 23595 | It also contains the following macro definitions, to simplify casting character |
| 23596 | strings and pointers to character strings: |
| 23597 | .display asis |
| 23598 | #define CS (char *) |
| 23599 | #define CCS (const char *) |
| 23600 | #define CSS (char **) |
| 23601 | #define US (unsigned char *) |
| 23602 | #define CUS (const unsigned char *) |
| 23603 | #define USS (unsigned char **) |
| 23604 | .endd |
| 23605 | |
| 23606 | The function prototype for \*local@_scan()*\ is: |
| 23607 | .display asis |
| 23608 | extern int local_scan(int fd, uschar **return_text); |
| 23609 | .endd |
| 23610 | The arguments are as follows: |
| 23611 | .numberpars $. |
| 23612 | \fd\ is a file descriptor for the file that contains the body of the message |
| 23613 | (the -D file). |
| 23614 | The file is open for reading and writing, but updating it is not recommended. |
| 23615 | \**Warning**\: You must \*not*\ close this file descriptor. |
| 23616 | |
| 23617 | The descriptor is positioned at character 19 of the file, which is the first |
| 23618 | character of the body itself, because the first 19 characters are the message |
| 23619 | id followed by \"-D"\ and a newline. If you rewind the file, you should use the |
| 23620 | macro \\SPOOL@_DATA@_START@_OFFSET\\ to reset to the start of the data, just in |
| 23621 | case this changes in some future version. |
| 23622 | |
| 23623 | .nextp |
| 23624 | \return@_text\ is an address which you can use to return a pointer to a text |
| 23625 | string at the end of the function. The value it points to on entry is NULL. |
| 23626 | .endp |
| 23627 | The function must return an \int\ value which is one of the following macros: |
| 23628 | .numberpars $. |
| 23629 | \"LOCAL@_SCAN@_ACCEPT"\ |
| 23630 | |
| 23631 | The message is accepted. If you pass back a string of text, it is saved with |
| 23632 | the message, and made available in the variable \$local@_scan@_data$\. No |
| 23633 | newlines are permitted (if there are any, they are turned into spaces) and the |
| 23634 | maximum length of text is 1000 characters. |
| 23635 | .nextp |
| 23636 | \"LOCAL@_SCAN@_ACCEPT@_FREEZE"\ |
| 23637 | |
| 23638 | This behaves as \\LOCAL@_SCAN@_ACCEPT\\, except that the accepted message is |
| 23639 | queued without immediate delivery, and is frozen. |
| 23640 | .nextp |
| 23641 | \"LOCAL@_SCAN@_ACCEPT@_QUEUE"\ |
| 23642 | |
| 23643 | This behaves as \\LOCAL@_SCAN@_ACCEPT\\, except that the accepted message is |
| 23644 | queued without immediate delivery. |
| 23645 | .nextp |
| 23646 | \"LOCAL@_SCAN@_REJECT"\ |
| 23647 | |
| 23648 | The message is rejected; the returned text is used as an error message which is |
| 23649 | passed back to the sender and which is also logged. Newlines are permitted -- |
| 23650 | they cause a multiline response for SMTP rejections, but are converted to |
| 23651 | \"@\n"\ in log lines. |
| 23652 | If no message is given, `Administrative prohibition' is used. |
| 23653 | .nextp |
| 23654 | \"LOCAL@_SCAN@_TEMPREJECT"\ |
| 23655 | |
| 23656 | The message is temporarily rejected; the returned text is used as an error |
| 23657 | message as for \\LOCAL@_SCAN@_REJECT\\. If no message is given, `Temporary |
| 23658 | local problem' is used. |
| 23659 | .nextp |
| 23660 | \"LOCAL@_SCAN@_REJECT@_NOLOGHDR"\ |
| 23661 | |
| 23662 | This behaves as \\LOCAL@_SCAN@_REJECT\\, except that the header of the rejected |
| 23663 | message is not written to the reject log. It has the effect of unsetting the |
| 23664 | \rejected@_header\ log selector for just this rejection. If \rejected@_header\ |
| 23665 | is already unset (see the discussion of the \log@_selection\ option in section |
| 23666 | ~~SECTlogselector), this code is the same as \\LOCAL@_SCAN@_REJECT\\. |
| 23667 | |
| 23668 | .nextp |
| 23669 | \"LOCAL@_SCAN@_TEMPREJECT@_NOLOGHDR"\ |
| 23670 | |
| 23671 | This code is a variation of \\LOCAL@_SCAN@_TEMPREJECT\\ in the same way that |
| 23672 | \\LOCAL__SCAN__REJECT__NOLOGHDR\\ is a variation of \\LOCAL@_SCAN@_REJECT\\. |
| 23673 | .endp |
| 23674 | |
| 23675 | If the message is not being received by interactive SMTP, rejections are |
| 23676 | reported by writing to \stderr\ or by sending an email, as configured by the |
| 23677 | \-oe-\ command line options. |
| 23678 | |
| 23679 | |
| 23680 | .section Configuration options for local@_scan() |
| 23681 | .rset SECTconoptloc "~~chapter.~~section" |
| 23682 | .index \*local@_scan()*\ function||configuration options |
| 23683 | It is possible to have option settings in the main configuration file |
| 23684 | that set values in static variables in the \*local@_scan()*\ module. If you |
| 23685 | want to do this, you must have the line |
| 23686 | .display asis |
| 23687 | LOCAL_SCAN_HAS_OPTIONS=yes |
| 23688 | .endd |
| 23689 | in your \(Local/Makefile)\ when you build Exim. (This line is in |
| 23690 | \(OS/Makefile-Default)\, commented out). Then, in the \*local@_scan()*\ source |
| 23691 | file, you must define static variables to hold the option values, and a table to |
| 23692 | define them. |
| 23693 | |
| 23694 | The table must be a vector called \local@_scan@_options\, of type |
| 23695 | \"optionlist"\. Each entry is a triplet, consisting of a name, an option type, |
| 23696 | and a pointer to the variable that holds the value. The entries must appear in |
| 23697 | alphabetical order. Following \local@_scan@_options\ you must also define a |
| 23698 | variable called \local@_scan@_options@_count\ that contains the number of |
| 23699 | entries in the table. Here is a short example, showing two kinds of option: |
| 23700 | .display asis |
| 23701 | static int my_integer_option = 42; |
| 23702 | static uschar *my_string_option = US"a default string"; |
| 23703 | |
| 23704 | optionlist local_scan_options[] = { |
| 23705 | { "my_integer", opt_int, &my_integer_option }, |
| 23706 | { "my_string", opt_stringptr, &my_string_option } |
| 23707 | }; |
| 23708 | int local_scan_options_count = |
| 23709 | sizeof(local_scan_options)/sizeof(optionlist); |
| 23710 | .endd |
| 23711 | The values of the variables can now be changed from Exim's runtime |
| 23712 | configuration file by including a local scan section as in this example: |
| 23713 | .display asis |
| 23714 | begin local_scan |
| 23715 | my_integer = 99 |
| 23716 | my_string = some string of text... |
| 23717 | .endd |
| 23718 | The available types of option data are as follows: |
| 23719 | |
| 23720 | .startitems |
| 23721 | |
| 23722 | .item opt@_bool |
| 23723 | This specifies a boolean (true/false) option. The address should point to |
| 23724 | a variable of type \"BOOL"\, which will be set to \\TRUE\\ or \\FALSE\\, which |
| 23725 | are macros that are defined as `1' and `0', respectively. If you want to detect |
| 23726 | whether such a variable has been set at all, you can initialize it to |
| 23727 | \\TRUE@_UNSET\\. (BOOL variables are integers underneath, so can hold more than |
| 23728 | two values.) |
| 23729 | |
| 23730 | .item "opt@_fixed" |
| 23731 | This specifies a fixed point number, such as is used for load averages. |
| 23732 | The address should point to a variable of type \"int"\. The value is stored |
| 23733 | multiplied by 1000, so, for example, 1.4142 is truncated and stored as 1414. |
| 23734 | |
| 23735 | .item "opt@_int" |
| 23736 | This specifies an integer; the address should point to a variable of type |
| 23737 | \"int"\. The value may be specified in any of the integer formats accepted by |
| 23738 | Exim. |
| 23739 | |
| 23740 | .item "opt@_mkint" |
| 23741 | This is the same as \opt@_int\, except that when such a value is output in a |
| 23742 | \-bP-\ listing, if it is an exact number of kilobytes or megabytes, it is |
| 23743 | printed with the suffix K or M. |
| 23744 | |
| 23745 | .item "opt@_octint" |
| 23746 | This also specifies an integer, but the value is always interpeted as an |
| 23747 | octal integer, whether or not it starts with the digit zero, and it is |
| 23748 | always output in octal. |
| 23749 | |
| 23750 | .item "opt@_stringptr" |
| 23751 | This specifies a string value; the address must be a pointer to a |
| 23752 | variable that points to a string (for example, of type \"uschar $*$"\). |
| 23753 | |
| 23754 | .item "opt@_time" |
| 23755 | This specifies a time interval value. The address must point to a variable of |
| 23756 | type \"int"\. The value that is placed there is a number of seconds. |
| 23757 | |
| 23758 | .enditems |
| 23759 | |
| 23760 | If the \-bP-\ command line option is followed by \"local@_scan"\, Exim prints |
| 23761 | out the values of all the \*local@_scan()*\ options. |
| 23762 | |
| 23763 | |
| 23764 | .section Available Exim variables |
| 23765 | .index \*local@_scan()*\ function||available Exim variables |
| 23766 | The header \(local@_scan.h)\ gives you access to a number of C variables. |
| 23767 | These are the only ones that are guaranteed to be maintained from release to |
| 23768 | release. Note, however, that you can obtain the value of any Exim variable by |
| 23769 | calling \*expand@_string()*\. The exported variables are as follows: |
| 23770 | |
| 23771 | .startitems |
| 23772 | |
| 23773 | .item "unsigned int debug@_selector" |
| 23774 | This variable is set to zero when no debugging is taking place. Otherwise, it |
| 23775 | is a bitmap of debugging selectors. Two bits are identified for use in |
| 23776 | \*local@_scan()*\; they are defined as macros: |
| 23777 | .numberpars $. |
| 23778 | The \"D@_v"\ bit is set when \-v-\ was present on the command line. This is a |
| 23779 | testing option that is not privileged -- any caller may set it. All the |
| 23780 | other selector bits can be set only by admin users. |
| 23781 | .nextp |
| 23782 | The \"D@_local@_scan"\ bit is provided for use by \*local@_scan()*\; it is set |
| 23783 | by the \"+local@_scan"\ debug selector. It is not included in the default set |
| 23784 | of debugging bits. |
| 23785 | .endp |
| 23786 | Thus, to write to the debugging output only when \"+local@_scan"\ has been |
| 23787 | selected, you should use code like this: |
| 23788 | .display asis |
| 23789 | if ((debug_selector & D_local_scan) != 0) |
| 23790 | debug_printf("xxx", ...); |
| 23791 | .endd |
| 23792 | |
| 23793 | .item "uschar *expand@_string@_message" |
| 23794 | After a failing call to \*expand@_string()*\ (returned value NULL), the |
| 23795 | variable \expand__string__message\ contains the error message, zero-terminated. |
| 23796 | |
| 23797 | .item "header@_line *header@_list" |
| 23798 | A pointer to a chain of header lines. The \header@_line\ structure is discussed |
| 23799 | below. |
| 23800 | |
| 23801 | .item "header@_line *header@_last" |
| 23802 | A pointer to the last of the header lines. |
| 23803 | |
| 23804 | .item "uschar *headers@_charset" |
| 23805 | The value of the \headers@_charset\ configuration option. |
| 23806 | |
| 23807 | .item "BOOL host@_checking" |
| 23808 | This variable is TRUE during a host checking session that is initiated by the |
| 23809 | \-bh-\ command line option. |
| 23810 | |
| 23811 | .item "uschar *interface@_address" |
| 23812 | The IP address of the interface that received the message, as a string. This |
| 23813 | is NULL for locally submitted messages. |
| 23814 | |
| 23815 | .item "int interface@_port" |
| 23816 | The port on which this message was received. |
| 23817 | |
| 23818 | .item "uschar *message@_id" |
| 23819 | This variable contains the message id for the incoming message as a |
| 23820 | zero-terminated string. |
| 23821 | |
| 23822 | |
| 23823 | .item "uschar *received@_protocol" |
| 23824 | The name of the protocol by which the message was received. |
| 23825 | |
| 23826 | .item "int recipients@_count" |
| 23827 | The number of accepted recipients. |
| 23828 | |
| 23829 | .item "recipient@_item *recipients@_list" |
| 23830 | .index recipient||adding in local scan |
| 23831 | .index recipient||removing in local scan |
| 23832 | The list of accepted recipients, held in a vector of length |
| 23833 | \recipients@_count\. The \recipient@_item\ structure is discussed below. You |
| 23834 | can add additional recipients by calling \*receive@_add@_recipient()*\ (see |
| 23835 | below). You can delete recipients by removing them from the vector and adusting |
| 23836 | the value in \recipients@_count\. In particular, by setting \recipients@_count\ |
| 23837 | to zero you remove all recipients. If you then return the value |
| 23838 | \"LOCAL@_SCAN@_ACCEPT"\, the message is accepted, but immediately blackholed. |
| 23839 | To replace the recipients, set \recipients@_count\ to zero and then call |
| 23840 | \*receive@_add@_recipient()*\ as often as needed. |
| 23841 | |
| 23842 | .item "uschar *sender@_address" |
| 23843 | The envelope sender address. For bounce messages this is the empty string. |
| 23844 | |
| 23845 | .item "uschar *sender@_host@_address" |
| 23846 | The IP address of the sending host, as a string. This is NULL for |
| 23847 | locally-submitted messages. |
| 23848 | |
| 23849 | .item "uschar *sender@_host@_authenticated" |
| 23850 | The name of the authentication mechanism that was used, or NULL if the message |
| 23851 | was not received over an authenticated SMTP connection. |
| 23852 | |
| 23853 | .item "uschar *sender@_host@_name" |
| 23854 | The name of the sending host, if known. |
| 23855 | |
| 23856 | .item "int sender@_host@_port" |
| 23857 | The port on the sending host. |
| 23858 | |
| 23859 | .item "BOOL smtp@_input" |
| 23860 | This variable is TRUE for all SMTP input, including BSMTP. |
| 23861 | |
| 23862 | .item "BOOL smtp@_batched@_input" |
| 23863 | This variable is TRUE for BSMTP input. |
| 23864 | |
| 23865 | .item "int store@_pool" |
| 23866 | The contents of this variable control which pool of memory is used for new |
| 23867 | requests. See section ~~SECTmemhanloc for details. |
| 23868 | |
| 23869 | .enditems |
| 23870 | |
| 23871 | |
| 23872 | .section Structure of header lines |
| 23873 | The \header@_line\ structure contains the members listed below. |
| 23874 | You can add additional header lines by calling the \*header@_add()*\ function |
| 23875 | (see below). You can cause header lines to be ignored (deleted) by setting |
| 23876 | their type to $*$. |
| 23877 | |
| 23878 | .startitems |
| 23879 | |
| 23880 | .item "struct header@_line *next" |
| 23881 | A pointer to the next header line, or NULL for the last line. |
| 23882 | |
| 23883 | .item "int type" |
| 23884 | A code identifying certain headers that Exim recognizes. The codes are printing |
| 23885 | characters, and are documented in chapter ~~CHAPspool of this manual. Notice in |
| 23886 | particular that any header line whose type is $*$ is not transmitted with the |
| 23887 | message. This flagging is used for header lines that have been rewritten, or |
| 23888 | are to be removed (for example, ::Envelope-sender:: header lines.) Effectively, |
| 23889 | $*$ means `deleted'. |
| 23890 | |
| 23891 | .item "int slen" |
| 23892 | The number of characters in the header line, including the terminating and any |
| 23893 | internal newlines. |
| 23894 | |
| 23895 | .item "uschar *text" |
| 23896 | A pointer to the text of the header. It always ends with a newline, followed by |
| 23897 | a zero byte. Internal newlines are preserved. |
| 23898 | |
| 23899 | .enditems |
| 23900 | |
| 23901 | |
| 23902 | |
| 23903 | .section Structure of recipient items |
| 23904 | The \recipient@_item\ structure contains these members: |
| 23905 | |
| 23906 | .startitems |
| 23907 | |
| 23908 | .item "uschar *address" |
| 23909 | This is a pointer to the recipient address as it was received. |
| 23910 | |
| 23911 | .item "int pno" |
| 23912 | This is used in later Exim processing when top level addresses are created |
| 23913 | by the \one@_time\ option. It is not relevant at the time \*local@_scan()*\ is |
| 23914 | run and |
| 23915 | must always contain -1 at this stage. |
| 23916 | |
| 23917 | .item "uschar *errors@_to" |
| 23918 | If this value is not NULL, bounce messages caused by failing to deliver to the |
| 23919 | recipient are sent to the address it contains. In other words, it overrides the |
| 23920 | envelope sender for this one recipient. (Compare the \errors@_to\ generic |
| 23921 | router option.) |
| 23922 | If a \*local@_scan()*\ function sets an \errors@_to\ field to an unqualified |
| 23923 | address, Exim qualifies it using the domain from \qualify@_recipient\. |
| 23924 | When \*local@_scan()*\ is called, the \errors@_to\ field is NULL for all |
| 23925 | recipients. |
| 23926 | .enditems |
| 23927 | |
| 23928 | |
| 23929 | .section Available Exim functions |
| 23930 | .index \*local@_scan()*\ function||available Exim functions |
| 23931 | The header \(local@_scan.h)\ gives you access to a number of Exim functions. |
| 23932 | These are the only ones that are guaranteed to be maintained from release to |
| 23933 | release: |
| 23934 | |
| 23935 | .startitems |
| 23936 | |
| 23937 | .item "pid@_t child@_open(uschar **argv, uschar **envp, int newumask, int *infdptr, int *outfdptr, BOOL make@_leader)" |
| 23938 | This function creates a child process that runs the command specified by |
| 23939 | \argv\. The environment for the process is specified by \envp\, which can be |
| 23940 | NULL if no environment variables are to be passed. A new umask is supplied for |
| 23941 | the process in \newumask\. |
| 23942 | |
| 23943 | Pipes to the standard input and output of the new process are set up |
| 23944 | and returned to the caller via the \infdptr\ and \outfdptr\ arguments. The |
| 23945 | standard error is cloned to the standard output. If there are any file |
| 23946 | descriptors `in the way' in the new process, they are closed. If the final |
| 23947 | argument is TRUE, the new process is made into a process group leader. |
| 23948 | |
| 23949 | The function returns the pid of the new process, or -1 if things go wrong. |
| 23950 | |
| 23951 | |
| 23952 | .item "int child@_close(pid@_t pid, int timeout)" |
| 23953 | This function waits for a child process to terminate, or for a timeout (in |
| 23954 | seconds) to expire. A timeout value of zero means wait as long as it takes. The |
| 23955 | return value is as follows: |
| 23956 | .numberpars $. |
| 23957 | >= 0 |
| 23958 | |
| 23959 | The process terminated by a normal exit and the value is the process ending |
| 23960 | status. |
| 23961 | .nextp |
| 23962 | < 0 and > --256 |
| 23963 | |
| 23964 | The process was terminated by a signal and the value is the negation of the |
| 23965 | signal number. |
| 23966 | .nextp |
| 23967 | --256 |
| 23968 | |
| 23969 | The process timed out. |
| 23970 | .nextp |
| 23971 | --257 |
| 23972 | |
| 23973 | The was some other error in wait(); \errno\ is still set. |
| 23974 | .endp |
| 23975 | |
| 23976 | |
| 23977 | .item "pid@_t child@_open@_exim(int *fd)" |
| 23978 | This function provide you with a means of submitting a new message to |
| 23979 | Exim. (Of course, you can also call \(/usr/sbin/sendmail)\ yourself if you |
| 23980 | want, but this packages it all up for you.) The function creates a pipe, |
| 23981 | forks a subprocess that is running |
| 23982 | .display asis |
| 23983 | exim -t -oem -oi -f <> |
| 23984 | .endd |
| 23985 | and returns to you (via the \"int *"\ argument) a file descriptor for the pipe |
| 23986 | that is connected to the standard input. The yield of the function is the PID |
| 23987 | of the subprocess. You can then write a message to the file descriptor, with |
| 23988 | recipients in ::To::, ::Cc::, and/or ::Bcc:: header lines. |
| 23989 | |
| 23990 | When you have finished, call \*child@_close()*\ to wait for the process to |
| 23991 | finish and to collect its ending status. A timeout value of zero is usually |
| 23992 | fine in this circumstance. Unless you have made a mistake with the recipient |
| 23993 | addresses, you should get a return code of zero. |
| 23994 | |
| 23995 | .item "void debug@_printf(char *, ...)" |
| 23996 | This is Exim's debugging function, with arguments as for \*(printf()*\. The |
| 23997 | output is written to the standard error stream. If no debugging is selected, |
| 23998 | calls to \*debug@_printf()*\ have no effect. Normally, you should make calls |
| 23999 | conditional on the \"local@_scan"\ debug selector by coding like this: |
| 24000 | .display asis |
| 24001 | if ((debug_selector & D_local_scan) != 0) |
| 24002 | debug_printf("xxx", ...); |
| 24003 | .endd |
| 24004 | |
| 24005 | .item "uschar *expand@_string(uschar *string)" |
| 24006 | This is an interface to Exim's string expansion code. The return value is the |
| 24007 | expanded string, or NULL if there was an expansion failure. |
| 24008 | The C variable \expand@_string@_message\ contains an error message after an |
| 24009 | expansion failure. If expansion does not change the string, the return value is |
| 24010 | the pointer to the input string. Otherwise, the return value points to a new |
| 24011 | block of memory that was obtained by a call to \*store@_get()*\. See section |
| 24012 | ~~SECTmemhanloc below for a discussion of memory handling. |
| 24013 | |
| 24014 | .item "void header@_add(int type, char *format, ...)" |
| 24015 | This function allows you to add additional header lines. The first argument is |
| 24016 | the type, and should normally be a space character. The second argument is a |
| 24017 | format string and any number of substitution arguments as for \*sprintf()*\. |
| 24018 | You may include internal newlines if you want, and you must ensure that the |
| 24019 | string ends with a newline. |
| 24020 | |
| 24021 | .item "uschar *lss@_b64encode(uschar *cleartext, int length)" |
| 24022 | .index base64 encoding||functions for \*local@_scan()*\ use |
| 24023 | This function base64-encodes a string, which is passed by address and length. |
| 24024 | The text may contain bytes of any value, including zero. The result is passed |
| 24025 | back in dynamic memory that is obtained by calling \*store@_get()*\. It is |
| 24026 | zero-terminated. |
| 24027 | |
| 24028 | .item "int lss@_b64decode(uschar *codetext, uschar **cleartext)" |
| 24029 | This function decodes a base64-encoded string. Its arguments are a |
| 24030 | zero-terminated base64-encoded string and the address of a variable that is set |
| 24031 | to point to the result, which is in dynamic memory. The length of the |
| 24032 | decoded string is the yield of the function. If the input is invalid base64 |
| 24033 | data, the yield is -1. A zero byte is added to the end of the output string to |
| 24034 | make it easy to interpret as a C string (assuming it contains no zeros of its |
| 24035 | own). The added zero byte is not included in the returned count. |
| 24036 | |
| 24037 | .item "int lss@_match@_domain(uschar *domain, uschar *list)" |
| 24038 | This function checks for a match in a domain list. Domains are always |
| 24039 | matched caselessly. The return value is one of the following: |
| 24040 | .display |
| 24041 | OK $rm{match succeeded} |
| 24042 | FAIL $rm{match failed} |
| 24043 | DEFER $rm{match deferred} |
| 24044 | .endd |
| 24045 | DEFER is usually caused by some kind of lookup defer, such as the |
| 24046 | inability to contact a database. |
| 24047 | |
| 24048 | .item "int lss@_match@_local@_part(uschar *localpart, uschar *list, BOOL caseless)" |
| 24049 | This function checks for a match in a local part list. The third argument |
| 24050 | controls case-sensitivity. The return values are as for |
| 24051 | \*lss@_match@_domain()*\. |
| 24052 | |
| 24053 | .item "int lss@_match@_address(uschar *address, uschar *list, BOOL caseless)" |
| 24054 | This function checks for a match in an address list. The third argument |
| 24055 | controls the case-sensitivity of the local part match. The domain is always |
| 24056 | matched caselessly. The return values are as for \*lss@_match@_domain()*\. |
| 24057 | |
| 24058 | .item "int lss@_match@_host(uschar *host@_name, uschar *host@_address, uschar *list)" |
| 24059 | This function checks for a match in a host list. The most common usage is |
| 24060 | expected to be |
| 24061 | .display asis |
| 24062 | lss_match_host(sender_host_name, sender_host_address, ...) |
| 24063 | .endd |
| 24064 | An empty address field matches an empty item in the host list. If the |
| 24065 | host name is NULL, the name corresponding to \$sender@_host@_address$\ is |
| 24066 | automatically looked up if a host name is required to match an item in the |
| 24067 | list. The return values are as for \*lss@_match@_domain()*\, but in addition, |
| 24068 | \*lss@_match@_host()*\ returns ERROR in the case when it had to look up a host |
| 24069 | name, but the lookup failed. |
| 24070 | |
| 24071 | .item "void log@_write(unsigned int selector, int which, char *format, ...)" |
| 24072 | This function writes to Exim's log files. The first argument should be zero (it |
| 24073 | is concerned with \log@_selector\). The second argument can be \"LOG@_MAIN"\ or |
| 24074 | \"LOG@_REJECT"\ or |
| 24075 | \"LOG@_PANIC"\ or the inclusive `or' of any combination of them. It specifies |
| 24076 | to which log or logs the message is written. |
| 24077 | The remaining arguments are a format and relevant insertion arguments. The |
| 24078 | string should not contain any newlines, not even at the end. |
| 24079 | |
| 24080 | |
| 24081 | .item "void receive@_add@_recipient(uschar *address, int pno)" |
| 24082 | This function adds an additional recipient to the message. The first argument |
| 24083 | is the recipient address. If it is unqualified (has no domain), it is qualified |
| 24084 | with the \qualify@_recipient\ domain. The second argument must always be -1. |
| 24085 | |
| 24086 | This function does not allow you to specify a private \errors@_to\ address (as |
| 24087 | described with the structure of \recipient@_item\ above), because it pre-dates |
| 24088 | the addition of that field to the structure. However, it is easy to add such a |
| 24089 | value afterwards. For example: |
| 24090 | .display asis |
| 24091 | receive_add_recipient(US"monitor@mydom.example", -1); |
| 24092 | recipients_list[recipients_count-1].errors_to = |
| 24093 | US"postmaster@mydom.example"; |
| 24094 | .endd |
| 24095 | |
| 24096 | .item "uschar *rfc2047@_decode(uschar *string, BOOL lencheck, uschar *target, int zeroval, int *lenptr, uschar **error)" |
| 24097 | This function decodes strings that are encoded according to RFC 2047. Typically |
| 24098 | these are the contents of header lines. First, each encoded `word' is decoded |
| 24099 | from the Q or B encoding into a byte-string. Then, if provided with the name of |
| 24100 | a charset encoding, and if the \*iconv()*\ function is available, an attempt is |
| 24101 | made to translate the result to the named character set. If this fails, the |
| 24102 | binary string is returned with an error message. |
| 24103 | |
| 24104 | The first argument is the string to be decoded. If \lencheck\ is TRUE, the |
| 24105 | maximum MIME word length is enforced. The third argument is the target |
| 24106 | encoding, or NULL if no translation is wanted. |
| 24107 | |
| 24108 | .index binary zero||in RFC 2047 decoding |
| 24109 | If a binary zero is encountered in the decoded string, it is replaced by the |
| 24110 | contents of the \zeroval\ argument. For use with Exim headers, the value must |
| 24111 | not be 0 because header lines are handled as zero-terminated strings. |
| 24112 | |
| 24113 | The function returns the result of processing the string, zero-terminated; if |
| 24114 | \lenptr\ is not NULL, the length of the result is set in the variable to which |
| 24115 | it points. When \zeroval\ is 0, \lenptr\ should not be NULL. |
| 24116 | |
| 24117 | If an error is encountered, the function returns NULL and uses the \error\ |
| 24118 | argument to return an error message. The variable pointed to by \error\ is set |
| 24119 | to NULL if there is no error; it may be set non-NULL even when the function |
| 24120 | returns a non-NULL value if decoding was successful, but there was a problem |
| 24121 | with translation. |
| 24122 | |
| 24123 | |
| 24124 | .item "int smtp@_fflush(void)" |
| 24125 | This function is used in conjunction with \*smtp@_printf()*\, as described |
| 24126 | below. |
| 24127 | |
| 24128 | .item "void smtp@_printf(char *, ...)" |
| 24129 | The arguments of this function are like \*printf()*\; it writes to the SMTP |
| 24130 | output stream. You should use this function only when there is an SMTP output |
| 24131 | stream, that is, when the incoming message is being received via interactive |
| 24132 | SMTP. This is the case when \smtp@_input\ is TRUE and \smtp@_batched@_input\ is |
| 24133 | FALSE. If you want to test for an incoming message from another host (as |
| 24134 | opposed to a local process that used the \-bs-\ command line option), you can |
| 24135 | test the value of \sender@_host@_address\, which is non-NULL when a remote host |
| 24136 | is involved. |
| 24137 | |
| 24138 | If an SMTP TLS connection is established, \*smtp@_printf()*\ uses the TLS |
| 24139 | output function, so it can be used for all forms of SMTP connection. |
| 24140 | |
| 24141 | Strings that are written by \*smtp@_printf()*\ from within \*local@_scan()*\ |
| 24142 | must start with an appropriate response code: 550 if you are going to return |
| 24143 | \\LOCAL@_SCAN@_REJECT\\, 451 if you are going to return |
| 24144 | \\LOCAL@_SCAN@_TEMPREJECT\\, and 250 otherwise. Because you are writing the |
| 24145 | initial lines of a multi-line response, the code must be followed by a hyphen |
| 24146 | to indicate that the line is not the final response line. You must also ensure |
| 24147 | that the lines you write terminate with CRLF. For example: |
| 24148 | .display asis |
| 24149 | smtp_printf("550-this is some extra info\r\n"); |
| 24150 | return LOCAL_SCAN_REJECT; |
| 24151 | .endd |
| 24152 | Note that you can also create multi-line responses by including newlines in |
| 24153 | the data returned via the \return@_text\ argument. The added value of using |
| 24154 | \*smtp@_printf()*\ is that, for instance, you could introduce delays between |
| 24155 | multiple output lines. |
| 24156 | |
| 24157 | The \*smtp@_printf()*\ function does not return any error indication, because it |
| 24158 | does not automatically flush pending output, and therefore does not test |
| 24159 | the state of the stream. (In the main code of Exim, flushing and error |
| 24160 | detection is done when Exim is ready for the next SMTP input command.) If |
| 24161 | you want to flush the output and check for an error (for example, the |
| 24162 | dropping of a TCP/IP connection), you can call \*smtp@_fflush()*\, which has no |
| 24163 | arguments. It flushes the output stream, and returns a non-zero value if there |
| 24164 | is an error. |
| 24165 | |
| 24166 | .item "void *store@_get(int)" |
| 24167 | This function accesses Exim's internal store (memory) manager. It gets a new |
| 24168 | chunk of memory whose size is given by the argument. Exim bombs out if it ever |
| 24169 | runs out of memory. See the next section for a discussion of memory handling. |
| 24170 | |
| 24171 | .item "void *store@_get@_perm(int)" |
| 24172 | This function is like \*store@_get()*\, but it always gets memory from the |
| 24173 | permanent pool. See the next section for a discussion of memory handling. |
| 24174 | |
| 24175 | .item "uschar *string@_copy(uschar *string)" |
| 24176 | .item "uschar *string@_copyn(uschar *string, int length)" 0 |
| 24177 | .item "uschar *string@_sprintf(char *format, ...)" 0 |
| 24178 | These three functions create strings using Exim's dynamic memory facilities. |
| 24179 | The first makes a copy of an entire string. The second copies up to a maximum |
| 24180 | number of characters, indicated by the second argument. The third uses a format |
| 24181 | and insertion arguments to create a new string. In each case, the result is a |
| 24182 | pointer to a new string |
| 24183 | in the current memory pool. See the next section for more discussion. |
| 24184 | |
| 24185 | .enditems |
| 24186 | |
| 24187 | |
| 24188 | |
| 24189 | .section More about Exim's memory handling |
| 24190 | .rset SECTmemhanloc "~~chapter.~~section" |
| 24191 | .index \*local@_scan()*\ function||memory handling |
| 24192 | No function is provided for freeing memory, because that is never needed. |
| 24193 | The dynamic memory that Exim uses when receiving a message is automatically |
| 24194 | recycled if another message is received by the same process (this applies only |
| 24195 | to incoming SMTP connections -- other input methods can supply only one message |
| 24196 | at a time). After receiving the last message, a reception process terminates. |
| 24197 | |
| 24198 | Because it is recycled, the normal dynamic memory cannot be used for holding |
| 24199 | data that must be preserved over a number of incoming messages on the same SMTP |
| 24200 | connection. However, Exim in fact uses two pools of dynamic memory; the second |
| 24201 | one is not recycled, and can be used for this purpose. |
| 24202 | |
| 24203 | If you want to allocate memory that remains available for subsequent messages |
| 24204 | in the same SMTP connection, you should set |
| 24205 | .display asis |
| 24206 | store_pool = POOL_PERM |
| 24207 | .endd |
| 24208 | before calling the function that does the allocation. There is no need to |
| 24209 | restore the value if you do not need to; however, if you do want to revert to |
| 24210 | the normal pool, you can either restore the previous value of \store@_pool\ or |
| 24211 | set it explicitly to \\POOL@_MAIN\\. |
| 24212 | |
| 24213 | The pool setting applies to all functions that get dynamic memory, including |
| 24214 | \*expand@_string()*\, \*store@_get()*\, and the \*string@_xxx()*\ functions. |
| 24215 | There is also a convenience function called \*store@_get@_perm()*\ that gets a |
| 24216 | block of memory from the permanent pool while preserving the value of |
| 24217 | \store@_pool\. |
| 24218 | |
| 24219 | |
| 24220 | |
| 24221 | |
| 24222 | |
| 24223 | . |
| 24224 | . |
| 24225 | . |
| 24226 | . |
| 24227 | . ============================================================================ |
| 24228 | .chapter System-wide message filtering |
| 24229 | .set runningfoot "system filtering" |
| 24230 | .rset CHAPsystemfilter "~~chapter" |
| 24231 | .index filter||system filter |
| 24232 | .index filtering all mail |
| 24233 | .index system filter |
| 24234 | The previous chapters (on ACLs and the local scan function) describe checks |
| 24235 | that can be applied to messages before they are accepted by a host. There is |
| 24236 | also a mechanism for checking messages once they have been received, but before |
| 24237 | they are delivered. This is called the $it{system filter}. |
| 24238 | |
| 24239 | The system filter operates in a similar manner to users' filter files, but it |
| 24240 | is run just once per message (however many recipients the message has). |
| 24241 | It should not normally be used as a substitute for routing, because \deliver\ |
| 24242 | commands in a system router provide new envelope recipient addresses. |
| 24243 | The system filter must be an Exim filter. It cannot be a Sieve filter. |
| 24244 | |
| 24245 | The system filter is run at the start of a delivery attempt, before any routing |
| 24246 | is done. If a message fails to be completely delivered at the first attempt, |
| 24247 | the system filter is run again at the start of every retry. |
| 24248 | If you want your filter to do something only once per message, you can make use |
| 24249 | of the \first@_delivery\ condition in an \if\ command in the filter to prevent |
| 24250 | it happening on retries. |
| 24251 | |
| 24252 | \**Warning**\: Because the system filter runs just once, variables that are |
| 24253 | specific to individual recipient addresses, such as \$local@_part$\ and |
| 24254 | \$domain$\, are not set, and the `personal' condition is not meaningful. If you |
| 24255 | want to run a centrally-specified filter for each recipient address |
| 24256 | independently, you can do so by setting up a suitable \%redirect%\ router, as |
| 24257 | described in section ~~SECTperaddfil below. |
| 24258 | |
| 24259 | .section Specifying a system filter |
| 24260 | .index uid (user id)||system filter |
| 24261 | .index gid (group id)||system filter |
| 24262 | The name of the file that contains the system filter must be specified by |
| 24263 | setting \system@_filter\. If you want the filter to run under a uid and gid |
| 24264 | other than root, you must also set \system@_filter@_user\ and |
| 24265 | \system@_filter@_group\ as appropriate. For example: |
| 24266 | .display asis |
| 24267 | system_filter = /etc/mail/exim.filter |
| 24268 | system_filter_user = exim |
| 24269 | .endd |
| 24270 | If a system filter generates any deliveries directly to files or pipes (via the |
| 24271 | \save\ or \pipe\ commands), transports to handle these deliveries must be |
| 24272 | specified by setting \system@_filter@_file@_transport\ and |
| 24273 | \system@_filter@_pipe@_transport\, respectively. Similarly, |
| 24274 | \system@_filter@_reply@_transport\ must be set to handle any messages generated |
| 24275 | by the \reply\ command. |
| 24276 | |
| 24277 | .section Testing a system filter |
| 24278 | You can run simple tests of a system filter in the same way as for a user |
| 24279 | filter, but you should use \-bF-\ rather than \-bf-\, so that features that |
| 24280 | are permitted only in system filters are recognized. |
| 24281 | |
| 24282 | .section Contents of a system filter |
| 24283 | The language used to specify system filters is the same as for users' filter |
| 24284 | files. It is described in the separate end-user document \*Exim's interface to |
| 24285 | mail filtering*\. However, there are some additional features that are |
| 24286 | available only in system filters; these are described in subsequent sections. |
| 24287 | If they are encountered in a user's filter file or when testing with \-bf-\, |
| 24288 | they cause errors. |
| 24289 | |
| 24290 | .index frozen messages||manual thaw, testing in filter |
| 24291 | There are two special conditions which, though available in users' filter |
| 24292 | files, are designed for use in system filters. The condition \first@_delivery\ |
| 24293 | is true only for the first attempt at delivering a message, and |
| 24294 | \manually@_thawed\ is true only if the message has been frozen, and |
| 24295 | subsequently thawed by an admin user. An explicit forced delivery counts as a |
| 24296 | manual thaw, but thawing as a result of the \auto__thaw\ setting does not. |
| 24297 | |
| 24298 | \**Warning**\: If a system filter uses the \first@_delivery\ condition to |
| 24299 | specify an `unseen' (non-significant) delivery, and that delivery does not |
| 24300 | succeed, it will not be tried again. |
| 24301 | If you want Exim to retry an unseen delivery until it succeeds, you should |
| 24302 | arrange to set it up every time the filter runs. |
| 24303 | |
| 24304 | When a system filter finishes running, the values of the variables \$n0$\ -- |
| 24305 | \$n9$\ are copied into \$sn0$\ -- \$sn9$\ and are thereby made available to |
| 24306 | users' filter files. Thus a system filter can, for example, set up `scores' to |
| 24307 | which users' filter files can refer. |
| 24308 | |
| 24309 | |
| 24310 | .section Additional variable for system filters |
| 24311 | The expansion variable \$recipients$\, containing a list of all the recipients |
| 24312 | of the message (separated by commas and white space), is available in system |
| 24313 | filters. It is not available in users' filters for privacy reasons. |
| 24314 | |
| 24315 | |
| 24316 | .section Defer, freeze, and fail commands for system filters |
| 24317 | .index freezing messages |
| 24318 | .index message||freezing |
| 24319 | .index message||forced failure |
| 24320 | .index \fail\||in system filter |
| 24321 | .index \freeze\ in system filter |
| 24322 | .index \defer\ in system filter |
| 24323 | There are three extra commands (\defer\, \freeze\ and \fail\) which are always |
| 24324 | available in system filters, but are not normally enabled in users' filters. |
| 24325 | (See the \allow@_defer\, |
| 24326 | \allow@_freeze\ and \allow@_fail\ options for the \%redirect%\ router.) These |
| 24327 | commands can optionally be followed by the word \text\ and a string containing |
| 24328 | an error message, for example: |
| 24329 | .display asis |
| 24330 | fail text "this message looks like spam to me" |
| 24331 | .endd |
| 24332 | The keyword \text\ is optional if the next character is a double quote. |
| 24333 | |
| 24334 | The \defer\ command defers delivery of the original recipients of the message. |
| 24335 | The \fail\ command causes all the original recipients to be failed, and a |
| 24336 | bounce message to be created. The \freeze\ command suspends all delivery |
| 24337 | attempts for the original recipients. In all cases, any new deliveries that are |
| 24338 | specified by the filter are attempted as normal after the filter has run. |
| 24339 | |
| 24340 | The \freeze\ command is ignored if the message has been manually unfrozen and |
| 24341 | not manually frozen since. This means that automatic freezing by a system |
| 24342 | filter can be used as a way of checking out suspicious messages. If a message |
| 24343 | is found to be all right, manually unfreezing it allows it to be delivered. |
| 24344 | |
| 24345 | .index log||\fail\ command log line |
| 24346 | .index \fail\||log line, reducing |
| 24347 | The text given with a fail command is used as part of the bounce message as |
| 24348 | well as being written to the log. If the message is quite long, this can fill |
| 24349 | up a lot of log space when such failures are common. To reduce the size of the |
| 24350 | log message, Exim interprets the text in a special way if it starts with the |
| 24351 | two characters \"@<@<"\ and contains \"@>@>"\ later. The text between these two |
| 24352 | strings is written to the log, and the rest of the text is used in the bounce |
| 24353 | message. For example: |
| 24354 | .display asis |
| 24355 | fail "<<filter test 1>>Your message is rejected \ |
| 24356 | because it contains attachments that we are \ |
| 24357 | not prepared to receive." |
| 24358 | .endd |
| 24359 | |
| 24360 | .index loop||caused by \fail\ |
| 24361 | Take great care with the \fail\ command when basing the decision to fail on the |
| 24362 | contents of the message, because the bounce message will of course include the |
| 24363 | contents of the original message and will therefore trigger the \fail\ command |
| 24364 | again (causing a mail loop) unless steps are taken to prevent this. Testing the |
| 24365 | \error@_message\ condition is one way to prevent this. You could use, for |
| 24366 | example |
| 24367 | .display asis |
| 24368 | if $message_body contains "this is spam" and not error_message |
| 24369 | then fail text "spam is not wanted here" endif |
| 24370 | .endd |
| 24371 | though of course that might let through unwanted bounce messages. The |
| 24372 | alternative is clever checking of the body and/or headers to detect bounces |
| 24373 | generated by the filter. |
| 24374 | |
| 24375 | The interpretation of a system filter file ceases after a |
| 24376 | \defer\, |
| 24377 | \freeze\, or \fail\ command is obeyed. However, any deliveries that were set up |
| 24378 | earlier in the filter file are honoured, so you can use a sequence such as |
| 24379 | .display asis |
| 24380 | mail ... |
| 24381 | freeze |
| 24382 | .endd |
| 24383 | to send a specified message when the system filter is freezing (or deferring or |
| 24384 | failing) a message. The normal deliveries for the message do not, of course, |
| 24385 | take place. |
| 24386 | |
| 24387 | |
| 24388 | .section Adding and removing headers in a system filter |
| 24389 | .index header lines||adding in system filter |
| 24390 | .index header lines||removing in system filter |
| 24391 | .index filter||header lines, adding/removing |
| 24392 | Two filter commands that are available only in system filters are: |
| 24393 | .display asis |
| 24394 | headers add <<string>> |
| 24395 | headers remove <<string>> |
| 24396 | .endd |
| 24397 | The argument for the \headers add\ is a string which is expanded and then added |
| 24398 | to the end of the message's headers. It is the responsibility of the filter |
| 24399 | maintainer to make sure it conforms to RFC 2822 syntax. Leading white space is |
| 24400 | ignored, and if the string is otherwise empty, or if the expansion is forced to |
| 24401 | fail, the command has no effect. |
| 24402 | |
| 24403 | If the message is not delivered at the first attempt, header lines that were |
| 24404 | added by the system filter are stored with the message, and so are still |
| 24405 | present at the next delivery attempt. For that reason, it is usual to make the |
| 24406 | \headers add\ command conditional on \first@_delivery\. |
| 24407 | |
| 24408 | You can use `@\n' within the string, followed by white space, to specify |
| 24409 | continued header lines. More than one header may be added in one command by |
| 24410 | including `@\n' within the string without any following white space. For |
| 24411 | example: |
| 24412 | .display asis |
| 24413 | headers add "X-header-1: ....\n \ |
| 24414 | continuation of X-header-1 ...\n\ |
| 24415 | X-header-2: ...." |
| 24416 | .endd |
| 24417 | Note that the header line continuation white space after the first newline must |
| 24418 | be placed before the backslash that continues the input string, because white |
| 24419 | space after input continuations is ignored. |
| 24420 | |
| 24421 | Header lines that are added by a system filter are visible to users' filter |
| 24422 | files and to all routers and transports. |
| 24423 | |
| 24424 | The argument for \headers remove\ is a colon-separated list of header names. |
| 24425 | This command applies only to those headers that are stored with the message; |
| 24426 | those that are added at delivery time (such as ::Envelope-To:: and |
| 24427 | ::Return-Path::) cannot be removed by this means. |
| 24428 | If there is more than one header with the same name, they are all removed. |
| 24429 | |
| 24430 | |
| 24431 | .section Setting an errors address in a system filter |
| 24432 | .index envelope sender |
| 24433 | In a system filter, if a \deliver\ command is followed by |
| 24434 | .display |
| 24435 | errors@_to <<some address>> |
| 24436 | .endd |
| 24437 | in order to change the envelope sender (and hence the error reporting) for that |
| 24438 | delivery, any address may be specified. (In a user filter, only the current |
| 24439 | user's address can be set.) For example, if some mail is being monitored, you |
| 24440 | might use |
| 24441 | .display asis |
| 24442 | unseen deliver monitor@spying.example errors_to root@local.example |
| 24443 | .endd |
| 24444 | to take a copy which would not be sent back to the normal error reporting |
| 24445 | address if its delivery failed. |
| 24446 | |
| 24447 | |
| 24448 | .section Per-address filtering |
| 24449 | .rset SECTperaddfil "~~chapter.~~section" |
| 24450 | In contrast to the system filter, which is run just once per message for each |
| 24451 | delivery attempt, it is also possible to set up a system-wide filtering |
| 24452 | operation that runs once for each recipient address. In this case, variables |
| 24453 | such as \$local@_part$\ and \$domain$\ can be used, and indeed, the choice of |
| 24454 | filter file could be made dependent on them. This is an example of a router |
| 24455 | which implements such a filter: |
| 24456 | .display asis |
| 24457 | central_filter: |
| 24458 | .newline |
| 24459 | check_local_user |
| 24460 | .newline |
| 24461 | driver = redirect |
| 24462 | domains = +local_domains |
| 24463 | file = /central/filters/$local_part |
| 24464 | no_verify |
| 24465 | allow_filter |
| 24466 | allow_freeze |
| 24467 | .endd |
| 24468 | The filter is run in a separate process under its own uid. Therefore, either |
| 24469 | \check@_local@_user\ must be set (as above), in which case the filter is run as |
| 24470 | the local user, or the \user\ option must be used to specify which user to use. |
| 24471 | If both are set, \user\ overrides. |
| 24472 | |
| 24473 | Care should be taken to ensure that none of the commands in the filter file |
| 24474 | specify a significant delivery if the message is to go on to be delivered to |
| 24475 | its intended recipient. The router will not then claim to have dealt with the |
| 24476 | address, so it will be passed on to subsequent routers to be delivered in the |
| 24477 | normal way. |
| 24478 | |
| 24479 | |
| 24480 | |
| 24481 | |
| 24482 | |
| 24483 | . |
| 24484 | . |
| 24485 | . |
| 24486 | . |
| 24487 | . ============================================================================ |
| 24488 | .chapter Customizing bounce and warning messages |
| 24489 | .set runningfoot "customizing messages" |
| 24490 | .rset CHAPemsgcust "~~chapter" |
| 24491 | When a message fails to be delivered, or remains on the queue for more than a |
| 24492 | configured amount of time, Exim sends a message to the original sender, or |
| 24493 | to an alternative configured address. The text of these messages is built into |
| 24494 | the code of Exim, but it is possible to change it, either by adding a single |
| 24495 | string, or by replacing each of the paragraphs by text supplied in a file. |
| 24496 | |
| 24497 | The ::From:: and ::To:: header lines are automatically generated; you can cause |
| 24498 | a ::Reply-To:: line to be added by setting the \errors@_reply@_to\ option. Exim |
| 24499 | also adds the line |
| 24500 | .display asis |
| 24501 | Auto-Submitted: auto-generated |
| 24502 | .endd |
| 24503 | to all warning and bounce messages, |
| 24504 | |
| 24505 | .section Customizing bounce messages |
| 24506 | .index customizing||bounce message |
| 24507 | .index bounce message||customizing |
| 24508 | If \bounce@_message@_text\ is set, its contents are included in the default |
| 24509 | message immediately after `This message was created automatically by mail |
| 24510 | delivery software.' The string is not expanded. It is not used if |
| 24511 | \bounce@_message@_file\ is set. |
| 24512 | |
| 24513 | When \bounce@_message@_file\ is set, it must point to a template file for |
| 24514 | constructing error messages. The file consists of a series of text items, |
| 24515 | separated by lines consisting of exactly four asterisks. If the file cannot be |
| 24516 | opened, default text is used and a message is written to the main and panic |
| 24517 | logs. If any text item in the file is empty, default text is used for that |
| 24518 | item. |
| 24519 | |
| 24520 | Each item of text that is read from the file is expanded, and there are two |
| 24521 | expansion variables which can be of use here: \$bounce@_recipient$\ is set to |
| 24522 | the recipient of an error message while it is being created, and |
| 24523 | \$return@_size@_limit$\ contains the value of the \return@_size@_limit\ option, |
| 24524 | rounded to a whole number. |
| 24525 | |
| 24526 | The items must appear in the file in the following order: |
| 24527 | .numberpars $. |
| 24528 | The first item is included in the headers, and should include at least a |
| 24529 | ::Subject:: header. Exim does not check the syntax of these headers. |
| 24530 | .nextp |
| 24531 | The second item forms the start of the error message. After it, Exim lists the |
| 24532 | failing addresses with their error messages. |
| 24533 | .nextp |
| 24534 | The third item is used to introduce any text from pipe transports that is to be |
| 24535 | returned to the sender. It is omitted if there is no such text. |
| 24536 | .nextp |
| 24537 | The fourth item is used to introduce the copy of the message that is returned |
| 24538 | as part of the error report. |
| 24539 | .nextp |
| 24540 | The fifth item is added after the fourth one if the returned message is |
| 24541 | truncated because it is bigger than \return@_size@_limit\. |
| 24542 | .nextp |
| 24543 | The sixth item is added after the copy of the original message. |
| 24544 | .endp |
| 24545 | The default state (\bounce@_message@_file\ unset) is equivalent to the |
| 24546 | following file, in which the sixth item is empty. The ::Subject:: line has been |
| 24547 | split into two here in order to fit it on the page: |
| 24548 | .if ~~sys.fancy |
| 24549 | .display flow asis |
| 24550 | .fontgroup 0 |
| 24551 | .font 54 |
| 24552 | .else |
| 24553 | .rule |
| 24554 | .display flow asis |
| 24555 | .linelength 80em |
| 24556 | .indent 0 |
| 24557 | .fi |
| 24558 | Subject: Mail delivery failed |
| 24559 | ${if eq{$sender_address}{$bounce_recipient}{: returning message to sender}} |
| 24560 | **** |
| 24561 | This message was created automatically by mail delivery software. |
| 24562 | |
| 24563 | A message ${if eq{$sender_address}{$bounce_recipient}{that you sent }{sent by |
| 24564 | |
| 24565 | <$sender_address> |
| 24566 | |
| 24567 | }}could not be delivered to all of its recipients. |
| 24568 | The following address(es) failed: |
| 24569 | **** |
| 24570 | The following text was generated during the delivery attempt(s): |
| 24571 | **** |
| 24572 | ------ This is a copy of the message, including all the headers. ------ |
| 24573 | **** |
| 24574 | ------ The body of the message is $message_size characters long; only the first |
| 24575 | ------ $return_size_limit or so are included here. |
| 24576 | **** |
| 24577 | .endd |
| 24578 | .if !~~sys.fancy |
| 24579 | .rule |
| 24580 | .fi |
| 24581 | |
| 24582 | .section Customizing warning messages |
| 24583 | .rset SECTcustwarn "~~chapter.~~section" |
| 24584 | .index customizing||warning message |
| 24585 | .index warning of delay||customizing the message |
| 24586 | The option |
| 24587 | \warn@_message@_file\ |
| 24588 | can be pointed at a template file for use when |
| 24589 | warnings about message delays are created. In this case there are only three |
| 24590 | text sections: |
| 24591 | .numberpars $. |
| 24592 | The first item is included in the headers, and should include at least a |
| 24593 | ::Subject:: header. Exim does not check the syntax of these headers. |
| 24594 | .nextp |
| 24595 | The second item forms the start of the warning message. After it, Exim lists |
| 24596 | the delayed addresses. |
| 24597 | .nextp |
| 24598 | The third item then ends the message. |
| 24599 | .endp |
| 24600 | The default state is equivalent to the following file, except that the line |
| 24601 | starting `A message' has been split here, in order to fit it on the page: |
| 24602 | .if ~~sys.fancy |
| 24603 | .display asis |
| 24604 | .fontgroup 0 |
| 24605 | .font 54 |
| 24606 | .else |
| 24607 | .rule |
| 24608 | .display asis |
| 24609 | .linelength 80em |
| 24610 | .indent 0 |
| 24611 | .fi |
| 24612 | .newline |
| 24613 | Subject: Warning: message $message_id delayed $warn_message_delay |
| 24614 | **** |
| 24615 | This message was created automatically by mail delivery software. |
| 24616 | |
| 24617 | A message ${if eq{$sender_address}{$warn_message_recipients} |
| 24618 | {that you sent }{sent by |
| 24619 | |
| 24620 | <$sender_address> |
| 24621 | |
| 24622 | }}has not been delivered to all of its recipients after |
| 24623 | more than $warn_message_delay on the queue on $primary_hostname. |
| 24624 | .newline |
| 24625 | |
| 24626 | The message identifier is: $message_id |
| 24627 | The subject of the message is: $h_subject |
| 24628 | The date of the message is: $h_date |
| 24629 | |
| 24630 | The following address(es) have not yet been delivered: |
| 24631 | **** |
| 24632 | No action is required on your part. Delivery attempts will continue for |
| 24633 | some time, and this warning may be repeated at intervals if the message |
| 24634 | remains undelivered. Eventually the mail delivery software will give up, |
| 24635 | and when that happens, the message will be returned to you. |
| 24636 | .endd |
| 24637 | .if !~~sys.fancy |
| 24638 | .rule |
| 24639 | .fi |
| 24640 | except that in the default state the subject and date lines are omitted if no |
| 24641 | appropriate headers exist. During the expansion of this file, |
| 24642 | \$warn@_message@_delay$\ |
| 24643 | is set to the delay time in one of the forms `<<n>> minutes' |
| 24644 | or `<<n>> hours', and |
| 24645 | \$warn@_message@_recipients$\ |
| 24646 | contains a list of recipients for the warning message. There may be more than |
| 24647 | one if there are multiple addresses with different \errors@_to\ settings on the |
| 24648 | routers that handled them. |
| 24649 | |
| 24650 | |
| 24651 | |
| 24652 | |
| 24653 | . |
| 24654 | . |
| 24655 | . |
| 24656 | . ============================================================================ |
| 24657 | .chapter Some common configuration requirements |
| 24658 | .set runningfoot "common configuration requirements" |
| 24659 | .rset CHAPcomconreq "~~chapter" |
| 24660 | This chapter discusses some configuration requirements that seem to be fairly |
| 24661 | common. More examples and discussion can be found in the Exim book. |
| 24662 | |
| 24663 | |
| 24664 | .section Sending mail to a smart host |
| 24665 | .index smart host||example router |
| 24666 | If you want to send all mail for non-local domains to a `smart host', you |
| 24667 | should replace the default \%dnslookup%\ router with a router which does the |
| 24668 | routing explicitly: |
| 24669 | .display asis |
| 24670 | send_to_smart_host: |
| 24671 | driver = manualroute |
| 24672 | route_list = !+local_domains smart.host.name |
| 24673 | transport = remote_smtp |
| 24674 | .endd |
| 24675 | You can use the smart host's IP address instead of the name if you wish. |
| 24676 | |
| 24677 | |
| 24678 | .section Using Exim to handle mailing lists |
| 24679 | .rset SECTmailinglists "~~chapter.~~section" |
| 24680 | .index mailing lists |
| 24681 | Exim can be used to run simple mailing lists, but for large and/or complicated |
| 24682 | requirements, the use of additional specialized mailing list software such as |
| 24683 | Majordomo or Mailman is recommended. |
| 24684 | |
| 24685 | The \%redirect%\ router can be used to handle mailing lists where each list |
| 24686 | is maintained in a separate file, which can therefore be managed by an |
| 24687 | independent manager. The \domains\ router option can be used to run these |
| 24688 | lists in a separate domain from normal mail. For example: |
| 24689 | .display asis |
| 24690 | lists: |
| 24691 | driver = redirect |
| 24692 | domains = lists.example |
| 24693 | file = /usr/lists/$local_part |
| 24694 | forbid_pipe |
| 24695 | forbid_file |
| 24696 | errors_to = $local_part-request@lists.example |
| 24697 | no_more |
| 24698 | .endd |
| 24699 | This router is skipped for domains other than \*lists.example*\. For addresses |
| 24700 | in that domain, it looks for a file that matches the local part. If there is no |
| 24701 | such file, the router declines, but because \no@_more\ is set, no subsequent |
| 24702 | routers are tried, and so the whole delivery fails. |
| 24703 | |
| 24704 | The \forbid@_pipe\ and \forbid@_file\ options prevent a local part from being |
| 24705 | expanded into a file name or a pipe delivery, which is usually inappropriate in |
| 24706 | a mailing list. |
| 24707 | |
| 24708 | .index \errors@_to\ |
| 24709 | The \errors@_to\ option specifies that any delivery errors caused by addresses |
| 24710 | taken from a mailing list are to be sent to the given address rather than the |
| 24711 | original sender of the message. However, before acting on this, Exim verifies |
| 24712 | the error address, and ignores it if verification fails. |
| 24713 | |
| 24714 | For example, using the configuration above, mail sent to |
| 24715 | \*dicts@@lists.example*\ is passed on to those addresses contained in |
| 24716 | \(/usr/lists/dicts)\, with error reports directed to |
| 24717 | \*dicts-request@@lists.example*\, provided that this address can be verified. |
| 24718 | There could be a file called \(/usr/lists/dicts-request)\ containing |
| 24719 | the address(es) of this particular list's manager(s), but other approaches, |
| 24720 | such as setting up an earlier router (possibly using the \local@_part@_prefix\ |
| 24721 | or \local@_part@_suffix\ options) to handle addresses of the form \owner-xxx\ |
| 24722 | or \xxx-request\, are also possible. |
| 24723 | |
| 24724 | |
| 24725 | .section Syntax errors in mailing lists |
| 24726 | .index mailing lists||syntax errors in |
| 24727 | If an entry in redirection data contains a syntax error, Exim normally defers |
| 24728 | delivery of the original address. That means that a syntax error in a mailing |
| 24729 | list holds up all deliveries to the list. This may not be appropriate when a |
| 24730 | list is being maintained automatically from data supplied by users, and the |
| 24731 | addresses are not rigorously checked. |
| 24732 | |
| 24733 | If the \skip@_syntax@_errors\ option is set, the \%redirect%\ router just skips |
| 24734 | entries that fail to parse, noting the incident in the log. If in addition |
| 24735 | \syntax@_errors@_to\ is set to a verifiable address, a message is sent to it |
| 24736 | whenever a broken address is skipped. It is usually appropriate to set |
| 24737 | \syntax@_errors@_to\ to the same address as \errors@_to\. |
| 24738 | |
| 24739 | |
| 24740 | .section Re-expansion of mailing lists |
| 24741 | .index mailing lists||re-expansion of |
| 24742 | Exim remembers every individual address to which a message has been delivered, |
| 24743 | in order to avoid duplication, but it normally stores only the original |
| 24744 | recipient addresses with a message. If all the deliveries to a mailing list |
| 24745 | cannot be done at the first attempt, the mailing list is re-expanded when the |
| 24746 | delivery is next tried. This means that alterations to the list are taken into |
| 24747 | account at each delivery attempt, so addresses that have been added to |
| 24748 | the list since the message arrived will therefore receive a copy of the |
| 24749 | message, even though it pre-dates their subscription. |
| 24750 | |
| 24751 | If this behaviour is felt to be undesirable, the \one@_time\ option can be set |
| 24752 | on the \%redirect%\ router. If this is done, any addresses generated by the |
| 24753 | router that fail to deliver at the first attempt are added to the message as |
| 24754 | `top level' addresses, and the parent address that generated them is marked |
| 24755 | `delivered'. Thus, expansion of the mailing list does not happen again at the |
| 24756 | subsequent delivery attempts. The disadvantage of this is that if any of the |
| 24757 | failing addresses are incorrect, correcting them in the file has no effect on |
| 24758 | pre-existing messages. |
| 24759 | |
| 24760 | The original top-level address is remembered with each of the generated |
| 24761 | addresses, and is output in any log messages. However, any intermediate parent |
| 24762 | addresses are not recorded. This makes a difference to the log only if the |
| 24763 | \all@_parents\ selector is set, but for mailing lists there is normally only |
| 24764 | one level of expansion anyway. |
| 24765 | |
| 24766 | |
| 24767 | .section Closed mailing lists |
| 24768 | .index mailing lists||closed |
| 24769 | The examples so far have assumed open mailing lists, to which anybody may |
| 24770 | send mail. It is also possible to set up closed lists, where mail is accepted |
| 24771 | from specified senders only. This is done by making use of the generic |
| 24772 | \senders\ option to restrict the router that handles the list. |
| 24773 | |
| 24774 | The following example uses the same file as a list of recipients and as a list |
| 24775 | of permitted senders. It requires three routers: |
| 24776 | .display asis |
| 24777 | lists_request: |
| 24778 | driver = redirect |
| 24779 | domains = lists.example |
| 24780 | local_part_suffix = -request |
| 24781 | file = /usr/lists/$local_part$local_part_suffix |
| 24782 | no_more |
| 24783 | |
| 24784 | lists_post: |
| 24785 | driver = redirect |
| 24786 | domains = lists.example |
| 24787 | senders = ${if exists {/usr/lists/$local_part}\ |
| 24788 | {lsearch;/usr/lists/$local_part}{*}} |
| 24789 | file = /usr/lists/$local_part |
| 24790 | forbid_pipe |
| 24791 | forbid_file |
| 24792 | errors_to = $local_part-request@lists.example |
| 24793 | no_more |
| 24794 | |
| 24795 | lists_closed: |
| 24796 | driver = redirect |
| 24797 | domains = lists.example |
| 24798 | allow_fail |
| 24799 | data = :fail: $local_part@lists.example is a closed mailing list |
| 24800 | .endd |
| 24801 | All three routers have the same \domains\ setting, so for any other domains, |
| 24802 | they are all skipped. The first router runs only if the local part ends in |
| 24803 | \@-request\. It handles messages to the list manager(s) by means of an open |
| 24804 | mailing list. |
| 24805 | |
| 24806 | The second router runs only if the \senders\ precondition is satisfied. It |
| 24807 | checks for the existence of a list that corresponds to the local part, and then |
| 24808 | checks that the sender is on the list by means of a linear search. It is |
| 24809 | necessary to check for the existence of the file before trying to search it, |
| 24810 | because otherwise Exim thinks there is a configuration error. If the file does |
| 24811 | not exist, the expansion of \senders\ is $*$, which matches all senders. This |
| 24812 | means that the router runs, but because there is no list, declines, and |
| 24813 | \no@_more\ ensures that no further routers are run. The address fails with an |
| 24814 | `unrouteable address' error. |
| 24815 | |
| 24816 | The third router runs only if the second router is skipped, which happens when |
| 24817 | a mailing list exists, but the sender is not on it. This router forcibly fails |
| 24818 | the address, giving a suitable error message. |
| 24819 | |
| 24820 | |
| 24821 | |
| 24822 | .section Virtual domains |
| 24823 | .rset SECTvirtualdomains "~~chapter.~~section" |
| 24824 | .index virtual domains |
| 24825 | .index domain||virtual |
| 24826 | The phrase \*virtual domain*\ is unfortunately used with two rather different |
| 24827 | meanings: |
| 24828 | .numberpars $. |
| 24829 | A domain for which there are no real mailboxes; all valid local parts are |
| 24830 | aliases for other email addresses. Common examples are organizational |
| 24831 | top-level domains and `vanity' domains. |
| 24832 | .nextp |
| 24833 | One of a number of independent domains that are all handled by the same host, |
| 24834 | with mailboxes on that host, but where the mailbox owners do not necessarily |
| 24835 | have login accounts on that host. |
| 24836 | .endp |
| 24837 | The first usage is probably more common, and does seem more `virtual' than the |
| 24838 | second. This kind of domain can be handled in Exim with a straightforward |
| 24839 | aliasing router. One approach is to create a separate alias file for each |
| 24840 | virtual domain. Exim can test for the existence of the alias file to determine |
| 24841 | whether the domain exists. The \%dsearch%\ lookup type is useful here, leading |
| 24842 | to a router of this form: |
| 24843 | .display asis |
| 24844 | virtual: |
| 24845 | driver = redirect |
| 24846 | domains = dsearch;/etc/mail/virtual |
| 24847 | data = ${lookup{$local_part}lsearch{/etc/mail/virtual/$domain}} |
| 24848 | no_more |
| 24849 | .endd |
| 24850 | The \domains\ option specifies that the router is to be skipped, unless there |
| 24851 | is a file in the \(/etc/mail/virtual)\ directory whose name is the same as the |
| 24852 | domain that is being processed. When the router runs, it looks up the local |
| 24853 | part in the file to find a new address (or list of addresses). The \no@_more\ |
| 24854 | setting ensures that if the lookup fails (leading to \data\ being an empty |
| 24855 | string), Exim gives up on the address without trying any subsequent routers. |
| 24856 | |
| 24857 | This one router can handle all the virtual domains because the alias file names |
| 24858 | follow a fixed pattern. Permissions can be arranged so that appropriate people |
| 24859 | can edit the different alias files. A successful aliasing operation results in |
| 24860 | a new envelope recipient address, which is then routed from scratch. |
| 24861 | |
| 24862 | The other kind of `virtual' domain can also be handled in a straightforward |
| 24863 | way. One approach is to create a file for each domain containing a list of |
| 24864 | valid local parts, and use it in a router like this: |
| 24865 | .display asis |
| 24866 | my_domains: |
| 24867 | driver = accept |
| 24868 | domains = dsearch;/etc/mail/domains |
| 24869 | local_parts = lsearch;/etc/mail/domains/$domain |
| 24870 | transport = my_mailboxes |
| 24871 | .endd |
| 24872 | The address is accepted if there is a file for the domain, and the local part |
| 24873 | can be found in the file. The \domains\ option is used to check for the file's |
| 24874 | existence because \domains\ is tested before the \local@_parts\ option (see |
| 24875 | section ~~SECTrouprecon). You can't use \require@_files\, because that option |
| 24876 | is tested after \local@_parts\. The transport is as follows: |
| 24877 | .display asis |
| 24878 | my_mailboxes: |
| 24879 | driver = appendfile |
| 24880 | file = /var/mail/$domain/$local_part |
| 24881 | user = mail |
| 24882 | .endd |
| 24883 | This uses a directory of mailboxes for each domain. The \user\ setting is |
| 24884 | required, to specify which uid is to be used for writing to the mailboxes. |
| 24885 | |
| 24886 | The configuration shown here is just one example of how you might support this |
| 24887 | requirement. There are many other ways this kind of configuration can be set |
| 24888 | up, for example, by using a database instead of separate files to hold all the |
| 24889 | information about the domains. |
| 24890 | |
| 24891 | |
| 24892 | .section Multiple user mailboxes |
| 24893 | .rset SECTmulbox "~~chapter.~~section" |
| 24894 | .index multiple mailboxes |
| 24895 | .index mailbox||multiple |
| 24896 | .index local part||prefix |
| 24897 | .index local part||suffix |
| 24898 | Heavy email users often want to operate with multiple mailboxes, into which |
| 24899 | incoming mail is automatically sorted. A popular way of handling this is to |
| 24900 | allow users to use multiple sender addresses, so that replies can easily be |
| 24901 | identified. Users are permitted to add prefixes or suffixes to their local |
| 24902 | parts for this purpose. The wildcard facility of the generic router options |
| 24903 | \local@_part@_prefix\ and \local@_part@_suffix\ can be used for this. For |
| 24904 | example, consider this router: |
| 24905 | .display asis |
| 24906 | userforward: |
| 24907 | driver = redirect |
| 24908 | check_local_user |
| 24909 | file = $home/.forward |
| 24910 | local_part_suffix = -* |
| 24911 | local_part_suffix_optional |
| 24912 | allow_filter |
| 24913 | .endd |
| 24914 | It runs a user's \(.forward)\ file for all local parts of the form |
| 24915 | \*username-$*$*\. Within the filter file the user can distinguish different |
| 24916 | cases by testing the variable \$local@_part@_suffix$\. For example: |
| 24917 | .display asis |
| 24918 | if $local_part_suffix contains -special then |
| 24919 | save /home/$local_part/Mail/special |
| 24920 | endif |
| 24921 | .endd |
| 24922 | If the filter file does not exist, or does not deal with such addresses, they |
| 24923 | fall through to subsequent routers, and, assuming no subsequent use of the |
| 24924 | \local@_part@_suffix\ option is made, they presumably fail. Thus, users have |
| 24925 | control over which suffixes are valid. |
| 24926 | |
| 24927 | Alternatively, a suffix can be used to trigger the use of a different |
| 24928 | \(.forward)\ file -- which is the way a similar facility is implemented in |
| 24929 | another MTA: |
| 24930 | .display asis |
| 24931 | userforward: |
| 24932 | driver = redirect |
| 24933 | check_local_user |
| 24934 | file = $home/.forward$local_part_suffix |
| 24935 | local_part_suffix = -* |
| 24936 | local_part_suffix_optional |
| 24937 | allow_filter |
| 24938 | .endd |
| 24939 | If there is no suffix, \(.forward)\ is used; if the suffix is \*-special*\, for |
| 24940 | example, \(.forward-special)\ is used. Once again, if the appropriate file |
| 24941 | does not exist, or does not deal with the address, it is passed on to |
| 24942 | subsequent routers, which could, if required, look for an unqualified |
| 24943 | \(.forward)\ file to use as a default. |
| 24944 | |
| 24945 | |
| 24946 | .section Simplified vacation processing |
| 24947 | .index vacation processing |
| 24948 | The traditional way of running the \*vacation*\ program is for a user to set up |
| 24949 | a pipe command in a \(.forward)\ file |
| 24950 | (see section ~~SECTspecitredli for syntax details). |
| 24951 | This is prone to error by inexperienced users. There are two features of Exim |
| 24952 | that can be used to make this process simpler for users: |
| 24953 | .numberpars $. |
| 24954 | A local part prefix such as `vacation-' can be specified on a router which |
| 24955 | can cause the message to be delivered directly to the \*vacation*\ program, or |
| 24956 | alternatively can use Exim's \%autoreply%\ transport. The contents of a user's |
| 24957 | \(.forward)\ file are then much simpler. For example: |
| 24958 | .display asis |
| 24959 | spqr, vacation-spqr |
| 24960 | .endd |
| 24961 | .nextp |
| 24962 | The \require@_files\ generic router option can be used to trigger a |
| 24963 | vacation delivery by checking for the existence of a certain file in the |
| 24964 | user's home directory. The \unseen\ generic option should also be used, to |
| 24965 | ensure that the original delivery also proceeds. In this case, all the user has |
| 24966 | to do is to create a file called, say, \(.vacation)\, containing a vacation |
| 24967 | message. |
| 24968 | .endp |
| 24969 | Another advantage of both these methods is that they both work even when the |
| 24970 | use of arbitrary pipes by users is locked out. |
| 24971 | |
| 24972 | |
| 24973 | .section Taking copies of mail |
| 24974 | .index message||copying every |
| 24975 | Some installations have policies that require archive copies of all messages to |
| 24976 | be made. A single copy of each message can easily be taken by an appropriate |
| 24977 | command in a system filter, which could, for example, use a different file for |
| 24978 | each day's messages. |
| 24979 | |
| 24980 | There is also a shadow transport mechanism that can be used to take copies of |
| 24981 | messages that are successfully delivered by local transports, one copy per |
| 24982 | delivery. This could be used, $it{inter alia}, to implement automatic |
| 24983 | notification of delivery by sites that insist on doing such things. |
| 24984 | |
| 24985 | |
| 24986 | .section Intermittently connected hosts |
| 24987 | .index intermittently connected hosts |
| 24988 | It has become quite common (because it is cheaper) for hosts to connect to the |
| 24989 | Internet periodically rather than remain connected all the time. The normal |
| 24990 | arrangement is that mail for such hosts accumulates on a system that is |
| 24991 | permanently connected. |
| 24992 | |
| 24993 | Exim was designed for use on permanently connected hosts, and so it is not |
| 24994 | particularly well-suited to use in an intermittently connected environment. |
| 24995 | Nevertheless there are some features that can be used. |
| 24996 | |
| 24997 | .section Exim on the upstream server host |
| 24998 | It is tempting to arrange for incoming mail for the intermittently connected |
| 24999 | host to remain on Exim's queue until the client connects. However, this |
| 25000 | approach does not scale very well. Two different kinds of waiting message are |
| 25001 | being mixed up in the same queue -- those that cannot be delivered because of |
| 25002 | some temporary problem, and those that are waiting for their destination host |
| 25003 | to connect. This makes it hard to manage the queue, as well as wasting |
| 25004 | resources, because each queue runner scans the entire queue. |
| 25005 | |
| 25006 | A better approach is to separate off those messages that are waiting for an |
| 25007 | intermittently connected host. This can be done by delivering these messages |
| 25008 | into local files in batch SMTP, `mailstore', or other envelope-preserving |
| 25009 | format, from where they are transmitted by other software when their |
| 25010 | destination connects. This makes it easy to collect all the mail for one host |
| 25011 | in a single directory, and to apply local timeout rules on a per-message basis |
| 25012 | if required. |
| 25013 | |
| 25014 | On a very small scale, leaving the mail on Exim's queue can be made to work. If |
| 25015 | you are doing this, you should configure Exim with a long retry period for the |
| 25016 | intermittent host. For example: |
| 25017 | .display |
| 25018 | cheshire.wonderland.fict.example * F,5d,24h |
| 25019 | .endd |
| 25020 | This stops a lot of failed delivery attempts from occurring, but Exim remembers |
| 25021 | which messages it has queued up for that host. Once the intermittent host comes |
| 25022 | online, forcing delivery of one message (either by using the \-M-\ or \-R-\ |
| 25023 | options, or by using the \\ETRN\\ SMTP command (see section ~~SECTETRN) |
| 25024 | causes all the queued up messages to be delivered, often down a single SMTP |
| 25025 | connection. While the host remains connected, any new messages get delivered |
| 25026 | immediately. |
| 25027 | |
| 25028 | If the connecting hosts do not have fixed IP addresses, that is, if a host is |
| 25029 | issued with a different IP address each time it connects, Exim's retry |
| 25030 | mechanisms on the holding host get confused, because the IP address is normally |
| 25031 | used as part of the key string for holding retry information. This can be |
| 25032 | avoided by unsetting \retry__include__ip__address\ on the \%smtp%\ transport. |
| 25033 | Since this has disadvantages for permanently connected hosts, it is best to |
| 25034 | arrange a separate transport for the intermittently connected ones. |
| 25035 | |
| 25036 | |
| 25037 | .section Exim on the intermittently connected client host |
| 25038 | The value of \smtp@_accept@_queue@_per@_connection\ should probably be |
| 25039 | increased, or even set to zero (that is, disabled) on the intermittently |
| 25040 | connected host, so that all incoming messages down a single connection get |
| 25041 | delivered immediately. |
| 25042 | |
| 25043 | .index SMTP||passed connection |
| 25044 | .index SMTP||multiple deliveries |
| 25045 | .index multiple SMTP deliveries |
| 25046 | Mail waiting to be sent from an intermittently connected host will probably |
| 25047 | not have been routed, because without a connection DNS lookups are not |
| 25048 | possible. This means that if a normal queue run is done at connection time, |
| 25049 | each message is likely to be sent in a separate SMTP session. This can be |
| 25050 | avoided by starting the queue run with a command line option beginning with |
| 25051 | \-qq-\ instead of \-q-\. In this case, the queue is scanned twice. In the first |
| 25052 | pass, routing is done but no deliveries take place. The second pass is a normal |
| 25053 | queue run; since all the messages have been previously routed, those destined |
| 25054 | for the same host are likely to get sent as multiple deliveries in a single |
| 25055 | SMTP connection. |
| 25056 | |
| 25057 | |
| 25058 | |
| 25059 | |
| 25060 | |
| 25061 | . |
| 25062 | . |
| 25063 | . |
| 25064 | . |
| 25065 | . ============================================================================ |
| 25066 | .chapter SMTP processing |
| 25067 | .set runningfoot "smtp processing" |
| 25068 | .rset CHAPSMTP ~~chapter |
| 25069 | .index SMTP||processing details |
| 25070 | .index LMTP||processing details |
| 25071 | Exim supports a number of different ways of using the SMTP protocol, and its |
| 25072 | LMTP variant, which is an interactive protocol for transferring messages into a |
| 25073 | closed mail store application. This chapter contains details of how SMTP is |
| 25074 | processed. For incoming mail, the following are available: |
| 25075 | .numberpars $. |
| 25076 | SMTP over TCP/IP (Exim daemon or \*inetd*\); |
| 25077 | .nextp |
| 25078 | SMTP over the standard input and output (the \-bs-\ option); |
| 25079 | .nextp |
| 25080 | Batched SMTP on the standard input (the \-bS-\ option). |
| 25081 | .endp |
| 25082 | For mail delivery, the following are available: |
| 25083 | .numberpars $. |
| 25084 | SMTP over TCP/IP (the \%smtp%\ transport); |
| 25085 | .nextp |
| 25086 | LMTP over TCP/IP (the \%smtp%\ transport with the \protocol\ option set to |
| 25087 | `lmtp'); |
| 25088 | .nextp |
| 25089 | LMTP over a pipe to a process running in the local host (the \%lmtp%\ |
| 25090 | transport); |
| 25091 | .nextp |
| 25092 | Batched SMTP to a file or pipe (the \%appendfile%\ and \%pipe%\ transports with |
| 25093 | the \use@_bsmtp\ option set). |
| 25094 | .endp |
| 25095 | \*Batched SMTP*\ is the name for a process in which batches of messages are |
| 25096 | stored in or read from files (or pipes), in a format in which SMTP commands are |
| 25097 | used to contain the envelope information. |
| 25098 | |
| 25099 | |
| 25100 | .section Outgoing SMTP and LMTP over TCP/IP |
| 25101 | .rset SECToutSMTPTCP "~~chapter.~~section" |
| 25102 | .index SMTP||outgoing over TCP/IP |
| 25103 | .index outgoing SMTP over TCP/IP |
| 25104 | .index LMTP||over TCP/IP |
| 25105 | .index outgoing LMTP over TCP/IP |
| 25106 | .index \\EHLO\\ |
| 25107 | .index \\HELO\\ |
| 25108 | .index \\SIZE\\ option on \\MAIL\\ command |
| 25109 | Outgoing SMTP and LMTP over TCP/IP is implemented by the \%smtp%\ transport. |
| 25110 | The \protocol\ option selects which protocol is to be used, but the actual |
| 25111 | processing is the same in both cases. |
| 25112 | |
| 25113 | If, in response to its \\EHLO\\ command, Exim is told that the \\SIZE\\ |
| 25114 | parameter is supported, it adds \\SIZE\\=<<n>> to each subsequent \\MAIL\\ |
| 25115 | command. The value of <<n>> is the message size plus the value of the |
| 25116 | \size@_addition\ option (default 1024) to allow for additions to the message |
| 25117 | such as per-transport header lines, or changes made in a |
| 25118 | .index transport||filter |
| 25119 | .index filter||transport filter |
| 25120 | transport filter. If \size@_addition\ is set negative, the use of \\SIZE\\ is |
| 25121 | suppressed. |
| 25122 | |
| 25123 | If the remote server advertises support for \\PIPELINING\\, Exim uses the |
| 25124 | pipelining extension to SMTP (RFC 2197) to reduce the number of TCP/IP packets |
| 25125 | required for the transaction. |
| 25126 | |
| 25127 | If the remote server advertises support for the \\STARTTLS\\ command, and Exim |
| 25128 | was built to support TLS encryption, it tries to start a TLS session unless the |
| 25129 | server matches \hosts@_avoid@_tls\. See chapter ~~CHAPTLS for more details. |
| 25130 | |
| 25131 | If the remote server advertises support for the \\AUTH\\ command, Exim scans |
| 25132 | the authenticators configuration for any suitable client settings, as described |
| 25133 | in chapter ~~CHAPSMTPAUTH. |
| 25134 | |
| 25135 | .index carriage return |
| 25136 | .index linefeed |
| 25137 | Responses from the remote host are supposed to be terminated by CR followed by |
| 25138 | LF. However, there are known to be hosts that do not send CR characters, so in |
| 25139 | order to be able to interwork with such hosts, Exim treats LF on its own as a |
| 25140 | line terminator. |
| 25141 | |
| 25142 | If a message contains a number of different addresses, all those with the same |
| 25143 | characteristics (for example, the same envelope sender) that resolve to the |
| 25144 | same set of hosts, in the same order, are sent in a single SMTP transaction, |
| 25145 | even if they are for different domains, unless there are more than the setting |
| 25146 | of the \max@_rcpts\ option in the \%smtp%\ transport allows, in which case they |
| 25147 | are split into groups containing no more than \max@_rcpts\ addresses each. If |
| 25148 | \remote@_max@_parallel\ is greater than one, such groups may be sent in |
| 25149 | parallel sessions. The order of hosts with identical MX values is not |
| 25150 | significant when checking whether addresses can be batched in this way. |
| 25151 | |
| 25152 | When the \%smtp%\ transport suffers a temporary failure that is not |
| 25153 | message-related, Exim updates its transport-specific database, which contains |
| 25154 | records indexed by host name that remember which messages are waiting for each |
| 25155 | particular host. It also updates the retry database with new retry times. |
| 25156 | .index hints database||retry keys |
| 25157 | Exim's retry hints are based on host name plus IP address, so if one address of |
| 25158 | a multi-homed host is broken, it will soon be skipped most of the time. |
| 25159 | See the next section for more detail about error handling. |
| 25160 | |
| 25161 | .index SMTP||passed connection |
| 25162 | .index SMTP||batching over TCP/IP |
| 25163 | When a message is successfully delivered over a TCP/IP SMTP connection, Exim |
| 25164 | looks in the hints database for the transport to see if there are any queued |
| 25165 | messages waiting for the host to which it is connected. If it finds one, it |
| 25166 | creates a new Exim process using the \-MC-\ option (which can only be used by a |
| 25167 | process running as root or the Exim user) and passes the TCP/IP socket to it so |
| 25168 | that it can deliver another message using the same socket. The new process does |
| 25169 | only those deliveries that are routed to the connected host, and may in turn |
| 25170 | pass the socket on to a third process, and so on. |
| 25171 | |
| 25172 | The \connection@_max@_messages\ option of the \%smtp%\ transport can be used to |
| 25173 | limit the number of messages sent down a single TCP/IP connection. |
| 25174 | .index asterisk||after IP address |
| 25175 | The second and subsequent messages delivered down an existing connection are |
| 25176 | identified in the main log by the addition of an asterisk after the closing |
| 25177 | square bracket of the IP address. |
| 25178 | |
| 25179 | |
| 25180 | |
| 25181 | .section Errors in outgoing SMTP |
| 25182 | .rset SECToutSMTPerr "~~chapter.~~section" |
| 25183 | .index error||in outgoing SMTP |
| 25184 | .index SMTP||errors in outgoing |
| 25185 | .index host||error |
| 25186 | Three different kinds of error are recognized for outgoing SMTP: host errors, |
| 25187 | message errors, and recipient errors. |
| 25188 | .numberpars |
| 25189 | A host error is not associated with a particular message or with a |
| 25190 | particular recipient of a message. The host errors are: |
| 25191 | .numberpars $. |
| 25192 | Connection refused or timed out, |
| 25193 | .nextp |
| 25194 | Any error response code on connection, |
| 25195 | .nextp |
| 25196 | Any error response code to \\EHLO\\ or \\HELO\\, |
| 25197 | .nextp |
| 25198 | Loss of connection at any time, except after `.', |
| 25199 | .nextp |
| 25200 | I/O errors at any time, |
| 25201 | .nextp |
| 25202 | Timeouts during the session, other than in response to \\MAIL\\, \\RCPT\\ or |
| 25203 | the `.' at the end of the data. |
| 25204 | .endp |
| 25205 | For a host error, a permanent error response on connection, or in response to |
| 25206 | \\EHLO\\, causes all addresses routed to the host to be failed. Any other host |
| 25207 | error causes all addresses to be deferred, and retry data to be created for the |
| 25208 | host. It is not tried again, for any message, until its retry time arrives. If |
| 25209 | the current set of addresses are not all delivered in this run (to some |
| 25210 | alternative host), the message is added to the list of those waiting for this |
| 25211 | host, so if it is still undelivered when a subsequent successful delivery is |
| 25212 | made to the host, it will be sent down the same SMTP connection. |
| 25213 | .nextp |
| 25214 | .index message||error |
| 25215 | A message error is associated with a particular message when sent to a |
| 25216 | particular host, but not with a particular recipient of the message. The |
| 25217 | message errors are: |
| 25218 | .numberpars $. |
| 25219 | Any error response code to \\MAIL\\, \\DATA\\, or the `.' that terminates |
| 25220 | the data, |
| 25221 | .nextp |
| 25222 | Timeout after \\MAIL\\, |
| 25223 | .nextp |
| 25224 | Timeout |
| 25225 | or loss of connection after the `.' that terminates the data. A timeout after |
| 25226 | the \\DATA\\ command itself is treated as a host error, as is loss of |
| 25227 | connection at any other time. |
| 25228 | .endp |
| 25229 | For a message error, a permanent error response (5$it{xx}) causes all addresses |
| 25230 | to be failed, and a delivery error report to be returned to the sender. A |
| 25231 | temporary error response (4$it{xx}), or one of the timeouts, causes all |
| 25232 | addresses to be deferred. Retry data is not created for the host, but instead, |
| 25233 | a retry record for the combination of host plus message id is created. The |
| 25234 | message is not added to the list of those waiting for this host. This ensures |
| 25235 | that the failing message will not be sent to this host again until the retry |
| 25236 | time arrives. However, other messages that are routed to the host are not |
| 25237 | affected, so if it is some property of the message that is causing the error, |
| 25238 | it will not stop the delivery of other mail. |
| 25239 | |
| 25240 | If the remote host specified support for the \\SIZE\\ parameter in its response |
| 25241 | to \\EHLO\\, Exim adds SIZE=$it{nnn} to the \\MAIL\\ command, so an |
| 25242 | over-large message will cause a message error because the error arrives as a |
| 25243 | response to \\MAIL\\. |
| 25244 | .nextp |
| 25245 | .index recipient||error |
| 25246 | A recipient error is associated with a particular recipient of a message. The |
| 25247 | recipient errors are: |
| 25248 | .numberpars $. |
| 25249 | Any error response to \\RCPT\\, |
| 25250 | .nextp |
| 25251 | Timeout after \\RCPT\\. |
| 25252 | .endp |
| 25253 | For a recipient error, a permanent error response (5$it{xx}) causes the |
| 25254 | recipient address to be failed, and a bounce message to be returned to the |
| 25255 | sender. A temporary error response (4$it{xx}) or a timeout causes the failing |
| 25256 | address to be deferred, and routing retry data to be created for it. This is |
| 25257 | used to delay processing of the address in subsequent queue runs, until its |
| 25258 | routing retry time arrives. This applies to all messages, but because it |
| 25259 | operates only in queue runs, one attempt will be made to deliver a new message |
| 25260 | to the failing address before the delay starts to operate. This ensures that, |
| 25261 | if the failure is really related to the message rather than the recipient |
| 25262 | (`message too big for this recipient' is a possible example), other messages |
| 25263 | have a chance of getting delivered. If a delivery to the address does succeed, |
| 25264 | the retry information gets cleared, so all stuck messages get tried again, and |
| 25265 | the retry clock is reset. |
| 25266 | |
| 25267 | The message is not added to the list of those waiting for this host. Use of the |
| 25268 | host for other messages is unaffected, and except in the case of a timeout, |
| 25269 | other recipients are processed independently, and may be successfully delivered |
| 25270 | in the current SMTP session. After a timeout it is of course impossible to |
| 25271 | proceed with the session, so all addresses get deferred. However, those other |
| 25272 | than the one that failed do not suffer any subsequent retry delays. Therefore, |
| 25273 | if one recipient is causing trouble, the others have a chance of getting |
| 25274 | through when a subsequent delivery attempt occurs before the failing |
| 25275 | recipient's retry time. |
| 25276 | .endp |
| 25277 | |
| 25278 | In all cases, if there are other hosts (or IP addresses) available for the |
| 25279 | current set of addresses (for example, from multiple MX records), they are |
| 25280 | tried in this run for any undelivered addresses, subject of course to their |
| 25281 | own retry data. In other words, recipient error retry data does not take effect |
| 25282 | until the next delivery attempt. |
| 25283 | |
| 25284 | Some hosts have been observed to give temporary error responses to every |
| 25285 | \\MAIL\\ command at certain times (`insufficient space' has been seen). It |
| 25286 | would be nice if such circumstances could be recognized, and defer data for the |
| 25287 | host itself created, but this is not possible within the current Exim design. |
| 25288 | What actually happens is that retry data for every (host, message) combination |
| 25289 | is created. |
| 25290 | |
| 25291 | The reason that timeouts after \\MAIL\\ and \\RCPT\\ are treated specially is |
| 25292 | that these can sometimes arise as a result of the remote host's verification |
| 25293 | procedures. Exim makes this assumption, and treats them as if a temporary error |
| 25294 | response had been received. A timeout after `.' is treated specially because it |
| 25295 | is known that some broken implementations fail to recognize the end of the |
| 25296 | message if the last character of the last line is a binary zero. Thus, it is |
| 25297 | helpful to treat this case as a message error. |
| 25298 | |
| 25299 | Timeouts at other times are treated as host errors, assuming a problem with the |
| 25300 | host, or the connection to it. If a timeout after \\MAIL\\, \\RCPT\\, |
| 25301 | or `.' is really a connection problem, the assumption is that at the next try |
| 25302 | the timeout is likely to occur at some other point in the dialogue, causing it |
| 25303 | then to be treated as a host error. |
| 25304 | |
| 25305 | There is experimental evidence that some MTAs drop the connection after the |
| 25306 | terminating `.' if they do not like the contents of the message for some |
| 25307 | reason, in contravention of the RFC, which indicates that a 5$it{xx} response |
| 25308 | should be given. That is why Exim treats this case as a message rather than a |
| 25309 | host error, in order not to delay other messages to the same host. |
| 25310 | |
| 25311 | |
| 25312 | |
| 25313 | |
| 25314 | .section Variable Envelope Return Paths (VERP) |
| 25315 | .index VERP |
| 25316 | .index Variable Envelope Return Paths |
| 25317 | .index envelope sender |
| 25318 | Variable Envelope Return Paths -- see |
| 25319 | \?ftp://koobera.math.uic.edu/www/proto/verp.txt?\ -- can be supported in Exim |
| 25320 | by using the \return@_path\ generic transport option to rewrite the return path |
| 25321 | at transport time. For example, the following could be used on an \%smtp%\ |
| 25322 | transport: |
| 25323 | .display asis |
| 25324 | return_path = \ |
| 25325 | ${if match {$return_path}{^(.+?)-request@your.dom.example\$}\ |
| 25326 | {$1-request=$local_part%$domain@your.dom.example}fail} |
| 25327 | .endd |
| 25328 | This has the effect of rewriting the return path (envelope sender) on all |
| 25329 | outgoing SMTP messages, if the local part of the original return path ends in |
| 25330 | `-request', and the domain is \*your.dom.example*\. The rewriting inserts the |
| 25331 | local part and domain of the recipient into the return path. Suppose, for |
| 25332 | example, that a message whose return path has been set to |
| 25333 | \*somelist-request@@your.dom.example*\ is sent to |
| 25334 | \*subscriber@@other.dom.example*\. In the transport, the return path is |
| 25335 | rewritten as |
| 25336 | .display asis |
| 25337 | somelist-request=subscriber%other.dom.example@your.dom.example |
| 25338 | .endd |
| 25339 | For this to work, you must arrange for outgoing messages that have `-request' |
| 25340 | in their return paths to have just a single recipient. This can be done by |
| 25341 | setting |
| 25342 | .display asis |
| 25343 | max_rcpt = 1 |
| 25344 | .endd |
| 25345 | in the \%smtp%\ transport. Otherwise a single copy of a message might be |
| 25346 | addressed to several different recipients in the same domain, in which case |
| 25347 | \$local@_part$\ is not available (because it is not unique). Of course, if you |
| 25348 | do start sending out messages with this kind of return path, you must also |
| 25349 | configure Exim to accept the bounce messages that come back to those paths. |
| 25350 | Typically this would be done by setting an \local@_part@_suffix\ option for a |
| 25351 | suitable router. |
| 25352 | |
| 25353 | The overhead incurred in using VERP depends very much on the size of the |
| 25354 | message, the number of recipient addresses that resolve to the same remote |
| 25355 | host, and the speed of the connection over which the message is being sent. If |
| 25356 | a lot of addresses resolve to the same host and the connection is slow, sending |
| 25357 | a separate copy of the message for each address may take substantially longer |
| 25358 | than sending a single copy with many recipients (for which VERP cannot be |
| 25359 | used). |
| 25360 | |
| 25361 | |
| 25362 | .section Incoming SMTP messages over TCP/IP |
| 25363 | .index SMTP||incoming over TCP/IP |
| 25364 | .index incoming SMTP over TCP/IP |
| 25365 | .index inetd |
| 25366 | .index daemon |
| 25367 | Incoming SMTP messages can be accepted in one of two ways: by running a |
| 25368 | listening daemon, or by using \*inetd*\. In the latter case, the entry in |
| 25369 | \(/etc/inetd.conf)\ should be like this: |
| 25370 | .display asis |
| 25371 | smtp stream tcp nowait exim /opt/exim/bin/exim in.exim -bs |
| 25372 | .endd |
| 25373 | Exim distinguishes between this case and the case of a locally running user |
| 25374 | agent using the \-bs-\ option by checking whether or not the standard input is |
| 25375 | a socket. When it is, either the port must be privileged (less than 1024), or |
| 25376 | the caller must be root or the Exim user. If any other user passes a socket |
| 25377 | with an unprivileged port number, Exim prints a message on the standard error |
| 25378 | stream and exits with an error code. |
| 25379 | |
| 25380 | By default, Exim does not make a log entry when a remote host connects or |
| 25381 | disconnects (either via the daemon or \*inetd*\), unless the disconnection is |
| 25382 | unexpected. It can be made to write such log entries by setting the |
| 25383 | \smtp@_connection\ log selector. |
| 25384 | |
| 25385 | .index carriage return |
| 25386 | .index linefeed |
| 25387 | Commands from the remote host are supposed to be terminated by CR followed by |
| 25388 | LF. However, there are known to be hosts that do not send CR characters. In |
| 25389 | order to be able to interwork with such hosts, Exim treats LF on its own as a |
| 25390 | line terminator. |
| 25391 | Furthermore, because common code is used for receiving messages from all |
| 25392 | sources, a CR on its own is also interpreted as a line terminator. However, the |
| 25393 | sequence `CR, dot, CR' does not terminate incoming SMTP data. |
| 25394 | |
| 25395 | .index \\EHLO\\||invalid data |
| 25396 | .index \\HELO\\||invalid data |
| 25397 | One area that sometimes gives rise to problems concerns the \\EHLO\\ or |
| 25398 | \\HELO\\ commands. Some clients send syntactically invalid versions of these |
| 25399 | commands, which Exim rejects by default. (This is nothing to do with verifying |
| 25400 | the data that is sent, so \helo@_verify@_hosts\ is not relevant.) You can tell |
| 25401 | Exim not to apply a syntax check by setting \helo@_accept@_junk@_hosts\ to |
| 25402 | match the broken hosts that send invalid commands. |
| 25403 | |
| 25404 | .index \\SIZE\\ option on \\MAIL\\ command |
| 25405 | .index \\MAIL\\||\\SIZE\\ option |
| 25406 | The amount of disk space available is checked whenever \\SIZE\\ is received on |
| 25407 | a \\MAIL\\ command, independently of whether \message@_size@_limit\ or |
| 25408 | \check@_spool@_space\ is configured, unless \smtp__check__spool__space\ is set |
| 25409 | false. A temporary error is given if there is not enough space. If |
| 25410 | \check@_spool@_space\ is set, the check is for that amount of space plus the |
| 25411 | value given with \\SIZE\\, that is, it checks that the addition of the incoming |
| 25412 | message will not reduce the space below the threshold. |
| 25413 | |
| 25414 | When a message is successfully received, Exim includes the local message id in |
| 25415 | its response to the final `.' that terminates the data. If the remote host logs |
| 25416 | this text it can help with tracing what has happened to a message. |
| 25417 | |
| 25418 | The Exim daemon can limit the number of simultaneous incoming connections it is |
| 25419 | prepared to handle (see the \smtp@_accept@_max\ option). It can also limit the |
| 25420 | number of simultaneous incoming connections from a single remote host (see the |
| 25421 | \smtp@_accept@_max@_per@_host\ option). Additional connection attempts are |
| 25422 | rejected using the SMTP temporary error code 421. |
| 25423 | |
| 25424 | The Exim daemon does not rely on the \\SIGCHLD\\ signal to detect when a |
| 25425 | subprocess has finished, as this can get lost at busy times. Instead, it looks |
| 25426 | for completed subprocesses every time it wakes up. Provided there are other |
| 25427 | things happening (new incoming calls, starts of queue runs), completed |
| 25428 | processes will be noticed and tidied away. On very quiet systems you may |
| 25429 | sometimes see a `defunct' Exim process hanging about. This is not a problem; it |
| 25430 | will be noticed when the daemon next wakes up. |
| 25431 | |
| 25432 | When running as a daemon, Exim can reserve some SMTP slots for specific hosts, |
| 25433 | and can also be set up to reject SMTP calls from non-reserved hosts at times of |
| 25434 | high system load -- for details see the \smtp@_accept@_reserve\, |
| 25435 | \smtp@_load@_reserve\, and \smtp@_reserve@_hosts\ options. The load check |
| 25436 | applies in both the daemon and \*inetd*\ cases. |
| 25437 | |
| 25438 | Exim normally starts a delivery process for each message received, though this |
| 25439 | can be varied by means of the \-odq-\ command line option and the |
| 25440 | \queue@_only\, \queue@_only@_file\, and \queue@_only@_load\ options. The number |
| 25441 | of simultaneously running delivery processes started in this way from SMTP |
| 25442 | input can be limited by the \smtp__accept__queue\ and |
| 25443 | \smtp__accept__queue__per__connection\ options. When either limit is reached, |
| 25444 | subsequently received messages are just put on the input queue without starting |
| 25445 | a delivery process. |
| 25446 | |
| 25447 | The controls that involve counts of incoming SMTP calls (\smtp@_accept@_max\, |
| 25448 | \smtp@_accept@_queue\, \smtp__accept__reserve\) are not available when Exim is |
| 25449 | started up from the \*inetd*\ daemon, because in that case each connection is |
| 25450 | handled by an entirely independent Exim process. Control by load average is, |
| 25451 | however, available with \*inetd*\. |
| 25452 | |
| 25453 | Exim can be configured to verify addresses in incoming SMTP commands as they |
| 25454 | are received. See chapter ~~CHAPACL for details. It can also be configured to |
| 25455 | rewrite addresses at this time -- before any syntax checking is done. See |
| 25456 | section ~~SECTrewriteS. |
| 25457 | |
| 25458 | Exim can also be configured to limit the rate at which a client host submits |
| 25459 | \\MAIL\\ and \\RCPT\\ commands in a single SMTP session. See the |
| 25460 | \smtp@_ratelimit@_hosts\ option. |
| 25461 | |
| 25462 | |
| 25463 | .section Unrecognized SMTP commands |
| 25464 | .index SMTP||unrecognized commands |
| 25465 | If Exim receives more than \smtp@_max@_unknown@_commands\ unrecognized SMTP |
| 25466 | commands during a single SMTP connection, it drops the connection after sending |
| 25467 | the error response to the last command. The default value for |
| 25468 | \smtp@_max@_unknown@_commands\ is 3. This is a defence against some kinds of |
| 25469 | abuse that subvert web servers into making connections to SMTP ports; in these |
| 25470 | circumstances, a number of non-SMTP lines are sent first. |
| 25471 | |
| 25472 | .section Syntax and protocol errors in SMTP commands |
| 25473 | .index SMTP||syntax errors |
| 25474 | .index SMTP||protocol errors |
| 25475 | A syntax error is detected if an SMTP command is recognized, but there is |
| 25476 | something syntactically wrong with its data, for example, a malformed email |
| 25477 | address in a \\RCPT\\ command. Protocol errors include invalid command |
| 25478 | sequencing such as \\RCPT\\ before \\MAIL\\. If Exim receives more than |
| 25479 | \smtp@_max@_synprot@_errors\ such commands during a single SMTP connection, it |
| 25480 | drops the connection after sending the error response to the last command. The |
| 25481 | default value for \smtp__max__synprot__errors\ is 3. This is a defence against |
| 25482 | broken clients that loop sending bad commands (yes, it has been seen). |
| 25483 | |
| 25484 | |
| 25485 | .section Use of non-mail SMTP commands |
| 25486 | .index SMTP||non-mail commands |
| 25487 | The `non-mail' SMTP commands are those other than \\MAIL\\, \\RCPT\\, and |
| 25488 | \\DATA\\. Exim counts such commands, and drops the connection if there are too |
| 25489 | many of them in a single SMTP session. This action catches some |
| 25490 | denial-of-service attempts and things like repeated failing \\AUTH\\s, or a mad |
| 25491 | client looping sending \\EHLO\\. The global option \smtp@_accept@_max@_nonmail\ |
| 25492 | defines what `too many' means. Its default value is 10. |
| 25493 | |
| 25494 | When a new message is expected, one occurrence of \\RSET\\ is not counted. This |
| 25495 | allows a client to send one \\RSET\\ between messages (this is not necessary, |
| 25496 | but some clients do it). Exim also allows one uncounted occurence of \\HELO\\ |
| 25497 | or \\EHLO\\, and one occurrence of \\STARTTLS\\ between messages. After |
| 25498 | starting up a TLS session, another \\EHLO\\ is expected, and so it too is not |
| 25499 | counted. |
| 25500 | |
| 25501 | The first occurrence of \\AUTH\\ in a connection, or immediately following |
| 25502 | \\STARTTLS\\ is also not counted. Otherwise, all commands other than \\MAIL\\, |
| 25503 | \\RCPT\\, \\DATA\\, and \\QUIT\\ are counted. |
| 25504 | |
| 25505 | You can control which hosts are subject to the limit set by |
| 25506 | \smtp@_accept@_max@_nonmail\ by setting |
| 25507 | \smtp@_accept@_max@_nonmail@_hosts\. The default value is \"$*$"\, which makes |
| 25508 | the limit apply to all hosts. This option means that you can exclude any |
| 25509 | specific badly-behaved hosts that you have to live with. |
| 25510 | |
| 25511 | |
| 25512 | |
| 25513 | .section The \\VRFY\\ and \\EXPN\\ commands |
| 25514 | When Exim receives a \\VRFY\\ or \\EXPN\\ command on a TCP/IP connection, it |
| 25515 | runs the ACL specified by \acl@_smtp@_vrfy\ or \acl@_smtp@_expn\ (as |
| 25516 | appropriate) in order to decide whether the command should be accepted or not. |
| 25517 | If no ACL is defined, the command is rejected. |
| 25518 | |
| 25519 | .index \\VRFY\\||processing |
| 25520 | When \\VRFY\\ is accepted, it runs exactly the same code as when Exim is |
| 25521 | called with the \-bv-\ option. |
| 25522 | .index \\EXPN\\||processing |
| 25523 | When \\EXPN\\ is accepted, a single-level expansion of the address is done. |
| 25524 | \\EXPN\\ is treated as an `address test' (similar to the \-bt-\ option) rather |
| 25525 | than a verification (the \-bv-\ option). If an unqualified local part is given |
| 25526 | as the argument to \\EXPN\\, it is qualified with \qualify@_domain\. Rejections |
| 25527 | of \\VRFY\\ and \\EXPN\\ commands are logged on the main and reject logs, and |
| 25528 | \\VRFY\\ verification failures are logged on the main log for consistency with |
| 25529 | \\RCPT\\ failures. |
| 25530 | |
| 25531 | |
| 25532 | .section The \\ETRN\\ command |
| 25533 | .rset SECTETRN "~~chapter.~~section" |
| 25534 | .index \\ETRN\\||processing |
| 25535 | RFC 1985 describes an SMTP command called \\ETRN\\ that is designed to |
| 25536 | overcome the security problems of the \\TURN\\ command (which has fallen into |
| 25537 | disuse). When Exim receives an \\ETRN\\ command on a TCP/IP connection, it runs |
| 25538 | the ACL specified by \acl@_smtp@_etrn\ in order to decide whether the command |
| 25539 | should be accepted or not. If no ACL is defined, the command is rejected. |
| 25540 | |
| 25541 | The \\ETRN\\ command is concerned with `releasing' messages that are awaiting |
| 25542 | delivery to certain hosts. As Exim does not organize its message queue by host, |
| 25543 | the only form of \\ETRN\\ that is supported by default is the one where the |
| 25544 | text starts with the `@#' prefix, in which case the remainder of the text is |
| 25545 | specific to the SMTP server. A valid \\ETRN\\ command causes a run of Exim with |
| 25546 | the \-R-\ option to happen, with the remainder of the \\ETRN\\ text as its |
| 25547 | argument. For example, |
| 25548 | .display asis |
| 25549 | ETRN #brigadoon |
| 25550 | .endd |
| 25551 | runs the command |
| 25552 | .display asis |
| 25553 | exim -R brigadoon |
| 25554 | .endd |
| 25555 | which causes a delivery attempt on all messages with undelivered addresses |
| 25556 | containing the text `brigadoon'. When \smtp@_etrn@_serialize\ is set (the |
| 25557 | default), Exim prevents the simultaneous execution of more than one queue run |
| 25558 | for the same argument string as a result of an \\ETRN\\ command. This stops |
| 25559 | a misbehaving client from starting more than one queue runner at once. |
| 25560 | |
| 25561 | .index hints database||\\ETRN\\ serialization |
| 25562 | Exim implements the serialization by means of a hints database in which a |
| 25563 | record is written whenever a process is started by \\ETRN\\, and deleted when |
| 25564 | the process completes. However, Exim does not keep the SMTP session waiting for |
| 25565 | the \\ETRN\\ process to complete. Once \\ETRN\\ is accepted, the client is sent |
| 25566 | a `success' return code. Obviously there is scope for hints records to get left |
| 25567 | lying around if there is a system or program crash. To guard against this, Exim |
| 25568 | ignores any records that are more than six hours old. |
| 25569 | |
| 25570 | .index \smtp@_etrn@_command\ |
| 25571 | For more control over what \\ETRN\\ does, the \smtp@_etrn@_command\ option can |
| 25572 | used. This specifies a command that is run whenever \\ETRN\\ is received, |
| 25573 | whatever the form of its argument. For |
| 25574 | example: |
| 25575 | .display asis |
| 25576 | smtp_etrn_command = /etc/etrn_command $domain $sender_host_address |
| 25577 | .endd |
| 25578 | The string is split up into arguments which are independently expanded. The |
| 25579 | expansion variable \$domain$\ is set to the argument of the \\ETRN\\ command, |
| 25580 | and no syntax checking is done on the contents of this argument. Exim does not |
| 25581 | wait for the command to complete, so its status code is not checked. Exim runs |
| 25582 | under its own uid and gid when receiving incoming SMTP, so it is not possible |
| 25583 | for it to change them before running the command. |
| 25584 | |
| 25585 | |
| 25586 | .section Incoming local SMTP |
| 25587 | .index SMTP||local incoming |
| 25588 | Some user agents use SMTP to pass messages to their local MTA using the |
| 25589 | standard input and output, as opposed to passing the envelope on the command |
| 25590 | line and writing the message to the standard input. This is supported by the |
| 25591 | \-bs-\ option. This form of SMTP is handled in the same way as incoming |
| 25592 | messages over TCP/IP (including the use of ACLs), except that the envelope |
| 25593 | sender given in a \\MAIL\\ command is ignored unless the caller is trusted. In |
| 25594 | an ACL you can detect this form of SMTP input by testing for an empty host |
| 25595 | identification. It is common to have this as the first line in the ACL that |
| 25596 | runs for \\RCPT\\ commands: |
| 25597 | .display asis |
| 25598 | accept hosts = : |
| 25599 | .endd |
| 25600 | This accepts SMTP messages from local processes without doing any other tests. |
| 25601 | |
| 25602 | |
| 25603 | .section Outgoing batched SMTP |
| 25604 | .rset SECTbatchSMTP "~~chapter.~~section" |
| 25605 | .index SMTP||batched outgoing |
| 25606 | .index batched SMTP output |
| 25607 | Both the \%appendfile%\ and \%pipe%\ transports can be used for handling batched |
| 25608 | SMTP. Each has an option called \use@_bsmtp\ which causes messages to be output |
| 25609 | in BSMTP format. No SMTP responses are possible for this form of delivery. All |
| 25610 | it is doing is using SMTP commands as a way of transmitting the envelope along |
| 25611 | with the message. |
| 25612 | |
| 25613 | The message is written to the file or pipe preceded by the SMTP commands |
| 25614 | \\MAIL\\ and \\RCPT\\, and followed by a line containing a single dot. Lines in |
| 25615 | the message that start with a dot have an extra dot added. The SMTP command |
| 25616 | \\HELO\\ is not normally used. If it is required, the \message@_prefix\ option |
| 25617 | can be used to specify it. |
| 25618 | |
| 25619 | Because \%appendfile%\ and \%pipe%\ are both local transports, they accept only |
| 25620 | one recipient address at a time by default. However, you can arrange for them |
| 25621 | to handle several addresses at once by setting the \batch@_max\ option. When |
| 25622 | this is done for BSMTP, messages may contain multiple \\RCPT\\ commands. See |
| 25623 | chapter ~~CHAPbatching for more details. |
| 25624 | |
| 25625 | When one or more addresses are routed to a BSMTP transport by a router that |
| 25626 | sets up a host list, the name of the first host on the list is available to the |
| 25627 | transport in the variable \$host$\. Here is an example of such a transport and |
| 25628 | router: |
| 25629 | .display asis |
| 25630 | begin routers |
| 25631 | route_append: |
| 25632 | driver = manualroute |
| 25633 | transport = smtp_appendfile |
| 25634 | route_list = domain.example batch.host.example |
| 25635 | |
| 25636 | begin transports |
| 25637 | smtp_appendfile: |
| 25638 | driver = appendfile |
| 25639 | directory = /var/bsmtp/$host |
| 25640 | batch_max = 1000 |
| 25641 | use_bsmtp |
| 25642 | user = exim |
| 25643 | .endd |
| 25644 | This causes messages addressed to \*domain.example*\ to be written in BSMTP |
| 25645 | format to \(/var/bsmtp/batch.host.example)\, with only a single copy of each |
| 25646 | message (unless there are more than 1000 recipients). |
| 25647 | |
| 25648 | |
| 25649 | .section Incoming batched SMTP |
| 25650 | .rset SECTincomingbatchedSMTP "~~chapter.~~section" |
| 25651 | .index SMTP||batched incoming |
| 25652 | .index batched SMTP input |
| 25653 | The \-bS-\ command line option causes Exim to accept one or more messages by |
| 25654 | reading SMTP on the standard input, but to generate no responses. If the caller |
| 25655 | is trusted, the senders in the \\MAIL\\ commands are believed; otherwise the |
| 25656 | sender is always the caller of Exim. Unqualified senders and receivers are not |
| 25657 | rejected (there seems little point) but instead just get qualified. \\HELO\\ |
| 25658 | and \\EHLO\\ act as \\RSET\\; \\VRFY\\, \\EXPN\\, \\ETRN\\ and \\HELP\\, act |
| 25659 | as \\NOOP\\; \\QUIT\\ quits. |
| 25660 | |
| 25661 | No policy checking is done for BSMTP input. That is, no ACL is run at anytime. |
| 25662 | In this respect it is like non-SMTP local input. |
| 25663 | |
| 25664 | If an error is detected while reading a message, including a missing `.' at |
| 25665 | the end, Exim gives up immediately. It writes details of the error to the |
| 25666 | standard output in a stylized way that the calling program should be able to |
| 25667 | make some use of automatically, for example: |
| 25668 | .display asis |
| 25669 | 554 Unexpected end of file |
| 25670 | Transaction started in line 10 |
| 25671 | Error detected in line 14 |
| 25672 | .endd |
| 25673 | It writes a more verbose version, for human consumption, to the standard error |
| 25674 | file, for example: |
| 25675 | .display asis |
| 25676 | An error was detected while processing a file of BSMTP input. |
| 25677 | The error message was: |
| 25678 | |
| 25679 | 501 '>' missing at end of address |
| 25680 | |
| 25681 | The SMTP transaction started in line 10. |
| 25682 | The error was detected in line 12. |
| 25683 | The SMTP command at fault was: |
| 25684 | |
| 25685 | rcpt to:<malformed@in.com.plete |
| 25686 | |
| 25687 | 1 previous message was successfully processed. |
| 25688 | The rest of the batch was abandoned. |
| 25689 | .endd |
| 25690 | The return code from Exim is zero only if there were no errors. It is 1 if some |
| 25691 | messages were accepted before an error was detected, and 2 if no messages were |
| 25692 | accepted. |
| 25693 | |
| 25694 | |
| 25695 | |
| 25696 | |
| 25697 | . |
| 25698 | . |
| 25699 | . |
| 25700 | . |
| 25701 | . ============================================================================ |
| 25702 | .chapter Message processing |
| 25703 | .set runningfoot "message processing" |
| 25704 | .rset CHAPmsgproc "~~chapter" |
| 25705 | .index message||general processing |
| 25706 | Exim performs various transformations on the sender and recipient addresses of |
| 25707 | all messages that it handles, and also on the messages' header lines. Some of |
| 25708 | these are optional and configurable, while others always take place. All of |
| 25709 | this processing, except rewriting as a result of routing, and the addition or |
| 25710 | removal of header lines while delivering, happens when a message is received, |
| 25711 | before it is placed on Exim's queue. |
| 25712 | |
| 25713 | Some of the automatic processing takes place |
| 25714 | by default |
| 25715 | only for `locally-originated' messages. This adjective is used to describe |
| 25716 | messages that are not received over TCP/IP, but instead are passed to an Exim |
| 25717 | process on its standard input. This includes the interactive `local SMTP' case |
| 25718 | that is set up by the \-bs-\ command line option. \**Note**\: messages received |
| 25719 | over TCP/IP on the loopback interface (127.0.0.1 or @:@:1) are not considered |
| 25720 | to be locally-originated. Exim does not treat the loopback interface specially |
| 25721 | in any way. |
| 25722 | |
| 25723 | |
| 25724 | .section Submission mode for non-local messages |
| 25725 | .rset SECTsubmodnon "~~chapter.~~section" |
| 25726 | |
| 25727 | .index message||submission |
| 25728 | Processing that happens automatically for locally-originated messages can also |
| 25729 | be requested for other messages. This is done by obeying the modifier |
| 25730 | .display asis |
| 25731 | control = submission |
| 25732 | .endd |
| 25733 | in one of the ACLs that are run for an incoming message (see section |
| 25734 | ~~SECTACLmodi). This makes Exim treat the message as a local submission, and is |
| 25735 | normally used when the source of the message is known to be an MUA running on a |
| 25736 | client host (as opposed to an MTA). In the descriptions below, the term |
| 25737 | `submission mode' is used to describe this state. |
| 25738 | |
| 25739 | When a ::From:: or ::Sender:: header is generated in submission mode, the value |
| 25740 | of \qualify@_domain\ is used by default. However, it is possible to specify |
| 25741 | another domain by a setting such as |
| 25742 | .display asis |
| 25743 | control = submission/domain=some.other.domain |
| 25744 | .endd |
| 25745 | |
| 25746 | |
| 25747 | |
| 25748 | .section Line endings |
| 25749 | .rset SECTlineendings "~~chapter.~~section" |
| 25750 | .index line endings |
| 25751 | .index carriage return |
| 25752 | .index linefeed |
| 25753 | RFC 2821 specifies that CRLF (two characters: carriage-return, followed by |
| 25754 | linefeed) is the line ending for messages transmitted over the Internet using |
| 25755 | SMTP over TCP/IP. However, within individual operating systems, different |
| 25756 | conventions are used. For example, Unix-like systems use just LF, but others |
| 25757 | use CRLF or just CR. |
| 25758 | |
| 25759 | Exim was designed for Unix-like systems, and internally, it stores messages |
| 25760 | using the system's convention of a single LF as a line terminator. When |
| 25761 | receiving a message, all line endings are translated to this standard format. |
| 25762 | Originally, it was thought that programs that passed messages directly to an |
| 25763 | MTA within an operating system would use that system's convention. Experience |
| 25764 | has shown that this is not the case; for example, there are Unix applications |
| 25765 | that use CRLF in this circumstance. For this reason, and for compatibility with |
| 25766 | other MTAs, the way Exim handles line endings for all messages is now as |
| 25767 | follows: |
| 25768 | .numberpars $. |
| 25769 | LF not preceded by CR is treated as a line ending. |
| 25770 | .nextp |
| 25771 | CR is treated as a line ending; if it is immediately followed by LF, the LF |
| 25772 | is ignored. |
| 25773 | .nextp |
| 25774 | The sequence `CR, dot, CR' does not terminate an incoming SMTP message, |
| 25775 | nor a local message in the state where a line containing only a dot is a |
| 25776 | terminator. |
| 25777 | .nextp |
| 25778 | If a bare CR is encountered within a header line, an extra space is added after |
| 25779 | the line terminator so as not to end the header line. The reasoning behind this |
| 25780 | is that bare CRs in header lines are most likely either to be mistakes, or |
| 25781 | people trying to play silly games. |
| 25782 | .nextp |
| 25783 | If the first header line received in a message ends with CRLF, a subsequent |
| 25784 | bare LF in a header line is treated in the same way as a bare CR in a header |
| 25785 | line. |
| 25786 | .endp |
| 25787 | |
| 25788 | |
| 25789 | |
| 25790 | .section Unqualified addresses |
| 25791 | .index unqualified addresses |
| 25792 | .index address||qualification |
| 25793 | By default, Exim expects every address it receives from an external host to be |
| 25794 | fully qualified. Unqualified addresses cause negative responses to SMTP |
| 25795 | commands. However, because SMTP is used as a means of transporting messages |
| 25796 | from MUAs running on personal workstations, there is sometimes a requirement to |
| 25797 | accept unqualified addresses from specific hosts or IP networks. |
| 25798 | |
| 25799 | Exim has two options that separately control which hosts may send unqualified |
| 25800 | sender or receipient addresses in SMTP commands, namely |
| 25801 | \sender__unqualified__hosts\ and \recipient__unqualified__hosts\. In both |
| 25802 | cases, if an unqualified address is accepted, it is qualified by adding the |
| 25803 | value of \qualify__domain\ or \qualify__recipient\, as appropriate. |
| 25804 | .index \qualify@_domain\ |
| 25805 | .index \qualify@_recipient\ |
| 25806 | |
| 25807 | |
| 25808 | .section The UUCP From line |
| 25809 | .index `From' line |
| 25810 | .index UUCP||`From' line |
| 25811 | .index sender||address |
| 25812 | .index \uucp@_from@_pattern\ |
| 25813 | .index \uucp@_from@_sender\ |
| 25814 | .index envelope sender |
| 25815 | .index Sendmail compatibility||`From' line |
| 25816 | Messages that have come from UUCP (and some other applications) often begin |
| 25817 | with a line containing the envelope sender and a timestamp, following the word |
| 25818 | `From'. Examples of two common formats are: |
| 25819 | .display asis |
| 25820 | From a.oakley@berlin.mus Fri Jan 5 12:35 GMT 1996 |
| 25821 | From f.butler@berlin.mus Fri, 7 Jan 97 14:00:00 GMT |
| 25822 | .endd |
| 25823 | This line precedes the RFC 2822 header lines. For compatibility with Sendmail, |
| 25824 | Exim recognizes such lines at the start of messages that are submitted to it |
| 25825 | via the command line (that is, on the standard input). It does not recognize |
| 25826 | such lines in incoming SMTP messages, unless the sending host matches |
| 25827 | \ignore@_fromline@_hosts\ or the \-bs-\ option was used for a local message and |
| 25828 | \ignore@_fromline@_local\ is set. The recognition is controlled by a regular |
| 25829 | expression that is defined by the \uucp@_from@_pattern\ option, whose default |
| 25830 | value matches the two common cases shown above and puts the address that |
| 25831 | follows `From' into \$1$\. |
| 25832 | |
| 25833 | .index numerical variables (\$1$\, \$2$\, etc)||in `From ' line handling |
| 25834 | When the caller of Exim for a non-SMTP message that contains a `From' line is a |
| 25835 | trusted user, the message's sender address is constructed by expanding the |
| 25836 | contents of \uucp@_sender@_address\, whose default value is `@$1'. This is then |
| 25837 | parsed as an RFC 2822 address. If there is no domain, the local part is |
| 25838 | qualified with \qualify@_domain\ unless it is the empty string. However, if the |
| 25839 | command line \-f-\ option is used, it overrides the `From' line. |
| 25840 | |
| 25841 | If the caller of Exim is not trusted, the `From' line is recognized, but the |
| 25842 | sender address is not changed. This is also the case for incoming SMTP messages |
| 25843 | that are permitted to contain `From' lines. |
| 25844 | |
| 25845 | Only one `From' line is recognized. If there is more than one, the second is |
| 25846 | treated as a data line that starts the body of the message, as it is not valid |
| 25847 | as a header line. This also happens if a `From' line is present in an incoming |
| 25848 | SMTP message from a source that is not permitted to send them. |
| 25849 | |
| 25850 | |
| 25851 | .section Resent- header lines |
| 25852 | .index \Resent@-\ header lines |
| 25853 | RFC 2822 makes provision for sets of header lines starting with the string |
| 25854 | \"Resent-"\ to be added to a message when it is resent by the original |
| 25855 | recipient to somebody else. These headers are ::Resent-Date::, ::Resent-From::, |
| 25856 | ::Resent-Sender::, ::Resent-To::, ::Resent-Cc::, ::Resent-Bcc:: and |
| 25857 | ::Resent-Message-ID::. The RFC says: |
| 25858 | |
| 25859 | \*Resent fields are strictly informational. They MUST NOT be used in the normal |
| 25860 | processing of replies or other such automatic actions on messages.*\ |
| 25861 | |
| 25862 | This leaves things a bit vague as far as other processing actions such as |
| 25863 | address rewriting are concerned. Exim treats \Resent@-\ header lines as |
| 25864 | follows: |
| 25865 | .numberpars $. |
| 25866 | A ::Resent-From:: line that just contains the login id of the submitting user |
| 25867 | is automatically rewritten in the same way as ::From:: (see below). |
| 25868 | .nextp |
| 25869 | If there's a rewriting rule for a particular header line, it is also applied to |
| 25870 | \Resent@-\ header lines of the same type. For example, a rule that rewrites |
| 25871 | ::From:: also rewrites ::Resent-From::. |
| 25872 | .nextp |
| 25873 | For local messages, if ::Sender:: is removed on input, ::Resent-Sender:: is also |
| 25874 | removed. |
| 25875 | .nextp |
| 25876 | For a locally-submitted message, |
| 25877 | if there are any \Resent@-\ header lines but no ::Resent-Date::, |
| 25878 | ::Resent-From::, or ::Resent-Message-Id::, they are added as necessary. It is |
| 25879 | the contents of ::Resent-Message-Id:: (rather than ::Message-Id::) which are |
| 25880 | included in log lines in this case. |
| 25881 | .nextp |
| 25882 | The logic for adding ::Sender:: is duplicated for ::Resent-Sender:: when any |
| 25883 | \Resent@-\ header lines are present. |
| 25884 | .endp |
| 25885 | |
| 25886 | |
| 25887 | .section The Auto-Submitted: header line |
| 25888 | Whenever Exim generates a bounce or a delay warning message, it includes the |
| 25889 | header line |
| 25890 | .display asis |
| 25891 | Auto-Submitted: auto-generated |
| 25892 | .endd |
| 25893 | |
| 25894 | |
| 25895 | .section The Bcc: header line |
| 25896 | .index ::Bcc:: header line |
| 25897 | If Exim is called with the \-t-\ option, to take recipient addresses from a |
| 25898 | message's header, it removes any ::Bcc:: header line that may exist (after |
| 25899 | extracting its addresses). If \-t-\ is not present on the command line, any |
| 25900 | existing ::Bcc:: is not removed. |
| 25901 | |
| 25902 | .section The Date: header line |
| 25903 | .index ::Date:: header line |
| 25904 | If a locally-generated |
| 25905 | or submission-mode |
| 25906 | message has no ::Date:: header line, Exim adds one, using the current date and |
| 25907 | time. |
| 25908 | |
| 25909 | .section The Delivery-date: header line |
| 25910 | .index ::Delivery-date:: header line |
| 25911 | .index \delivery@_date@_remove\ |
| 25912 | ::Delivery-date:: header lines are not part of the standard RFC 2822 header |
| 25913 | set. Exim can be configured to add them to the final delivery of messages. (See |
| 25914 | the generic \delivery@_date@_add\ transport option.) They should not be present |
| 25915 | in messages in transit. If the \delivery@_date@_remove\ configuration option is |
| 25916 | set (the default), Exim removes ::Delivery-date:: header lines from incoming |
| 25917 | messages. |
| 25918 | |
| 25919 | .section The Envelope-to: header line |
| 25920 | .index ::Envelope-to:: header line |
| 25921 | .index \envelope@_to@_remove\ |
| 25922 | ::Envelope-to:: header lines are not part of the standard RFC 2822 header set. |
| 25923 | Exim can be configured to add them to the final delivery of messages. (See the |
| 25924 | generic \envelope@_to@_add\ transport option.) They should not be present in |
| 25925 | messages in transit. If the \envelope@_to@_remove\ configuration option is set |
| 25926 | (the default), Exim removes ::Envelope-to:: header lines from incoming |
| 25927 | messages. |
| 25928 | |
| 25929 | .section The From: header line |
| 25930 | .index ::From:: header line |
| 25931 | .index Sendmail compatibility||`From' line |
| 25932 | If a submission-mode message does not contain a ::From:: header line, Exim adds |
| 25933 | one if either of the following conditions is true: |
| 25934 | .numberpars alpha |
| 25935 | The envelope sender address is not empty (that is, this is not a bounce |
| 25936 | message); the added header line copies the envelope sender address. |
| 25937 | .nextp |
| 25938 | The SMTP session is authenticated and \$authenticated@_id$\ is not empty; the |
| 25939 | added header's local part is \$authenticated@_id$\ and the domain is |
| 25940 | the domain specified on the submission control, or \$qualify@_domain$\ if that |
| 25941 | is not set. |
| 25942 | .endp |
| 25943 | A non-empty envelope sender takes precedence. |
| 25944 | |
| 25945 | If a locally-generated incoming message does not contain a ::From:: header |
| 25946 | line, Exim adds one containing the sender's address. The calling user's login |
| 25947 | name and full name are used to construct the address, as described in section |
| 25948 | ~~SECTconstr. They are obtained from the password data by calling |
| 25949 | \*getpwuid()*\ (but see the \unknown@_login\ configuration option). The address |
| 25950 | is qualified with \qualify@_domain\. |
| 25951 | |
| 25952 | For compatibility with Sendmail, if an incoming, non-SMTP message has a |
| 25953 | ::From:: header line containing just the unqualified login name of the calling |
| 25954 | user, this is replaced by an address containing the user's login name and full |
| 25955 | name as described in section ~~SECTconstr. |
| 25956 | |
| 25957 | .section The Message-ID: header line |
| 25958 | .index ::Message-ID:: header line |
| 25959 | If a locally-generated |
| 25960 | or submission-mode |
| 25961 | incoming message does not contain a ::Message-ID:: or ::Resent-Message-ID:: |
| 25962 | header line, Exim adds one to the message. If there are any ::Resent-:: headers |
| 25963 | in the message, it creates ::Resent-Message-ID::. The id is constructed from |
| 25964 | Exim's internal message id, preceded by the letter E to ensure it starts with a |
| 25965 | letter, and followed by @@ and the primary host name. Additional information |
| 25966 | can be included in this header line by setting the |
| 25967 | .index \message@_id@_header@_text\ |
| 25968 | \message@_id@_header@_text\ and/or \message__id__header__domain\ options. |
| 25969 | |
| 25970 | |
| 25971 | .section The Received: header line |
| 25972 | .index ::Received:: header line |
| 25973 | A ::Received:: header line is added at the start of every message. The contents |
| 25974 | are defined by the \received@_header@_text\ configuration option, and Exim |
| 25975 | automatically adds a semicolon and a timestamp to the configured string. |
| 25976 | |
| 25977 | The ::Received:: header is generated as soon as the message's header lines have |
| 25978 | been received. At this stage, the timestamp in the ::Received:: header line is |
| 25979 | the time that the message started to be received. This is the value that is |
| 25980 | seen by the \\DATA\\ ACL and by the \*local@_scan()*\ function. |
| 25981 | |
| 25982 | Once a message is accepted, the timestamp in the ::Received:: header line is |
| 25983 | changed to the time of acceptance, which is (apart from a small delay while the |
| 25984 | -H spool file is written) the earliest time at which delivery could start. |
| 25985 | |
| 25986 | |
| 25987 | .section The Return-path: header line |
| 25988 | .index ::Return-path:: header line |
| 25989 | .index \return@_path@_remove\ |
| 25990 | ::Return-path:: header lines are defined as something an MTA may insert when |
| 25991 | it does the final delivery of messages. (See the generic \return@_path@_add\ |
| 25992 | transport option.) Therefore, they should not be present in messages in |
| 25993 | transit. If the \return@_path@_remove\ configuration option is set (the |
| 25994 | default), Exim removes ::Return-path:: header lines from incoming messages. |
| 25995 | |
| 25996 | |
| 25997 | .section The Sender: header line |
| 25998 | .rset SECTthesenhea "~~chapter.~~section" |
| 25999 | .index ::Sender:: header line |
| 26000 | For a locally-originated message from an untrusted user, Exim may remove an |
| 26001 | existing ::Sender:: header line, and it may add a new one. You can modify these |
| 26002 | actions by setting \local@_sender@_retain\ true or \local@_from@_check\ false. |
| 26003 | |
| 26004 | When a local message is received from an untrusted user and |
| 26005 | \local@_from@_check\ is true (the default), a check is made to see if the |
| 26006 | address given in the ::From:: header line is the correct (local) sender of the |
| 26007 | message. The address that is expected has the login name as the local part and |
| 26008 | the value of \qualify@_domain\ as the domain. Prefixes and suffixes for the |
| 26009 | local part can be permitted by setting \local@_from@_prefix\ and |
| 26010 | \local@_from@_suffix\ appropriately. If ::From:: does not contain the correct |
| 26011 | sender, a ::Sender:: line is added to the message. |
| 26012 | |
| 26013 | If you set \local@_from@_check\ false, this checking does not occur. However, |
| 26014 | the removal of an existing ::Sender:: line still happens, unless you also set |
| 26015 | \local@_sender@_retain\ to be true. It is not possible to set both of these |
| 26016 | options true at the same time. |
| 26017 | |
| 26018 | By default, no processing of ::Sender:: header lines is done for messages |
| 26019 | received by TCP/IP or for messages submitted by trusted users. However, when a |
| 26020 | message is received over TCP/IP in submission mode, ::Sender:: header lines are |
| 26021 | always removed. If the SMTP session is authenticated, and \$authenticated@_id$\ |
| 26022 | is not empty, a sender address is created with \$authenticated@_id$\ as the |
| 26023 | local part and either the domain specified in the submission control or, if |
| 26024 | that is not specified, \$qualify@_domain$\ as the domain. This is compared with |
| 26025 | the address in the ::From:: header line. If they are different, a ::Sender:: |
| 26026 | header line is added. Prefixes and suffixes for the local part in ::From:: can |
| 26027 | be permitted by setting \local@_from@_prefix\ and \local@_from@_suffix\ |
| 26028 | appropriately. |
| 26029 | |
| 26030 | |
| 26031 | .section Adding and removing header lines |
| 26032 | .index header lines||adding |
| 26033 | .index header lines||removing |
| 26034 | .rset SECTheadersaddrem "~~chapter.~~section" |
| 26035 | When a message is delivered, the addition and removal of header lines can be |
| 26036 | specified on any of the routers and transports, and also in the system filter. |
| 26037 | Changes specified in the system filter affect all deliveries of a message. |
| 26038 | |
| 26039 | Header changes specified on a router affect all addresses handled by that |
| 26040 | router, and also any new addresses it generates. If an address passes through |
| 26041 | several routers, the changes are cumulative. When a message is processed by a |
| 26042 | transport, the message's original set of header lines is output, except for |
| 26043 | those named in any \headers@_remove\ options that the address has encountered |
| 26044 | as it was processed, and any in the transport's own \headers@_remove\ option. |
| 26045 | Then the new header lines from \headers@_add\ options are output. |
| 26046 | |
| 26047 | |
| 26048 | .section Constructed addresses |
| 26049 | .rset SECTconstr "~~chapter.~~section" |
| 26050 | .index address||constructed |
| 26051 | .index constructed address |
| 26052 | When Exim constructs a sender address for a locally-generated message, it uses |
| 26053 | the form |
| 26054 | .display |
| 26055 | <<user name>> <$$<<login>>@@<<qualify@_domain>>$$> |
| 26056 | .endd |
| 26057 | For example: |
| 26058 | .display asis |
| 26059 | Zaphod Beeblebrox <zaphod@end.univ.example> |
| 26060 | .endd |
| 26061 | The user name is obtained from the \-F-\ command line option if set, or |
| 26062 | otherwise by looking up the calling user by \*getpwuid()*\ and extracting the |
| 26063 | `gecos' field from the password entry. If the `gecos' field contains an |
| 26064 | ampersand character, this is replaced by the login name with the first letter |
| 26065 | upper cased, as is conventional in a number of operating systems. See the |
| 26066 | \gecos@_name\ option for a way to tailor the handling of the `gecos' field. The |
| 26067 | \unknown@_username\ option can be used to specify user names in cases when |
| 26068 | there is no password file entry. |
| 26069 | |
| 26070 | In all cases, the user name is made to conform to RFC 2822 by quoting all or |
| 26071 | parts of it if necessary. In addition, if it contains any non-printing |
| 26072 | characters, it is encoded as described in RFC 2047, which defines a way of |
| 26073 | including non-ASCII characters in header lines. |
| 26074 | The value of the \headers@_charset\ option specifies the name of the encoding |
| 26075 | that is used (the characters are assumed to be in this encoding). |
| 26076 | The setting of \print@_topbitchars\ controls whether characters with the top |
| 26077 | bit set (that is, with codes greater than 127) count as printing characters or |
| 26078 | not. |
| 26079 | |
| 26080 | |
| 26081 | .section Case of local parts |
| 26082 | .index case of local parts |
| 26083 | .index local part||case of |
| 26084 | RFC 2822 states that the case of letters in the local parts of addresses cannot |
| 26085 | be assumed to be non-significant. Exim preserves the case of local parts of |
| 26086 | addresses, but by default it uses a lower-cased form when it is routing, |
| 26087 | because on most Unix systems, usernames are in lower case and case-insensitive |
| 26088 | routing is required. However, any particular router can be made to use the |
| 26089 | original case for local parts by setting the \caseful@_local@_part\ generic |
| 26090 | router option. |
| 26091 | |
| 26092 | .index mixed-case login names |
| 26093 | If you must have mixed-case user names on your system, the best way to proceed, |
| 26094 | assuming you want case-independent handling of incoming email, is to set up |
| 26095 | your first router to convert incoming local parts in your domains to the |
| 26096 | correct case by means of a file lookup. For example: |
| 26097 | .display asis |
| 26098 | correct_case: |
| 26099 | driver = redirect |
| 26100 | domains = +local_domains |
| 26101 | data = ${lookup{$local_part}cdb\ |
| 26102 | {/etc/usercased.cdb}{$value}fail}\ |
| 26103 | @$domain |
| 26104 | .endd |
| 26105 | For this router, the local part is forced to lower case by the default action |
| 26106 | (\caseful@_local@_part\ is not set). The lower-cased local part is used to look |
| 26107 | up a new local part in the correct case. If you then set \caseful@_local@_part\ |
| 26108 | on any subsequent routers which process your domains, they will operate on |
| 26109 | local parts with the correct case in a case-sensitive manner. |
| 26110 | |
| 26111 | |
| 26112 | .section Dots in local parts |
| 26113 | .index dot||in local part |
| 26114 | .index local part||dots in |
| 26115 | RFC 2822 forbids empty components in local parts. That is, an unquoted local |
| 26116 | part may not begin or end with a dot, nor have two consecutive dots in the |
| 26117 | middle. However, it seems that many MTAs do not enforce this, so Exim permits |
| 26118 | empty components for compatibility. |
| 26119 | |
| 26120 | |
| 26121 | .section Rewriting addresses |
| 26122 | .index rewriting||addresses |
| 26123 | Rewriting of sender and recipient addresses, and addresses in headers, can |
| 26124 | happen automatically, or as the result of configuration options, as described |
| 26125 | in chapter ~~CHAPrewrite. The headers that may be affected by this are ::Bcc::, |
| 26126 | ::Cc::, ::From::, ::Reply-To::, ::Sender::, and ::To::. |
| 26127 | |
| 26128 | Automatic rewriting includes qualification, as mentioned above. The other case |
| 26129 | in which it can happen is when an incomplete non-local domain is given. The |
| 26130 | routing process may cause this to be expanded into the full domain name. For |
| 26131 | example, a header such as |
| 26132 | .display asis |
| 26133 | To: hare@teaparty |
| 26134 | .endd |
| 26135 | might get rewritten as |
| 26136 | .display asis |
| 26137 | To: hare@teaparty.wonderland.fict.example |
| 26138 | .endd |
| 26139 | Rewriting as a result of routing is the one kind of message processing that |
| 26140 | does not happen at input time, as it cannot be done until the address has |
| 26141 | been routed. |
| 26142 | |
| 26143 | Strictly, one should not do $it{any} deliveries of a message until all its |
| 26144 | addresses have been routed, in case any of the headers get changed as a |
| 26145 | result of routing. However, doing this in practice would hold up many |
| 26146 | deliveries for unreasonable amounts of time, just because one address could not |
| 26147 | immediately be routed. Exim therefore does not delay other deliveries when |
| 26148 | routing of one or more addresses is deferred. |
| 26149 | |
| 26150 | |
| 26151 | |
| 26152 | |
| 26153 | |
| 26154 | . |
| 26155 | . |
| 26156 | . |
| 26157 | . |
| 26158 | . ============================================================================ |
| 26159 | .chapter Log files |
| 26160 | .set runningfoot "log files" |
| 26161 | .rset CHAPlog "~~chapter" |
| 26162 | .index log||types of |
| 26163 | .index log||general description |
| 26164 | Exim writes three different logs, referred to as the main log, the reject log, |
| 26165 | and the panic log: |
| 26166 | .numberpars $. |
| 26167 | .index main log |
| 26168 | The main log records the arrival of each message and each delivery in a single |
| 26169 | line in each case. The format is as compact as possible, in an attempt to keep |
| 26170 | down the size of log files. Two-character flag sequences make it easy to pick |
| 26171 | out these lines. A number of other events are recorded in the main log. Some of |
| 26172 | them are optional, in which case the \log@_selector\ option controls whether |
| 26173 | they are included or not. A Perl script called \*eximstats*\, which does simple |
| 26174 | analysis of main log files, is provided in the Exim distribution (see section |
| 26175 | ~~SECTmailstat). |
| 26176 | .nextp |
| 26177 | .index reject log |
| 26178 | The reject log records information from messages that are rejected as a result |
| 26179 | of a configuration option (that is, for policy reasons). |
| 26180 | The first line of each rejection is a copy of the line that is also written to |
| 26181 | the main log. Then, if the message's header has been read at the time the log |
| 26182 | is written, its contents are written to this log. Only the original header |
| 26183 | lines are available; header lines added by ACLs are not logged. You can use the |
| 26184 | reject log to check that your policy controls are working correctly; on a busy |
| 26185 | host this may be easier than scanning the main log for rejection messages. You |
| 26186 | can suppress the writing of the reject log by setting \write@_rejectlog\ false. |
| 26187 | .nextp |
| 26188 | .index panic log |
| 26189 | .index system log |
| 26190 | When certain serious errors occur, Exim writes entries to its panic log. If the |
| 26191 | error is sufficiently disastrous, Exim bombs out afterwards. Panic log entries |
| 26192 | are usually written to the main log as well, but can get lost amid the mass of |
| 26193 | other entries. The panic log should be empty under normal circumstances. It is |
| 26194 | therefore a good idea to check it (or to have a \*cron*\ script check it) |
| 26195 | regularly, in order to become aware of any problems. When Exim cannot open its |
| 26196 | panic log, it tries as a last resort to write to the system log (syslog). This |
| 26197 | is opened with LOG@_PID+LOG@_CONS and the facility code of LOG@_MAIL. The |
| 26198 | message itself is written at priority LOG@_CRIT. |
| 26199 | .endp |
| 26200 | Every log line starts with a timestamp, in the format shown in this example: |
| 26201 | .display asis |
| 26202 | 2001-09-16 16:09:47 SMTP connection from [127.0.0.1] closed by QUIT |
| 26203 | .endd |
| 26204 | By default, the timestamps are in the local timezone. There are two |
| 26205 | ways of changing this: |
| 26206 | .numberpars $. |
| 26207 | You can set the \timezone\ option to a different time zone; in particular, if |
| 26208 | you set |
| 26209 | .display asis |
| 26210 | timezone = UTC |
| 26211 | .endd |
| 26212 | the timestamps will be in UTC (aka GMT). |
| 26213 | .nextp |
| 26214 | If you set \log@_timezone\ true, the time zone is added to the timestamp, for |
| 26215 | example: |
| 26216 | .display asis |
| 26217 | 2003-04-25 11:17:07 +0100 Start queue run: pid=12762 |
| 26218 | .endd |
| 26219 | .endp |
| 26220 | |
| 26221 | |
| 26222 | |
| 26223 | .section Where the logs are written |
| 26224 | .rset SECTwhelogwri "~~chapter.~~section" |
| 26225 | .index log||destination |
| 26226 | .index log||to file |
| 26227 | .index log||to syslog |
| 26228 | .index syslog |
| 26229 | The logs may be written to local files, or to syslog, or both. However, it |
| 26230 | should be noted that many syslog implementations use UDP as a transport, and |
| 26231 | are therefore unreliable in the sense that messages are not guaranteed to |
| 26232 | arrive at the loghost, nor is the ordering of messages necessarily maintained. |
| 26233 | It has also been reported that on large log files (tens of megabytes) you may |
| 26234 | need to tweak syslog to prevent it syncing the file with each write -- on Linux |
| 26235 | this has been seen to make syslog take 90% plus of CPU time. |
| 26236 | |
| 26237 | The destination for Exim's logs is configured by setting \\LOG@_FILE@_PATH\\ in |
| 26238 | \(Local/Makefile)\ or by setting \log@_file@_path\ in the run time |
| 26239 | configuration. This latter string is expanded, so it can contain, for example, |
| 26240 | references to the host name: |
| 26241 | .display asis |
| 26242 | log_file_path = /var/log/$primary_hostname/exim_%slog |
| 26243 | .endd |
| 26244 | It is generally advisable, however, to set the string in \(Local/Makefile)\ |
| 26245 | rather than at run time, because then the setting is available right from the |
| 26246 | start of Exim's execution. Otherwise, if there's something it wants to log |
| 26247 | before it has read the configuration file (for example, an error in the |
| 26248 | configuration file) it will not use the path you want, and may not be able to |
| 26249 | log at all. |
| 26250 | |
| 26251 | The value of \\LOG@_FILE@_PATH\\ or \log@_file@_path\ is a colon-separated |
| 26252 | list, currently limited to at most two items. This is one option where the |
| 26253 | facility for changing a list separator may not be used. The list must always be |
| 26254 | colon-separated. If an item in the list is `syslog' then syslog is used; |
| 26255 | otherwise the item must either be an absolute path, containing \"%s"\ at the |
| 26256 | point where `main', `reject', or `panic' is to be inserted, or be empty, |
| 26257 | implying the use of a default path. |
| 26258 | |
| 26259 | When Exim encounters an empty item in the list, it searches the list defined by |
| 26260 | \\LOG@_FILE@_PATH\\, and uses the first item it finds that is neither empty nor |
| 26261 | `syslog'. This means that an empty item in \log@_file@_path\ can be used to |
| 26262 | mean `use the path specified at build time'. It no such item exists, log files |
| 26263 | are written in the \(log)\ subdirectory of the spool directory. This is |
| 26264 | equivalent to the setting: |
| 26265 | .display asis |
| 26266 | log_file_path = $spool_directory/log/%slog |
| 26267 | .endd |
| 26268 | If you do not specify anything at build time or run time, that is where the |
| 26269 | logs are written. |
| 26270 | |
| 26271 | A log file path may also contain \"%D"\ if datestamped log file names are in |
| 26272 | use -- see section ~~SECTdatlogfil below. |
| 26273 | |
| 26274 | Here are some examples of possible settings: |
| 26275 | .display |
| 26276 | .tabs 42 |
| 26277 | LOG@_FILE@_PATH=syslog $t $rm{syslog only} |
| 26278 | LOG@_FILE@_PATH=:syslog $t $rm{syslog and default path} |
| 26279 | LOG@_FILE@_PATH=syslog : /usr/log/exim@_%s $t $rm{syslog and specified path} |
| 26280 | LOG@_FILE@_PATH=/usr/log/exim@_%s $t $rm{specified path only} |
| 26281 | .endd |
| 26282 | If there are more than two paths in the list, the first is used and a panic |
| 26283 | error is logged. |
| 26284 | |
| 26285 | |
| 26286 | .section Logging to local files that are periodically `cycled' |
| 26287 | .index log||cycling local files |
| 26288 | .index cycling logs |
| 26289 | .index \*exicyclog*\ |
| 26290 | .index log||local files, writing to |
| 26291 | Some operating systems provide centralized and standardised methods for cycling |
| 26292 | log files. For those that do not, a utility script called \*exicyclog*\ is |
| 26293 | provided (see section ~~SECTcyclogfil). This renames and compresses the main |
| 26294 | and reject logs each time it is called. The maximum number of old logs to keep |
| 26295 | can be set. It is suggested this script is run as a daily \*cron*\ job. |
| 26296 | |
| 26297 | An Exim delivery process opens the main log when it first needs to write to it, |
| 26298 | and it keeps the file open in case subsequent entries are required -- for |
| 26299 | example, if a number of different deliveries are being done for the same |
| 26300 | message. However, remote SMTP deliveries can take a long time, and this means |
| 26301 | that the file may be kept open long after it is renamed if \*exicyclog*\ or |
| 26302 | something similar is being used to rename log files on a regular basis. To |
| 26303 | ensure that a switch of log files is noticed as soon as possible, Exim calls |
| 26304 | \*stat()*\ on the main log's name before reusing an open file, and if the file |
| 26305 | does not exist, or its inode has changed, the old file is closed and Exim |
| 26306 | tries to open the main log from scratch. Thus, an old log file may remain open |
| 26307 | for quite some time, but no Exim processes should write to it once it has been |
| 26308 | renamed. |
| 26309 | |
| 26310 | |
| 26311 | .section Datestamped log files |
| 26312 | .rset SECTdatlogfil "~~chapter.~~section" |
| 26313 | .index log||datestamped files |
| 26314 | Instead of cycling the main and reject log files by renaming them |
| 26315 | periodically, some sites like to use files whose names contain a datestamp, |
| 26316 | for example, \(mainlog-20031225)\. The datestamp is in the form \(yyyymmdd)\. |
| 26317 | Exim has support for this way of working. It is enabled by setting the |
| 26318 | \log@_file@_path\ option to a path that includes \"%D"\ at the point where the |
| 26319 | datestamp is required. For example: |
| 26320 | .display asis |
| 26321 | log_file_path = /var/spool/exim/log/%slog-%D |
| 26322 | log_file_path = /var/log/exim-%s-%D.log |
| 26323 | log_file_path = /var/spool/exim/log/%D-%slog |
| 26324 | .endd |
| 26325 | As before, \"%s"\ is replaced by `main' or `reject'; the following are examples |
| 26326 | of names generated by the above examples: |
| 26327 | .display asis |
| 26328 | /var/spool/exim/log/mainlog-20021225 |
| 26329 | /var/log/exim-reject-20021225.log |
| 26330 | /var/spool/exim/log/20021225-mainlog |
| 26331 | .endd |
| 26332 | When this form of log file is specified, Exim automatically switches to new |
| 26333 | files at midnight. It does not make any attempt to compress old logs; you |
| 26334 | will need to write your own script if you require this. You should not |
| 26335 | run \*exicyclog*\ with this form of logging. |
| 26336 | |
| 26337 | The location of the panic log is also determined by \log@_file@_path\, but it |
| 26338 | is not datestamped, because rotation of the panic log does not make sense. |
| 26339 | When generating the name of the panic log, \"%D"\ is removed from the string. |
| 26340 | In addition, if it immediately follows a slash, a following non-alphanumeric |
| 26341 | character is removed; otherwise a preceding non-alphanumeric character is |
| 26342 | removed. Thus, the three examples above would give these panic log names: |
| 26343 | .display asis |
| 26344 | /var/spool/exim/log/paniclog |
| 26345 | /var/log/exim-panic.log |
| 26346 | /var/spool/exim/log/paniclog |
| 26347 | .endd |
| 26348 | |
| 26349 | |
| 26350 | .section Logging to syslog |
| 26351 | .index log||syslog, writing to |
| 26352 | The use of syslog does not change what Exim logs or the format of its messages, |
| 26353 | except in one respect. If \syslog@_timestamp\ is set false, the timestamps on |
| 26354 | Exim's log lines are omitted when these lines are sent to syslog. Apart from |
| 26355 | that, the same strings are written to syslog as to log files. The syslog |
| 26356 | `facility' is set to \\LOG@_MAIL\\, and the program name to `exim' |
| 26357 | by default, but you can change these by setting the \syslog@_facility\ and |
| 26358 | \syslog@_processname\ options, respectively. If Exim was compiled with |
| 26359 | \\SYSLOG@_LOG@_PID\\ set in \(Local/Makefile)\ (this is the default in |
| 26360 | \(src/EDITME)\), then, on systems that permit it (all except ULTRIX), the |
| 26361 | \\LOG@_PID\\ flag is set so that the \*syslog()*\ call adds the pid as well as |
| 26362 | the time and host name to each line. |
| 26363 | The three log streams are mapped onto syslog priorities as follows: |
| 26364 | .numberpars " " |
| 26365 | \*mainlog*\ is mapped to \\LOG@_INFO\\ |
| 26366 | .nextp |
| 26367 | \*rejectlog*\ is mapped to \\LOG@_NOTICE\\ |
| 26368 | .nextp |
| 26369 | \*paniclog*\ is mapped to \\LOG@_ALERT\\ |
| 26370 | .endp |
| 26371 | Many log lines are written to both \*mainlog*\ and \*rejectlog*\, and some are |
| 26372 | written to both \*mainlog*\ and \*paniclog*\, so there will be duplicates if |
| 26373 | these are routed by syslog to the same place. You can suppress this duplication |
| 26374 | by setting \syslog@_duplication\ false. |
| 26375 | |
| 26376 | Exim's log lines can sometimes be very long, and some of its \*rejectlog*\ |
| 26377 | entries contain multiple lines when headers are included. To cope with both |
| 26378 | these cases, entries written to syslog are split into separate \*syslog()*\ |
| 26379 | calls at each internal newline, and also after a maximum of |
| 26380 | 870 data characters. (This allows for a total syslog line length of 1024, when |
| 26381 | additions such as timestamps are added.) If you are running a syslog |
| 26382 | replacement that can handle lines longer than the 1024 characters allowed by |
| 26383 | RFC 3164, you should set |
| 26384 | .display asis |
| 26385 | SYSLOG_LONG_LINES=yes |
| 26386 | .endd |
| 26387 | in \(Local/Makefile)\ before building Exim. That stops Exim from splitting long |
| 26388 | lines, but it still splits at internal newlines in \*reject*\ log entries. |
| 26389 | |
| 26390 | To make it easy to re-assemble split lines later, each component of a split |
| 26391 | entry starts with a string of the form `[<<n>>/<<m>>]' or `[<<n>>@\<<m>>]' |
| 26392 | where <<n>> is the component number and <<m>> is the total number of components |
| 26393 | in the entry. The / delimiter is used when the line was split because it was |
| 26394 | too long; if it was split because of an internal newline, the @\ delimiter is |
| 26395 | used. For example, supposing the length limit to be 70 instead of 1000, the |
| 26396 | following would be the result of a typical rejection message to \*mainlog*\ |
| 26397 | (LOG@_INFO), each line in addition being preceded by the time, host name, and |
| 26398 | pid as added by syslog: |
| 26399 | .display |
| 26400 | .indent 0 |
| 26401 | $smc{[1/3] 2002-09-16 16:09:43 16RdAL-0006pc-00 rejected from [127.0.0.1] (ph10): |
| 26402 | [2/3] syntax error in 'From' header when scanning for sender: missing or ma |
| 26403 | [3/3] lformed local part in "<>" (envelope sender is <ph10@@cam.example>)} |
| 26404 | .endd |
| 26405 | The same error might cause the following lines to be written to `rejectlog' |
| 26406 | (LOG@_NOTICE): |
| 26407 | .display flow |
| 26408 | .indent 0 |
| 26409 | $smc{[1/14] 2002-09-16 16:09:43 16RdAL-0006pc-00 rejected from [127.0.0.1] (ph10): |
| 26410 | [2/14] syntax error in 'From' header when scanning for sender: missing or ma |
| 26411 | [3@\14] lformed local part in "@<@>" (envelope sender is <ph10@@cam.example>) |
| 26412 | [4@\14] Recipients: ph10@@some.domain.cam.example |
| 26413 | [5@\14] P Received: from [127.0.0.1] (ident=ph10) |
| 26414 | [6@\14] by xxxxx.cam.example with smtp (Exim 4.00) |
| 26415 | [7@\14] id 16RdAL-0006pc-00 |
| 26416 | [8@\14] for ph10@@cam.example; Mon, 16 Sep 2002 16:09:43 +0100 |
| 26417 | [9@\14] F From: @<@> |
| 26418 | [10@\14] Subject: this is a test header |
| 26419 | [11@\14] X-something: this is another header |
| 26420 | [12@\14] I Message-Id: <E16RdAL-0006pc-00@@xxxxx.cam.example> |
| 26421 | [13@\14] B Bcc: |
| 26422 | [14/14] Date: Mon, 16 Sep 2002 16:09:43 +0100} |
| 26423 | .endd |
| 26424 | Log lines that are neither too long nor contain newlines are written to syslog |
| 26425 | without modification. |
| 26426 | |
| 26427 | If only syslog is being used, the Exim monitor is unable to provide a log tail |
| 26428 | display, unless syslog is routing \*mainlog*\ to a file on the local host and |
| 26429 | the environment variable \\EXIMON@_LOG@_FILE@_PATH\\ is set to tell the monitor |
| 26430 | where it is. |
| 26431 | |
| 26432 | |
| 26433 | .section Log line flags |
| 26434 | One line is written to the main log for each message received, and for each |
| 26435 | successful, unsuccessful, and delayed delivery. These lines can readily be |
| 26436 | picked out by the distinctive two-character flags that immediately follow the |
| 26437 | timestamp. The flags are: |
| 26438 | .display |
| 26439 | .tabs 6 |
| 26440 | <= $t $rm{message arrival} |
| 26441 | => $t $rm{normal message delivery} |
| 26442 | -> $t $rm{additional address in same delivery} |
| 26443 | *> $t $rm{delivery suppressed by \-N-\} |
| 26444 | ** $t $rm{delivery failed; address bounced} |
| 26445 | == $t $rm{delivery deferred; temporary problem} |
| 26446 | .endd |
| 26447 | |
| 26448 | |
| 26449 | .section Logging message reception |
| 26450 | .index log||reception line |
| 26451 | The format of the single-line entry in the main log that is written for every |
| 26452 | message received is shown in the basic example below, which is split over |
| 26453 | several lines in order to fit it on the page: |
| 26454 | .display |
| 26455 | .indent 0 |
| 26456 | 2002-10-31 08:57:53 16ZCW1-0005MB-00 <= kryten@@dwarf.fict.example |
| 26457 | H=mailer.fict.example [192.168.123.123] U=exim |
| 26458 | P=smtp S=5678 id=<<incoming message id>> |
| 26459 | .endd |
| 26460 | The address immediately following `<=' is the envelope sender address. A bounce |
| 26461 | message is shown with the sender address `<>', and if it is locally generated, |
| 26462 | this is followed by an item of the form |
| 26463 | .display |
| 26464 | R=<<message id>> |
| 26465 | .endd |
| 26466 | which is a reference to the message that caused the bounce to be sent. |
| 26467 | |
| 26468 | .index \\HELO\\ |
| 26469 | .index \\EHLO\\ |
| 26470 | For messages from other hosts, the H and U fields identify the remote host and |
| 26471 | record the RFC 1413 identity of the user that sent the message, if one was |
| 26472 | received. The number given in square brackets is the IP address of the sending |
| 26473 | host. If there is a single, unparenthesized host name in the H field, as |
| 26474 | above, it has been verified to correspond to the IP address (see the |
| 26475 | \host@_lookup\ option). If the name is in parentheses, it was the name quoted |
| 26476 | by the remote host in the SMTP \\HELO\\ or \\EHLO\\ command, and has not been |
| 26477 | verified. If verification yields a different name to that given for \\HELO\\ or |
| 26478 | \\EHLO\\, the verified name appears first, followed by the \\HELO\\ or \\EHLO\\ |
| 26479 | name in parentheses. |
| 26480 | |
| 26481 | Misconfigured hosts (and mail forgers) sometimes put an IP address, with or |
| 26482 | without brackets, in the \\HELO\\ or \\EHLO\\ command, leading to entries in |
| 26483 | the log containing text like these examples: |
| 26484 | .display |
| 26485 | H=(10.21.32.43) [192.168.8.34] |
| 26486 | H=([10.21.32.43]) [192.168.8.34] |
| 26487 | .endd |
| 26488 | This can be confusing. Only the final address in square brackets can be relied |
| 26489 | on. |
| 26490 | |
| 26491 | For locally generated messages (that is, messages not received over TCP/IP), |
| 26492 | the H field is omitted, and the U field contains the login name of the caller |
| 26493 | of Exim. |
| 26494 | |
| 26495 | .index authentication||logging |
| 26496 | .index \\AUTH\\||logging |
| 26497 | For all messages, the P field specifies the protocol used to receive the |
| 26498 | message. This is set to `asmtp' for messages received from hosts which have |
| 26499 | authenticated themselves using the SMTP \\AUTH\\ command. In this case there is |
| 26500 | an additional item A= followed by the name of the authenticator that was used. |
| 26501 | If an authenticated identification was set up by the authenticator's |
| 26502 | \server@_set@_id\ option, this is logged too, separated by a colon from the |
| 26503 | authenticator name. |
| 26504 | |
| 26505 | The id field records the existing message id, if present. |
| 26506 | .index size||of message |
| 26507 | The size of the received message is given by the S field. When the message is |
| 26508 | delivered, headers may get removed or added, so that the size of delivered |
| 26509 | copies of the message may not correspond with this value (and indeed may be |
| 26510 | different to each other). |
| 26511 | |
| 26512 | The \log@_selector\ option can be used to request the logging of additional |
| 26513 | data when a message is received. See section ~~SECTlogselector below. |
| 26514 | |
| 26515 | |
| 26516 | .section Logging deliveries |
| 26517 | .index log||delivery line |
| 26518 | The format of the single-line entry in the main log that is written for every |
| 26519 | delivery is shown in one of the examples below, for local and remote deliveries, |
| 26520 | respectively. Each example has been split into two lines in order to fit |
| 26521 | it on the page: |
| 26522 | .display |
| 26523 | .indent 0 |
| 26524 | 2002-10-31 08:59:13 16ZCW1-0005MB-00 => marv <marv@@hitch.fict.example> |
| 26525 | R=localuser T=local@_delivery |
| 26526 | 2002-10-31 09:00:10 16ZCW1-0005MB-00 => monk@@holistic.fict.example |
| 26527 | R=dnslookup T=remote@_smtp H=holistic.fict.example [192.168.234.234] |
| 26528 | .endd |
| 26529 | For ordinary local deliveries, the original address is given in angle brackets |
| 26530 | after the final delivery address, which might be a pipe or a file. If |
| 26531 | intermediate address(es) exist between the original and the final address, the |
| 26532 | last of these is given in parentheses after the final address. The R and T |
| 26533 | fields record the router and transport that were used to process the address. |
| 26534 | |
| 26535 | If a shadow transport was run after a successful local delivery, the log line |
| 26536 | for the successful delivery has an item added on the end, of the form |
| 26537 | .display |
| 26538 | ST=<<shadow transport name>> |
| 26539 | .endd |
| 26540 | If the shadow transport did not succeed, the error message is put in |
| 26541 | parentheses afterwards. |
| 26542 | |
| 26543 | When more than one address is included in a single delivery (for example, two |
| 26544 | SMTP \\RCPT\\ commands in one transaction) the second and subsequent |
| 26545 | addresses are flagged with `$tt{@-@>}' instead of `$tt{@=@>}'. When two or more |
| 26546 | messages are delivered down a single SMTP connection, an asterisk follows the |
| 26547 | IP address in the log lines for the second and subsequent messages. |
| 26548 | |
| 26549 | The generation of a reply message by a filter file gets logged as a `delivery' |
| 26550 | to the addressee, preceded by `>'. |
| 26551 | |
| 26552 | The \log@_selector\ option can be used to request the logging of additional |
| 26553 | data when a message is delivered. See section ~~SECTlogselector below. |
| 26554 | |
| 26555 | |
| 26556 | .section Discarded deliveries |
| 26557 | .index discarded messages |
| 26558 | .index message||discarded |
| 26559 | .index delivery||discarded, logging |
| 26560 | When a message is discarded as a result of the command `seen finish' being |
| 26561 | obeyed in a filter file which generates no deliveries, a log entry of the form |
| 26562 | .display |
| 26563 | 2002-12-10 00:50:49 16auJc-0001UB-00 => discarded |
| 26564 | <low.club@@bridge.example> R=userforward |
| 26565 | .endd |
| 26566 | is written, to record why no deliveries are logged. When a message is discarded |
| 26567 | because it is aliased to `:blackhole:' the log line is like this: |
| 26568 | .display asis |
| 26569 | 1999-03-02 09:44:33 10HmaX-0005vi-00 => :blackhole: |
| 26570 | <hole@nowhere.example> R=blackhole_router |
| 26571 | .endd |
| 26572 | |
| 26573 | |
| 26574 | .section Deferred deliveries |
| 26575 | When a delivery is deferred, a line of the following form is logged: |
| 26576 | .display |
| 26577 | .indent 0 |
| 26578 | 2002-12-19 16:20:23 16aiQz-0002Q5-00 == marvin@@endrest.example |
| 26579 | R=dnslookup T=smtp defer (146): Connection refused |
| 26580 | .endd |
| 26581 | In the case of remote deliveries, the error is the one that was given for the |
| 26582 | last IP address that was tried. Details of individual SMTP failures are also |
| 26583 | written to the log, so the above line would be preceded by something like |
| 26584 | .display |
| 26585 | .indent 0 |
| 26586 | 2002-12-19 16:20:23 16aiQz-0002Q5-00 Failed to connect to |
| 26587 | mail1.endrest.example [192.168.239.239]: Connection refused |
| 26588 | .endd |
| 26589 | When a deferred address is skipped because its retry time has not been reached, |
| 26590 | a message is written to the log, but this can be suppressed by setting an |
| 26591 | appropriate value in \log@_selector\. |
| 26592 | |
| 26593 | |
| 26594 | .section Delivery failures |
| 26595 | .index delivery||failure, logging |
| 26596 | If a delivery fails because an address cannot be routed, a line of the |
| 26597 | following form is logged: |
| 26598 | .display asis |
| 26599 | .indent 0 |
| 26600 | 1995-12-19 16:20:23 0tRiQz-0002Q5-00 ** jim@trek99.example |
| 26601 | <jim@trek99.example>: unknown mail domain |
| 26602 | .endd |
| 26603 | If a delivery fails at transport time, the router and transport are shown, and |
| 26604 | the response from the remote host is included, as in this example: |
| 26605 | .display asis |
| 26606 | .indent 0 |
| 26607 | 2002-07-11 07:14:17 17SXDU-000189-00 ** ace400@pb.example R=dnslookup |
| 26608 | .newline |
| 26609 | T=remote_smtp: SMTP error from remote mailer after pipelined |
| 26610 | .newline |
| 26611 | RCPT TO:<ace400@pb.example>: host pbmail3.py.example |
| 26612 | [192.168.63.111]: 553 5.3.0 <ace400@pb.example>... |
| 26613 | Addressee unknown |
| 26614 | .endd |
| 26615 | The word `pipelined' indicates that the SMTP \\PIPELINING\\ extension was being |
| 26616 | used. See \hosts@_avoid@_esmtp\ in the \%smtp%\ transport for a way of |
| 26617 | disabling \\PIPELINING\\. |
| 26618 | |
| 26619 | The log lines for all forms of delivery failure are flagged with \"**"\. |
| 26620 | |
| 26621 | |
| 26622 | .section Fake deliveries |
| 26623 | .index delivery||fake, logging |
| 26624 | If a delivery does not actually take place because the \-N-\ option has been |
| 26625 | used to suppress it, a normal delivery line is written to the log, except that |
| 26626 | `=>' is replaced by `$*$>'. |
| 26627 | |
| 26628 | |
| 26629 | .section Completion |
| 26630 | A line of the form |
| 26631 | .display |
| 26632 | 2002-10-31 09:00:11 16ZCW1-0005MB-00 Completed |
| 26633 | .endd |
| 26634 | is written to the main log when a message is about to be removed from the spool |
| 26635 | at the end of its processing. |
| 26636 | |
| 26637 | |
| 26638 | |
| 26639 | .section Summary of Fields in Log Lines |
| 26640 | .index log||summary of fields |
| 26641 | A summary of the field identifiers that are used in log lines is shown in |
| 26642 | the following table: |
| 26643 | .display flow |
| 26644 | .tabs 8 |
| 26645 | A $t $rm{authenticator name (and optional id)} |
| 26646 | C $t $rm{SMTP confirmation on delivery} |
| 26647 | .newline |
| 26648 | CV $t $rm{certificate verification status} |
| 26649 | DN $t $rm{distinguished name from peer certificate} |
| 26650 | DT $t $rm{time taken for a delivery} |
| 26651 | .newline |
| 26652 | F $t $rm{sender address (on delivery lines)} |
| 26653 | H $t $rm{host name and IP address} |
| 26654 | .newline |
| 26655 | I $t $rm{local interface used} |
| 26656 | .newline |
| 26657 | id $t $rm{message id for incoming message} |
| 26658 | P $t $rm{on \"<="\ lines: protocol used} |
| 26659 | .newline |
| 26660 | $t $rm{on \"=>"\ lines: return path} |
| 26661 | QT $t $rm{time spent on queue} |
| 26662 | .newline |
| 26663 | R $t $rm{on \"<="\ lines: reference for local bounce} |
| 26664 | $t $rm{on \"=>"\ lines: router name} |
| 26665 | S $t $rm{size of message} |
| 26666 | ST $t $rm{shadow transport name} |
| 26667 | T $t $rm{on \"<="\ lines: message subject (topic)} |
| 26668 | $t $rm{on \"=>"\ lines: transport name} |
| 26669 | U $t $rm{local user or RFC 1413 identity} |
| 26670 | X $t $rm{TLS cipher suite} |
| 26671 | .endd |
| 26672 | |
| 26673 | |
| 26674 | .section Other log entries |
| 26675 | Various other types of log entry are written from time to time. Most should be |
| 26676 | self-explanatory. Among the more common are: |
| 26677 | .numberpars $. |
| 26678 | .index retry||time not reached |
| 26679 | \*retry time not reached*\##An address previously suffered a temporary error |
| 26680 | during routing or local delivery, and the time to retry has not yet arrived. |
| 26681 | This message is not written to an individual message log file unless it happens |
| 26682 | during the first delivery attempt. |
| 26683 | .nextp |
| 26684 | \*retry time not reached for any host*\##An address previously suffered |
| 26685 | temporary errors during remote delivery, and the retry time has not yet arrived |
| 26686 | for any of the hosts to which it is routed. |
| 26687 | .nextp |
| 26688 | .index spool directory||file locked |
| 26689 | \*spool file locked*\##An attempt to deliver a message cannot proceed because |
| 26690 | some other Exim process is already working on the message. This can be quite |
| 26691 | common if queue running processes are started at frequent intervals. The |
| 26692 | \*exiwhat*\ utility script can be used to find out what Exim processes are |
| 26693 | doing. |
| 26694 | .nextp |
| 26695 | .index error||ignored |
| 26696 | \*error ignored*\##There are several circumstances that give rise to this |
| 26697 | message: |
| 26698 | .numberpars " " |
| 26699 | Exim failed to deliver a bounce message whose age was greater than |
| 26700 | \ignore__bounce__errors__after\. The bounce was discarded. |
| 26701 | .nextp |
| 26702 | A filter file set up a delivery using the `noerror' option, and the delivery |
| 26703 | failed. The delivery was discarded. |
| 26704 | .nextp |
| 26705 | A delivery set up by a router configured with |
| 26706 | .display asis |
| 26707 | errors_to = <> |
| 26708 | .endd |
| 26709 | failed. The delivery was discarded. |
| 26710 | .endp |
| 26711 | .endp |
| 26712 | |
| 26713 | |
| 26714 | |
| 26715 | .section Reducing or increasing what is logged |
| 26716 | .rset SECTlogselector "~~chapter.~~section" |
| 26717 | .index log||selectors |
| 26718 | By setting the \log@_selector\ global option, you can disable some of Exim's |
| 26719 | default logging, or you can request additional logging. The value of |
| 26720 | \log@_selector\ is made up of names preceded by plus or minus characters. For |
| 26721 | example: |
| 26722 | .display asis |
| 26723 | log_selector = +arguments -retry_defer |
| 26724 | .endd |
| 26725 | The list of optional log items is in the following table, with the default |
| 26726 | selection marked by asterisks: |
| 26727 | .display flow |
| 26728 | .tabs 32 |
| 26729 | address@_rewrite $t $rm{address rewriting} |
| 26730 | all@_parents $t $rm{all parents in => lines} |
| 26731 | arguments $t $rm{command line arguments} |
| 26732 | *connection@_reject $t $rm{connection rejections} |
| 26733 | *delay@_delivery $t $rm{immediate delivery delayed} |
| 26734 | .newline |
| 26735 | deliver@_time $t $rm{time taken to perform delivery} |
| 26736 | .newline |
| 26737 | delivery@_size $t $rm{add S=nnn to => lines} |
| 26738 | *dnslist@_defer $t $rm{defers of DNS list (aka RBL) lookups} |
| 26739 | *etrn $t $rm{ETRN commands} |
| 26740 | *host@_lookup@_failed $t $rm{as it says} |
| 26741 | .newline |
| 26742 | ident@_timeout $t $rm{timeout for ident connection} |
| 26743 | .newline |
| 26744 | incoming@_interface $t $rm{incoming interface on <= lines} |
| 26745 | incoming@_port $t $rm{incoming port on <= lines} |
| 26746 | *lost@_incoming@_connection $t $rm{as it says (includes timeouts)} |
| 26747 | .newline |
| 26748 | outgoing@_port $t $rm{add remote port to => lines} |
| 26749 | .newline |
| 26750 | *queue@_run $t $rm{start and end queue runs} |
| 26751 | .newline |
| 26752 | queue@_time $t $rm{time on queue} |
| 26753 | .newline |
| 26754 | received@_recipients $t $rm{recipients on <= lines} |
| 26755 | received@_sender $t $rm{sender on <= lines} |
| 26756 | *rejected@_header $t $rm{header contents on reject log} |
| 26757 | *retry@_defer $t $rm{`retry time not reached'} |
| 26758 | .newline |
| 26759 | return@_path@_on@_delivery $t $rm{put return path on => and ** lines} |
| 26760 | .newline |
| 26761 | sender@_on@_delivery $t $rm{add sender to => lines} |
| 26762 | *size@_reject $t $rm{rejection because too big} |
| 26763 | *skip@_delivery $t $rm{delivery skipped in a queue run} |
| 26764 | .newline |
| 26765 | smtp@_confirmation $t $rm{SMTP confirmation on => lines} |
| 26766 | .newline |
| 26767 | smtp@_connection $t $rm{SMTP connections} |
| 26768 | smtp@_incomplete@_transaction $t $rm{incomplete SMTP transactions} |
| 26769 | smtp@_protocol@_error $t $rm{SMTP protocol errors} |
| 26770 | smtp@_syntax@_error $t $rm{SMTP syntax errors} |
| 26771 | subject $t $rm{contents of ::Subject:: on <= lines} |
| 26772 | .newline |
| 26773 | tls@_certificate@_verified $t $rm{certificate verification status} |
| 26774 | .newline |
| 26775 | *tls@_cipher $t $rm{TLS cipher suite on <= and => lines} |
| 26776 | tls@_peerdn $t $rm{TLS peer DN on <= and => lines} |
| 26777 | |
| 26778 | all $t $rm{all of the above} |
| 26779 | .endd |
| 26780 | More details on each of these items follows: |
| 26781 | .numberpars $. |
| 26782 | .index log||rewriting |
| 26783 | .index rewriting||logging |
| 26784 | \address@_rewrite\: This applies both to global rewrites and per-transport |
| 26785 | rewrites, |
| 26786 | but not to rewrites in filters run as an unprivileged user (because such users |
| 26787 | cannot access the log). |
| 26788 | .nextp |
| 26789 | .index log||full parentage |
| 26790 | \all@_parents\: Normally only the original and final addresses are logged on |
| 26791 | delivery lines; with this selector, intermediate parents are given in |
| 26792 | parentheses between them. |
| 26793 | .nextp |
| 26794 | .index log||Exim arguments |
| 26795 | .index Exim arguments, logging |
| 26796 | \arguments\: This causes Exim to write the arguments with which it was called |
| 26797 | to the main log, |
| 26798 | preceded by the current working directory. |
| 26799 | This is a debugging feature, added to make it easier to find out how certain |
| 26800 | MUAs call \(/usr/sbin/sendmail)\. The logging does not happen if Exim has given |
| 26801 | up root privilege because it was called with the \-C-\ or \-D-\ options. |
| 26802 | Arguments that are empty or that contain whitespace are quoted. Non-printing |
| 26803 | characters are shown as escape sequences. |
| 26804 | This facility cannot log unrecognized arguments, because the arguments are |
| 26805 | checked before the configuration file is read. The only way to log such cases |
| 26806 | is to interpose a script such as \(util/logargs.sh)\ between the caller and |
| 26807 | Exim. |
| 26808 | .nextp |
| 26809 | .index log||connection rejections |
| 26810 | \connection@_reject\: A log entry is written whenever an incoming SMTP |
| 26811 | connection is rejected, for whatever reason. |
| 26812 | .nextp |
| 26813 | .index log||delayed delivery |
| 26814 | .index delayed delivery, logging |
| 26815 | \delay@_delivery\: A log entry is written whenever a delivery process is not |
| 26816 | started for an incoming message because the load is too high or too many |
| 26817 | messages were received on one connection. Logging does not occur if no delivery |
| 26818 | process is started because \queue@_only\ is set or \-odq-\ was used. |
| 26819 | .nextp |
| 26820 | .index log||delivery duration |
| 26821 | \deliver@_time\: For each delivery, the amount of real time it has taken to |
| 26822 | perform the actual delivery is logged as DT=<<time>>, for example, \"DT=1s"\. |
| 26823 | .nextp |
| 26824 | .index log||message size on delivery |
| 26825 | .index size||of message |
| 26826 | \delivery@_size\: For each delivery, the size of message delivered is added to |
| 26827 | the `=>' line, tagged with S=. |
| 26828 | .nextp |
| 26829 | .index log||dnslist defer |
| 26830 | .index DNS list||logging defer |
| 26831 | .index black list (DNS) |
| 26832 | \dnslist@_defer\: A log entry is written if an attempt to look up a host in a |
| 26833 | DNS black list suffers a temporary error. |
| 26834 | .nextp |
| 26835 | .index log||ETRN commands |
| 26836 | .index \\ETRN\\||logging |
| 26837 | \etrn\: Every legal ETRN command that is received is logged, before the ACL is |
| 26838 | run to determine whether or not it is actually accepted. An invalid ETRN |
| 26839 | command, or one received within a message transaction is not logged by this |
| 26840 | selector (see \smtp@_syntax@_error\ and \smtp@_protocol@_error\). |
| 26841 | .nextp |
| 26842 | .index log||host lookup failure |
| 26843 | \host@_lookup@_failed\: When a lookup of a host's IP addresses fails to find |
| 26844 | any addresses, or when a lookup of an IP address fails to find a host name, a |
| 26845 | log line is written. This logging does not apply to direct DNS lookups when |
| 26846 | routing email addresses, but it does apply to `byname' lookups. |
| 26847 | .nextp |
| 26848 | .index log||ident timeout |
| 26849 | .index RFC 1413||logging timeout |
| 26850 | \ident@_timeout\: A log line is written whenever an attempt to connect to a |
| 26851 | client's ident port times out. |
| 26852 | .nextp |
| 26853 | .index log||incoming interface |
| 26854 | .index interface||logging |
| 26855 | \incoming@_interface\: The interface on which a message was received is added |
| 26856 | to the `<=' line as an IP address in square brackets, tagged by I= and followed |
| 26857 | by a colon and the port number. |
| 26858 | The local interface and port are also added to other SMTP log |
| 26859 | lines, for example `SMTP connection from', and to rejection lines. |
| 26860 | .nextp |
| 26861 | .index log||incoming remote port |
| 26862 | .index port||logging remote |
| 26863 | .index TCP/IP||logging incoming remote port |
| 26864 | \incoming@_port\: The remote port number from which a message was received is |
| 26865 | added to log entries and ::Received:: header lines, following the IP address in |
| 26866 | square brackets, and separated from it by a colon. This is implemented by |
| 26867 | changing the value that is put in the \$sender@_fullhost$\ and |
| 26868 | \$sender@_rcvhost$\ variables. Recording the remote port number has become more |
| 26869 | important with the widening use of NAT (see RFC 2505). |
| 26870 | .nextp |
| 26871 | .index log||dropped connection |
| 26872 | \lost@_incoming@_connection\: A log line is written when an incoming SMTP |
| 26873 | connection is unexpectedly dropped. |
| 26874 | .nextp |
| 26875 | .index log||outgoing remote port |
| 26876 | .index port||logging outgoint remote |
| 26877 | .index TCP/IP||logging ougtoing remote port |
| 26878 | \outgoing@_port\: The remote port number is added to delivery log lines (those |
| 26879 | containing => tags) following the IP address. This option is not included in |
| 26880 | the default setting, because for most ordinary configurations, the remote port |
| 26881 | number is always 25 (the SMTP port). |
| 26882 | .nextp |
| 26883 | .index log||queue run |
| 26884 | .index queue runner||logging |
| 26885 | \queue@_run\: The start and end of every queue run are logged. |
| 26886 | .nextp |
| 26887 | .index log||queue time |
| 26888 | \queue@_time\: The amount of time the message has been in the queue on the |
| 26889 | local host is logged as QT=<<time>>, for example, \"QT=3m45s"\. The clock |
| 26890 | starts when Exim starts to receive the message, so it includes reception time |
| 26891 | as well as the delivery time of the current address. |
| 26892 | .nextp |
| 26893 | .index log||recipients |
| 26894 | \received@_recipients\: The recipients of a message are listed in the main log |
| 26895 | as soon as the message is received. The list appears at the end of the log line |
| 26896 | that is written when a message is received, preceded by the word `for'. The |
| 26897 | addresses are listed after they have been qualified, but before any rewriting |
| 26898 | has taken place. |
| 26899 | Recipients that were discarded by an ACL for \\MAIL\\ or \\RCPT\\ do not appear |
| 26900 | in the list. |
| 26901 | .nextp |
| 26902 | .index log||sender reception |
| 26903 | \received@_sender\: The unrewritten original sender of a message is added to |
| 26904 | the end of the log line that records the message's arrival, after the word |
| 26905 | `from' (before the recipients if \received@_recipients\ is also set). |
| 26906 | .nextp |
| 26907 | .index log||header lines for rejection |
| 26908 | \rejected@_header\: If a message's header has been received at the time a |
| 26909 | rejection is written to the reject log, the complete header is added to the |
| 26910 | log. Header logging can be turned off individually for messages that are |
| 26911 | rejected by the \*local@_scan()*\ function (see section ~~SECTapiforloc). |
| 26912 | .nextp |
| 26913 | .index log||retry defer |
| 26914 | \retry@_defer\: A log line is written if a delivery is deferred because a retry |
| 26915 | time has not yet been reached. However, this `retry time not reached' message |
| 26916 | is always omitted from individual message logs after the first delivery |
| 26917 | attempt. |
| 26918 | .nextp |
| 26919 | .index log||return path |
| 26920 | \return@_path@_on@_delivery\: The return path that is being transmitted with |
| 26921 | the message is included in delivery and bounce lines, using the tag P=. |
| 26922 | .nextp |
| 26923 | .index log||sender on delivery |
| 26924 | \sender@_on@_delivery\: The message's sender address is added to every delivery |
| 26925 | and bounce line, tagged by F= (for `from'). |
| 26926 | This is the original sender that was received with the message; it is not |
| 26927 | necessarily the same as the outgoing return path. |
| 26928 | .nextp |
| 26929 | .index log||size rejection |
| 26930 | \size@_reject\: A log line is written whenever a message is rejected because it |
| 26931 | is too big. |
| 26932 | .nextp |
| 26933 | .index log||frozen messages, skipped |
| 26934 | .index frozen messages||logging skipping |
| 26935 | \skip@_delivery\: A log line is written whenever a message is skipped during a |
| 26936 | queue run because it is frozen or because another process is already delivering |
| 26937 | it. |
| 26938 | .nextp |
| 26939 | .index log||smtp confirmation |
| 26940 | .index SMTP||logging confirmation |
| 26941 | \smtp@_confirmation\: The response to the final `.' in the SMTP dialogue for |
| 26942 | outgoing messages is added to delivery log lines in the form `C="<<text>>"'. A |
| 26943 | number of MTAs (including Exim) return an identifying string in this response. |
| 26944 | .nextp |
| 26945 | .index log||SMTP connections |
| 26946 | .index SMTP||logging connections |
| 26947 | \smtp@_connection\: A log line is written whenever an SMTP connection is |
| 26948 | established or closed. (By contrast, \lost@_incoming@_connection\ applies only |
| 26949 | when the closure is unexpected.) This applies to connections from local |
| 26950 | processes that use \-bs-\ as well as to TCP/IP connections. If a connection is |
| 26951 | dropped in the middle of a message, a log line is always written, whether this |
| 26952 | selector is set or not, but otherwise nothing is written at the start and end |
| 26953 | of connections unless this selector is enabled. |
| 26954 | |
| 26955 | For TCP/IP connections to an Exim daemon, the current number of connections is |
| 26956 | included in the log message for each new connection, but note that the count is |
| 26957 | reset if the daemon is restarted. |
| 26958 | Also, because connections are closed (and the closure is logged) in |
| 26959 | subprocesses, the count may not include connections that have been closed but |
| 26960 | whose termination the daemon has not yet noticed. Thus, while it is possible to |
| 26961 | match up the opening and closing of connections in the log, the value of the |
| 26962 | logged counts may not be entirely accurate. |
| 26963 | .nextp |
| 26964 | .index log||SMTP transaction, incomplete |
| 26965 | .index SMTP||logging incomplete transactions |
| 26966 | \smtp@_incomplete@_transaction\: When a mail transaction is aborted by |
| 26967 | \\RSET\\, \\QUIT\\, loss of connection, or otherwise, the incident is logged, |
| 26968 | and the message sender plus any accepted recipients are included in the log |
| 26969 | line. This can provide evidence of dictionary attacks. |
| 26970 | .nextp |
| 26971 | .index log||SMTP protocol error |
| 26972 | .index SMTP||logging protocol error |
| 26973 | \smtp@_protocol@_error\: A log line is written for every SMTP protocol error |
| 26974 | encountered. |
| 26975 | Exim does not have perfect detection of all protocol errors because of |
| 26976 | transmission delays and the use of pipelining. If \\PIPELINING\\ has been |
| 26977 | advertised to a client, an Exim server assumes that the client will use it, and |
| 26978 | therefore it does not count `expected' errors (for example, \\RCPT\\ received |
| 26979 | after rejecting \\MAIL\\) as protocol errors. |
| 26980 | .nextp |
| 26981 | .index SMTP||logging syntax errors |
| 26982 | .index SMTP||syntax errors, logging |
| 26983 | .index SMTP||unknown command, logging |
| 26984 | .index log||unknown SMTP command |
| 26985 | .index log||SMTP syntax error |
| 26986 | \smtp@_syntax@_error\: A log line is written for every SMTP syntax error |
| 26987 | encountered. An unrecognized command is treated as a syntax error. For an |
| 26988 | external connection, the host identity is given; for an internal connection |
| 26989 | using \-bs-\ the sender identification (normally the calling user) is given. |
| 26990 | .nextp |
| 26991 | .index log||subject |
| 26992 | .index subject, logging |
| 26993 | \subject\: The subject of the message is added to the arrival log line, |
| 26994 | preceded by `T=' (T for `topic', since S is already used for `size'). |
| 26995 | Any MIME `words' in the subject are decoded. The \print@_topbitchars\ option |
| 26996 | specifies whether characters with values greater than 127 should be logged |
| 26997 | unchanged, or whether they should be rendered as escape sequences. |
| 26998 | .nextp |
| 26999 | .index log||certificate verification |
| 27000 | \tls@_certificate@_verified\: An extra item is added to <= and => log lines |
| 27001 | when TLS is in use. The item is \"CV=yes"\ if the peer's certificate was |
| 27002 | verified, and \"CV=no"\ if not. |
| 27003 | .nextp |
| 27004 | .index log||TLS cipher |
| 27005 | .index TLS||logging cipher |
| 27006 | \tls@_cipher\: When a message is sent or received over an encrypted connection, |
| 27007 | the cipher suite used is added to the log line, preceded by X=. |
| 27008 | .nextp |
| 27009 | .index log||TLS peer DN |
| 27010 | .index TLS||logging peer DN |
| 27011 | \tls@_peerdn\: When a message is sent or received over an encrypted connection, |
| 27012 | and a certificate is supplied by the remote host, the peer DN is added to the |
| 27013 | log line, preceded by DN=. |
| 27014 | .endp |
| 27015 | |
| 27016 | .section Message log |
| 27017 | .index message||log file for |
| 27018 | .index log||message log, description of |
| 27019 | In addition to the general log files, Exim writes a log file for each message |
| 27020 | that it handles. The names of these per-message logs are the message ids, and |
| 27021 | .index \(msglog)\ directory |
| 27022 | they are kept in the \(msglog)\ sub-directory of the spool directory. Each |
| 27023 | message log contains copies of the log lines that apply to the message. This |
| 27024 | makes it easier to inspect the status of an individual message without having |
| 27025 | to search the main log. A message log is deleted when processing of the message |
| 27026 | is complete, |
| 27027 | .index \preserve@_message@_logs\ |
| 27028 | unless \preserve__message__logs\ is set, but this should be used only with |
| 27029 | great care because they can fill up your disk very quickly. |
| 27030 | |
| 27031 | On a heavily loaded system, it may be desirable to disable the use of |
| 27032 | per-message logs, in order to reduce disk I/O. This can be done by setting the |
| 27033 | \message@_logs\ option false. |
| 27034 | |
| 27035 | |
| 27036 | |
| 27037 | . |
| 27038 | . |
| 27039 | . |
| 27040 | . ============================================================================ |
| 27041 | .chapter Exim utilities |
| 27042 | .set runningfoot "utilities" |
| 27043 | .rset CHAPutils ~~chapter |
| 27044 | .index utilities |
| 27045 | A number of utility scripts and programs are supplied with Exim and are |
| 27046 | described in this chapter. There is also the Exim Monitor, which is covered in |
| 27047 | the next chapter. The utilities described here are: |
| 27048 | |
| 27049 | . This duplication seems to be the only way to arrange that the cross- |
| 27050 | . references are omitted in the Texinfo version. They look horribly ugly. |
| 27051 | |
| 27052 | .if ~~texinfo |
| 27053 | .display rm |
| 27054 | .tabs 22 |
| 27055 | \*exiwhat*\ $t $rm{list what Exim processes are doing} |
| 27056 | .newline |
| 27057 | \*exiqgrep*\ $t $rm{grep the queue} |
| 27058 | .newline |
| 27059 | \*exiqsumm*\ $t $rm{summarize the queue} |
| 27060 | \*exigrep*\ $t $rm{search the main log} |
| 27061 | \*exipick*\ $t $rm{select messages on various criteria} |
| 27062 | \*exicyclog*\ $t $rm{cycle (rotate) log files} |
| 27063 | \*eximstats*\ $t $rm{extract statistics from the log} |
| 27064 | \*exim@_checkaccess*\ $t $rm{check address acceptance from given IP} |
| 27065 | \*exim@_dbmbuild*\ $t $rm{build a DBM file} |
| 27066 | \*exinext*\ $t $rm{extract retry information} |
| 27067 | \*exim@_dumpdb*\ $t $rm{dump a hints database} |
| 27068 | \*exim@_tidydb*\ $t $rm{clean up a hints database} |
| 27069 | \*exim@_fixdb*\ $t $rm{patch a hints database} |
| 27070 | \*exim@_lock*\ $t $rm{lock a mailbox file} |
| 27071 | .endd |
| 27072 | . |
| 27073 | .else |
| 27074 | . |
| 27075 | .display rm |
| 27076 | .tabs 22 |
| 27077 | ~~SECTfinoutwha \*exiwhat*\ $t $rm{list what Exim processes are doing} |
| 27078 | .newline |
| 27079 | ~~SECTgreptheque \*exiqgrep*\ $t $rm{grep the queue} |
| 27080 | .newline |
| 27081 | ~~SECTsumtheque \*exiqsumm*\ $t $rm{summarize the queue} |
| 27082 | ~~SECTextspeinf \*exigrep*\ $t $rm{search the main log} |
| 27083 | .newline |
| 27084 | ~~SECTexipick \*exipick*\ $t $rm{select messages on various criteria} |
| 27085 | .newline |
| 27086 | ~~SECTcyclogfil \*exicyclog*\ $t $rm{cycle (rotate) log files} |
| 27087 | ~~SECTmailstat \*eximstats*\ $t $rm{extract statistics from the log} |
| 27088 | ~~SECTcheckaccess \*exim@_checkaccess*\ $t $rm{check address acceptance from given IP} |
| 27089 | ~~SECTdbmbuild \*exim@_dbmbuild*\ $t $rm{build a DBM file} |
| 27090 | ~~SECTfinindret \*exinext*\ $t $rm{extract retry information} |
| 27091 | ~~SECThindatmai \*exim@_dumpdb*\ $t $rm{dump a hints database} |
| 27092 | ~~SECThindatmai \*exim@_tidydb*\ $t $rm{clean up a hints database} |
| 27093 | ~~SECThindatmai \*exim@_fixdb*\ $t $rm{patch a hints database} |
| 27094 | ~~SECTmailboxmaint \*exim@_lock*\ $t $rm{lock a mailbox file} |
| 27095 | .endd |
| 27096 | .fi |
| 27097 | |
| 27098 | .section Finding out what Exim processes are doing (exiwhat) |
| 27099 | .rset SECTfinoutwha "~~chapter.~~section" |
| 27100 | .index \*exiwhat*\ |
| 27101 | .index process, querying |
| 27102 | .index \\SIGUSR1\\ |
| 27103 | On operating systems that can restart a system call after receiving a signal |
| 27104 | (most modern OS), an Exim process responds to the \\SIGUSR1\\ signal by writing |
| 27105 | a line describing what it is doing to the file \(exim-process.info)\ in the |
| 27106 | Exim spool directory. The \*exiwhat*\ script sends the signal to all Exim |
| 27107 | processes it can find, having first emptied the file. It then waits for one |
| 27108 | second to allow the Exim processes to react before displaying the results. |
| 27109 | In order to run \*exiwhat*\ successfully you have to have sufficient privilege to |
| 27110 | send the signal to the Exim processes, so it is normally run as root. |
| 27111 | |
| 27112 | Unfortunately, the \*ps*\ command which \*exiwhat*\ uses to find Exim processes |
| 27113 | varies in different operating systems. Not only are different options used, |
| 27114 | but the format of the output is different. For this reason, there are some |
| 27115 | system configuration options that configure exactly how \*exiwhat*\ works. If it |
| 27116 | doesn't seem to be working for you, check the following compile-time options: |
| 27117 | .display |
| 27118 | EXIWHAT@_PS@_CMD $rm{the command for running \*ps*\} |
| 27119 | EXIWHAT@_PS@_ARG $rm{the argument for \*ps*\} |
| 27120 | EXIWHAT@_EGREP@_ARG $rm{the argument for \*egrep*\ to select from \*ps*\ output} |
| 27121 | EXIWHAT@_KILL@_ARG $rm{the argument for the \*kill*\ command} |
| 27122 | .endd |
| 27123 | An example of typical output from \*exiwhat*\ is |
| 27124 | .display |
| 27125 | .indent 0 |
| 27126 | 164 daemon: -q1h, listening on port 25 |
| 27127 | 10483 running queue: waiting for 0tAycK-0002ij-00 (10492) |
| 27128 | 10492 delivering 0tAycK-0002ij-00 to mail.ref.example [10.19.42.42] |
| 27129 | (editor@@ref.example) |
| 27130 | 10592 handling incoming call from [192.168.243.242] |
| 27131 | 10628 accepting a local non-SMTP message |
| 27132 | .endd |
| 27133 | The first number in the output line is the process number. The third line has |
| 27134 | been split here, in order to fit it on the page. |
| 27135 | |
| 27136 | |
| 27137 | .section Selective queue listing (exiqgrep) |
| 27138 | .rset SECTgreptheque "~~chapter.~~section" |
| 27139 | .index \*exiqgrep*\ |
| 27140 | .index queue||grepping |
| 27141 | This utility is a Perl script contributed by Matt Hubbard. It runs |
| 27142 | .display asis |
| 27143 | exim -bpu |
| 27144 | .endd |
| 27145 | to obtain a queue listing with undelivered recipients only, and then greps the |
| 27146 | output to select messages that match given criteria. The following selection |
| 27147 | options are available: |
| 27148 | |
| 27149 | .startoptions |
| 27150 | |
| 27151 | .option f <<regex>> |
| 27152 | Match the sender address. The field that is tested is enclosed in angle |
| 27153 | brackets, so you can test for bounce messages with |
| 27154 | .display asis |
| 27155 | exiqgrep -f '^<>$' |
| 27156 | .endd |
| 27157 | |
| 27158 | .option r <<regex>> |
| 27159 | Match a recipient address. The field that is tested is not enclosed in angle |
| 27160 | brackets. |
| 27161 | |
| 27162 | .option s <<regex>> |
| 27163 | Match against the size field. |
| 27164 | |
| 27165 | .option y <<seconds>> |
| 27166 | Match messages that are younger than the given time. |
| 27167 | |
| 27168 | .option o <<seconds>> |
| 27169 | Match messages that are older than the given time. |
| 27170 | |
| 27171 | .option z |
| 27172 | Match only frozen messages. |
| 27173 | |
| 27174 | .option x |
| 27175 | Match only non-frozen messages. |
| 27176 | |
| 27177 | .endoptions |
| 27178 | |
| 27179 | The following options control the format of the output: |
| 27180 | |
| 27181 | .startoptions |
| 27182 | |
| 27183 | .option c |
| 27184 | Display only the count of matching messages. |
| 27185 | |
| 27186 | .option l |
| 27187 | Long format -- display the full message information as output by Exim. This is |
| 27188 | the default. |
| 27189 | |
| 27190 | .option i |
| 27191 | Display message ids only. |
| 27192 | |
| 27193 | .option b |
| 27194 | Brief format -- one line per message. |
| 27195 | |
| 27196 | .option R |
| 27197 | Display messages in reverse order. |
| 27198 | |
| 27199 | .endoptions |
| 27200 | |
| 27201 | There is one more option, \-h-\, which outputs a list of options. |
| 27202 | |
| 27203 | |
| 27204 | .section Summarising the queue (exiqsumm) |
| 27205 | .rset SECTsumtheque "~~chapter.~~section" |
| 27206 | .index \*exiqsumm*\ |
| 27207 | .index queue||summary |
| 27208 | The \*exiqsumm*\ utility is a Perl script which reads the output of \*exim |
| 27209 | -bp*\ and produces a summary of the messages on the queue. Thus, you use it by |
| 27210 | running a command such as |
| 27211 | .display asis |
| 27212 | exim -bp | exiqsumm |
| 27213 | .endd |
| 27214 | The output consists of one line for each domain that has messages waiting for |
| 27215 | it, as in the following example: |
| 27216 | .display asis |
| 27217 | 3 2322 74m 66m msn.com.example |
| 27218 | .endd |
| 27219 | Each line lists the number of |
| 27220 | pending deliveries for a domain, their total volume, and the length of time |
| 27221 | that the oldest and the newest messages have been waiting. Note that the number |
| 27222 | of pending deliveries is greater than the number of messages when messages |
| 27223 | have more than one recipient. |
| 27224 | |
| 27225 | A summary line is output at the end. By default the output is sorted on the |
| 27226 | domain name, but \*exiqsumm*\ has the options \-a-\ and \-c-\, which cause the |
| 27227 | output to be sorted by oldest message and by count of messages, respectively. |
| 27228 | |
| 27229 | The output of \*exim -bp*\ contains the original addresses in the message, so |
| 27230 | this also applies to the output from \*exiqsumm*\. No domains from addresses |
| 27231 | generated by aliasing or forwarding are included (unless the \one@_time\ option |
| 27232 | of the \%redirect%\ router has been used to convert them into `top level' |
| 27233 | addresses). |
| 27234 | |
| 27235 | |
| 27236 | |
| 27237 | .section Extracting specific information from the log (exigrep) |
| 27238 | .rset SECTextspeinf "~~chapter.~~section" |
| 27239 | .index \*exigrep*\ |
| 27240 | .index log||extracts, grepping for |
| 27241 | The \*exigrep*\ utility is a Perl script that searches one or more main log |
| 27242 | files for entries that match a given pattern. When it finds a match, it |
| 27243 | extracts all the log entries for the relevant message, not just those that |
| 27244 | match the pattern. Thus, \*exigrep*\ can extract complete log entries for a |
| 27245 | given message, or all mail for a given user, or for a given host, for example. |
| 27246 | |
| 27247 | If a matching log line is not associated with a specific message, it is always |
| 27248 | included in \*exigrep*\'s output. |
| 27249 | The usage is: |
| 27250 | .display asis |
| 27251 | exigrep [-l] [-t<n>] <pattern> [<log file>] ... |
| 27252 | .endd |
| 27253 | The \-t-\ argument specifies a number of seconds. It adds an additional |
| 27254 | condition for message selection. Messages that are complete are shown only if |
| 27255 | they spent more than <<n>> seconds on the queue. |
| 27256 | |
| 27257 | The \-l-\ flag means `literal', that is, treat all characters in the |
| 27258 | pattern as standing for themselves. Otherwise the pattern must be a Perl |
| 27259 | regular expression. The pattern match is case-insensitive. If no file names are |
| 27260 | given on the command line, the standard input is read. |
| 27261 | |
| 27262 | If the location of a \*zcat*\ command is known from the definition of |
| 27263 | \\ZCAT@_COMMAND\\ in \(Local/Makefile)\, \*exigrep*\ automatically passes any |
| 27264 | file whose name ends in \\COMPRESS@_SUFFIX\\ through \*zcat*\ as it searches |
| 27265 | it. |
| 27266 | |
| 27267 | .section Selecting messages by various criteria (exipick) |
| 27268 | .rset SECTexipick "~~chapter.~~section" |
| 27269 | .index \*exipick*\ |
| 27270 | John Jetmore's \*exipick*\ utility is included in the Exim distribution. It |
| 27271 | lists messages from the queue according to a variety of criteria. For details, |
| 27272 | run: |
| 27273 | .display asis |
| 27274 | exipick --help |
| 27275 | .endd |
| 27276 | |
| 27277 | |
| 27278 | .section Cycling log files (exicyclog) |
| 27279 | .rset SECTcyclogfil "~~chapter.~~section" |
| 27280 | .index log||cycling local files |
| 27281 | .index cycling logs |
| 27282 | .index \*exicyclog*\ |
| 27283 | The \*exicyclog*\ script can be used to cycle (rotate) \*mainlog*\ and |
| 27284 | \*rejectlog*\ files. This is not necessary if only syslog is being used, |
| 27285 | or if you are using log files with datestamps in their names (see section |
| 27286 | ~~SECTdatlogfil). |
| 27287 | Some operating systems have their own standard mechanisms for log cycling, and |
| 27288 | these can be used instead of \*exicyclog*\ if preferred. |
| 27289 | |
| 27290 | Each time \*exicyclog*\ is run the file names get `shuffled down' by one. If the |
| 27291 | main log file name is \(mainlog)\ (the default) then when \*exicyclog*\ is run |
| 27292 | \(mainlog)\ becomes \(mainlog.01)\, the previous \(mainlog.01)\ becomes |
| 27293 | \(mainlog.02)\ and so on, up to a limit which is set in the script, and which |
| 27294 | defaults to 10. Reject logs are handled similarly. |
| 27295 | |
| 27296 | If no \(mainlog)\ file exists, the script does nothing. Files that `drop off' |
| 27297 | the end are deleted. All files with numbers greater than 01 are compressed, |
| 27298 | using a compression command which is configured by the \\COMPRESS@_COMMAND\\ |
| 27299 | setting in \(Local/Makefile)\. It is usual to run \*exicyclog*\ daily from a |
| 27300 | root \crontab\ entry of the form |
| 27301 | .display |
| 27302 | 1 0 * * * su exim -c /usr/exim/bin/exicyclog |
| 27303 | .endd |
| 27304 | assuming you have used the name `exim' for the Exim user. You can run |
| 27305 | \*exicyclog*\ as root if you wish, but there is no need. |
| 27306 | |
| 27307 | |
| 27308 | .section Mail statistics (eximstats) |
| 27309 | .rset SECTmailstat "~~chapter.~~section" |
| 27310 | .index statistics |
| 27311 | .index \*eximstats*\ |
| 27312 | A Perl script called \*eximstats*\ is provided for extracting statistical |
| 27313 | information from log files. The output is either plain text, or HTML. |
| 27314 | Exim log files are also suported by the \*Lire*\ system produced by the |
| 27315 | LogReport Foundation (\?http://www.logreport.org?\). |
| 27316 | |
| 27317 | The \*eximstats*\ script has been hacked about quite a bit over time. The |
| 27318 | latest version is the result of some extensive revision by Steve Campbell. A |
| 27319 | lot of information is given by default, but there are options for suppressing |
| 27320 | various parts of it. Following any options, the arguments to the script are a |
| 27321 | list of files, which should be main log files. For example: |
| 27322 | .display asis |
| 27323 | eximstats -nr /var/spool/exim/log/mainlog.01 |
| 27324 | .endd |
| 27325 | By default, \*eximstats*\ extracts information about the number and volume of |
| 27326 | messages received from or delivered to various hosts. The information is sorted |
| 27327 | both by message count and by volume, and the top fifty hosts in each category |
| 27328 | are listed on the standard output. Similar information, based on email |
| 27329 | addresses or domains instead of hosts can be requested by means of various |
| 27330 | options. For messages delivered and received locally, similar statistics are |
| 27331 | also produced per user. |
| 27332 | |
| 27333 | The output also includes total counts and statistics about delivery errors, and |
| 27334 | histograms showing the number of messages received and deliveries made in each |
| 27335 | hour of the day. A delivery with more than one address in its envelope (for |
| 27336 | example, an SMTP transaction with more than one \\RCPT\\ command) is counted |
| 27337 | as a single delivery by \*eximstats*\. |
| 27338 | |
| 27339 | Though normally more deliveries than receipts are reported (as messages may |
| 27340 | have multiple recipients), it is possible for \*eximstats*\ to report more |
| 27341 | messages received than delivered, even though the queue is empty at the start |
| 27342 | and end of the period in question. If an incoming message contains no valid |
| 27343 | recipients, no deliveries are recorded for it. A bounce message is handled as |
| 27344 | an entirely separate message. |
| 27345 | |
| 27346 | \*eximstats*\ always outputs a grand total summary giving the volume and number |
| 27347 | of messages received and deliveries made, and the number of hosts involved in |
| 27348 | each case. It also outputs the number of messages that were delayed (that is, |
| 27349 | not completely delivered at the first attempt), and the number that had at |
| 27350 | least one address that failed. |
| 27351 | |
| 27352 | The remainder of the output is in sections that can be independently disabled |
| 27353 | or modified by various options. It consists of a summary of deliveries by |
| 27354 | transport, histograms of messages received and delivered per time interval |
| 27355 | (default per hour), information about the time messages spent on the queue, |
| 27356 | a list of relayed messages, lists of the top fifty sending hosts, local |
| 27357 | senders, destination hosts, and destination local users by count and by volume, |
| 27358 | and a list of delivery errors that occurred. |
| 27359 | |
| 27360 | The relay information lists messages that were actually relayed, that is, they |
| 27361 | came from a remote host and were directly delivered to some other remote host, |
| 27362 | without being processed (for example, for aliasing or forwarding) locally. |
| 27363 | |
| 27364 | The options for \*eximstats*\ are as follows: |
| 27365 | |
| 27366 | .startoptions |
| 27367 | .index \*eximstats*\||options |
| 27368 | .option bydomain |
| 27369 | The `league tables' are computed on the basis of the superior domains of the |
| 27370 | sending hosts instead of the sending and receiving hosts. This option may be |
| 27371 | combined with \-byhost-\ and/or \-byemail-\. |
| 27372 | |
| 27373 | .option byedomain |
| 27374 | This is a synonym for \-byemaildomain-\. |
| 27375 | |
| 27376 | .option byemail |
| 27377 | The `league tables' are computed on the basis of complete email addresses, |
| 27378 | instead of sending and receiving hosts. This option may be combined with |
| 27379 | \-byhost-\ and/or \-bydomain-\. |
| 27380 | |
| 27381 | .option byemaildomain |
| 27382 | The `league tables' are computed on the basis of the sender's email domain |
| 27383 | instead of the sending and receiving hosts. This option may be combined with |
| 27384 | \-byhost-\, \-bydomain-\, or \-byemail-\. |
| 27385 | |
| 27386 | .option byhost |
| 27387 | The `league tables' are computed on the basis of sending and receiving hosts. |
| 27388 | This is the default option. It may be combined with \-bydomain-\ and/or |
| 27389 | \-byemail-\. |
| 27390 | |
| 27391 | .option cache |
| 27392 | Cache results of \*timegm()*\ lookups. This results in a significant speedup |
| 27393 | when processing hundreds of thousands of messages, at a cost of increasing the |
| 27394 | memory utilisation. |
| 27395 | |
| 27396 | .option chartdir <<dir>> |
| 27397 | When \-charts-\ is specified, create the charts in the directory <<dir>>. |
| 27398 | |
| 27399 | .option chartrel <<dir>> |
| 27400 | When \-charts-\ is specified, this option specifies the relative directory for |
| 27401 | the \"img src="\ tags from where to include the charts. |
| 27402 | |
| 27403 | .option charts |
| 27404 | Create graphical charts to be displayed in HTML output. This requires the |
| 27405 | \"GD"\, \"GDTextUtil"\, and \"GDGraph"\ Perl modules, which can be obtained |
| 27406 | from \?http://www.cpan.org/modules/01modules.index.html?\. |
| 27407 | |
| 27408 | To install these, download and unpack them, then use the normal Perl |
| 27409 | installation procedure: |
| 27410 | .display asis |
| 27411 | perl Makefile.PL |
| 27412 | make |
| 27413 | make test |
| 27414 | make install |
| 27415 | .endd |
| 27416 | |
| 27417 | .option d |
| 27418 | This is a debug flag. It causes \*eximstats*\ to output the \*eval()*\'d parser |
| 27419 | to the standard output, which makes it easier to trap errors in the eval |
| 27420 | section. Remember to add one to the line numbers to allow for the title. |
| 27421 | |
| 27422 | |
| 27423 | .option help |
| 27424 | Show help information about \*eximstats*\' options. |
| 27425 | |
| 27426 | .option h <<n>> |
| 27427 | This option controls the histograms of messages received and deliveries per |
| 27428 | time interval. By default the time interval is one hour. If \-h0-\ is given, |
| 27429 | the histograms are suppressed; otherwise the value of <<n>> gives the number of |
| 27430 | divisions per hour. Valid values are 0, 1, 2, 3, 5, 10, 15, 20, 30 or 60, so |
| 27431 | \-h2-\ sets an interval of 30 minutes, and the default is equivalent to \-h1-\. |
| 27432 | |
| 27433 | .option html |
| 27434 | Output the results in HTML instead of plain text. |
| 27435 | |
| 27436 | .option merge |
| 27437 | This option causes \*eximstats*\ to merge old reports into a combined report. |
| 27438 | When this option is used, the input files must be outputs from previous calls |
| 27439 | to \*eximstats*\, not raw log files. For example, you could produce a set of |
| 27440 | daily reports and a weekly report by commands such as |
| 27441 | .display asis |
| 27442 | eximstats mainlog.sun > report.sun.txt |
| 27443 | eximstats mainlog.mon > report.mon.txt |
| 27444 | eximstats mainlog.tue > report.tue.txt |
| 27445 | eximstats mainlog.wed > report.wed.txt |
| 27446 | eximstats mainlog.thu > report.thu.txt |
| 27447 | eximstats mainlog.fri > report.fri.txt |
| 27448 | eximstats mainlog.sat > report.sat.txt |
| 27449 | eximstats -merge -html report.*.txt > weekly_report.html |
| 27450 | .endd |
| 27451 | You can merge text or html reports and output the results as text or html. You |
| 27452 | can use all the normal \*eximstats*\ output options, but only data included in |
| 27453 | the original reports can be shown. When merging reports, some loss of accuracy |
| 27454 | may occur in the `league tables', towards the ends of the lists. The order of |
| 27455 | items in the `league tables' may vary when the data volumes round to the same |
| 27456 | value. |
| 27457 | |
| 27458 | .option ne |
| 27459 | Suppress the display of information about failed deliveries (errors). |
| 27460 | |
| 27461 | .option nr |
| 27462 | Suppress information about messages relayed through this host. |
| 27463 | |
| 27464 | .option nr /pattern/ |
| 27465 | Suppress information about relayed messages that match the pattern, which is |
| 27466 | matched against a string of the following form (split over two lines here in |
| 27467 | order to fit it on the page): |
| 27468 | .display asis |
| 27469 | H=<host> [<ip address>] A=<sender address> => |
| 27470 | H=<host> A=<recipient address> |
| 27471 | .endd |
| 27472 | for example |
| 27473 | .display asis |
| 27474 | H=in.host [1.2.3.4] A=from@some.where.example => |
| 27475 | H=out.host A=to@else.where.example |
| 27476 | .endd |
| 27477 | The sending host name appears in parentheses if it has not been verified as |
| 27478 | matching the IP address. The mail addresses are taken from the envelope, not |
| 27479 | the headers. This option allows you to screen out hosts whom you are happy to |
| 27480 | have using your host as a relay. |
| 27481 | |
| 27482 | .option nt |
| 27483 | Suppress the statistics about delivery by transport. |
| 27484 | |
| 27485 | .option nt/<<pattern>>/ |
| 27486 | Suppress the statistics about delivery by any transport whose name matches the |
| 27487 | pattern. If you are using one transport to send all messages to a scanning |
| 27488 | mechanism before doing the real delivery, this feature can be used to omit that |
| 27489 | transport from your normal statistics (on the grounds that it is of no |
| 27490 | interest). |
| 27491 | |
| 27492 | |
| 27493 | .option "pattern" "#<<description>>#/<<pattern>>/" |
| 27494 | Count lines matching specified patterns and show them in |
| 27495 | the results. For example: |
| 27496 | .display asis |
| 27497 | -pattern 'Refused connections' '/refused connection/' |
| 27498 | .endd |
| 27499 | This option can be specified multiple times. |
| 27500 | |
| 27501 | .option q0 |
| 27502 | Suppress information about times messages spend on the queue. |
| 27503 | |
| 27504 | .option q <<n1>>... |
| 27505 | This option sets an alternative list of time intervals for the queueing |
| 27506 | information. The values are separated by commas and are in seconds, but can |
| 27507 | involve arithmetic multipliers, so for example you can set 3$*$60 to specify 3 |
| 27508 | minutes. A setting such as |
| 27509 | .display asis |
| 27510 | -q60,5*60,10*60 |
| 27511 | .endd |
| 27512 | causes \*eximstats*\ to give counts of messages that stayed on the queue for less |
| 27513 | than one minute, less than five minutes, less than ten minutes, and over ten |
| 27514 | minutes. |
| 27515 | |
| 27516 | .option t <<n>> |
| 27517 | Sets the `top' count to <<n>>. This controls the listings of the `top <<n>>' |
| 27518 | hosts and users by count and volume. The default is 50, and setting 0 |
| 27519 | suppresses the output altogether. |
| 27520 | |
| 27521 | .option tnl |
| 27522 | Omit local information from the `top' listings. |
| 27523 | |
| 27524 | .option t@_remote@_users |
| 27525 | Include remote users in the `top' listings. |
| 27526 | |
| 27527 | .endoptions |
| 27528 | |
| 27529 | |
| 27530 | .section Checking access policy (exim@_checkaccess) |
| 27531 | .rset SECTcheckaccess "~~chapter.~~section" |
| 27532 | .index \*exim@_checkaccess*\ |
| 27533 | .index policy control||checking access |
| 27534 | .index checking access |
| 27535 | The \-bh-\ command line argument allows you to run a fake SMTP session with |
| 27536 | debugging output, in order to check what Exim is doing when it is applying |
| 27537 | policy controls to incoming SMTP mail. However, not everybody is sufficiently |
| 27538 | familiar with the SMTP protocol to be able to make full use of \-bh-\, and |
| 27539 | sometimes you just want to answer the question \*Does this address have |
| 27540 | access?*\ without bothering with any further details. |
| 27541 | |
| 27542 | The \*exim@_checkaccess*\ utility is a `packaged' version of \-bh-\. It takes |
| 27543 | two arguments, an IP address and an email address: |
| 27544 | .display asis |
| 27545 | exim_checkaccess 10.9.8.7 A.User@a.domain.example |
| 27546 | .endd |
| 27547 | The utility runs a call to Exim with the \-bh-\ option, to test whether the |
| 27548 | given email address would be accepted in a \\RCPT\\ command in a TCP/IP |
| 27549 | connection from the host with the given IP address. The output of the utility |
| 27550 | is either the word `accepted', or the SMTP error response, for example: |
| 27551 | .display asis |
| 27552 | Rejected: |
| 27553 | 550 Relay not permitted |
| 27554 | .endd |
| 27555 | When running this test, the utility uses \"<>"\ as the envelope sender address |
| 27556 | for the \\MAIL\\ command, but you can change this by providing additional |
| 27557 | options. These are passed directly to the Exim command. For example, to specify |
| 27558 | that the test is to be run with the sender address \*himself@@there.example*\ |
| 27559 | you can use: |
| 27560 | .display asis |
| 27561 | exim_checkaccess 10.9.8.7 A.User@a.domain.example \ |
| 27562 | -f himself@there.example |
| 27563 | .endd |
| 27564 | Note that these additional Exim command line items must be given after the two |
| 27565 | mandatory arguments. |
| 27566 | |
| 27567 | Because the \exim@_checkaccess\ uses \-bh-\, it does not perform callouts while |
| 27568 | running its checks. You can run checks that include callouts by using \-bhc-\, |
| 27569 | but this is not yet available in a `packaged' form. |
| 27570 | |
| 27571 | |
| 27572 | .section Making DBM files (exim@_dbmbuild) |
| 27573 | .rset SECTdbmbuild "~~chapter.~~section" |
| 27574 | .index DBM||building dbm files |
| 27575 | .index building DBM files |
| 27576 | .index \*exim@_dbmbuild*\ |
| 27577 | .index lower casing |
| 27578 | .index binary zero||in lookup key |
| 27579 | The \*exim@_dbmbuild*\ program reads an input file containing keys and data in |
| 27580 | the format used by the \%lsearch%\ lookup (see section ~~SECTsinglekeylookups). |
| 27581 | It writes a DBM file using the lower-cased alias names as keys and the |
| 27582 | remainder of the information as data. The lower-casing can be prevented by |
| 27583 | calling the program with the \-nolc-\ option. |
| 27584 | |
| 27585 | A terminating zero is included as part of the key string. This is expected by |
| 27586 | the \%dbm%\ lookup type. However, if the option \-nozero-\ is given, |
| 27587 | \*exim@_dbmbuild*\ creates files without terminating zeroes in either the key |
| 27588 | strings or the data strings. The \%dbmnz%\ lookup type can be used with such |
| 27589 | files. |
| 27590 | |
| 27591 | The program requires two arguments: the name of the input file (which can be a |
| 27592 | single hyphen to indicate the standard input), and the name of the output file. |
| 27593 | It creates the output under a temporary name, and then renames it if all went |
| 27594 | well. |
| 27595 | .index \\USE@_DB\\ |
| 27596 | If the native DB interface is in use (\\USE@_DB\\ is set in a compile-time |
| 27597 | configuration file -- this is common in free versions of Unix) the two file |
| 27598 | names must be different, because in this mode the Berkeley DB functions create |
| 27599 | a single output file using exactly the name given. For example, |
| 27600 | .display asis |
| 27601 | exim_dbmbuild /etc/aliases /etc/aliases.db |
| 27602 | .endd |
| 27603 | reads the system alias file and creates a DBM version of it in |
| 27604 | \(/etc/aliases.db)\. |
| 27605 | |
| 27606 | In systems that use the \*ndbm*\ routines (mostly proprietary versions of Unix), |
| 27607 | two files are used, with the suffixes \(.dir)\ and \(.pag)\. In this |
| 27608 | environment, the suffixes are added to the second argument of |
| 27609 | \*exim@_dbmbuild*\, so it can be the same as the first. This is also the case |
| 27610 | when the Berkeley functions are used in compatibility mode (though this is not |
| 27611 | recommended), because in that case it adds a \(.db)\ suffix to the file name. |
| 27612 | |
| 27613 | If a duplicate key is encountered, the program outputs a warning, and when it |
| 27614 | finishes, its return code is 1 rather than zero, unless the \-noduperr-\ option |
| 27615 | is used. By default, only the first of a set of duplicates is used -- this |
| 27616 | makes it compatible with \%lsearch%\ lookups. There is an option \-lastdup-\ |
| 27617 | which causes it to use the data for the last duplicate instead. There is also |
| 27618 | an option \-nowarn-\, which stops it listing duplicate keys to \stderr\. For |
| 27619 | other errors, where it doesn't actually make a new file, the return code is 2. |
| 27620 | |
| 27621 | |
| 27622 | |
| 27623 | .section Finding individual retry times (exinext) |
| 27624 | .rset SECTfinindret "~~chapter.~~section" |
| 27625 | .index retry||times |
| 27626 | .index \*exinext*\ |
| 27627 | A utility called \*exinext*\ (mostly a Perl script) provides the ability to fish |
| 27628 | specific information out of the retry database. Given a mail domain (or a |
| 27629 | complete address), it looks up the hosts for that domain, and outputs any retry |
| 27630 | information for the hosts or for the domain. At present, the retry information |
| 27631 | is obtained by running \*exim@_dumpdb*\ (see below) and post-processing the |
| 27632 | output. For example: |
| 27633 | .display asis |
| 27634 | $ exinext piglet@milne.fict.example |
| 27635 | kanga.milne.fict.example:192.168.8.1 error 146: Connection refused |
| 27636 | first failed: 21-Feb-1996 14:57:34 |
| 27637 | last tried: 21-Feb-1996 14:57:34 |
| 27638 | next try at: 21-Feb-1996 15:02:34 |
| 27639 | roo.milne.fict.example:192.168.8.3 error 146: Connection refused |
| 27640 | first failed: 20-Jan-1996 13:12:08 |
| 27641 | last tried: 21-Feb-1996 11:42:03 |
| 27642 | next try at: 21-Feb-1996 19:42:03 |
| 27643 | past final cutoff time |
| 27644 | .endd |
| 27645 | You can also give \*exinext*\ a local part, without a domain, and it |
| 27646 | will give any retry information for that local part in your default domain. |
| 27647 | A message id can be used to obtain retry information pertaining to a specific |
| 27648 | message. This exists only when an attempt to deliver a message to a remote host |
| 27649 | suffers a message-specific error (see section ~~SECToutSMTPerr). \*exinext*\ is |
| 27650 | not particularly efficient, but then it isn't expected to be run very often. |
| 27651 | |
| 27652 | The \*exinext*\ utility calls Exim to find out information such as the location |
| 27653 | of the spool directory. The utility has \-C-\ and \-D-\ options, which are |
| 27654 | passed on to the \*exim*\ commands. The first specifies an alternate Exim |
| 27655 | configuration file, and the second sets macros for use within the configuration |
| 27656 | file. These features are mainly to help in testing, but might also be useful in |
| 27657 | environments where more than one configuration file is in use. |
| 27658 | |
| 27659 | |
| 27660 | |
| 27661 | .section Hints database maintenance (exim@_dumpdb, exim@_fixdb, exim@_tidydb) |
| 27662 | .rset SECThindatmai "~~chapter.~~section" |
| 27663 | .index hints database||maintenance |
| 27664 | .index maintaining Exim's hints database |
| 27665 | Three utility programs are provided for maintaining the DBM files that Exim |
| 27666 | uses to contain its delivery hint information. Each program requires two |
| 27667 | arguments. The first specifies the name of Exim's spool directory, and the |
| 27668 | second is the name of the database it is to operate on. These are as |
| 27669 | follows: |
| 27670 | .numberpars $. |
| 27671 | \*retry*\: the database of retry information |
| 27672 | .nextp |
| 27673 | \*wait-*\<<transport name>>: databases of information about messages waiting |
| 27674 | for remote hosts |
| 27675 | .nextp |
| 27676 | \*callout*\: the callout cache |
| 27677 | .nextp |
| 27678 | \*misc*\: other hints data |
| 27679 | .endp |
| 27680 | The \*misc*\ database is used for |
| 27681 | .numberpars alpha |
| 27682 | Serializing \\ETRN\\ runs (when \smtp@_etrn@_serialize\ is set) |
| 27683 | .nextp |
| 27684 | Serializing delivery to a specific host (when \serialize@_hosts\ is set in an |
| 27685 | \%smtp%\ transport) |
| 27686 | .endp |
| 27687 | .index \*exim@_dumpdb*\ |
| 27688 | The entire contents of a database are written to the standard output by the |
| 27689 | \*exim@_dumpdb*\ program, which has no options or arguments other than the |
| 27690 | spool and database names. For example, to dump the retry database: |
| 27691 | .display asis |
| 27692 | exim_dumpdb /var/spool/exim retry |
| 27693 | .endd |
| 27694 | Two lines of output are produced for each entry: |
| 27695 | .display |
| 27696 | T:mail.ref.example:192.168.242.242 146 77 Connection refused |
| 27697 | 31-Oct-1995 12:00:12 02-Nov-1995 12:21:39 02-Nov-1995 20:21:39 * |
| 27698 | .endd |
| 27699 | The first item on the first line is the key of the record. It starts with one |
| 27700 | of the letters R, or T, depending on whether it refers to a routing or |
| 27701 | transport retry. For a local delivery, the next part is the local address; for |
| 27702 | a remote delivery it is the name of the remote host, followed by its failing IP |
| 27703 | address (unless \no@_retry@_include@_ip@_address\ is set on the \%smtp%\ |
| 27704 | transport). |
| 27705 | If the remote port is not the standard one (port 25), it is added to the IP |
| 27706 | address. |
| 27707 | Then there follows an error code, an additional error code, and a |
| 27708 | textual description of the error. |
| 27709 | |
| 27710 | The three times on the second line are the time of first failure, the time of |
| 27711 | the last delivery attempt, and the computed time for the next attempt. The line |
| 27712 | ends with an asterisk if the cutoff time for the last retry rule has been |
| 27713 | exceeded. |
| 27714 | |
| 27715 | Each output line from \*exim@_dumpdb*\ for the \*wait-*\$it{xxx} databases |
| 27716 | consists of a host name followed by a list of ids for messages that are or were |
| 27717 | waiting to be delivered to that host. If there are a very large number for any |
| 27718 | one host, continuation records, with a sequence number added to the host name, |
| 27719 | may be seen. The data in these records is often out of date, because a message |
| 27720 | may be routed to several alternative hosts, and Exim makes no effort to keep |
| 27721 | cross-references. |
| 27722 | |
| 27723 | .index \*exim@_tidydb*\ |
| 27724 | The \*exim@_tidydb*\ utility program is used to tidy up the contents of the |
| 27725 | hints databases. If run with no options, it removes all records from a database |
| 27726 | that are more than 30 days old. The cutoff date can be altered by means of the |
| 27727 | \-t-\ option, which must be followed by a time. For example, to remove all |
| 27728 | records older than a week from the retry database: |
| 27729 | .display asis |
| 27730 | exim_tidydb -t 7d /var/spool/exim retry |
| 27731 | .endd |
| 27732 | Both the \*wait-*\$it{xxx} and \*retry*\ databases contain items that involve |
| 27733 | message ids. In the former these appear as data in records keyed by host -- |
| 27734 | they were messages that were waiting for that host -- and in the latter they |
| 27735 | are the keys for retry information for messages that have suffered certain |
| 27736 | types of error. When \*exim@_tidydb*\ is run, a check is made to ensure that |
| 27737 | message ids in database records are those of messages that are still on the |
| 27738 | queue. Message ids for messages that no longer exist are removed from |
| 27739 | \*wait-*\$it{xxx} records, and if this leaves any records empty, they are |
| 27740 | deleted. For the \*retry*\ database, records whose keys are non-existent message |
| 27741 | ids are removed. The \*exim@_tidydb*\ utility outputs comments on the standard |
| 27742 | output whenever it removes information from the database. |
| 27743 | |
| 27744 | Removing records from a DBM file does not normally make the file smaller, but |
| 27745 | all the common DBM libraries are able to re-use the space that is released. |
| 27746 | It is therefore suggested that \*exim@_tidydb*\ be run periodically on all the |
| 27747 | hints databases, but at a quiet time of day, because it requires a database to |
| 27748 | be locked (and therefore inaccessible to Exim) while it does its work. |
| 27749 | |
| 27750 | .index \*exim@_fixdb*\ |
| 27751 | The \*exim@_fixdb*\ program is a utility for interactively modifying databases. |
| 27752 | Its main use is for testing Exim, but it might also be occasionally useful for |
| 27753 | getting round problems in a live system. It has no options, and its interface |
| 27754 | is somewhat crude. On entry, it prompts for input with a right angle-bracket. A |
| 27755 | key of a database record can then be entered, and the data for that record is |
| 27756 | displayed. |
| 27757 | |
| 27758 | If `d' is typed at the next prompt, the entire record is deleted. For all |
| 27759 | except the \*retry*\ database, that is the only operation that can be carried |
| 27760 | out. For the \*retry*\ database, each field is output preceded by a number, and |
| 27761 | data for individual fields can be changed by typing the field number followed |
| 27762 | by new data, for example: |
| 27763 | .display asis |
| 27764 | > 4 951102:1000 |
| 27765 | .endd |
| 27766 | resets the time of the next delivery attempt. Time values are given as a |
| 27767 | sequence of digit pairs for year, month, day, hour, and minute. Colons can be |
| 27768 | used as optional separators. |
| 27769 | |
| 27770 | |
| 27771 | |
| 27772 | .section Mailbox maintenance (exim@_lock) |
| 27773 | .rset SECTmailboxmaint "~~chapter.~~section" |
| 27774 | .index mailbox||maintenance |
| 27775 | .index \*exim@_lock*\ |
| 27776 | .index locking mailboxes |
| 27777 | The \*exim@_lock*\ utility locks a mailbox file using the same algorithm as |
| 27778 | Exim. For a discussion of locking issues, see section ~~SECTopappend. |
| 27779 | \*Exim@_lock*\ can be used to prevent any modification of a mailbox by Exim or |
| 27780 | a user agent while investigating a problem. The utility requires the name of |
| 27781 | the file as its first argument. If the locking is successful, the second |
| 27782 | argument is run as a command (using C's \*system()*\ function); if there is no |
| 27783 | second argument, the value of the SHELL environment variable is used; if this |
| 27784 | is unset or empty, \(/bin/sh)\ is run. When the command finishes, the mailbox |
| 27785 | is unlocked and the utility ends. The following options are available: |
| 27786 | |
| 27787 | .startoptions |
| 27788 | |
| 27789 | .option fcntl |
| 27790 | Use \*fcntl()*\ locking on the open mailbox. |
| 27791 | |
| 27792 | .option flock |
| 27793 | Use \*flock()*\ locking on the open mailbox, provided the operating system |
| 27794 | supports it. |
| 27795 | |
| 27796 | .option interval |
| 27797 | This must be followed by a number, which is a number of seconds; it sets the |
| 27798 | interval to sleep between retries (default 3). |
| 27799 | |
| 27800 | .option lockfile |
| 27801 | Create a lock file before opening the mailbox. |
| 27802 | |
| 27803 | .option mbx |
| 27804 | Lock the mailbox using MBX rules. |
| 27805 | |
| 27806 | .option q |
| 27807 | Suppress verification output. |
| 27808 | |
| 27809 | .option retries |
| 27810 | This must be followed by a number; it sets the number of times to try to get |
| 27811 | the lock (default 10). |
| 27812 | |
| 27813 | .option restore@_time |
| 27814 | This option causes \exim@_lock\ to restore the modified and read times to the |
| 27815 | locked file before exiting. This allows you to access a locked mailbox (for |
| 27816 | example, to take a backup copy) without disturbing the times that the user |
| 27817 | subsequently sees. |
| 27818 | |
| 27819 | .option timeout |
| 27820 | This must be followed by a number, which is a number of seconds; it sets a |
| 27821 | timeout to be used with a blocking \*fcntl()*\ lock. If it is not set (the |
| 27822 | default), a non-blocking call is used. |
| 27823 | |
| 27824 | .option v |
| 27825 | Generate verbose output. |
| 27826 | |
| 27827 | .endoptions |
| 27828 | |
| 27829 | If none of \-fcntl-\, |
| 27830 | \-flock-\, |
| 27831 | \-lockfile-\ or \-mbx-\ are given, the default is to create a lock file and |
| 27832 | also to use \*fcntl()*\ locking on the mailbox, which is the same as Exim's |
| 27833 | default. The use of |
| 27834 | \-flock-\ |
| 27835 | or \-fcntl-\ requires that the file be writeable; the use of |
| 27836 | \-lockfile-\ requires that the directory containing the file be writeable. |
| 27837 | Locking by lock file does not last for ever; Exim assumes that a lock file is |
| 27838 | expired if it is more than 30 minutes old. |
| 27839 | |
| 27840 | The \-mbx-\ option can be used with either or both of \-fcntl-\ or \-flock-\. |
| 27841 | It assumes \-fcntl-\ by default. |
| 27842 | MBX locking causes a shared lock to be taken out on the open mailbox, and an |
| 27843 | exclusive lock on the file \(/tmp/.$it{n}.$it{m})\ where $it{n} and $it{m} are |
| 27844 | the device number and inode number of the mailbox file. When the locking is |
| 27845 | released, if an exclusive lock can be obtained for the mailbox, the file in |
| 27846 | \(/tmp)\ is deleted. |
| 27847 | |
| 27848 | The default output contains verification of the locking that takes place. The |
| 27849 | \-v-\ option causes some additional information to be given. The \-q-\ option |
| 27850 | suppresses all output except error messages. |
| 27851 | |
| 27852 | A command such as |
| 27853 | .display asis |
| 27854 | exim_lock /var/spool/mail/spqr |
| 27855 | .endd |
| 27856 | runs an interactive shell while the file is locked, whereas |
| 27857 | .display |
| 27858 | exim@_lock -q /var/spool/mail/spqr @<@<End |
| 27859 | <<some commands>> |
| 27860 | End |
| 27861 | .endd |
| 27862 | runs a specific non-interactive sequence of commands while the file is locked, |
| 27863 | suppressing all verification output. A single command can be run by a command |
| 27864 | such as |
| 27865 | .display asis |
| 27866 | exim_lock -q /var/spool/mail/spqr \ |
| 27867 | "cp /var/spool/mail/spqr /some/where" |
| 27868 | .endd |
| 27869 | Note that if a command is supplied, it must be entirely contained within the |
| 27870 | second argument -- hence the quotes. |
| 27871 | |
| 27872 | |
| 27873 | |
| 27874 | . |
| 27875 | . |
| 27876 | . |
| 27877 | . |
| 27878 | . ============================================================================ |
| 27879 | .chapter The Exim monitor |
| 27880 | .set runningfoot "monitor" |
| 27881 | .rset CHAPeximon ~~chapter |
| 27882 | .index monitor |
| 27883 | .index Exim monitor |
| 27884 | .index X-windows |
| 27885 | .index \*eximon*\ |
| 27886 | .index Local/eximon.conf |
| 27887 | .index \(exim@_monitor/EDITME)\ |
| 27888 | The Exim monitor is an application which displays in an X window information |
| 27889 | about the state of Exim's queue and what Exim is doing. An admin user can |
| 27890 | perform certain operations on messages from this GUI interface; however all |
| 27891 | such facilities are also available from the command line, and indeed, the |
| 27892 | monitor itself makes use of the command line to perform any actions requested. |
| 27893 | |
| 27894 | |
| 27895 | .section Running the monitor |
| 27896 | The monitor is started by running the script called \*eximon*\. This is a shell |
| 27897 | script that sets up a number of environment variables, and then runs the |
| 27898 | binary called \(eximon.bin)\. The default appearance of the monitor window can |
| 27899 | be changed by editing the \(Local/eximon.conf)\ file created by editing |
| 27900 | \(exim@_monitor/EDITME)\. Comments in that file describe what the various |
| 27901 | parameters are for. |
| 27902 | |
| 27903 | The parameters that get built into the \*eximon*\ script can be overridden for a |
| 27904 | particular invocation by setting up environment variables of the same names, |
| 27905 | preceded by `$tt{EXIMON@_}'. For example, a shell command such as |
| 27906 | .display asis |
| 27907 | EXIMON_LOG_DEPTH=400 eximon |
| 27908 | .endd |
| 27909 | (in a Bourne-compatible shell) runs \*eximon*\ with an overriding setting of the |
| 27910 | \\LOG@_DEPTH\\ parameter. If \\EXIMON@_LOG@_FILE@_PATH\\ is set in the |
| 27911 | environment, it overrides the Exim log file configuration. This makes it |
| 27912 | possible to have \*eximon*\ tailing log data that is written to syslog, provided |
| 27913 | that MAIL.INFO syslog messages are routed to a file on the local host. |
| 27914 | |
| 27915 | X resources can be used to change the appearance of the window in the normal |
| 27916 | way. For example, a resource setting of the form |
| 27917 | .display asis |
| 27918 | Eximon*background: gray94 |
| 27919 | .endd |
| 27920 | changes the colour of the background to light grey rather than white. The |
| 27921 | stripcharts are drawn with both the data lines and the reference lines in |
| 27922 | black. This means that the reference lines are not visible when on top of the |
| 27923 | data. However, their colour can be changed by setting a resource called |
| 27924 | `highlight' (an odd name, but that's what the Athena stripchart widget uses). |
| 27925 | For example, if your X server is running Unix, you could set up lighter |
| 27926 | reference lines in the stripcharts by obeying |
| 27927 | .display asis |
| 27928 | xrdb -merge <<End |
| 27929 | Eximon*highlight: gray |
| 27930 | End |
| 27931 | .endd |
| 27932 | |
| 27933 | .index admin user |
| 27934 | In order to see the contents of messages on the queue, and to operate on them, |
| 27935 | \*eximon*\ must either be run as root or by an admin user. |
| 27936 | |
| 27937 | The monitor's window is divided into three parts. The first contains one or |
| 27938 | more stripcharts and two action buttons, the second contains a `tail' of the |
| 27939 | main log file, and the third is a display of the queue of messages awaiting |
| 27940 | delivery, with two more action buttons. The following sections describe these |
| 27941 | different parts of the display. |
| 27942 | |
| 27943 | |
| 27944 | |
| 27945 | .section The stripcharts |
| 27946 | .index stripchart |
| 27947 | The first stripchart is always a count of messages on the queue. Its name can |
| 27948 | be configured by setting \\QUEUE@_STRIPCHART@_NAME\\ in the |
| 27949 | \(Local/eximon.conf)\ file. The remaining stripcharts are defined in the |
| 27950 | configuration script by regular expression matches on log file entries, making |
| 27951 | it possible to display, for example, counts of messages delivered to certain |
| 27952 | hosts or using certain transports. The supplied defaults display counts of |
| 27953 | received and delivered messages, and of local and SMTP deliveries. The default |
| 27954 | period between stripchart updates is one minute; this can be adjusted by a |
| 27955 | parameter in the \(Local/eximon.conf)\ file. |
| 27956 | |
| 27957 | The stripchart displays rescale themselves automatically as the value they are |
| 27958 | displaying changes. There are always 10 horizontal lines in each chart; the |
| 27959 | title string indicates the value of each division when it is greater than one. |
| 27960 | For example, `x2' means that each division represents a value of 2. |
| 27961 | |
| 27962 | It is also possible to have a stripchart which shows the percentage fullness of |
| 27963 | a particular disk partition, which is useful when local deliveries are confined |
| 27964 | to a single partition. |
| 27965 | .index \statvfs\ function |
| 27966 | This relies on the availability of the \*statvfs()*\ function or equivalent in |
| 27967 | the operating system. Most, but not all versions of Unix that support Exim have |
| 27968 | this. For this particular stripchart, the top of the chart always represents |
| 27969 | 100%, and the scale is given as `x10%'. This chart is configured by setting |
| 27970 | \\SIZE@_STRIPCHART\\ and (optionally) \\SIZE@_STRIPCHART@_NAME\\ in the |
| 27971 | \(Local/eximon.conf)\ file. |
| 27972 | |
| 27973 | |
| 27974 | |
| 27975 | .section Main action buttons |
| 27976 | .index size||of monitor window |
| 27977 | .index monitor window size |
| 27978 | .index window size |
| 27979 | Below the stripcharts there is an action button for quitting the monitor. Next |
| 27980 | to this is another button marked `Size'. They are placed here so that shrinking |
| 27981 | the window to its default minimum size leaves just the queue count stripchart |
| 27982 | and these two buttons visible. Pressing the `Size' button causes the window to |
| 27983 | expand to its maximum size, unless it is already at the maximum, in which case |
| 27984 | it is reduced to its minimum. |
| 27985 | |
| 27986 | When expanding to the maximum, if the window cannot be fully seen where it |
| 27987 | currently is, it is moved back to where it was the last time it was at full |
| 27988 | size. When it is expanding from its minimum size, the old position is |
| 27989 | remembered, and next time it is reduced to the minimum it is moved back there. |
| 27990 | |
| 27991 | The idea is that you can keep a reduced window just showing one or two |
| 27992 | stripcharts at a convenient place on your screen, easily expand it to show |
| 27993 | the full window when required, and just as easily put it back to what it was. |
| 27994 | The idea is copied from what the \*twm*\ window manager does for its |
| 27995 | \*f.fullzoom*\ action. The minimum size of the window can be changed by setting |
| 27996 | the \\MIN@_HEIGHT\\ and \\MIN@_WIDTH\\ values in \(Local/eximon.conf)\. |
| 27997 | |
| 27998 | Normally, the monitor starts up with the window at its full size, but it can be |
| 27999 | built so that it starts up with the window at its smallest size, by setting |
| 28000 | \\START@_SMALL\\=yes in \(Local/eximon.conf)\. |
| 28001 | |
| 28002 | |
| 28003 | .section The log display |
| 28004 | .index log||tail of, in monitor |
| 28005 | The second section of the window is an area in which a display of the tail of |
| 28006 | the main log is maintained. |
| 28007 | To save space on the screen, the timestamp on each log line is shortened by |
| 28008 | removing the date and, if \log@_timezone\ is set, the timezone. |
| 28009 | The log tail is not available when the only destination for logging data is |
| 28010 | syslog, unless the syslog lines are routed to a local file whose name is passed |
| 28011 | to \*eximon*\ via the \\EXIMON@_LOG@_FILE@_PATH\\ environment variable. |
| 28012 | |
| 28013 | The log sub-window has a scroll bar at its lefthand side which can be used to |
| 28014 | move back to look at earlier text, and the up and down arrow keys also have a |
| 28015 | scrolling effect. The amount of log that is kept depends on the setting of |
| 28016 | \\LOG@_BUFFER\\ in \(Local/eximon.conf)\, which specifies the amount of memory |
| 28017 | to use. When this is full, the earlier 50% of data is discarded -- this is much |
| 28018 | more efficient than throwing it away line by line. The sub-window also has a |
| 28019 | horizontal scroll bar for accessing the ends of long log lines. This is the |
| 28020 | only means of horizontal scrolling; the right and left arrow keys are not |
| 28021 | available. Text can be cut from this part of the window using the mouse in the |
| 28022 | normal way. The size of this subwindow is controlled by parameters in the |
| 28023 | configuration file \(Local/eximon.conf)\. |
| 28024 | |
| 28025 | Searches of the text in the log window can be carried out by means of the ^R |
| 28026 | and ^S keystrokes, which default to a reverse and a forward search, |
| 28027 | respectively. The search covers only the text that is displayed in the window. |
| 28028 | It cannot go further back up the log. |
| 28029 | |
| 28030 | The point from which the search starts is indicated by a caret marker. This is |
| 28031 | normally at the end of the text in the window, but can be positioned explicitly |
| 28032 | by pointing and clicking with the left mouse button, and is moved automatically |
| 28033 | by a successful search. If new text arrives in the window when it is scrolled |
| 28034 | back, the caret remains where it is, but if the window is not scrolled back, |
| 28035 | the caret is moved to the end of the new text. |
| 28036 | |
| 28037 | Pressing ^R or ^S pops up a window into which the search text can be typed. |
| 28038 | There are buttons for selecting forward or reverse searching, for carrying out |
| 28039 | the search, and for cancelling. If the `Search' button is pressed, the search |
| 28040 | happens and the window remains so that further searches can be done. If the |
| 28041 | `Return' key is pressed, a single search is done and the window is closed. If |
| 28042 | ^C is typed the search is cancelled. |
| 28043 | |
| 28044 | The searching facility is implemented using the facilities of the Athena text |
| 28045 | widget. By default this pops up a window containing both `search' and `replace' |
| 28046 | options. In order to suppress the unwanted `replace' portion for eximon, a |
| 28047 | modified version of the \TextPop\ widget is distributed with Exim. However, the |
| 28048 | linkers in BSDI and HP-UX seem unable to handle an externally provided version |
| 28049 | of \TextPop\ when the remaining parts of the text widget come from the standard |
| 28050 | libraries. The compile-time option \\EXIMON@_TEXTPOP\\ can be unset to cut out |
| 28051 | the modified \TextPop\, making it possible to build Eximon on these systems, at |
| 28052 | the expense of having unwanted items in the search popup window. |
| 28053 | |
| 28054 | |
| 28055 | .section The queue display |
| 28056 | .index queue||display in monitor |
| 28057 | The bottom section of the monitor window contains a list of all messages that |
| 28058 | are on the queue, which includes those currently being received or delivered, |
| 28059 | as well as those awaiting delivery. The size of this subwindow is controlled by |
| 28060 | parameters in the configuration file \(Local/eximon.conf)\, and the frequency |
| 28061 | at which it is updated is controlled by another parameter in the same file -- |
| 28062 | the default is 5 minutes, since queue scans can be quite expensive. However, |
| 28063 | there is an `Update' action button just above the display which can be used to |
| 28064 | force an update of the queue display at any time. |
| 28065 | |
| 28066 | When a host is down for some time, a lot of pending mail can build up for it, |
| 28067 | and this can make it hard to deal with other messages on the queue. To help |
| 28068 | with this situation there is a button next to `Update' called `Hide'. If |
| 28069 | pressed, a dialogue box called `Hide addresses ending with' is put up. If you |
| 28070 | type anything in here and press `Return', the text is added to a chain of such |
| 28071 | texts, and if every undelivered address in a message matches at least one |
| 28072 | of the texts, the message is not displayed. |
| 28073 | |
| 28074 | If there is an address that does not match any of the texts, all the addresses |
| 28075 | are displayed as normal. The matching happens on the ends of addresses so, for |
| 28076 | example, \*cam.ac.uk*\ specifies all addresses in Cambridge, while |
| 28077 | \*xxx@@foo.com.example*\ specifies just one specific address. When any hiding |
| 28078 | has been set up, a button called `Unhide' is displayed. If pressed, it cancels |
| 28079 | all hiding. Also, to ensure that hidden messages do not get forgotten, a hide |
| 28080 | request is automatically cancelled after one hour. |
| 28081 | |
| 28082 | While the dialogue box is displayed, you can't press any buttons or do anything |
| 28083 | else to the monitor window. For this reason, if you want to cut text from the |
| 28084 | queue display to use in the dialogue box, you have to do the cutting before |
| 28085 | pressing the `Hide' button. |
| 28086 | |
| 28087 | The queue display contains, for each unhidden queued message, the length of |
| 28088 | time it has been on the queue, the size of the message, the message id, the |
| 28089 | message sender, and the first undelivered recipient, all on one line. If it is |
| 28090 | a bounce message, the sender is shown as `<>'. If there is more than one |
| 28091 | recipient to which the message has not yet been delivered, subsequent ones are |
| 28092 | listed on additional lines, up to a maximum configured number, following which |
| 28093 | an ellipsis is displayed. Recipients that have already received the message are |
| 28094 | not shown. |
| 28095 | .index frozen messages||display |
| 28096 | If a message is frozen, an asterisk is displayed at the left-hand side. |
| 28097 | |
| 28098 | The queue display has a vertical scroll bar, and can also be scrolled by means |
| 28099 | of the arrow keys. Text can be cut from it using the mouse in the normal way. |
| 28100 | The text searching facilities, as described above for the log window, are also |
| 28101 | available, but the caret is always moved to the end of the text when the queue |
| 28102 | display is updated. |
| 28103 | |
| 28104 | |
| 28105 | .section The queue menu |
| 28106 | .index queue||menu in monitor |
| 28107 | If the \shift\ key is held down and the left button is clicked when the mouse |
| 28108 | pointer is over the text for any message, an action menu pops up, and the first |
| 28109 | line of the queue display for the message is highlighted. This does not affect |
| 28110 | any selected text. |
| 28111 | |
| 28112 | If you want to use some other event for popping up the menu, you can set the |
| 28113 | \\MENU@_EVENT\\ parameter in \(Local/eximon.conf)\ to change the default, or |
| 28114 | set \\EXIMON@_MENU@_EVENT\\ in the environment before starting the monitor. The |
| 28115 | value set in this parameter is a standard X event description. For example, to |
| 28116 | run eximon using \ctrl\ rather than \shift\ you could use |
| 28117 | .display asis |
| 28118 | EXIMON_MENU_EVENT='Ctrl<Btn1Down>' eximon |
| 28119 | .endd |
| 28120 | The title of the menu is the message id, and it contains entries which act as |
| 28121 | follows: |
| 28122 | .numberpars $. |
| 28123 | \*message log*\: The contents of the message log for the message are displayed in |
| 28124 | a new text window. |
| 28125 | .nextp |
| 28126 | \*headers*\: Information from the spool file that contains the envelope |
| 28127 | information and headers is displayed in a new text window. See chapter |
| 28128 | ~~CHAPspool for a description of the format of spool files. |
| 28129 | .nextp |
| 28130 | \*body*\: The contents of the spool file containing the body of the message are |
| 28131 | displayed in a new text window. There is a default limit of 20,000 bytes to the |
| 28132 | amount of data displayed. This can be changed by setting the \\BODY@_MAX\\ |
| 28133 | option at compile time, or the \\EXIMON@_BODY@_MAX\\ option at run time. |
| 28134 | .nextp |
| 28135 | \*deliver message*\: A call to Exim is made using the \-M-\ option to request |
| 28136 | delivery of the message. This causes an automatic thaw if the message is |
| 28137 | frozen. The \-v-\ option is also set, and the output from Exim is displayed in |
| 28138 | a new text window. The delivery is run in a separate process, to avoid holding |
| 28139 | up the monitor while the delivery proceeds. |
| 28140 | .nextp |
| 28141 | \*freeze message*\: A call to Exim is made using the \-Mf-\ option to request |
| 28142 | that the message be frozen. |
| 28143 | .nextp |
| 28144 | .index thawing messages |
| 28145 | .index unfreezing messages |
| 28146 | .index frozen messages||thawing |
| 28147 | \*thaw message*\: A call to Exim is made using the \-Mt-\ option to request that |
| 28148 | the message be thawed. |
| 28149 | .nextp |
| 28150 | .index delivery||forcing failure |
| 28151 | \*give up on msg*\: A call to Exim is made using the \-Mg-\ option to request |
| 28152 | that Exim gives up trying to deliver the message. A bounce message is generated |
| 28153 | for any remaining undelivered addresses. |
| 28154 | .nextp |
| 28155 | \*remove message*\: A call to Exim is made using the \-Mrm-\ option to request |
| 28156 | that the message be deleted from the system without generating a bounce |
| 28157 | message. |
| 28158 | .nextp |
| 28159 | \*add recipient*\: A dialog box is displayed into which a recipient address can |
| 28160 | be typed. If the address is not qualified and the \\QUALIFY@_DOMAIN\\ parameter |
| 28161 | is set in \(Local/eximon.conf)\, the address is qualified with that domain. |
| 28162 | Otherwise it must be entered as a fully qualified address. Pressing \\RETURN\\ |
| 28163 | causes a call to Exim to be made using the \-Mar-\ option to request that an |
| 28164 | additional recipient be added to the message, unless the entry box is empty, in |
| 28165 | which case no action is taken. |
| 28166 | .nextp |
| 28167 | \*mark delivered*\: A dialog box is displayed into which a recipient address can |
| 28168 | be typed. If the address is not qualified and the \\QUALIFY@_DOMAIN\\ parameter |
| 28169 | is set in \(Local/eximon.conf)\, the address is qualified with that domain. |
| 28170 | Otherwise it must be entered as a fully qualified address. Pressing \\RETURN\\ |
| 28171 | causes a call to Exim to be made using the \-Mmd-\ option to mark the given |
| 28172 | recipient address as already delivered, unless the entry box is empty, in which |
| 28173 | case no action is taken. |
| 28174 | .nextp |
| 28175 | \*mark all delivered*\: A call to Exim is made using the \-Mmad-\ option to mark |
| 28176 | all recipient addresses as already delivered. |
| 28177 | .nextp |
| 28178 | \*edit sender*\: A dialog box is displayed initialized with the current sender's |
| 28179 | address. Pressing \\RETURN\\ causes a call to Exim to be made using the \-Mes-\ |
| 28180 | option to replace the sender address, unless the entry box is empty, in which |
| 28181 | case no action is taken. If you want to set an empty sender (as in bounce |
| 28182 | messages), you must specify it as `<>'. Otherwise, if the address is not |
| 28183 | qualified and the \\QUALIFY@_DOMAIN\\ parameter is set in |
| 28184 | \(Local/eximon.conf)\, the address is qualified with that domain. |
| 28185 | .endp |
| 28186 | When a delivery is forced, a window showing the \-v-\ output is displayed. In |
| 28187 | other cases when a call to Exim is made, if there is any output from Exim (in |
| 28188 | particular, if the command fails) a window containing the command and the |
| 28189 | output is displayed. Otherwise, the results of the action are normally apparent |
| 28190 | from the log and queue displays. However, if you set \\ACTION@_OUTPUT\\=yes in |
| 28191 | \(Local/eximon.conf)\, a window showing the Exim command is always opened, even |
| 28192 | if no output is generated. |
| 28193 | |
| 28194 | The queue display is automatically updated for actions such as freezing and |
| 28195 | thawing, unless \\ACTION@_QUEUE@_UPDATE\\=no has been set in |
| 28196 | \(Local/eximon.conf)\. In this case the `Update' button has to be used to force |
| 28197 | an update of the display after one of these actions. |
| 28198 | |
| 28199 | In any text window that is displayed as result of a menu action, the normal |
| 28200 | cut-and-paste facility is available, and searching can be carried out using ^R |
| 28201 | and ^S, as described above for the log tail window. |
| 28202 | |
| 28203 | |
| 28204 | |
| 28205 | |
| 28206 | |
| 28207 | |
| 28208 | . |
| 28209 | . |
| 28210 | . |
| 28211 | . |
| 28212 | . ============================================================================ |
| 28213 | .chapter Security considerations |
| 28214 | .set runningfoot "security" |
| 28215 | .rset CHAPsecurity ~~chapter |
| 28216 | .index security |
| 28217 | This chapter discusses a number of issues concerned with security, some of |
| 28218 | which are also covered in other parts of this manual. |
| 28219 | |
| 28220 | For reasons that this author does not understand, some people have promoted |
| 28221 | Exim as a `particularly secure' mailer. Perhaps it is because of the existence |
| 28222 | of this chapter in the documentation. However, the intent of the chapter is |
| 28223 | simply to describe the way Exim works in relation to certain security concerns, |
| 28224 | not to make any specific claims about the effectiveness of its security as |
| 28225 | compared with other MTAs. |
| 28226 | |
| 28227 | What follows is a description of the way Exim is supposed to be. Best efforts |
| 28228 | have been made to try to ensure that the code agrees with the theory, but an |
| 28229 | absence of bugs can never be guaranteed. Any that are reported will get fixed |
| 28230 | as soon as possible. |
| 28231 | |
| 28232 | .section Building a more `hardened' Exim |
| 28233 | .index security||build-time features |
| 28234 | There are a number of build-time options that can be set in \(Local/Makefile)\ |
| 28235 | to create Exim binaries that are `harder' to attack, in particular by a rogue |
| 28236 | Exim administrator who does not have the root password, or by someone who has |
| 28237 | penetrated the Exim (but not the root) account. These options are as follows: |
| 28238 | .numberpars $. |
| 28239 | \\ALT@_CONFIG@_PREFIX\\ can be set to a string that is required to match the |
| 28240 | start of any file names used with the \-C-\ option. When it is set, these file |
| 28241 | names are also not allowed to contain the sequence `/../'. (However, if the |
| 28242 | value of the \-C-\ option is identical to the value of \\CONFIGURE@_FILE\\ in |
| 28243 | \(Local/Makefile)\, Exim ignores \-C-\ and proceeds as usual.) There is no |
| 28244 | default setting for \ALT@_CONFIG@_PREFIX\. |
| 28245 | |
| 28246 | If the permitted configuration files are confined to a directory to |
| 28247 | which only root has access, this guards against someone who has broken |
| 28248 | into the Exim account from running a privileged Exim with an arbitrary |
| 28249 | configuration file, and using it to break into other accounts. |
| 28250 | .nextp |
| 28251 | If \\ALT@_CONFIG@_ROOT@_ONLY\\ is defined, root privilege is retained for \-C-\ |
| 28252 | and \-D-\ only if the caller of Exim is root. Without it, the Exim user may |
| 28253 | also use \-C-\ and \-D-\ and retain privilege. Setting this option locks out |
| 28254 | the possibility of testing a configuration using \-C-\ right through message |
| 28255 | reception and delivery, even if the caller is root. The reception works, but by |
| 28256 | that time, Exim is running as the Exim user, so when it re-execs to regain |
| 28257 | privilege for the delivery, the use of \-C-\ causes privilege to be lost. |
| 28258 | However, root can test reception and delivery using two separate commands. |
| 28259 | \\ALT@_CONFIG@_ROOT@_ONLY\\ is not set by default. |
| 28260 | .nextp |
| 28261 | If \\DISABLE@_D@_OPTION\\ is defined, the use of the \-D-\ command line option |
| 28262 | is disabled. |
| 28263 | .nextp |
| 28264 | \\FIXED@_NEVER@_USERS\\ can be set to a colon-separated list of users that are |
| 28265 | never to be used for any deliveries. This is like the \never@_users\ runtime |
| 28266 | option, but it cannot be overridden; the runtime option adds additional users |
| 28267 | to the list. The default setting is `root'; this prevents a non-root user who |
| 28268 | is permitted to modify the runtime file from using Exim as a way to get root. |
| 28269 | .endp |
| 28270 | |
| 28271 | |
| 28272 | .section Root privilege |
| 28273 | .index setuid |
| 28274 | .index root privilege |
| 28275 | The Exim binary is normally setuid to root, which means that it gains root |
| 28276 | privilege (runs as root) when it starts execution. In some special cases (for |
| 28277 | example, when the daemon is not in use and there are no local deliveries), it |
| 28278 | may be possible to run Exim setuid to some user other than root. This is |
| 28279 | discussed in the next section. However, in most installations, root privilege |
| 28280 | is required for two things: |
| 28281 | .numberpars $. |
| 28282 | To set up a socket connected to the standard SMTP port (25) when initialising |
| 28283 | the listening daemon. If Exim is run from \*inetd*\, this privileged action is |
| 28284 | not required. |
| 28285 | .nextp |
| 28286 | To be able to change uid and gid in order to read users' \(.forward)\ files and |
| 28287 | perform local deliveries as the receiving user or as specified in the |
| 28288 | configuration. |
| 28289 | .endp |
| 28290 | It is not necessary to be root to do any of the other things Exim does, such as |
| 28291 | receiving messages and delivering them externally over SMTP, and it is |
| 28292 | obviously more secure if Exim does not run as root except when necessary. |
| 28293 | For this reason, a user and group for Exim to use must be defined in |
| 28294 | \(Local/Makefile)\. These are known as `the Exim user' and `the Exim group'. |
| 28295 | Their values can be changed by the run time configuration, though this is not |
| 28296 | recommended. Often a user called \*exim*\ is used, but some sites use \*mail*\ |
| 28297 | or another user name altogether. |
| 28298 | |
| 28299 | Exim uses \*setuid()*\ whenever it gives up root privilege. This is a permanent |
| 28300 | abdication; the process cannot regain root afterwards. Prior to release 4.00, |
| 28301 | \*seteuid()*\ was used in some circumstances, but this is no longer the case. |
| 28302 | |
| 28303 | After a new Exim process has interpreted its command line options, it changes |
| 28304 | uid and gid in the following cases: |
| 28305 | .numberpars $. |
| 28306 | .index \-C-\ option |
| 28307 | .index \-D-\ option |
| 28308 | If the \-C-\ option is used to specify an alternate configuration file, or if |
| 28309 | the \-D-\ option is used to define macro values for the configuration, and the |
| 28310 | calling process is not running as root or the Exim user, the uid and gid are |
| 28311 | changed to those of the calling process. |
| 28312 | However, if \\ALT@_CONFIG@_ROOT@_ONLY\\ is defined in \(Local/Makefile)\, only |
| 28313 | root callers may use \-C-\ and \-D-\ without losing privilege, and if |
| 28314 | \\DISABLE@_D@_OPTION\\ is set, the \-D-\ option may not be used at all. |
| 28315 | .nextp |
| 28316 | .index \-be-\ option |
| 28317 | .index \-bf-\ option |
| 28318 | .index \-bF-\ option |
| 28319 | If the expansion test option (\-be-\) or one of the filter testing options |
| 28320 | (\-bf-\ or \-bF-\) are used, the uid and gid are changed to those of the |
| 28321 | calling process. |
| 28322 | .nextp |
| 28323 | If the process is not a daemon process or a queue runner process or a delivery |
| 28324 | process or a process for testing address routing (started with \-bt-\), the uid |
| 28325 | and gid are changed to the Exim user and group. This means that Exim always |
| 28326 | runs under its own uid and gid when receiving messages. This also applies when |
| 28327 | testing address verification |
| 28328 | .index \-bv-\ option |
| 28329 | .index \-bh-\ option |
| 28330 | (the \-bv-\ option) and testing incoming message policy controls (the \-bh-\ |
| 28331 | option). |
| 28332 | .nextp |
| 28333 | For a daemon, queue runner, delivery, or address testing process, the uid |
| 28334 | remains as root at this stage, but the gid is changed to the Exim group. |
| 28335 | .endp |
| 28336 | The processes that initially retain root privilege behave as follows: |
| 28337 | .numberpars $. |
| 28338 | A daemon process changes the gid to the Exim group and the uid to the Exim user |
| 28339 | after setting up one or more listening sockets. The \*initgroups()*\ function |
| 28340 | is called, so that if the Exim user is in any additional groups, they will be |
| 28341 | used during message reception. |
| 28342 | .nextp |
| 28343 | A queue runner process retains root privilege throughout its execution. Its job |
| 28344 | is to fork a controlled sequence of delivery processes. |
| 28345 | .nextp |
| 28346 | A delivery process retains root privilege throughout most of its execution, |
| 28347 | but any actual deliveries (that is, the transports themselves) are run in |
| 28348 | subprocesses which always change to a non-root uid and gid. For local |
| 28349 | deliveries this is typically the uid and gid of the owner of the mailbox; for |
| 28350 | remote deliveries, the Exim uid and gid are used. Once all the delivery |
| 28351 | subprocesses have been run, a delivery process changes to the Exim uid and gid |
| 28352 | while doing post-delivery tidying up such as updating the retry database and |
| 28353 | generating bounce and warning messages. |
| 28354 | |
| 28355 | While the recipient addresses in a message are being routed, the delivery |
| 28356 | process runs as root. However, if a user's filter file has to be processed, |
| 28357 | this is done in a subprocess that runs under the individual user's uid and |
| 28358 | gid. A system filter is run as root unless \system@_filter@_user\ is set. |
| 28359 | .nextp |
| 28360 | A process that is testing addresses (the \-bt-\ option) runs as root so that |
| 28361 | the routing is done in the same environment as a message delivery. |
| 28362 | .endp |
| 28363 | |
| 28364 | |
| 28365 | .section Running Exim without privilege |
| 28366 | .index privilege, running without |
| 28367 | .index unprivileged running |
| 28368 | .index root privilege||running without |
| 28369 | Some installations like to run Exim in an unprivileged state for more of its |
| 28370 | operation, for added security. Support for this mode of operation is provided |
| 28371 | by the global option \deliver@_drop@_privilege\. When this is set, the uid and |
| 28372 | gid are changed to the Exim user and group at the start of a delivery process |
| 28373 | (and also queue runner and address testing processes). This means that address |
| 28374 | routing is no longer run as root, and the deliveries themselves cannot change |
| 28375 | to any other uid. |
| 28376 | |
| 28377 | Leaving the binary setuid to root, but setting \deliver@_drop@_privilege\ means |
| 28378 | that the daemon can still be started in the usual way, and it can respond |
| 28379 | correctly to SIGHUP because the re-invocation regains root privilege. |
| 28380 | |
| 28381 | An alternative approach is to make Exim setuid to the Exim user and also setgid |
| 28382 | to the Exim group. |
| 28383 | If you do this, the daemon must be started from a root process. (Calling |
| 28384 | Exim from a root process makes it behave in the way it does when it is setuid |
| 28385 | root.) However, the daemon cannot restart itself after a SIGHUP signal because |
| 28386 | it cannot regain privilege. |
| 28387 | |
| 28388 | It is still useful to set \deliver@_drop@_privilege\ in this case, because it |
| 28389 | stops Exim from trying to re-invoke itself to do a delivery after a message has |
| 28390 | been received. Such a re-invocation is a waste of resources because it has no |
| 28391 | effect. |
| 28392 | |
| 28393 | If restarting the daemon is not an issue (for example, if \*inetd*\ is being |
| 28394 | used instead of a daemon), having the binary setuid to the Exim user seems a |
| 28395 | clean approach, but there is one complication: |
| 28396 | |
| 28397 | In this style of operation, Exim is running with the real uid and gid set to |
| 28398 | those of the calling process, and the effective uid/gid set to Exim's values. |
| 28399 | Ideally, any association with the calling process' uid/gid should be dropped, |
| 28400 | that is, the real uid/gid should be reset to the effective values so as to |
| 28401 | discard any privileges that the caller may have. While some operating systems |
| 28402 | have a function that permits this action for a non-root effective uid, quite a |
| 28403 | number of them do not. Because of this lack of standardization, Exim does not |
| 28404 | address this problem at this time. |
| 28405 | |
| 28406 | For this reason, the recommended approach for `mostly unprivileged' running is |
| 28407 | to keep the Exim binary setuid to root, and to set \deliver@_drop@_privilege\. |
| 28408 | This also has the advantage of allowing a daemon to be used in the most |
| 28409 | straightforward way. |
| 28410 | |
| 28411 | If you configure Exim not to run delivery processes as root, there are a |
| 28412 | number of restrictions on what you can do: |
| 28413 | .numberpars $. |
| 28414 | You can deliver only as the Exim user/group. You should explicitly use the |
| 28415 | \user\ and \group\ options to override routers or local transports that |
| 28416 | normally deliver as the recipient. This makes sure that configurations that |
| 28417 | work in this mode function the same way in normal mode. Any implicit or |
| 28418 | explicit specification of another user causes an error. |
| 28419 | .nextp |
| 28420 | Use of \(.forward)\ files is severely restricted, such that it is usually |
| 28421 | not worthwhile to include them in the configuration. |
| 28422 | .nextp |
| 28423 | Users who wish to use \(.forward)\ would have to make their home directory and |
| 28424 | the file itself accessible to the Exim user. Pipe and append-to-file entries, |
| 28425 | and their equivalents in Exim filters, cannot be used. While they could be |
| 28426 | enabled in the Exim user's name, that would be insecure and not very useful. |
| 28427 | .nextp |
| 28428 | Unless the local user mailboxes are all owned by the Exim user (possible in |
| 28429 | some POP3 or IMAP-only environments): |
| 28430 | .numberpars $*$ |
| 28431 | They must be owned by the Exim group and be writable by that group. This |
| 28432 | implies you must set \mode\ in the appendfile configuration, as well as the |
| 28433 | mode of the mailbox files themselves. |
| 28434 | .nextp |
| 28435 | You must set \no@_check@_owner\, since most or all of the files will not be |
| 28436 | owned by the Exim user. |
| 28437 | .nextp |
| 28438 | You must set \file@_must@_exist\, because Exim cannot set the owner correctly |
| 28439 | on a newly created mailbox when unprivileged. This also implies that new |
| 28440 | mailboxes need to be created manually. |
| 28441 | .endp |
| 28442 | .endp |
| 28443 | These restrictions severely restrict what can be done in local deliveries. |
| 28444 | However, there are no restrictions on remote deliveries. If you are running a |
| 28445 | gateway host that does no local deliveries, setting \deliver@_drop@_privilege\ |
| 28446 | gives more security at essentially no cost. |
| 28447 | |
| 28448 | |
| 28449 | .section Delivering to local files |
| 28450 | Full details of the checks applied by \%appendfile%\ before it writes to a file |
| 28451 | are given in chapter ~~CHAPappendfile. |
| 28452 | |
| 28453 | |
| 28454 | .section IPv4 source routing |
| 28455 | .index source routing||in IP packets |
| 28456 | .index IP source routing |
| 28457 | Many operating systems suppress IP source-routed packets in the kernel, but |
| 28458 | some cannot be made to do this, so Exim does its own check. It logs incoming |
| 28459 | IPv4 source-routed TCP calls, and then drops them. Things are all different in |
| 28460 | IPv6. No special checking is currently done. |
| 28461 | |
| 28462 | |
| 28463 | .section The VRFY, EXPN, and ETRN commands in SMTP |
| 28464 | Support for these SMTP commands is disabled by default. If required, they can |
| 28465 | be enabled by defining suitable ACLs. |
| 28466 | |
| 28467 | |
| 28468 | |
| 28469 | .section Privileged users |
| 28470 | .index trusted user |
| 28471 | .index admin user |
| 28472 | .index privileged user |
| 28473 | .index user||trusted |
| 28474 | .index user||admin |
| 28475 | Exim recognises two sets of users with special privileges. Trusted users are |
| 28476 | able to submit new messages to Exim locally, but supply their own sender |
| 28477 | addresses and information about a sending host. For other users submitting |
| 28478 | local messages, Exim sets up the sender address from the uid, and doesn't |
| 28479 | permit a remote host to be specified. |
| 28480 | |
| 28481 | .index \-f-\ option |
| 28482 | However, an untrusted user is permitted to use the \-f-\ command line option in |
| 28483 | the special form \-f @<@>-\ to indicate that a delivery failure for the message |
| 28484 | should not cause an error report. This affects the message's envelope, but it |
| 28485 | does not affect the ::Sender:: header. Untrusted users may also be permitted to |
| 28486 | use specific forms of address with the \-f-\ option by setting the |
| 28487 | \untrusted@_set@_sender\ option. |
| 28488 | |
| 28489 | Trusted users are used to run processes that receive mail messages from some |
| 28490 | other mail domain and pass them on to Exim for delivery either locally, or over |
| 28491 | the Internet. Exim trusts a caller that is running as root, as the Exim user, |
| 28492 | as any user listed in the \trusted@_users\ configuration option, or under any |
| 28493 | group listed in the \trusted@_groups\ option. |
| 28494 | |
| 28495 | Admin users are permitted to do things to the messages on Exim's queue. They |
| 28496 | can freeze or thaw messages, cause them to be returned to their senders, remove |
| 28497 | them entirely, or modify them in various ways. In addition, admin users can run |
| 28498 | the Exim monitor and see all the information it is capable of providing, which |
| 28499 | includes the contents of files on the spool. |
| 28500 | |
| 28501 | .index \-M-\ option |
| 28502 | .index \-q-\ option |
| 28503 | By default, the use of the \-M-\ and \-q-\ options to cause Exim to attempt |
| 28504 | delivery of messages on its queue is restricted to admin users. This |
| 28505 | restriction can be relaxed by setting the \no@_prod@_requires@_admin\ option. |
| 28506 | Similarly, the use of \-bp-\ (and its variants) to list the contents of the |
| 28507 | queue is also restricted to admin users. This restriction can be relaxed by |
| 28508 | setting \no@_queue@_list@_requires@_admin\. |
| 28509 | |
| 28510 | Exim recognises an admin user if the calling process is running as root or as |
| 28511 | the Exim user or if any of the groups associated with the calling process is |
| 28512 | the Exim group. It is not necessary actually to be running under the Exim |
| 28513 | group. However, if admin users who are not root or the Exim user are to access |
| 28514 | the contents of files on the spool via the Exim monitor (which runs |
| 28515 | unprivileged), Exim must be built to allow group read access to its spool |
| 28516 | files. |
| 28517 | |
| 28518 | |
| 28519 | .section Spool files |
| 28520 | .index spool directory||files |
| 28521 | Exim's spool directory and everything it contains is owned by the Exim user and |
| 28522 | set to the Exim group. The mode for spool files is defined in the |
| 28523 | \(Local/Makefile)\ configuration file, and defaults to 0640. This means that |
| 28524 | any user who is a member of the Exim group can access these files. |
| 28525 | |
| 28526 | |
| 28527 | .section Use of argv[0] |
| 28528 | Exim examines the last component of \argv[0]\, and if it matches one of a set |
| 28529 | of specific strings, Exim assumes certain options. For example, calling Exim |
| 28530 | with the last component of \argv[0]\ set to `rsmtp' is exactly equivalent to |
| 28531 | calling it with the option \-bS-\. There are no security implications in this. |
| 28532 | |
| 28533 | |
| 28534 | .section Use of %f formatting |
| 28535 | The only use made of `%f' by Exim is in formatting load average values. These |
| 28536 | are actually stored in integer variables as 1000 times the load average. |
| 28537 | Consequently, their range is limited and so therefore is the length of the |
| 28538 | converted output. |
| 28539 | |
| 28540 | |
| 28541 | .section Embedded Exim path |
| 28542 | Exim uses its own path name, which is embedded in the code, only when it needs |
| 28543 | to re-exec in order to regain root privilege. Therefore, it is not root when it |
| 28544 | does so. If some bug allowed the path to get overwritten, it would lead to an |
| 28545 | arbitrary program's being run as exim, not as root. |
| 28546 | |
| 28547 | |
| 28548 | .section Use of sprintf() |
| 28549 | .index \*sprintf()*\ |
| 28550 | A large number of occurrences of `sprintf' in the code are actually calls to |
| 28551 | \*string@_sprintf()*\, a function that returns the result in malloc'd store. |
| 28552 | The intermediate formatting is done into a large fixed buffer by a function |
| 28553 | that runs through the format string itself, and checks the length of each |
| 28554 | conversion before performing it, thus preventing buffer overruns. |
| 28555 | |
| 28556 | The remaining uses of \*sprintf()*\ happen in controlled circumstances where |
| 28557 | the output buffer is known to be sufficiently long to contain the converted |
| 28558 | string. |
| 28559 | |
| 28560 | |
| 28561 | .section Use of debug@_printf() and log@_write() |
| 28562 | Arbitrary strings are passed to both these functions, but they do their |
| 28563 | formatting by calling the function \*string@_vformat()*\, which runs through |
| 28564 | the format string itself, and checks the length of each conversion. |
| 28565 | |
| 28566 | |
| 28567 | .section Use of strcat() and strcpy() |
| 28568 | These are used only in cases where the output buffer is known to be large |
| 28569 | enough to hold the result. |
| 28570 | |
| 28571 | |
| 28572 | |
| 28573 | |
| 28574 | . |
| 28575 | . |
| 28576 | . |
| 28577 | . |
| 28578 | . ============================================================================ |
| 28579 | .chapter Format of spool files |
| 28580 | .set runningfoot "spool file format" |
| 28581 | .rset CHAPspool ~~chapter |
| 28582 | .index format||spool files |
| 28583 | .index spool directory||format of files |
| 28584 | .index spool||files, format of |
| 28585 | .index spool||files, editing |
| 28586 | A message on Exim's queue consists of two files, whose names are the message id |
| 28587 | followed by -D and -H, respectively. The data portion of the message is kept in |
| 28588 | the -D file on its own. The message's envelope, status, and headers are all |
| 28589 | kept in the -H file, whose format is described in this chapter. Each of these |
| 28590 | two files contains the final component of its own name as its first line. This |
| 28591 | is insurance against disk crashes where the directory is lost but the files |
| 28592 | themselves are recoverable. |
| 28593 | |
| 28594 | Some people are tempted into editing -D files in order to modify messages. You |
| 28595 | need to be extremely careful if you do this; it is not recommended and you are |
| 28596 | on your own if you do it. Here are some of the pitfalls: |
| 28597 | .numberpars $. |
| 28598 | You must use the \*exim@_lock*\ utility to ensure that Exim does not try to |
| 28599 | deliver the message while you are fiddling with it. The lock is implemented |
| 28600 | by opening the -D file and taking out a write lock on it. If you update the |
| 28601 | file in place, the lock will be retained. If you write a new file and rename |
| 28602 | it, the lock will be lost at the instant of rename. |
| 28603 | .nextp |
| 28604 | If you change the number of lines in the file, the value of |
| 28605 | \$body@_linecount$\, which is stored in the -H file, will be incorrect. |
| 28606 | .nextp |
| 28607 | If the message is in MIME format, you must take care not to break it. |
| 28608 | .nextp |
| 28609 | If the message is cryptographically signed, any change will invalidate the |
| 28610 | signature. |
| 28611 | .endp |
| 28612 | |
| 28613 | Files whose names end with -J may also be seen in the \(input)\ directory (or |
| 28614 | its subdirectories when \split@_spool@_directory\ is set). These are journal |
| 28615 | files, used to record addresses to which the message has been delivered during |
| 28616 | the course of a delivery run. At the end of the run, the -H file is updated, |
| 28617 | and the -J file is deleted. |
| 28618 | |
| 28619 | .section Format of the -H file |
| 28620 | .index uid (user id)||in spool file |
| 28621 | .index gid (group id)||in spool file |
| 28622 | The second line of the -H file contains the login name for the uid of the |
| 28623 | process that called Exim to read the message, followed by the numerical uid and |
| 28624 | gid. For a locally generated message, this is normally the user who sent the |
| 28625 | message. For a message received over TCP/IP, it is normally the Exim user. |
| 28626 | |
| 28627 | The third line of the file contains the address of the message's sender as |
| 28628 | transmitted in the envelope, contained in angle brackets. The sender address is |
| 28629 | empty for bounce messages. For incoming SMTP mail, the sender address is given |
| 28630 | in the \\MAIL\\ command. For locally generated mail, the sender address is |
| 28631 | created by Exim from the login name of the current user and the configured |
| 28632 | \qualify@_domain\. However, this can be overridden by the \-f-\ option or a |
| 28633 | leading `From' line if the caller is trusted, or if the supplied address is |
| 28634 | `@<@>' or an address that matches \untrusted@_set@_senders\. |
| 28635 | |
| 28636 | The fourth line contains two numbers. The first is the time that the message |
| 28637 | was received, in the conventional Unix form -- the number of seconds since the |
| 28638 | start of the epoch. The second number is a count of the number of messages |
| 28639 | warning of delayed delivery that have been sent to the sender. |
| 28640 | |
| 28641 | There follow a number of lines starting with a hyphen. These can appear in any |
| 28642 | order, and are omitted when not relevant: |
| 28643 | .numberpars $. |
| 28644 | \-acl <<number>> <<length>>-\: A line of this form is present for every ACL |
| 28645 | variable that is not empty. The number identifies the variable; the |
| 28646 | \acl@_c\*x*\$$\ variables are numbered 0--9 and the \acl@_m\*x*\$$\ variables |
| 28647 | are numbered 10--19. The length is the length of the data string for the |
| 28648 | variable. The string itself starts at the beginning of the next line, and is |
| 28649 | followed by a newline character. It may contain internal newlines. |
| 28650 | .nextp |
| 28651 | \-allow@_unqualified@_recipient-\: This is present if unqualified recipient |
| 28652 | addresses are permitted in header lines (to stop such addresses from being |
| 28653 | qualified if rewriting occurs at transport time). Local messages that were |
| 28654 | input using \-bnq-\ and remote messages from hosts that match |
| 28655 | \recipient@_unqualified@_hosts\ set this flag. |
| 28656 | .nextp |
| 28657 | \-allow@_unqualified@_sender-\: This is present if unqualified sender |
| 28658 | addresses are permitted in header lines (to stop such addresses from being |
| 28659 | qualified if rewriting occurs at transport time). Local messages that were |
| 28660 | input using \-bnq-\ and remote messages from hosts that match |
| 28661 | \sender@_unqualified@_hosts\ set this flag. |
| 28662 | .nextp |
| 28663 | \-auth@_id <<text>>-\: The id information for a message received on an |
| 28664 | authenticated SMTP connection -- the value of the \$authenticated@_id$\ |
| 28665 | variable. |
| 28666 | .nextp |
| 28667 | \-auth@_sender <<address>>-\: The address of an authenticated sender -- the |
| 28668 | value of the \$authenticated@_sender$\ variable. |
| 28669 | .nextp |
| 28670 | \-body@_linecount <<number>>-\: This records the number of lines in the body of |
| 28671 | the message, and is always present. |
| 28672 | .nextp |
| 28673 | \-deliver@_firsttime-\: This is written when a new message is first added to |
| 28674 | the spool. When the spool file is updated after a deferral, it is omitted. |
| 28675 | .nextp |
| 28676 | .index frozen messages||spool data |
| 28677 | \-frozen <<time>>-\: The message is frozen, and the freezing happened at |
| 28678 | <<time>>. |
| 28679 | .nextp |
| 28680 | \-helo@_name <<text>>-\: This records the host name as specified by a remote |
| 28681 | host in a \\HELO\\ or \\EHLO\\ command. |
| 28682 | .nextp |
| 28683 | \-host@_address <<address>>.<<port>>-\: This records the IP address of the host |
| 28684 | from which the message was received and the remote port number that was used. |
| 28685 | It is omitted for locally generated messages. |
| 28686 | .nextp |
| 28687 | \-host@_auth <<text>>-\: If the message was received on an authenticated SMTP |
| 28688 | connection, this records the name of the authenticator -- the value of the |
| 28689 | \$sender@_host@_authenticated$\ variable. |
| 28690 | .nextp |
| 28691 | \-host@_lookup@_failed-\: This is present if an attempt to look up the sending |
| 28692 | host's name from its IP address failed. It corresponds to the |
| 28693 | \$host@_lookup@_failed$\ variable. |
| 28694 | .nextp |
| 28695 | .index DNS||reverse lookup |
| 28696 | .index reverse DNS lookup |
| 28697 | \-host@_name <<text>>-\: This records the name of the remote host from which |
| 28698 | the message was received, if the host name was looked up from the IP address |
| 28699 | when the message was being received. It is not present if no reverse lookup was |
| 28700 | done. |
| 28701 | .nextp |
| 28702 | \-ident <<text>>-\: For locally submitted messages, this records the login of |
| 28703 | the originating user, unless it was a trusted user and the \-oMt-\ option was |
| 28704 | used to specify an ident value. For messages received over TCP/IP, this records |
| 28705 | the ident string supplied by the remote host, if any. |
| 28706 | .nextp |
| 28707 | \-interface@_address <<address>>.<<port>>-\: This records the IP address of the |
| 28708 | local interface and the port number through which a message was received from a |
| 28709 | remote host. It is omitted for locally generated messages. |
| 28710 | .nextp |
| 28711 | \-local-\: The message is from a local sender. |
| 28712 | .nextp |
| 28713 | \-localerror-\: The message is a locally-generated bounce message. |
| 28714 | .nextp |
| 28715 | \-local@_scan <<string>>-\: This records the data string that was |
| 28716 | returned by the \*local@_scan()*\ function when the message was received -- the |
| 28717 | value of the \$local@_scan@_data$\ variable. It is omitted if no data was |
| 28718 | returned. |
| 28719 | .nextp |
| 28720 | \-manual@_thaw-\: The message was frozen but has been thawed manually, that is, |
| 28721 | by an explicit Exim command rather than via the auto-thaw process. |
| 28722 | .nextp |
| 28723 | \-N-\: A testing delivery process was started using the \-N-\ option to |
| 28724 | suppress any actual deliveries, but delivery was deferred. At any further |
| 28725 | delivery attempts, \-N-\ is assumed. |
| 28726 | .nextp |
| 28727 | \-received@_protocol-\: This records the value of the \$received@_protocol$\ |
| 28728 | variable, which contains the name of the protocol by which the message was |
| 28729 | received. |
| 28730 | .nextp |
| 28731 | \-sender@_set@_untrusted-\: The envelope sender of this message was set by an |
| 28732 | untrusted local caller (used to ensure that the caller is displayed in queue |
| 28733 | listings). |
| 28734 | .nextp |
| 28735 | \-tls@_certificate@_verified-\: A TLS certificate was received from the client |
| 28736 | that sent this message, and the certificate was verified by the server. |
| 28737 | .nextp |
| 28738 | \-tls@_cipher <<cipher name>>-\: When the message was received over an |
| 28739 | encrypted connection, this records the name of the cipher suite that was used. |
| 28740 | .nextp |
| 28741 | \-tls@_peerdn <<peer DN>>-\: When the message was received over an encrypted |
| 28742 | connection, and a certificate was received from the client, this records the |
| 28743 | Distinguished Name from that certificate. |
| 28744 | .endp |
| 28745 | |
| 28746 | Following the options there is a list of those addresses to which the message |
| 28747 | is not to be delivered. This set of addresses is initialized from the command |
| 28748 | line when the \-t-\ option is used and \extract__addresses__remove__arguments\ |
| 28749 | is set; otherwise it starts out empty. Whenever a successful delivery is made, |
| 28750 | the address is added to this set. The addresses are kept internally as a |
| 28751 | balanced binary tree, and it is a representation of that tree which is written |
| 28752 | to the spool file. If an address is expanded via an alias or forward file, the |
| 28753 | original address is added to the tree when deliveries to all its child |
| 28754 | addresses are complete. |
| 28755 | |
| 28756 | If the tree is empty, there is a single line in the spool file containing just |
| 28757 | the text `XX'. Otherwise, each line consists of two letters, which are either Y |
| 28758 | or N, followed by an address. The address is the value for the node of the |
| 28759 | tree, and the letters indicate whether the node has a left branch and/or a |
| 28760 | right branch attached to it, respectively. If branches exist, they immediately |
| 28761 | follow. Here is an example of a three-node tree: |
| 28762 | .display asis |
| 28763 | YY darcy@austen.fict.example |
| 28764 | NN alice@wonderland.fict.example |
| 28765 | NN editor@thesaurus.ref.example |
| 28766 | .endd |
| 28767 | After the non-recipients tree, there is a list of the message's recipients. |
| 28768 | This is a simple list, preceded by a count. It includes all the original |
| 28769 | recipients of the message, including those to whom the message has already been |
| 28770 | delivered. In the simplest case, the list contains one address per line. For |
| 28771 | example: |
| 28772 | .display asis |
| 28773 | 4 |
| 28774 | editor@thesaurus.ref.example |
| 28775 | darcy@austen.fict.example |
| 28776 | rdo@foundation |
| 28777 | alice@wonderland.fict.example |
| 28778 | .endd |
| 28779 | However, when a child address has been added to the top-level addresses as a |
| 28780 | result of the use of the \one@_time\ option on a \%redirect%\ router, each line |
| 28781 | is of the following form: |
| 28782 | .display |
| 28783 | <<top-level address>> <<errors@_to address>> <<length>>,<<parent number>>@#<<flag bits>> |
| 28784 | .endd |
| 28785 | The 01 flag bit indicates the presence of the three other fields that follow |
| 28786 | the top-level address. Other bits may be used in future to support additional |
| 28787 | fields. The <<parent number>> is the offset in the recipients list of the |
| 28788 | original parent of the `one time' address. The first two fields are the |
| 28789 | envelope sender that is associated with this address and its length. If the |
| 28790 | length is zero, there is no special envelope sender (there are then two space |
| 28791 | characters in the line). A non-empty field can arise from a \%redirect%\ router |
| 28792 | that has an \errors@_to\ setting. |
| 28793 | |
| 28794 | |
| 28795 | A blank line separates the envelope and status information from the headers |
| 28796 | which follow. A header may occupy several lines of the file, and to save effort |
| 28797 | when reading it in, each header is preceded by a number and an identifying |
| 28798 | character. The number is the number of characters in the header, including any |
| 28799 | embedded newlines and the terminating newline. The character is one of the |
| 28800 | following: |
| 28801 | .display |
| 28802 | .tabs 9 |
| 28803 | <<blank>> $t $rm{header in which Exim has no special interest} |
| 28804 | #B $t $rm{::Bcc:: header} |
| 28805 | #C $t $rm{::Cc:: header} |
| 28806 | #F $t $rm{::From:: header} |
| 28807 | #I $t $rm{::Message-id:: header} |
| 28808 | #P $t $rm{::Received:: header -- P for `postmark'} |
| 28809 | #R $t $rm{::Reply-To:: header} |
| 28810 | #S $t $rm{::Sender:: header} |
| 28811 | #T $t $rm{::To:: header} |
| 28812 | #* $t $rm{replaced or deleted header} |
| 28813 | .endd |
| 28814 | Deleted or replaced (rewritten) headers remain in the spool file for debugging |
| 28815 | purposes. They are not transmitted when the message is delivered. Here is a |
| 28816 | typical set of headers: |
| 28817 | .display asis |
| 28818 | 111P Received: by hobbit.fict.example with local (Exim 4.00) |
| 28819 | id 14y9EI-00026G-00; Fri, 11 May 2001 10:28:59 +0100 |
| 28820 | 049 Message-Id: <E14y9EI-00026G-00@hobbit.fict.example> |
| 28821 | 038* X-rewrote-sender: bb@hobbit.fict.example |
| 28822 | 042* From: Bilbo Baggins <bb@hobbit.fict.example> |
| 28823 | 049F From: Bilbo Baggins <B.Baggins@hobbit.fict.example> |
| 28824 | 099* To: alice@wonderland.fict.example, rdo@foundation, |
| 28825 | darcy@austen.fict.example, editor@thesaurus.ref.example |
| 28826 | 109T To: alice@wonderland.fict.example, rdo@foundation.fict.example, |
| 28827 | darcy@austen.fict.example, editor@thesaurus.ref.example |
| 28828 | 038 Date: Fri, 11 May 2001 10:28:59 +0100 |
| 28829 | .endd |
| 28830 | The asterisked headers indicate that the envelope sender, ::From:: header, and |
| 28831 | ::To:: header have been rewritten, the last one because routing expanded the |
| 28832 | unqualified domain \*foundation*\. |
| 28833 | |
| 28834 | . |
| 28835 | . |
| 28836 | . |
| 28837 | . |
| 28838 | . ============================================================================ |
| 28839 | .chapter Adding new drivers or lookup types |
| 28840 | .set runningfoot "adding drivers" |
| 28841 | .index adding drivers |
| 28842 | .index new drivers, adding |
| 28843 | .index drivers||adding new |
| 28844 | The following actions have to be taken in order to add a new router, transport, |
| 28845 | authenticator, or lookup type to Exim: |
| 28846 | .numberpars |
| 28847 | Choose a name for the driver or lookup type that does not conflict with any |
| 28848 | existing name; I will use `newdriver' in what follows. |
| 28849 | .nextp |
| 28850 | Add to \(src/EDITME)\ the line |
| 28851 | .display |
| 28852 | <<type>>@_NEWDRIVER=yes |
| 28853 | .endd |
| 28854 | where <<type>> is \\ROUTER\\, \\TRANSPORT\\, \\AUTH\\, or \\LOOKUP\\. If the |
| 28855 | code is not to be included in the binary by default, comment this line out. You |
| 28856 | should also add any relevant comments about the driver or lookup type. |
| 28857 | .nextp |
| 28858 | Add to \(src/config.h.defaults)\ the line |
| 28859 | .display |
| 28860 | @#define <<type>>@_NEWDRIVER |
| 28861 | .endd |
| 28862 | .nextp |
| 28863 | Edit \(src/drtables.c)\, adding conditional code to pull in the private header |
| 28864 | and create a table entry as is done for all the other drivers and lookup types. |
| 28865 | .nextp |
| 28866 | Edit \(Makefile)\ in the appropriate sub-directory (\(src/routers)\, |
| 28867 | \(src/transports)\, \(src/auths)\, or \(src/lookups)\); add a line for the new |
| 28868 | driver or lookup type and add it to the definition of OBJ. |
| 28869 | .nextp |
| 28870 | Create \(newdriver.h)\ and \(newdriver.c)\ in the appropriate sub-directory of |
| 28871 | \(src)\. |
| 28872 | .nextp |
| 28873 | Edit \(scripts/MakeLinks)\ and add commands to link the \(.h)\ and \(.c)\ files |
| 28874 | as for other drivers and lookups. |
| 28875 | .endp |
| 28876 | Then all you need to do is write the code! A good way to start is to make a |
| 28877 | proforma by copying an existing module of the same type, globally changing all |
| 28878 | occurrences of the name, and cutting out most of the code. Note that any |
| 28879 | options you create must be listed in alphabetical order, because the tables are |
| 28880 | searched using a binary chop procedure. |
| 28881 | |
| 28882 | There is a \(README)\ file in each of the sub-directories of \(src)\ describing |
| 28883 | the interface that is expected. |
| 28884 | |
| 28885 | . |
| 28886 | . |
| 28887 | . |
| 28888 | . |
| 28889 | . ============================================================================ |
| 28890 | . Fudge for the index page number. We want it to be on a right-hand page. |
| 28891 | . |
| 28892 | .set indexpage ~~sys.pagenumber + 1 |
| 28893 | .if even ~~indexpage |
| 28894 | .set indexpage ~~indexpage + 1 |
| 28895 | .fi |
| 28896 | .if ~~sgcal |
| 28897 | .%index Index$e~~indexpage-- |
| 28898 | .fi |
| 28899 | . |
| 28900 | . |
| 28901 | . End of Exim specification |